Claude Codeが勝手に従量課金になる原因、ANTHROPIC_API_KEYの優先順位だった
Claude Codeでサブスク契約中なのに従量課金された時に疑うべきはANTHROPIC_API_KEY環境変数。認証の優先順位を公式ドキュメントで確認し、確認方法と直し方をまとめた。
エンジニアのゆとです。
Maxプラン払ってるのに、月末にAnthropic Consoleの請求を見たら従量課金の項目が乗ってた、みたいな話をXでちらほら見かける。僕も一度、複数のクライアント案件を行き来してる最中に似たようなことをやりかけて、原因を追ったら環境変数だった。
結論から言うと、Claude Codeは「サブスクにログインしてるか」より「ANTHROPIC_API_KEYが設定されてるか」を優先する。しかもこの優先順位、UIのどこにも派手に警告が出るわけじゃない。一度承認すると、次からは黙って従量課金ルートを使い続ける。
公式ドキュメントの認証優先順位のページを読み込んで、なぜこれが起きるのか、どう気づいて、どう直すのかを整理した。
Claude Codeの認証には優先順位がある
公式ドキュメントの「Authentication precedence」に、複数の認証情報が存在する時にClaude Codeがどれを選ぶかの順番がそのまま書いてある。上から強い順に並べるとこうなる。
- クラウドプロバイダーの認証情報（Bedrock/Vertex/Foundryの環境変数が設定されてる場合）
ANTHROPIC_AUTH_TOKEN環境変数ANTHROPIC_API_KEY環境変数apiKeyHelperスクリプトの出力CLAUDE_CODE_OAUTH_TOKEN環境変数/loginによるサブスクリプションのOAuth認証情報（Pro/Max/Team/Enterpriseユーザーのデフォルト）
見ての通り、サブスクのログインは一番下だ。つまり環境変数にANTHROPIC_API_KEYが1つ残ってるだけで、Maxプランにログイン済みでもそっちが勝つ。ドキュメントにもそのまま書いてある。「アクティブなサブスクがあってもANTHROPIC_API_KEYが環境にセットされていれば、承認後はAPIキーが優先される」と。
初回だけ「このAPIキーを使いますか」という確認プロンプトが出て、そこでYesを選ぶと、その選択が記憶される。次回以降は確認なしでAPIキー経由になる。だから「最初に何となくYesを押した記憶はあるけど、そのあと何も気にしてなかった」という状態が一番危ない。
なぜ気づかないうちにAPIキーが残るのか
フリーランスエンジニアがこれにハマる典型パターンを並べる。
別プロジェクトのdevcontainerやCI設定を試した名残
GitHub Actionsやdevcontainerのセットアップ手順を試すときにexport ANTHROPIC_API_KEY=sk-ant-xxxをローカルのシェルにも打ち込んで、そのままシェルの設定ファイル（.zshrcや.bashrc）に残してしまうケース。一度きりのつもりが恒久化する。
クライアントから支給されたAPIキーをそのまま使い続けた
特定案件でAPI経由の検証を頼まれてキーを受け取り、その場だけのつもりでexportしたのに、シェルを開き直しても環境変数がグローバルに残る設定になってて、他の案件の作業中もそのキーが有効なまま。
複数ターミナルタブ・複数プロジェクトを往復してる
シェルの初期化ファイルにAPIキーをexportで書いてる場合、開いてるターミナルすべてに影響する。案件Aのディレクトリで作業してるつもりでも、環境変数はプロジェクト単位で切り替わらない。
キーが無効化・期限切れになっていたケース
ここが一番厄介で、ドキュメントには「キーが無効化・期限切れの組織に属している場合、認証エラーの原因になる」ともある。GitHub上のissue（#50537）でも、claude.aiのトークンとAPIキーが両方設定されてる状態で「Auth error: No API key available」というエラーに悩まされた報告がある。このissueはWindows環境の個別バグとして「対応予定なし」でクローズされてるけど、根っこにあるのは同じ「両方設定されてる時にどっちが勝つか分かりにくい」という設計の話だ。
今すぐ確認する2つの方法
/statusを叩く
Claude Codeのプロンプトで/statusを実行すると、Login methodの行に今ログインしてるサブスクアカウントが表示される。それとは別にAPI keyという行が出ていたら、それが今まさに優先されて使われてる証拠になる。この行が無ければAPIキーは使われていない。
Anthropic Consoleの使用量ページを見る
platform.claude.com/usageで、実際にトークン課金が発生してるかを確認できる。Pro/Maxのサブスク利用は基本的にここには乗らない。ここに数字が積み上がっていたら、それはAPIキー経由で消費された分だ。
Claude Code内の/usageコマンドでも大まかな傾向は見れるけど、これはローカルのセッション履歴から計算した概算で、実際の請求とは別物という注意書きがある。正確な金額を確認したいなら、必ずConsoleの使用量ページを見る。
直し方は環境変数を消すだけ
原因が分かればやることはシンプル。
unset ANTHROPIC_API_KEYこれでそのターミナルセッションではサブスク認証に戻る。ただし.zshrcや.bashrcにexport ANTHROPIC_API_KEY=...と書いてある場合は、そこを消さないと新しいターミナルを開くたびに復活する。恒久的に直すならシェルの設定ファイルを開いて該当行を削除するところまでやる必要がある。
/configから「Use custom API key」のトグルを操作する方法もある。ただしこのトグルはANTHROPIC_API_KEYが環境にセットされてる間しか表示されない。環境変数自体を消せば、このトグルごと消える。
意図的に案件ごとでAPIキーを使い分けたい場合は、グローバルなexportではなくdirenvのようなツールでプロジェクトディレクトリ単位に環境変数を隔離するのがフリーランスの実務としては安全だ。案件Aのディレクトリに入った時だけAPIキーが有効になり、出れば自動で無効化される。誤って隣の案件の作業にまでAPIキーが漏れ出す事故を防げる。
意図的にAPIキーを使う方が向いてる場面
ここまでは「気づかず課金された」トラブルの話だったけど、APIキー経由の従量課金がフリーランスにとって合理的な場面もある。
会社の開発プロジェクトですでにAnthropic ConsoleのAPIキーを発行していて、個人でサブスクを別途契約せずに会社のAPI予算に乗せたい場合。この場合はむしろAPIキー優先の挙動がそのまま便利に働く。
CI/CDパイプラインでClaude Codeを非対話モード（-pフラグ）で動かす場合も、ドキュメントに「non-interactiveモードではAPIキーがある限り常に使われる」と明記されてる。ここは確認プロンプトすら出ない仕様なので、CI用のリポジトリに限定したキー管理をしておくのが安全だ。ただしAPIキー経由だとUsage Tierに応じたレート制限の対象にもなるので、並列実行数が多いCIだと今度は429に当たりやすくなる。そっちの切り分け方は別記事にまとめた。
判断の軸はシンプルで、「このディレクトリでの作業は個人のサブスクでやりたいのか、それとも特定のAPI予算に乗せたいのか」を案件ごとに意識すること。意識せずに環境変数だけが生き残ると、今回書いたような事故につながる。
FAQ
Maxプランに入ってるのにAPIキーを承認するとどうなる?
Maxプランの権利は使われず、APIキーが紐づいてるAnthropic Consoleのワークスペースにトークン単位で課金される。サブスクとAPI従量課金は完全に別会計で、サブスクの未消化分がAPI利用に自動で充当されることはない。
Claude Code on the Webでも同じことが起きる?
起きない。公式ドキュメントには「Claude Code on the Webは常にサブスクの認証情報を使い、サンドボックス環境でANTHROPIC_API_KEYやANTHROPIC_AUTH_TOKENをセットしてもサブスクの認証情報を上書きしない」とある。この事故はローカルのCLI環境特有のものだ。
apiKeyHelperを設定してる場合はどう影響する?
apiKeyHelperは優先順位でANTHROPIC_API_KEYより下だけど、サブスクのOAuth認証情報よりは上に来る。動的にキーを発行するスクリプトを設定してる場合、そのスクリプトが生きてる限りサブスクより優先されるので、同じ注意が必要になる。
意図せず従量課金になる話は、突き詰めると「環境変数の管理をどれだけ丁寧にやってるか」に尽きる。複数案件を掛け持ちするフリーランスほど、シェルの設定ファイルに何が残ってるか、たまにenv | grep ANTHROPICで棚卸しする習慣をつけておいた方がいい。
