Claude Code API 設定：キー、settings.json、モデル、ゲートウェイの確認手順

Claude CodeにAPIキーを設定する基本形は、ANTHROPIC_API_KEYを渡して同じターミナルからclaudeを起動し、対話モードでキーの使用を承認することです。ただし、会社のキーが社内ゲートウェイ用なら接続先のURLも必要で、Bearer認証なら変数はANTHROPIC_AUTH_TOKENになります。既に会社が設定を配布している場合は、自分でキーを追加する前に/statusを確認してください。

設定が済んだら、認証元・接続先・モデルを確認してから短いメッセージを送ります。/statusに期待する値が出たことだけでは、モデルの利用権限や通信の成功までは確認できません。以下は2026年10月6日に確認した公式ドキュメントにもとづく手順です。キーを使うリクエストには利用先の料金が発生し得るため、会社で承認された接続先とモデルを使います。

先に接続方法を選ぶ

会社から渡された文字列が「APIキー」と呼ばれていても、Anthropicに直接送るキーとは限りません。配布元に、接続先、認証ヘッダー、使えるモデル名を確認すると、設定する変数が決まります。

これらは公式の認証方法です。APIキーは必須ではありません。また、Consoleへのログイン、個別のAPIキー、claude.aiのサブスクリプションは同じ認証情報ではありません。

会社のAPIキーをCLIに設定する

Anthropicに直接接続する最短手順

Claude Codeをインストール済みで、会社からAnthropic API用のキーを受け取っている場合の例です。次のコードはBash用です。キーをコマンドそのものに書かず、入力時にも画面へ表示しません。

read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
printf '\n'
export ANTHROPIC_API_KEY
claude

起動後にAPIキーの使用確認が出たら、今回そのキーを使う意図があることを確認して承認します。次にClaude Code内で/statusを開き、API keyの行でANTHROPIC_API_KEYが有効になっているか確認します。ほかの認証方式や社内ゲートウェイが表示された場合は、下の「認証優先度を確認する」に進んでください。

キーの承認・拒否は記憶されます。以前拒否したキーを使いたいときは、ターミナルの/configにあるUse custom API keyを確認します。この項目はANTHROPIC_API_KEYが設定されているときに表示されます。ほかの認証方式が優先される場合を除き、非対話モードの-pでは、キーが存在すれば対話的な承認を挟まずに使用します。 対話モードで拒否したから自動化にも使われない、とは判断できません。認証の優先順位と承認動作

このexportは、そのBashとそこから起動したプログラムに適用されます。新しいターミナルやDockから開いたエディタには自動で引き継がれません。継続して使う設定は、次節の保存先を選んでから追加します。既存の保存済みログインを先に削除する必要はありません。

Consoleのログインを使う場合

会社がキーではなくConsoleアカウントへの招待を用意した場合は、/loginからConsoleの認証を選びます。Claude Code v2.1.242以降には、APIキーを新規作成せずConsoleにログインする方式があります。これはAnthropic profileを使う認証で、従来のConsoleログインでAPIキーを作成する方式とは区別します。

キーなしのConsoleログインを選ぶ場合は、ANTHROPIC_API_KEYが残っていないことを確認してください。このログインは保存済みのclaude.aiログインをサインアウトさせるため、個人用ログインを残したい人は切り替えの影響も確認します。組織ポリシーによって選べる方式が変わるので、会社の手順を優先してください。Console認証の現行仕様

会社が既に名前付きprofileを設定しているなら、その名前をANTHROPIC_PROFILEで指定できます。/statusのProfile行で選択元を確認し、OrganizationとEmailで意図したアカウントかを確認します。profileの認証ファイルや保存済みトークンを、APIキーとしてコピーする手順ではありません。

settings.json の範囲を分ける

個人の全プロジェクトに使う設定は~/.claude/settings.json、そのプロジェクトだけの個人設定は.claude/settings.local.json、チームに共有する設定は.claude/settings.jsonです。Windowsのユーザー設定は%USERPROFILE%\.claude\settings.jsonに相当します。

ユーザー設定かローカル設定に、APIキーを置く場合のJSONは次の形です。REPLACE_WITH_YOUR_API_KEYは説明用の仮値で、実際には使えません。既存ファイルを丸ごと置き換えず、必要な項目を追加してください。

{
  "env": {
    "ANTHROPIC_API_KEY": "REPLACE_WITH_YOUR_API_KEY"
  }
}

設定ファイルはコメントや末尾のカンマを許さない厳密なJSONです。$ANTHROPIC_API_KEYと書けばシェルの値を参照できる、とも考えないでください。会社がキーの平文保存を認めていない場合は、管理者が指定した環境変数の配布やapiKeyHelperを使います。設定ファイルの仕様、認証情報の保存先

Claude Codeがローカル設定を書き込む場合はGitの除外設定も追加しますが、手作業で作ったファイルは自分で除外が必要です。除外しただけで暗号化や漏えい防止が完了するわけではありません。

また、Gitリポジトリのローカル設定は、通常はリポジトリのルート、worktreeではメインcheckoutのルートを使います。Windowsやリポジトリの所有者などによる例外もあります。サブディレクトリやworktreeごとに別ファイルを置けば必ず独立する、とは限りません。ローカル設定の読み込み位置

設定と環境変数の優先順位

同じ設定キーを複数の場所で指定した場合、基本の順序は次のとおりです。

1. managed settings
2. 起動時のコマンドライン指定
3. プロジェクトのローカル設定
4. 共有プロジェクト設定
5. ユーザー設定

環境変数は、この一覧の上に一律で追加される第6の設定階層ではありません。対応する変数と設定キーごとに優先関係が決まります。たとえばANTHROPIC_MODELは設定ファイルのmodelより優先しますが、ANTHROPIC_DEFAULT_MODELはファイルにmodelがない場合の既定値です。公式の設定優先順位

同じ環境変数をシェルのexportと設定ファイルのenvの両方に書いている場合は、設定ファイル側の値が適用されます。シェルでURLを直したのに古いゲートウェイへ接続するなら、読み込まれた設定ファイルのenvにも同じ変数がないか確認します。環境変数の設定

permissions.allowなどのリストは通常マージされるため、低い階層のファイルが丸ごと無効になるわけではありません。モデル選択リストなどには固有の規則があります。認証の問題を直すために権限全体を広げる必要はありません。

認証優先度を確認する

APIキーが設定されているのに使われない場合は、より優先される認証か、対話モードの承認状態を確認します。以下は通常のCLIで複数の認証情報がある場合の順序です。

ここには例外があります。SSOでログイン済みのClaude apps gatewayは、この一覧の外でクラウドプロバイダーよりも優先します。 そのセッションではAPIキー、Bearerトークン、helperやprofileを追加しても、それらは認証に使われません。会社がその方式を採用している場合は、通常のゲートウェイ用変数へ置き換えようとせず、会社のSSO手順を確認します。認証優先順位とgatewayの例外

forceLoginMethod、forceLoginOrgUUID、allowedProvidersなどの組織設定で起動や接続先が制限される場合もあります。ローカルのexportでは解除できません。ポリシーによる拒否なら管理者に相談し、キーや保存済みログインの削除を繰り返さないでください。

ANTHROPIC_AUTH_TOKEN と apiKeyHelper の使い分け

ANTHROPIC_AUTH_TOKENはBearer認証で送る値です。AnthropicのAPIキーを直接使う場合のANTHROPIC_API_KEYとは、送信ヘッダーが異なります。ゲートウェイの仕様がx-api-keyなら、トークンと呼ばれている文字列でもANTHROPIC_API_KEY側へ設定する必要があります。

キーが短時間で失効する、保管サービスから取得するなどの場合は、会社が用意したapiKeyHelperを参照します。たとえば管理者から次の実行ファイルを配布された場合の設定は、この形です。パスは例なので、実際に配布されたものへ置き換えます。

{
  "apiKeyHelper": "/absolute/path/to/company-credential-helper"
}

helperはシステムのシェルを通して実行され、標準出力には認証情報だけを返します。v2.1.227以降は、挨拶やログが混ざると失敗します。値は既定で5分間キャッシュされ、helperの認証情報はAuthorizationとx-api-keyの両方に送られます。上位のANTHROPIC_AUTH_TOKENや使用が承認されたANTHROPIC_API_KEYが残っていれば、helperが選ばれない点にも注意してください。helperの設定と動作

API キーとゲートウェイ

ゲートウェイに接続するには、指定されたbase URLと認証方式の両方を設定します。次はBearer方式の設定例です。ユーザー設定またはプロジェクトのローカル設定に追加し、URLと仮トークンを会社から指定された値に置き換えます。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_YOUR_GATEWAY_TOKEN"
  }
}

x-api-key方式なら、ANTHROPIC_AUTH_TOKENの項目をANTHROPIC_API_KEYに変更します。ヘッダーが違うと正しい文字列でも認証に失敗するので、両方へ無差別に追加せず、配布元の仕様に合わせてください。ゲートウェイへの接続手順

base URLだけでAPI課金へ切り替わるわけではない

ANTHROPIC_BASE_URLはリクエストの接続先を変えます。認証情報は別に選択されます。ゲートウェイの認証情報が有効なら、保存済みのclaude.aiログインは残っていても、そのリクエストには使われず、ゲートウェイが上流へ渡す認証情報の所有者に従量料金が発生します。

一方、base URLだけを指定してゲートウェイ用の認証情報を渡していない場合、保存済みのclaude.aiログインが使われることがあります。この場合はサブスクリプションの利用条件が残り、ゲートウェイ側にはOAuthの対応ヘッダーを転送する能力が必要です。URLだけでは認証や課金先を確定できません。サブスクリプションとゲートウェイ

「API互換」の確認ポイント

Claude Code用には、対応するAPI形式が必要です。OpenAI形式の/v1/chat/completionsが動くという説明だけでは、Claude Codeに接続できるとは判断できません。Anthropic形式なら、/v1/messages、ストリーミング、必要なanthropic-version・anthropic-betaヘッダーとリクエスト項目を扱えるか確認します。count_tokensは任意です。

systemなどのロールを拒否する400が出る場合は、指示の優先度を保ったロールエラーの修正手順で、送信されたJSONと接続先の仕様を確認してください。

BedrockやGoogle Cloudのネイティブ形式を扱うゲートウェイなら、選択変数やエンドポイントもその形式に合わせます。Claude Codeの機能追加に合わせて必要なヘッダー等を転送できるかはゲートウェイ側の実装に依存します。Anthropicは第三者ゲートウェイを監査・保証しているわけではありません。互換性の仕様、第三者ゲートウェイの範囲

モデルとクラウド接続を設定する

モデルの優先順位と保存先

接続先URLを変更してもモデル名は変わりません。モデルは、その接続先で提供され、会社のアカウントに利用が認められた名前を指定します。通常の選択順は、現在のセッションの/model、起動時の--model、ANTHROPIC_MODEL、設定ファイルのmodel、ANTHROPIC_DEFAULT_MODELです。たとえば、その接続先でsonnetが利用可能なら、次のように今回の起動に指定できます。固定IDを指定したい場合は、sonnetを管理者が確認した実際のモデル名へ置き換えます。

claude --model sonnet

毎回の既定値として保存するなら、適切な範囲の設定ファイルに次の項目を追加します。既存のenvがある場合は、同じJSONオブジェクト内にmodelを追加します。

{
  "model": "sonnet"
}

これは現行版の動作です。v2.1.144〜v2.1.152では/modelが当該セッションのみを変更する仕様だったため、古い説明と現在の保存動作を混同しないでください。-pでの/model指定は当該セッションだけに適用され、既定値を保存しません。公式のモデル選択・保存仕様

会社のavailableModelsは選択できるモデルを制限します。managed settingsのmodelは起動時の既定値なので、許可された範囲で/model変更はできますが、次回起動には組織やプロジェクトの設定が再適用されます。再開するセッションにはモデルの復元規則もあるので、設定を変えた直後の確認には新規セッションを使うと切り分けやすくなります。

モデル名には別名と固定IDがあります。Anthropic APIのモデルID、BedrockのモデルIDやinference profile ARN、Google Cloudのモデル名、Foundryのdeployment名は同じ文字列ではありません。sonnetなどの別名の対応先も接続先や版で変わります。固定したい場合は、使う環境の実際のIDを指定してください。モデル名の指定方法

Bedrock・Google Cloud・Foundryを使う場合

次の項目は、利用するクラウドが既に準備され、認証とモデル権限がある場合の設定の目安です。Anthropic APIキーとbase URLを置き換えるだけの手順ではありません。

各設定はBedrock、Google Cloud、Foundryの公式手順で確認できます。Google Cloudの製品名が変わっても、上記のVERTEX変数名はそのままです。

Foundryの認証はANTHROPIC_FOUNDRY_AUTH_TOKEN、ANTHROPIC_FOUNDRY_API_KEY、Azure SDKの既定認証の順です。起動時にモデルの利用可否を検証しないため、起動できても最初のリクエストでdeployment名や権限の問題が出る場合があります。リージョンやモデルの提供状況は利用するアカウントで確認してください。

VS CodeとDesktopでは設定場所が違う

VS Code拡張のログイン確認にも変数を渡す

ターミナルで動くのにVS Code拡張がログインを求める場合、拡張側の起動前の認証確認に値が届いていない可能性があります。VS CodeでPreferences: Open User Settings (JSON)を開き、VS Code自身のユーザー設定へ次の形で追加します。これはClaude Codeのsettings.jsonとは別のファイルです。

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://llm-gateway.example.com"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "REPLACE_WITH_YOUR_GATEWAY_TOKEN"
    }
  ]
}

APIキー方式なら認証用のnameをANTHROPIC_API_KEYへ変更します。Anthropicへ直接接続する場合はゲートウェイURLの項目を入れません。機密情報の保存や同期は会社のルールに合わせてください。

~/.claude/settings.jsonのenvは起動されるClaude Codeプロセスには届いても、拡張自身のログイン確認には届きません。この違いを踏まえて、拡張側で設定し、新しいセッションで認証元と接続先を確認します。/configのターミナルメニューをVS Codeチャットパネルで開く手順ではありません。VS Codeでの設定

Desktopのゲートウェイは専用設定を使う

Desktopアプリは、ゲートウェイへの接続にANTHROPIC_BASE_URLやClaude Codeのsettings.jsonを使いません。組織が配布した、またはアプリ内で指定したThird-Party Inference設定を使います。

管理者配布の設定がない端末では、公式手順はHelp → Troubleshooting → Enable Developer Modeから再起動し、Developer → Configure Third-Party Inferenceを開く流れです。会社から配布された設定が優先される場合、このフォームは編集できません。ゲートウェイ設定時のDesktopセッションはローカル実行で、SSH、Anthropicのクラウド環境、Remote Controlは使えません。Desktopのゲートウェイ設定

通常のクラウドセッションでも、CLI用のAPIキー変数でサブスクリプション認証を上書きすることはできません。CLIで成功した設定を、すべてのClaudeアプリへ同じように適用できるとは考えないでください。

確認手順

まず、新しいCLIセッションで/statusを確認します。APIキーなら有効なキーの変数名、profileならProfile行、ゲートウェイなら接続先と認証情報の両方を見ます。会社のSSO gatewayやクラウド経由なら、その経路が選ばれていることを確認します。

次に/modelで実際に選ばれたモデルを確認します。見るだけなら選択を確定せず閉じ、当該セッションだけ変更したい場合はsを使います。

最後に、使用が承認されている環境で、ファイル編集を求めない短いメッセージを送ります。たとえば「接続確認です。OKとだけ返してください」です。正常な応答が返ることが、認証とモデルリクエストが通る確認になります。ただし、ツール実行や長い会話で使うすべての機能まで確認したことにはなりません。

/statusの設定元と/configのメニューは、JSONの全項目と採用値を表示する機能ではありません。設定が拒否された場合はclaude doctorで項目ごとのエラーを確認できます。多くの設定は変更時に再読み込みされますが、モデルなど起動時に読む項目は、新規起動か/modelで確認します。設定の確認とエラー

設定したのに動かないとき

unknown modelというエラーだけで、正常な推論や課金先まで確認したことにはなりません。ゲートウェイごとに検証の順序が違うため、HTTPコードだけで成功と決めないでください。認証・接続先・モデルを確認しても403、503、529が残る場合は、エラー原文と接続先を手がかりにClaude Codeの403・503・529の発生元と直し方へ進みます。

よくある質問

Claude CodeにAPIキーは必須ですか？

必須ではありません。利用資格のあるclaude.aiログイン、Consoleの認証、対応クラウド、会社のSSO gatewayも選択肢です。会社からAPIキーを配布された場合は、そのキーの接続先と認証方式を確認して設定します。公式の認証方法

ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENを両方設定しますか？

通常は、使う接続先が指定した片方を設定します。ANTHROPIC_AUTH_TOKENはBearerヘッダー、ANTHROPIC_API_KEYはx-api-keyで送信されます。両方ある場合は通常Bearer側が優先されるので、APIキーを更新しても認証が変わらないことがあります。クラウド選択やログイン済みのClaude apps gatewayなどの例外もあります。認証優先順位

apiKeyHelperを設定したのに使われないのはなぜですか？

通常のCLIではANTHROPIC_AUTH_TOKENと使用が承認されたANTHROPIC_API_KEYがhelperより優先されます。まず/statusで実際の認証元を確認してください。helperが選ばれているのに失敗する場合は、配布されたコマンドの終了状態、空の出力、認証情報以外の標準出力を管理者と確認します。秘密値そのものをログに貼る必要はありません。認証情報とhelper

/modelで変更したモデルは次回も使われますか？

現行の対話モードでは、Enterや/model <名前>で選ぶとユーザー設定に保存します。このセッションだけにしたい場合はpickerのsを使います。ただし、プロジェクトや組織の起動時設定、モデルの許可範囲は次回にも適用されます。--modelとANTHROPIC_MODELは、その起動への指定です。モデルの保存仕様

settings.jsonがない場合はどこに作りますか？

インストールしただけでは設定ファイルは作られません。個人全体なら~/.claude/settings.json、特定プロジェクトなら.claude/settings.local.jsonを選びます。手作業でローカルファイルを作る場合は、バージョン管理から除外してください。共有用の.claude/settings.jsonにキーを入れず、Claude Code自身が管理するログイン状態のファイルを設定ファイルとして編集しないでください。設定ファイルの作成