Claude CodeをLLMゲートウェイに接続する方法 — CLI/VS Code別の設定

社内で運用しているLLMゲートウェイにClaude Codeをつなぐには、ベースURLと認証情報の2つを設定するだけです。ただしCLI・VS Code拡張・デスクトップアプリ・GitHub Actions・Agent SDKでは設定の置き場所が違い、Slack・Web・Remote Controlはそもそもゲートウェイ経由になりません。面ごとの違いを取り違えると「CLIでは動くのにVS Codeだけログイン画面に戻る」といった事象になります。

自分の環境がゲートウェイ経由になっているか確認する

管理者がmanaged settingsやMDMでゲートウェイのアドレスと認証情報をすでに配布している場合、開発者側で設定することは何もありません。まず現状を確認します。

claudeを起動してログイン画面が出るなら、ゲートウェイの認証情報は配布されていません。セッションが普通に始まったら/statusを開き、Statusタブの2行を見ます。「Anthropic base URL」の行がなければゲートウェイ宛てになっていません。「Auth token」または「API key」の行がANTHROPIC_AUTH_TOKEN・ANTHROPIC_API_KEY・apiKeyHelperのいずれかを名指ししていればゲートウェイの認証情報が有効です。「Login method」がclaude.aiアカウントを示している場合は認証情報が配布されていません。

両方の行が正しく見えるのにメッセージが失敗するなら、原因は接続情報ではなく後述のエラー別対処にあります。

ベースURLと認証情報を自分で設定する

ゲートウェイチームから受け取る情報は2つです。ゲートウェイのベースURLと、鍵・トークン文字列またはそれを取得するコマンドとしての認証情報です。どの変数に入れるかを言われていない場合は、次の表から選びます。

種類を聞いていなければANTHROPIC_AUTH_TOKENから試します。後述の検証リクエストで正しいかどうか分かります。

最初の接続確認はシェルのexportで行い、動作を確かめてからsettings fileに移すのが安全です。

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-gateway-key

シェルのexportはそのターミナルセッションと、そこから起動したプログラムにしか効きません。Dockやスタートメニューから起動したエディタには渡りません。新しいターミナルでも有効にするには~/.zshrc等のシェルプロファイルに同じ行を足します。シェルだけに設定した場合、supervisorがホストするバックグラウンドエージェントには確実に届きません。バックグラウンドエージェントを必ずゲートウェイ経由にしたいなら、settings fileでの設定が必要です。

すべての実行箇所に適用するには、settings fileのenvブロックに変数を書きます。~/.claude/settings.jsonは全プロジェクトに適用され、.claude/settings.local.jsonは1プロジェクトに適用されます。.claude/settings.local.jsonはClaude Code自身が設定を保存する際にグローバルなgitignoreへ自動で追加しますが、手でファイルを作成した場合やClaude自身に書かせた場合は、認証情報を誤ってコミットしないよう自分でgitignoreに追加してください。

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

プロジェクトの.claude/settings.json(gitignore対象外)には認証情報を書きません。全員に配布されているファイルだからです。シェルのexportとsettings fileのenvブロックで同じ変数を設定すると、settings fileの値が優先されます。

接続を検証する

Claude Codeを開く前に、シェルでexportした変数を使って1トークンのリクエストを直接送ります。ゲートウェイ側の問題と設定側の問題を切り分けられます。

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

{"id":"msg_で始まり"content":[...]を含むJSONが返ればゲートウェイに届いて認証も通っています。未知のモデル名を名指しするエラーが返った場合も、ゲートウェイが先にリクエストを認証してからモデル名を拒否したという意味なので、URLと認証情報は動いています。401は認証情報が拒否された合図です。変数を推測で選んだなら、もう一方に切り替えて再実行します。

x-api-keyヘッダーで鍵を受け取るゲートウェイなら、Authorizationヘッダーをx-api-key: $ANTHROPIC_API_KEYに置き換えます。

確認できたら同じシェルからclaudeを起動し、メッセージを送って/statusを開きます。「Anthropic base URL」の行にゲートウェイのアドレスが出ていればリクエストはそこに向いています。設定した変数を名指しする「Auth token」または「API key」の行が、保存済みのclaude.aiログインではなくゲートウェイの認証情報が有効であることを示します。

ヘッダーへの対応とログインとの競合

ANTHROPIC_AUTH_TOKENはAuthorization: Bearerヘッダーに、ANTHROPIC_API_KEYはx-api-keyヘッダーに、apiKeyHelperは両方に値を送ります。違う変数に入れた認証情報は、ゲートウェイが読まないヘッダーに届いて401になります。検証リクエストが401を返したら、もう一方の変数に切り替えます。

ゲートウェイの認証情報変数は、保存済みのclaude.aiログインより優先されます。ANTHROPIC_AUTH_TOKENは即座に優先されますが、ANTHROPIC_API_KEYは対話モードで一度だけ承認を求められます。起動時に2つの認証ソースを名指しする警告が出た場合、/statusでどちらが有効かを確認し、ゲートウェイの認証情報だけを残すなら/logoutで保存済みログインを消します。詳しい変数の挙動はANTHROPIC_BASE_URLとANTHROPIC_AUTH_TOKENとANTHROPIC_API_KEYの違いにまとめています。

VS Code拡張・デスクトップアプリ・GitHub Actions・Agent SDKでの設定

CLIは上記の環境変数とsettings fileをそのまま読みますが、他の利用形態は設定の置き場所が別です。

VS Code拡張

VS Codeのコマンドパレットで「Preferences: Open User Settings (JSON)」を実行して開くユーザー設定に、ゲートウェイの変数を書きます。

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

BedrockやVertex、Foundryなど特定のクラウドプロバイダー経由でVS Code拡張を使う場合の設定は、VS Code拡張でサードパーティプロバイダーを使う設定で個別に扱っています。

デスクトップアプリ

デスクトップアプリはHelp → Troubleshooting → Enable Developer Modeで開くDeveloper → Configure Third-Party Inferenceにゲートウェイのベースアドレスを入力します。組織側で配布済みの設定があれば、その設定が優先されてこのフォームは読み取り専用になり、開発者側の作業は不要です。ゲートウェイ設定が有効な間、環境ピッカーはSSHセッションやAnthropicホスト型のクラウド環境を提供しなくなり、Remote Controlも使えません。リモートホストでゲートウェイ経由のClaude Codeを使いたい場合は、そのホスト上でCLIを起動して環境変数を設定します。「Gateway was unreachable」と表示される場合は、起動時にベースURLへ到達できなかったという意味なので、前述のcurl検証でURLとネットワーク経路を確認します。

GitHub Actions

Claude Code GitHub ActionsはワークフローのenvブロックからANTHROPIC_BASE_URLとANTHROPIC_CUSTOM_HEADERSを読みます。認証情報はアクションのanthropic_api_key入力として渡し、アクションはそれをANTHROPIC_API_KEYとして設定するためx-api-keyヘッダーでゲートウェイに届きます。

x-api-key型のゲートウェイなら、ベースURLをenvに置き、ゲートウェイの鍵を入力として渡すだけです。

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
 
steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

bearer token型のゲートウェイでは、同じシークレットを2箇所に渡します。アクションは起動前にanthropic_api_key・CLAUDE_CODE_OAUTH_TOKEN・workload identity federationのいずれかを要求するため、anthropic_api_key入力はその起動チェックを満たすためだけに存在し、値自体は使われません。実際にAuthorizationヘッダーへ鍵を入れているのはenvブロックのANTHROPIC_AUTH_TOKENです。

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}
 
steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Agent SDK

Agent SDKにゲートウェイ専用のオプションはありません。SDKが生成するClaude Codeプロセスに環境変数を渡すだけです。TypeScriptはoptions.envを設定すると環境全体を置き換えるため、process.envを展開してから上書きします。PythonのClaudeAgentOptions(env=...)は継承した環境の上にマージされるので、親プロセスで設定済みのゲートウェイ変数はそのまま引き継がれます。

const result = query({
  prompt: "...",
  options: {
    env: {
      ...process.env,
      ANTHROPIC_BASE_URL: "https://llm-gateway.example.com",
      ANTHROPIC_AUTH_TOKEN: process.env.GATEWAY_KEY,
    },
  },
})

options = ClaudeAgentOptions(
    env={
        "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
        "ANTHROPIC_AUTH_TOKEN": os.environ["GATEWAY_KEY"],
    }
)

Slack・Web・Remote Controlはゲートウェイ経由にならない

Claude Code in SlackとClaude Code on the webはAnthropicがホストする製品で、常にAnthropicのAPIを直接使います。クラウドセッションの環境設定でゲートウェイ変数を入れても適用されません。トラフィックを必ずゲートウェイに通す必要があるなら、これらの利用形態は該当ユーザーに有効化しません。

Remote Controlと音声入力はclaude.aiのアカウントに依存する機能で、ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN・apiKeyHelperのいずれかが有効な間は使えません。Remote Controlはv2.1.196以降、ANTHROPIC_BASE_URLがAnthropic以外のホストを指しているだけでも無効になります(それ以前のバージョンではベースURLだけでは無効化されませんでした)。どちらを復元するにもclaude.aiにログインし、該当する変数を外します。claude doctorのRemote Control欄が現在ブロックしている原因を教えてくれます。詳しい原因の切り分けはRemote Controlが使えない「requires the Anthropic API」の意味にまとめています。

追加設定が必要になるケース

ここから先は、管理者に指示されたときかネットワーク制限があるときだけ設定します。

• カスタムヘッダー: テナントIDやルーティングキーを毎リクエストに付けるゲートウェイではANTHROPIC_CUSTOM_HEADERSにName: Valueの形式で1行ずつ書きます。書式の詳細はANTHROPIC_CUSTOM_HEADERSとはを参照してください
• モデルピッカーへのゲートウェイモデル追加: CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1を設定すると、起動時にゲートウェイへモデル一覧を問い合わせ/modelピッカーに追加します。組み込みモデルだけで足りるなら不要です
• apiKeyHelperでの認証情報ローテーション: 認証情報が期限切れになる、またはvaultから取得する場合は、鍵だけを標準出力に印字するコマンドをapiKeyHelperに指定します。v2.1.227以降、鍵と一緒にバナーやログ行を印字するとヘルパー自体が失敗扱いになる点に注意します。既定では5分間キャッシュされ、401が返るたびに再実行されます
• ゲートウェイ経路以外の通信を止める: バージョンチェックやテレメトリなど非必須の通信もゲートウェイの外に出ます。ゲートウェイ以外へのegressを許可していないネットワークではCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1を設定します。自動更新も止まる点はDISABLE_NONESSENTIAL_TRAFFICとはで確認してください
• クラウドプロバイダー向けの専用変数経由でゲートウェイに接続する: ゲートウェイチームがAmazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundry・Claude Platform on AWSのいずれかを名指しした場合は、ANTHROPIC_BASE_URLの代わりにそのプロバイダー専用のベースURL変数を使います。個別の設定手順はClaude Code Bedrockセットアップにまとめています

よくあるゲートウェイ接続エラーと対処

Extra inputs are not permittedのようにアップストリームがフィールドを拒否するケースは、ゲートウェイがAnthropic形式のフィールドを転送しきれていないことが原因です。個別の対処はExtra inputs are not permitted — Claude Codeの原因と対処にまとめています。

よくある質問

シェルのexportとsettings fileの両方に同じ変数を設定したらどちらが勝ちますか

settings fileのenvブロックの値が優先されます。/statusで実際にどちらのソースが使われているかを確認できます。

ゲートウェイ経由でもclaude.aiのサブスクリプション枠は使われますか

ゲートウェイの認証情報変数(またはapiKeyHelper)が有効な間はサブスクリプションのログインは使われず、そのセッションの利用上限も適用されません。ANTHROPIC_BASE_URLだけを設定し認証情報を設定しなかった場合は、保存済みのclaude.aiログインがそのまま有効なままです。ゲートウェイとサブスクリプションの関係はClaude CodeのLLMゲートウェイ互換性で詳しく扱っています。

WSL環境でも同じ設定で反映されますか

wslInheritsWindowsSettingsがtrueになっている場合のみ、Windows側のmanaged settingsをWSLが引き継ぎます。個人のシェルexportやsettings fileはOSごとに別です。

apiKeyHelperのキャッシュ時間は変えられますか

CLAUDE_CODE_API_KEY_HELPER_TTL_MSにミリ秒で指定します。既定は5分(300000)です。

まとめ

自分で設定する場合は、ゲートウェイチームからベースURLと認証情報の種類を聞き、シェルのexportで検証してからsettings fileへ移すのが確実な順序です。CLI以外の面ではVS Code拡張のユーザー設定・デスクトップアプリのサードパーティ推論設定・GitHub Actionsのenvブロック・Agent SDKのenvオプションと、それぞれ別の場所に設定が必要になります。Slack・Web・Remote Controlはゲートウェイの対象外なので、これらを使う開発者がいる場合は事前に伝えておくと混乱を防げます。組織としてゲートウェイをこれから配る側は、Claude CodeのLLMゲートウェイをロールアウトする手順を参照してください。