Claude CodeのAPIキー設定:発行、確認、保存場所、課金の注意

Claude CodeにAnthropicのAPIキーを渡す方法は3つあります。環境変数 ANTHROPIC_API_KEY、apiKeyHelper のスクリプト、/login によるConsoleへのサインインです。Macの場合、/login で作ったキーはmacOSのキーチェーンに入りますが、残りの2つではキーは置いた場所にそのまま残り、それが平文のファイルであることも珍しくありません。Claudeのプランでログインした状態で環境変数を設定し、その使用を承認すると、課金先はサブスクリプションから、キーが属するConsoleの組織に切り替わります。

最初にお断りしておくと、私たちはfideliusというMacアプリを開発しています。APIキーをシェルやプロジェクトのファイルに置かずに済ませるためのアプリで、iCloudキーチェーンの上に作られており、独自の保管庫や同期の仕組みは持っていません。記事の最後で紹介しますが、そこまでの内容はfideliusがなくてもそのまま使えます。

APIキーを発行する

APIキーは、platform.claude.comのClaude ConsoleにあるAPI keysの画面で発行します。料金はトークン単位で、キーが属するConsoleの組織に請求されます。Claude Pro、Max、Ultra、Team、Enterpriseの各プランとは請求が別です。いずれかのプランを契約しているなら、キーは不要かもしれません。claude.aiのアカウントで /login すれば、サブスクリプションの範囲内で使えます。

キーを渡す方法

方法キーの保存場所向いている場面
Consoleアカウントで /loginmacOSのキーチェーン。SSH接続中などでキーチェーンがロックされていると、サインインに失敗します自分のMac
export ANTHROPIC_API_KEY=...シェルと、exportを書いたファイル(多くは ~/.zshrc)スクリプトや claude -p
設定ファイルの envsettings.json や settings.local.json に平文のままキーの置き場所としてはまず不向き
apiKeyHelperヘルパーが読み出す場所(キーチェーンなど)どのファイルにもキーを書きたくないとき

v2.1.242以降は、/login でConsoleにサインインするときに、キーを作るかどうかを聞かれます。キーを作らない方法には「recommended」(推奨)、キーを作る方法には「legacy」(従来方式)と表示され、キーを作らない場合はOAuthのログインとして保存されます。サブスクリプションのログインもキーチェーンに保存されますが、キーチェーンがロックされているときに保存先が ~/.claude/.credentials.json(パーミッション0600)へ切り替わるのは、サブスクリプションのログインだけです。認証方法の一覧はClaude Codeの認証ドキュメントにまとまっています。

どれが優先されるか

認証情報が複数設定されている場合、Claude Codeは次の順に調べて、最初に見つかったものを使います。

  1. クラウドプロバイダーの認証情報(CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY のいずれかを設定している場合)
  2. ANTHROPIC_AUTH_TOKEN(ゲートウェイやプロキシ用)
  3. ANTHROPIC_API_KEY
  4. apiKeyHelper の出力
  5. CLAUDE_CODE_OAUTH_TOKEN(claude setup-token で作るもの)
  6. Anthropicのプロファイルとフェデレーションの認証情報
  7. /login でのサブスクリプションのログイン

思わぬ課金の原因になりやすいのが3番目です。対話モードではキーを使うかどうかを一度だけ聞かれ、その答えが記憶されます。claude -p では確認なしでキーが使われます。別のプロジェクト用に ~/.zshrc に書いたキーが残っていると、Claude Codeの利用分がいつの間にかAPIの従量課金になっていることがあります。状態を確認して元に戻すには、まずシェルの設定ファイルから export ANTHROPIC_API_KEY の行を削除します。消しておかないと、新しいウィンドウを開いたときにまた設定されてしまいます。そのうえで、次を実行します。

$ unset ANTHROPIC_API_KEY$ claude# Claude Codeの中で /status を実行すると、使っている認証情報を確認できます

記憶された答えを変えるには、/config の「Use custom API key」を切り替えます。この項目は、環境変数が設定されているときにだけ表示されます。

設定ファイルにはキーが平文で残る

Claude Codeは、ユーザー設定の ~/.claude/settings.json、コミットする前提のプロジェクト設定 .claude/settings.json、コミットしない .claude/settings.local.json の3か所にある env ブロックを読み込みます。ここに書いたキーは平文のままです。しかも設定リファレンスにあるとおり、env の値はClaude Codeが起動するすべてのサブプロセスに渡ります。ローカルの設定ファイルがGitHubに大量に流出している件は、「Claude Codeはsettings.local.jsonにパスワードを保存するのか」(英語)で取り上げました。

apiKeyHelperでキーチェーンからキーを渡す

apiKeyHelper には、キーを出力するシェルコマンドを指定します。キーが必要になるとClaude Codeがそのコマンドを実行するので、キーをどのファイルにも書かずに済みます。まず、macOSの security コマンドでキーを一度保存しておきます。-w を最後に付けると値の入力を求められるので、キーがシェルの履歴に残りません。

$ security add-generic-password -a "$USER" -s anthropic-api-key -w

次に、~/.claude/settings.json でこのコマンドをClaude Codeに指定します。

{
  "apiKeyHelper": "security find-generic-password -s anthropic-api-key -w"
}

ANTHROPIC_API_KEY が設定されていないことも確認してください。設定されていると、ヘルパーよりそちらが優先されます。逆に、ヘルパーはサブスクリプションのログインより優先されるので、ヘルパーを設定しているあいだは、そのキーを発行したConsoleの組織に従量課金されます。ヘルパーが初めて動くときに、security がこの項目を読み出すのを許可するかどうか、macOSから確認されることがあります。毎回聞かれないようにするには「常に許可」を選びます。

Claude Codeが実行するコマンドにもキーが見える

シェルでexportした変数は claude に引き継がれ、さらにClaude Codeが代わりに実行するすべてのコマンドにも渡ります。セッション中に一度でも env や printenv が実行されれば、キーが会話に表示されてしまいます。ここで役立つ設定が1つあります。環境変数のリファレンスによると、CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1 を設定すれば、Claude Codeが起動するBashコマンド、フック、stdioのMCPサーバーの環境から、名前や値が認証情報らしく見える変数が取り除かれます。ただし、GitHubのトークンとプロキシの設定は残ります。これは防御策の1つにすぎず、これだけで防げるわけではありません。そもそもClaude Codeの環境にキーが入らないほうが安全です。

$ export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1

fideliusでできること

fideliusはAPIキーをプロジェクトごとにキーチェーンへ保存します。~/.zshrc にも .envファイルにもキーを書かなくてよいので、Claude Codeはキーを持たない状態で起動します。キーが必要なコマンドは accio myapp npm test のように accio 経由で実行する、という指示もワンクリックでClaude Codeに追加できます。キーはそのコマンドにだけ渡され、Claude Codeはその指示に従う限り、キーの値ではなく変数名で作業します。また、Claude Codeから実行されたことを検出すると、accio はコマンドの出力に出てきたキーの値も伏せます。ただし確実に伏せられるわけではなく、うっかり表示されたときのための備えです。