SpyBara
Go Premium

llm-gateway-rollout.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 16 additions and 2 deletions.

2026
Mon 14 22:58 Fri 18 23:58 Tue 22 23:59

組織向けの LLM ゲートウェイをロールアウトする

Claude Code 用のゲートウェイ製品をデプロイします。Claude Code が送信する内容を転送するように設定し、開発者認証情報を発行し、マネージド設定を通じて設定を配布し、ロールアウトを検証します。

このページでは、管理者が Claude Code 用の LLM ゲートウェイをロールアウトする手順を説明します。ゲートウェイ要件を満たすゲートウェイ製品がデプロイされていることを前提としています。特定の製品のデプロイまたは運用はここでは説明しません。ベンダーのドキュメントに従って、お客様のゲートウェイをデプロイしてください。

前提条件

ロールアウトを完了するには、以下が必要です。

  • インフラストラクチャにデプロイされたゲートウェイ。HTTPS で開発者に配布する正確なアドレスで提供され、リダイレクト先のアドレスではなく、Claude モデル名をプロバイダーにルーティングするように設定されている
  • ゲートウェイが転送するプロバイダー認証情報。以下のいずれか。
  • 開発者マシンに設定ファイルを配信する方法。MDM または設定管理など

ゲートウェイ要件

ゲートウェイを提供する製品がどれであれ、以下を満たす必要があります。

  • サポートされている API 形式を受け入れる：API 形式テーブルの形式のいずれか。以下のロールアウト手順は、ほとんどのゲートウェイが提供する POST /v1/messages の Anthropic Messages API を想定しています
  • レスポンスをストリーミングする：サーバー送信イベントをバッファリングせずに到着時に通す。キープアライブピングを含め、レスポンス全体をバッファリングする代わりに到着時に通す。ストリーミングでは、バッファリングまたはピングの削除が何を破損するかについて説明しています
  • Claude モデル名をルーティングする：開発者が使用する各名前をアップストリームモデルにマップする。Claude Code は各リクエストで claude-sonnet-4-6 などのモデル名を送信します。ほとんどのゲートウェイ製品では、マッピングはゲートウェイ自体の設定内のモデルリストまたはルーティングテーブルです
  • ヘッダーと本文を変更せずに転送する：anthropic-beta、anthropic-version、およびリクエスト本文を両方向で通す。機能パススルーテーブルは各機能をそれなしで破損するものにマップします
  • アップストリームエラーを変更せずに返す：Claude Code の自動復旧はエラーの文言に一致するため、ゲートウェイ独自のエンベロープでエラーをラップすると破損します。ただし、エンベロープのメッセージが Claude apps ゲートウェイがクラウドプロバイダーのエラー文言の代わりに使用する capability_rejected: トークンのいずれかを含む場合は除きます
  • リクエスト本文 WAF 検査からパスを除外する：Claude Code プロンプトはソースコードと XML スタイルのタグを含み、クロスサイトスクリプティング本文ルールに一致します。ゲートウェイの前の WAF は実際のセッションで 403 を返しますが、短いテストリクエストは通ります

オプションで、GET /v1/models を提供して、Claude Code が モデル検出でゲートウェイからモデルピッカーを入力できるようにします。

ロールアウトステップ

ロールアウトは 5 つのステップで構成され、各ステップにはチェックポイントがあります。

  1. ゲートウェイがモデルをルーティングしていることを確認する
  2. 各開発者に認証情報を発行する
  3. ゲートウェイに対して Claude Code をテストする
  4. ベース URL と認証情報を配布する
  5. 開発者マシンからロールアウトを検証する

ステップには 3 つの異なる認証情報が関わり、チェックポイントではプレースホルダーで名前を付けているため、何か失敗した場合にどの認証情報が原因かを特定できます。

認証情報 保有者 チェックポイント内のプレースホルダー
プロバイダー認証情報 ゲートウェイ（アップストリームプロバイダーに転送） ゲートウェイで設定済み。クライアントコマンドには表示されない
ゲートウェイ管理認証情報 ゲートウェイ製品が管理またはテストインターフェース用に発行する場合は、あなた <gateway-key>
開発者キー 各開発者（開発者認証情報を発行するでゲートウェイが発行） <developer-key>

ゲートウェイがモデルをルーティングしていることを確認する

ゲートウェイはプロバイダー認証情報で既に設定されており、ベース URL でリッスンしており、リクエストをプロバイダーの API に転送しているはずです。デプロイメントから 2 つの値を代入して、最小限のリクエストでパスが端から端まで機能することをテストします。

  • <gateway-key> は、現在ゲートウェイを呼び出すことができる認証情報です。管理キー、テストキー、または既に発行した自分の開発者キーです。すべてのゲートウェイ製品に個別の管理認証情報があるわけではありません。ない場合は、まず 開発者認証情報を発行するで自分用の開発者キーを発行してください。
  • model はゲートウェイがルーティングするように設定されている Claude モデル名です。例では claude-sonnet-4-6 を使用しています。設定した名前に置き換えてください。
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 はゲートウェイのプロバイダー認証情報が間違っていることを意味します。

ゲートウェイのルーティング設定内の Claude モデル名ごとに 1 回リクエストを繰り返します。ゲートウェイがルーティングしない名前は、それを選択した開発者に 404 を返すため、ロールアウト前にすべての名前をテストしてください。

開発者認証情報を発行する

各開発者は、認証するためにゲートウェイキーが必要です。製品の認証情報管理ドキュメントに従って、ゲートウェイで開発者ごとに認証情報を作成します。

新しく発行されたキーが ゲートウェイがモデルをルーティングしていることを確認すると同じリクエストでゲートウェイに対して機能することを確認し、<gateway-key> を新しい <developer-key> に置き換えます。

curl -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": 1, "messages": [{"role": "user", "content": "."}]}'

チェックポイント：content フィールド付きの 200 は、開発者キーがゲートウェイに到達し、ゲートウェイがそれを転送することを意味します。前のステップが成功した場合のここでの 401 は、開発者キーが間違っているか、ゲートウェイでまだ有効になっていないことを意味します。

開発者ごとに 1 つのキーを発行することは、共有キーではなく、開発者ごとの使用状況の属性化と個別のオフボーディングを機能させるものです。キーを保持する環境変数は、ゲートウェイが読み取るヘッダーによって異なります。Authorization: Bearer ヘッダーで認証情報をチェックするゲートウェイの場合、開発者は ANTHROPIC_AUTH_TOKEN でキーを設定します。x-api-key ヘッダーからキーを読み取るゲートウェイの場合、開発者は代わりに ANTHROPIC_API_KEY を設定します。認証情報テーブルはマッピングをカバーしています。

ゲートウェイに対して Claude Code をテストする

ロールアウトが fleet 全体に配布する同じ設定を使用して、ゲートウェイを通じて Claude Code を自分で実行してください。これらをターミナルに直接入力し、.env またはセッティングファイルには入力しないでください。これらはこのターミナルセッションのみ有効なため、セッションを閉じるとマシンは通常の設定に戻ります。ゲートウェイが x-api-key ヘッダーを読み取る場合は、ANTHROPIC_AUTH_TOKEN の代わりに ANTHROPIC_API_KEY を使用してください。

export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
export ANTHROPIC_AUTH_TOKEN="<developer-key>"

次に、ゲートウェイを通じてワンショットプロンプトを送信します。

claude -p "Reply with one word: connected"

チェックポイント：プロンプトが応答を返し、リクエストがゲートウェイのログに /v1/messages パスへの POST として状態 200 で表示されます。Claude Code は ?beta=true などのクエリ文字列を追加するため、完全な URL ではなくパスで一致させてください。 2 つの失敗メッセージは異なる方向を指しています。

  • Not logged in：ゲートウェイログをチェックして 2 つの原因を区別します。ログが空の場合、認証情報がセッションに到達せず、リクエストがマシンから出ていません。テストしているシェルで exports を再実行してください。401 ボディに x-api-key が表示されている拒否されたリクエストが表示される場合、ゲートウェイは代わりにそのヘッダーでキーを期待しています。ANTHROPIC_API_KEY に切り替えてください。
  • Failed to authenticate. API Error: 401 は、認証情報が送信されて拒否されたことを意味し、ゲートウェイログはどこかを示しています。api.anthropic.com またはプロバイダーのエンドポイントに名前を付けた 401 は、ゲートウェイがアップストリームに到達したが、ゲートウェイが保持するプロバイダー認証情報が拒否されたことを意味します。開発者キーは機能し、ゲートウェイが保持するプロバイダー認証情報が間違っているか、プレースホルダーです。

間違ったまたは到達不可能なベース URL は異なる症状を生成します。Claude Code は バックオフで接続を再試行し、エラーを報告する前に数分間出力がない状態で待機できます。コマンドがハングしているように見える場合は、待つ代わりにゲートウェイログをチェックしてください。到着するリクエストがないことは、ANTHROPIC_BASE_URL がゲートウェイを指していないことを意味します。

設定を配布する

すべての開発者マシンにはゲートウェイアドレスと認証情報が必要です。マネージドセッティングを通じて中央から配布できるため、開発者は何も設定する必要がなく、または開発者に値を設定させることができます。

配布する内容

どちらのパスを選択するかに関わらず、同じ変数セットが適用されます。ほとんどのロールアウトは ANTHROPIC_BASE_URL と認証情報のみが必要です。ゲートウェイセットアップが必要とする場合は、条件付き行を含めてください。

変数またはセッティング 機能 含める場合
ANTHROPIC_BASE_URL Claude Code の API リクエストを api.anthropic.com の代わりにゲートウェイに送信します 常に
apiKeyHelper、または ANTHROPIC_AUTH_TOKEN または ANTHROPIC_API_KEY の認証情報 ゲートウェイへの各リクエストを認証します。ヘルパーはキーを取得するコマンドを実行します。変数は静的キーを保持し、それぞれ Authorization: Bearer と x-api-key として送信されます 常に。3 つのうち 1 つ
ANTHROPIC_CUSTOM_HEADERS すべての API リクエストに追加の HTTP ヘッダーを追加します ゲートウェイがすべてのリクエストでテナントまたはルーティングヘッダーを必要とする場合
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY 起動時にゲートウェイの /v1/models をクエリし、返された名前を /model ピッカーに追加します ゲートウェイが /v1/models を提供し、開発者のピッカーをそこから入力したい場合
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Claude Code がプリリリース機能ヘッダーとボディフィールドを送信するのを停止します。プリリリース機能を無効にするは正確なスコープをカバーしています ゲートウェイが Amazon Bedrock または Google Cloud の Agent Platform アップストリームに転送し、ベータフィールドを拒否する場合。ゲートウェイ要件を参照してください。
CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS または CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK ANTHROPIC_BASE_URL に従う代わりに api.anthropic.com に直接呼び出す可用性チェックが失敗、インターセプト、または Anthropic 認証情報がないためスキップされた場合、高速モードを復元します 組織が高速モードを使用し、開発者が ANTHROPIC_AUTH_TOKEN のみで認証する場合、ANTHROPIC_API_KEY のゲートウェイ発行キーまたは apiKeyHelper から認証する場合、またはネットワークが api.anthropic.com への直接リクエストをブロックまたはインターセプトする場合。プロキシと LLM ゲートウェイの背後で高速モードを使用するは、どちらの変数が設定に一致するかをカバーしています。
ANTHROPIC_MODEL または ANTHROPIC_DEFAULT_HAIKU_MODEL Claude Code がメインセッションとバックグラウンドトラフィックに要求するモデル名を設定します ゲートウェイが Claude Code のデフォルトと一致しないモデル名をルーティングする場合、または バックグラウンド機能を別のモデルにルーティングする場合。オーバーライド名と、オーバーライドが設定されていない場合に Claude Code が要求する組み込みモデル ID の両方をルーティングしてください。一部のバックグラウンドサブコールはオーバーライドに関わらず組み込み ID を要求するため。モデル設定は、セッションの各部分が使用するモデルをカバーしています。
ANTHROPIC_BEDROCK_BASE_URL、ANTHROPIC_VERTEX_BASE_URL、ANTHROPIC_FOUNDRY_BASE_URL、または ANTHROPIC_AWS_BASE_URL（そのプロバイダーの変数付き） Claude Code をゲートウェイ経由でプロバイダー固有のベース URL を通じてポイントします。Amazon Bedrock と Google Cloud の Agent Platform はそれらのプロバイダーのネイティブリクエスト形式にも切り替わります ゲートウェイが Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、または AWS 上の Claude Platform の前面にある場合。API 形式を参照してください。

マネージドセッティングを通じて配布する

マネージドセッティングファイルの env ブロックを通じて変数を配布し、MDM、レジストリポリシー、または設定管理によってプッシュします。

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

テーブルから条件付き変数を同じ env ブロックに追加します。マネージドされた ANTHROPIC_BASE_URL は強制され、Claude Code がプロセス環境と低優先度セッティングの上に適用するため、開発者のシェルエクスポートでオーバーライドできません。

マネージドセッティングにゲートウェイ認証情報と一緒に forceLoginMethod または forceLoginOrgUUID を含めないでください。どちらのキーでも、任意の値で、起動時に ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、および apiKeyHelper をブロックし、開発者は進行できません。This machine's managed settings require a first-party login または "gateway" 値の下で Administrator policy requires a Cloud gateway sign-inが表示されます。

サーバーマネージドセッティング配布には api.anthropic.com への直接接続が必要なため、ゲートウェイルーティングセッションに到達しません。ゲートウェイデプロイメントはこのファイルベースのマネージドセッティングパスを使用し、同じキーを強制します。

認証情報については、上記のように示されているマネージドセッティングファイルで 1 つの apiKeyHelperコマンドを配布します。コマンドはローカル開発者としてシークレットストアに認証するため、各マシンは独自のキーを受け取ります。または、既存のシークレットプロセスを通じて各開発者にキーを配布し、自分で ANTHROPIC_AUTH_TOKEN を設定させます。

一部の環境には個別の配布が必要です。

  • デスクトップアプリはマネージドセッティングではなく、サードパーティ推論設定からゲートウェイルーティングを読み取ります。マネージドセッティングと一緒に MDM を通じてそのファイルをデプロイし、デスクトップセッションもゲートウェイを通じてルーティングするようにしてください。デスクトップサードパーティ設定ドキュメントとデスクトップゲートウェイドキュメントを参照してください。
  • CI ランナーは ランナーの環境で ANTHROPIC_BASE_URL と認証情報を設定する必要があります。
  • マネージドされた Windows マシン上の WSL は、wslInheritsWindowsSettingsが true の場合のみ Windows マネージドセッティングを読み取ります。

開発者に値を自分で設定させる

マネージドセッティング配布が設定されていない場合は、各開発者に 接続ページに従うために必要なものを送信します。

  • ゲートウェイ URL
  • 個人認証情報
  • 認証情報を入力する変数：ベアラートークンゲートウェイの場合は ANTHROPIC_AUTH_TOKEN、x-api-key ゲートウェイの場合は ANTHROPIC_API_KEY。開発者にどちらかを伝えることで、接続ページで説明されている試行錯誤を節約できます。
  • 配布する内容テーブルからの条件付き変数（値付き）

接続ページは、開発者に各変数の設定方法を説明しています。

チェックポイント：開発者マシンで、claude はログイン画面を表示せずにセッションを開始します。配布された認証情報が認証を満たすためです。次に /status を実行し、Status タブを開きます。Anthropic base URL 行はゲートウェイアドレスを表示し、マネージド配布の場合 Setting sources 行にはマネージドセッティングが含まれます。ログイン画面、または欠落している Anthropic base URL 行は、設定がマシンに到達しなかったことを意味します。

ロールアウトを検証する

ゲートウェイホストではなく開発者マシンからすべてが機能することを確認し、テストが開発者が使用するネットワークパスをカバーするようにします。ストリーミングリクエストを送信します。これはエンドポイント、ストリーミングパススルー、およびモデルルーティングを一度にチェックします。

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 Code を停止させます。404 はモデル名がルーティングされていないことを意味します。モデル名ごとに繰り返します。

次に claude を開始してメッセージを送信します。このステップでの各症状には 1 つの原因があります。

  • ログインプロンプトは認証情報ギャップを意味します。/status を実行し、Status タブを開きます。Setting sources 行にマネージドセッティングが含まれていない場合、配布がマシンに到達しませんでした。含まれている場合、開発者認証情報が配布されなかったため、ANTHROPIC_AUTH_TOKEN または apiKeyHelper を設定してください。
  • Failed to authenticate エラーはゲートウェイがリクエストを拒否していることを意味します。そのログはどの認証情報が失敗したかを示しています。ゲートウェイ自体がログする拒否は開発者キーに名前を付けますが、api.anthropic.com またはプロバイダーのエンドポイントからの 401 は、ゲートウェイが保持するプロバイダー認証情報が拒否されたことを意味します。
  • キーが x-api-key ヘッダーで期待される場合、初回使用時の 1 回限りの承認プロンプトは予想されます。ANTHROPIC_API_KEY として設定されます。ANTHROPIC_AUTH_TOKEN では、プロンプトは表示されず、変数が静かに引き継ぎます。以前に保存された claude.ai ログインはそのセッションでは非アクティブです。

組織が 高速モードを使用する場合は、ここで /fast も実行してください。可用性チェックはゲートウェイベース URL に従う代わりに api.anthropic.com に直接呼び出すため、ゲートウェイルーティングセッションは推論が機能していても高速モードが利用不可または無効として報告できます。プロキシと LLM ゲートウェイの背後で高速モードを使用するは、各メッセージを、設定の残りと一緒に配布される変数にマップします。

最後に、送信したメッセージのゲートウェイログをチェックします。認証情報は開発者を識別し、x-claude-code-session-id ヘッダーはセッションごとにリクエストをグループ化します。機能が トラブルシューティング症状で失敗する場合、ゲートウェイはヘッダーを削除またはエラーを書き直しています。上記の ゲートウェイ要件を参照してください。

ゲートウェイを維持する

ロールアウト後、3 種類の変更が時間とともにゲートウェイに到達します。各変更には、監視する症状と実行するアクションがあります。

変更 ゲートウェイが追いついていない場合の症状 アクション
新しい Claude Code リリースは anthropic-beta 値とリクエスト本文フィールドを追加します 開発者は Claude Code を更新した後、新しいフィールドに名前を付ける 400 エラーを報告します。機能パススルーを参照してください anthropic-* ヘッダーとリクエスト本文を許可リストではなく逐語的に転送します。新しい Claude Code リリースを開発者に到達する前にゲートウェイに対してテストします。Plan Claude Code version upgradesの領域をチェックします
新しい Claude モデルが利用可能になります 開発者が新しいモデル名を選択すると 404 が表示されます。/model ピッカーはそれをリストしません モデル名をゲートウェイのルーティング設定に追加し、ルーティングチェックを再実行します。ANTHROPIC_MODEL またはデフォルトモデル変数を配布する場合は、マネージド設定を更新します
認証情報の有効期限が切れるか、ローテーションが必要です すべての開発者リクエストがアップストリームからの 401 で失敗し始めます ゲートウェイのプロバイダー認証情報を独自のスケジュールでローテーションします。開発者キーはゲートウェイでローテーションし、apiKeyHelperは設定を再配布せずに開発者ごとのローテーションを処理します

キーごとのレート制限をサイズ設定するときは、クライアント 一時的な障害を再試行することを考慮に入れます。429 レスポンスを含め、バックオフで最大 10 回、Retry-After を尊重します。互換性ガイドを各 Claude Code リリースが送信する内容のリファレンスとして保持します。

Claude Code バージョンアップグレードを計画する

一部の Claude Code の動作はゲートウェイで設定されるのではなく、インストールされたバージョンに組み込まれているため、開発者を新しいリリースに移行すると、ゲートウェイ設定が変更されていない場合でも、デプロイメント全体の動作が変わる可能性があります。これが発生するタイミングを制御するには、requiredMaximumVersionでテスト済みバージョンに開発者をピンします。または、独自のチャネルを通じて Claude Code を配布する場合は、DISABLE_UPDATESを使用します。ピンを上げる前に、新しいリリースのchangelogエントリを読み、ゲートウェイに対してテストします。

リリースをテストするときに、ゲートウェイが拒否する新しいヘッダーまたはリクエストフィールドは、ゲートウェイを維持するで説明されている 400 エラーとして表示されます。以下の表は、エラーを生成しないバージョン依存の変更をカバーしており、各変更をアップグレード全体で一定に保つ設定を示しています。

領域 開発者がアップグレードするときに変更できる内容 それを一定に保つ設定
機能フラグのデフォルト Anthropic から機能フラグをフェッチしないセッション（クラウドプロバイダー上のセッションやテレメトリがオフになっているセッションなど）は、インストールされたバージョンに組み込まれたフラグのデフォルトを使用します。リリースがこれらのデフォルトの 1 つを変更すると、開発者がアップグレードするとすぐにそれらの開発者の動作が変わります バージョンピン自体、requiredMaximumVersion または DISABLE_UPDATES
モデル機能の仮定 インストールされたバージョンが認識しないモデル ID（ゲートウェイエイリアス prod-opus など）は、adaptive reasoning、effort パラメータ、およびコンテキストウィンドウのデフォルト仮定で実行されます。後のバージョンが ID を認識するか、マップを作成するまで ゲートウェイで Anthropic モデル ID をルーティングするか、Anthropic モデル ID をエイリアスにマップするmodelOverridesエントリを追加します。クラウドプロバイダー接続では、代わりにピンされたモデルの機能を宣言できます
デフォルトモデルとエイリアス 新しいセッションがデフォルトで開始するモデル、および opus や sonnet などのエイリアスが解決するモデルは、各バージョンに組み込まれており、開発者がアップグレードするときに変更できます 新しいセッションが開始するモデルの場合はANTHROPIC_DEFAULT_MODEL、各エイリアスが解決する内容の場合はANTHROPIC_DEFAULT_*_MODEL変数（ANTHROPIC_DEFAULT_OPUS_MODEL など）。ANTHROPIC_DEFAULT_MODEL には Claude Code v2.1.236 以降が必要です