Claude Code APIキー — 入手先、設定場所、誤った変数で何も表示されず失敗する理由

Claude Codeは2通りの方法で認証でき、どちらが必要かですべてが決まります。claude.aiのサブスクリプションログインはProまたはMaxプラン内の利用をカバーします。APIキーはプラン上限なしでトークン単位に課金されます。このガイドでは、キーの取得場所、正確な設定場所、2つの認証情報変数、誤った方を選ぶとサイレントに失敗する理由、動作後に料金を抑える方法を説明します。

そもそもキーは必要ですか？

開始前に知っておくべきこと：キーを設定するとサブスクリプションが一時停止されます。認証情報変数が有効な間、Claude Codeは保存済みのclaude.aiログインではなくキーを使い、プランの上限は適用されず、利用料金はキーの所有者に請求されます。変数の設定を解除すると、Claude Codeはサブスクリプションに戻ります。

オプション1 — Anthropicの公式キー

1. console.anthropic.com（claude.aiとは別のアカウント）にサインインします。
2. Billingでクレジットを追加します。APIは前払いで、サブスクリプションとは別です。ProプランでAPI料金が支払われることはありません。
3. API Keysでキーを作成します。キーはsk-ant-で始まり、一度だけ表示されます。

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

そのスニペットの2番目の手順に注意してください。ANTHROPIC_API_KEYはx-api-keyヘッダーで送信され、Claude Codeが使用する前に一度だけ対話的な承認が必要です。そのプロンプトを一度でも拒否すると、その後はプロンプトがまったく表示されずにキーが無視されます。これは変数が読み取られていない場合とまったく同じに見えます。/config → Use custom API keyで再有効化してください。

オプション2 — トークン単価の安いキー

Claude CodeはANTHROPIC_BASE_URLをネイティブに読み取るため、Anthropic Messages APIを提供する任意のエンドポイントで動作します。プラグイン、プロキシ、パッチ済みバイナリは不要です。これはゲートウェイでサポートされる方法であり、同じClaudeモデルをより安い料金で実行できます。

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URLはオリジンのみです。/v1/messagesはClaude Code自身が追加します。モデル指定はそのままにしてください。Claude Codeの組み込みデフォルトとopusエイリアスは、どちらも最新のOpusに解決されます。Kunavoがそのモデルをまだ提供していない場合、最初のリクエストは404を返します。opus行はClaude Opus 5.5に固定します。これはClaude Code v2.1.280以降が必要です（古いバージョンではclaude updateを実行してください）。sonnetエイリアスはSonnet 5.5を要求しますが、Kunavoは提供していないため、ANTHROPIC_DEFAULT_SONNET_MODEL、/model sonnet、opusplanの実行フェーズ、sonnetに設定されたサブエージェントはすべて404を返します。登録して$10をチャージした後、ダッシュボードでsk-kn-キーを作成してください。月額料金はなく、残高も失効しません。

メインラインモデルのリスト価格より約30%低くなります。完全な料金はClaude API料金ガイドにあり、Claude Codeの料金ではこの経路とProおよびMaxプラン料金を比較しています。タスクごとのモデルルーティングやゲートウェイの背後で変わる内容を含む完全な設定は、Claude Codeルーターガイドにあります。CLIがまだインストールされていない場合は、Claude Codeのインストールから始めてください。

キーを実際に設定する場所

2つの変数、2つの異なるHTTPヘッダーです。サーバーが読み取らないヘッダーにキーを入れると、401で失敗します。

キーの種類を知らされていない場合は、承認手順が不要なANTHROPIC_AUTH_TOKENから始めてください。Kunavoではどちらの変数でもClaude Codeがモデル一覧を検出できます。/v1/modelsはどちらのヘッダーからもキーを読み取るためです。

シェルのexportと設定ファイル

シェルのexportは、そのターミナルと子プロセスにのみ適用されます。Dockから起動したエディターには見えず、バックグラウンドエージェントにも見えません。永続的に設定する場合は、~/.claude/settings.jsonのenvブロックを使用してください。同じキーがClaude Codeの実行場所すべてに適用されます。キーをプロジェクトの.claude/settings.jsonに入れないでください。このファイルはコミットされ、リポジトリをクローンする全員と共有されます。

/statusを実行して、どの認証情報が有効か確認します。変数名を示すAuth tokenまたはAPI key行があればキーは有効です。claude.aiアカウントを示すLogin method行があれば、キーは有効ではありません。

ファイルを編集せずにキーをローテーションする

認証情報が定期的に期限切れになる場合やボールトから取得する場合は、apiKeyHelperを現在のキーを出力するコマンドに指定します。

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

設定ファイルでは"apiKeyHelper": "~/bin/get-key.sh"として参照します。Claude Codeは出力を5分間キャッシュし、401時に再実行します。CLAUDE_CODE_API_KEY_HELPER_TTL_MSで調整できます。値は両方のヘッダーで送信されるため、どちらの方式でも動作します。

料金を予測可能に保つ

エージェント型コーディングはトークンを大量に消費します。各ステップでシステムプロンプト、タスク履歴、新しいファイルコンテキストが再送信されるためです。何より重要な4つの点は次のとおりです。

1. Haikuの行を残してください。ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5がないと、Claude CodeのhaikuエイリアスはKunavoが提供していないモデルID（v2.1.293以降はHaiku 5.5）を要求し、/model haikuとhaikuに設定したサブエージェントは404を返します。この行により、Claude Codeが自動で生成する要約やタイトルもメインモデルから別のモデルに切り替わります。作業が複数のタスクに分岐するほど節約効果も大きくなります。料金はClaude Codeのワークフローの費用をご覧ください。
2. 同じ2つの変数でAgent SDKもルーティングする。 Agent SDK自体にはベースURLのオプションがありません。このCLIを起動して環境をそのまま渡すため、Agent SDKプログラムも上記とまったく同じ設定でルーティングされます。
3. 1つのタスクを永遠に延長せず、新しいタスクを開始する。各ステップでコンテキストが再送信されるため、長いセッションは二次関数的に高くなります。メインモデルにどのティアを設定するかは、トークン単価ではなく完了タスク単価としてOpusとSonnetとHaikuの比較で検討しています。
4. プロンプトキャッシュを活用する。キャッシュ済み入力は入力料金の10%で課金され、ネイティブMessages API経路はcache_controlを未翻訳のまま渡します（詳細）。
5. ダッシュボードでエディターに支出上限付きの専用キーを割り当てるようにし、1週間後に利用状況を確認してください。キーごとの上限により、暴走したループの支出にも上限を設けられます。

トラブルシューティング

よくある質問