Claude CodeのLLMゲートウェイをロールアウトする手順 — 管理者向け5ステップ

社内で運用しているLLMゲートウェイをClaude Code向けに展開する作業は、確認のチェックポイント付きで5ステップに分けられます。順番を飛ばすと「開発者の鍵は動くのに配布後だけ失敗する」ような切り分けにくい不具合が起きやすいため、各ステップの完了条件を先に決めてから進めます。

ロールアウト前に用意するもの

必要なものは3つです。ゲートウェイ自体が配布予定のアドレスでHTTPSを提供していること(リダイレクト先ではなく実アドレス)、プロバイダー認証情報(Anthropic APIならConsoleで発行したAPIキー、クラウドプロバイダーならBedrock/Vertex/Foundryそれぞれの認証情報)、そしてMDMや構成管理などsettings fileを配る手段です。

ゲートウェイ製品側が満たすべき要件は次の6点です。

任意でGET /v1/modelsに対応させると、model discoveryでモデルピッカーに自社のモデル一覧を表示できます。

5ステップのロールアウト手順

手順は3種類の認証情報を扱います。プロバイダー認証情報(ゲートウェイが保持し上流に転送する)、ゲートウェイの管理者が使う認証情報、そして各開発者の鍵です。以下のチェックポイントでは<gateway-key>と<developer-key>の表記でどちらが原因かを区別します。

ステップ1: ゲートウェイが自社のモデルをルーティングできるか確認する

管理者用の鍵か、自分用に発行したテスト用の開発者鍵で最小のリクエストを送ります。

curl -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <gateway-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'

contentフィールドを含む200が返ればそのモデル名でプロバイダーまで届いています。404はゲートウェイ側でそのモデル名がルーティングされていない合図、プロバイダー側からの401はゲートウェイが持つプロバイダー認証情報が間違っている合図です。ルーティング設定にあるモデル名ごとに同じリクエストを繰り返します。ゲートウェイをリダイレクト経由で配信するのは避けます。リダイレクトはリクエストボディを落としたり認証ヘッダーを剥がしたりすることがあり、model discoveryもリダイレクトを失敗として扱うため認証情報がリダイレクト先へ漏れることはありませんが、機能自体が動きません。

ステップ2: 開発者ごとに認証情報を発行する

各開発者に専用の鍵をゲートウェイ側で発行します。ステップ1と同じリクエストで新しい鍵を検証し、<gateway-key>を新しい<developer-key>に置き換えます。ステップ1が成功した状態でここが401になるなら、開発者の鍵が間違っているかゲートウェイ側でまだ有効になっていません。

共有の鍵ではなく開発者ごとに1本発行することが、利用量の帰属とオフボーディング時の個別失効を成立させます。鍵をどの変数に入れるかは、ゲートウェイが読むヘッダー次第です。Authorization: Bearerで読むゲートウェイならANTHROPIC_AUTH_TOKEN、x-api-keyで読むゲートウェイならANTHROPIC_API_KEYに入れます。変数と認証情報の対応はClaude CodeをLLMゲートウェイに接続する方法にまとめています。

ステップ3: Claude Code自体をゲートウェイに対してテストする

配布予定と同じ設定で、まず自分でClaude Codeを動かします。ターミナルに直接入力し(.envやsettings fileには書かない)、そのターミナルを閉じれば元の設定に戻ります。

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"
claude -p "Reply with one word: connected"

応答が返り、ゲートウェイのログに/v1/messagesへの200のPOSTが記録されていれば成功です(Claude Codeはクエリ文字列を付けるため、パス単位で一致を見ます)。2つの失敗メッセージは原因が違います。「Not logged in」はゲートウェイのログが空なら認証情報がセッションに届いていない、ログにx-api-key絡みの401があるならヘッダーの種類を間違えています。「Failed to authenticate. API Error: 401」は認証情報が送られて拒否された合図で、ログがapi.anthropic.comやプロバイダーのエンドポイントを名指ししていれば開発者の鍵は通り、ゲートウェイが持つプロバイダー認証情報の方が間違っています。ベースURLが誤っている場合は症状が異なり、Claude Codeは接続を再試行し続けて数分間出力なしになることがあります。コマンドが固まったように見えたら待たずにゲートウェイのログを確認します。

ステップ4: ベースURLと認証情報を配布する

配布方法はmanaged settingsによる一括配布か、開発者に値を渡して自分で設定してもらう方法のどちらかです。両者には強制力の違いがあります。開発者が自分のシェルでexport ANTHROPIC_BASE_URL=...を設定する方法は、開発者自身が値を上書きできてしまいます。一方managed settingsのANTHROPIC_BASE_URLはClaude Codeがプロセス環境や下位の設定より上位に適用する強制値で、開発者のシェルexportでは上書きできません。全社員に必ずゲートウェイ経由で通信させたい管理者がmanaged settings経路を選ぶのは、この強制力が理由です。ほとんどのロールアウトで必要なのはANTHROPIC_BASE_URLと認証情報だけですが、構成によっては次の変数も含めます。

envブロックにまとめてmanaged settings fileへ書きます。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com"
  },
  "apiKeyHelper": "/usr/local/bin/get-gateway-key"
}

forceLoginMethodやforceLoginOrgUUIDはゲートウェイの認証情報と同居できません。どちらかがmanaged settingsにあると、起動時にANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN・apiKeyHelperがすべてブロックされ「This machine's managed settings require a first-party login」と表示されます。サーバー管理設定(claude.aiの管理コンソールから配る方式)はapi.anthropic.comへの直接接続を前提にしているため、ゲートウェイ経由のセッションには届きません。ゲートウェイを使う組織はこのファイルベースのmanaged settings経路を使います。

配布経路が別になる環境もあります。デスクトップアプリはサードパーティ推論設定を読むためmanaged settingsとは別にMDMで配ります。CI runnerはランナー自身の環境変数として設定します。管理対象Windows機のWSLはwslInheritsWindowsSettingsがtrueのときだけWindows側の設定を引き継ぎます。

managed settingsを配れない場合は、ゲートウェイURL・個人の認証情報・どの変数に入れるかを開発者に伝え、Claude CodeをLLMゲートウェイに接続する方法の手順を自分で実行してもらいます。

チェックポイント: 開発者のマシンでclaudeがログイン画面を出さずにセッションを始め、/statusのSetting sourcesにmanaged settingsが含まれていれば配布は成功です。ログイン画面が出る、またはAnthropic base URLの行が無いなら設定がそのマシンに届いていません。

ステップ5: ロールアウトを検証する

ゲートウェイのホストではなく開発者のマシンから確認します。ストリーミングのリクエストを送ると、エンドポイント・ストリーミングの中継・モデルルーティングを一度に確認できます。

curl -N -X POST "https://llm-gateway.example.com/v1/messages" \
  -H "Authorization: Bearer <developer-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 16, "stream": true, "messages": [{"role": "user", "content": "count to 3"}]}'

data:行が少しずつ届けば正常です。しばらく間が空いてから応答全体が一度に届く場合はゲートウェイがバッファリングしています。続けてclaudeを起動しメッセージを送ります。ログインを求められたら/statusのSetting sourcesにmanaged settingsが含まれるか確認し、含まれないなら配布が届いていません。含まれるのに認証だけ失敗するなら開発者の鍵が配布されていません。「Failed to authenticate」が出るならゲートウェイのログでどちらの認証情報が拒否されたかを確認します。x-api-key型のゲートウェイでは初回に一度だけ承認プロンプトが出るのは想定内の挙動です。fast modeを使っている組織はここで/fastも確認します。fast modeの可用性チェックはゲートウェイのベースURLを経由せずapi.anthropic.comに直接向かうため、ゲートウェイ越しでも推論自体は動くのにfast modeだけ利用不可と表示されることがあります。

最後にゲートウェイのログで送ったメッセージを確認します。認証情報が開発者を識別し、x-claude-code-session-idヘッダーでリクエストをセッション単位にまとめられます。

ロールアウト後の運用で起きる変化

配布して終わりではなく、3種類の変化がゲートウェイ側の追従を必要とします。

鍵ごとのレート制限を決めるときは、クライアントが429を含む一時的な失敗をRetry-Afterに従いながら最大10回まで再試行することを見込んでおきます。

よくある質問

claude.aiの管理コンソールから配るサーバー管理設定はゲートウェイ配下でも使えますか

使えません。サーバー管理設定はapi.anthropic.comへの直接接続を前提にしており、ゲートウェイ経由のセッションには届きません。ファイルベースのmanaged settingsで配ります。

Anthropic純正のClaude apps gatewayでも同じ手順ですか

いいえ。Claude apps gatewayはclaudeバイナリに同梱された別製品で、SSOサインインなど専用のクイックスタートがあります。自社で運用中の別ゲートウェイ製品を使う場合の手順が本記事です。両者の違いはClaude CodeのLLMゲートウェイ互換性にまとめています。

開発者に値を直接渡す方式でもロールアウトとして成立しますか

成立します。managed settingsの配布手段が無い組織では、ゲートウェイURL・個人の鍵・どの変数に入れるかを伝える方式で問題ありません。開発者側の設定手順はClaude CodeをLLMゲートウェイに接続する方法で扱っています。

デスクトップアプリのゲートウェイ設定もmanaged settingsで一緒に配れますか

配れません。デスクトップアプリはサードパーティ推論設定という別の仕組みを読むため、MDMなどで別途配布します。

まとめ

ロールアウトはルーティング確認・開発者クレデンシャル発行・自分でのテスト・配布・検証の5ステップで、各ステップにチェックポイントを置くと失敗の切り分けが早くなります。配布後もClaude Codeのリリースごとに新しいヘッダーやフィールドが増えるため、ゲートウェイ側を追従させる運用体制まで含めてロールアウトと考えておくと安全です。