SpyBara
Go Premium

llm-gateway-protocol.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 62 additions and 62 deletions.

2026
Thu 1 23:59 Fri 2 22:59 Sat 3 23:57 Mon 5 23:58 Tue 6 23:59 Thu 8 22:58 Tue 13 23:57 Wed 14 22:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Sun 25 23:58

Claude Code ゲートウェイ互換性ガイド

Claude Code と互換性のある LLM ゲートウェイを保つ：呼び出すエンドポイント、転送する必要があるヘッダーとボディフィールド、および削除されると機能しなくなるもの。

このページでは、Claude Code がゲートウェイに送信するリクエストについて説明します。呼び出すエンドポイント、ゲートウェイが転送する必要があるヘッダーとボディフィールド、および転送されない場合に機能しなくなる機能が含まれます。このガイドは、Claude Code と連携するようにゲートウェイ製品を構成するオペレーター向けに作成されています。

Claude apps ゲートウェイは Anthropic の自己ホスト型ゲートウェイであり、GET /protocol でその独自のエンドポイントリファレンスを提供しており、そのゲートウェイのサインイン、推論、管理設定、モデル検出、およびテレメトリエンドポイントをカバーしています。このガイドとは別のドキュメントです。

[!NOTE]

このページでは、以下について説明します：

このページでは、ゲートウェイが各ヘッダーとボディフィールドで実行する操作に対して 2 つの用語を使用します：

  • 変更なしで転送：アップストリームにバイト単位で渡す
  • 使用：ゲートウェイはルーティング、属性、またはトレース用に読み取ることができ、転送する必要はありません

変更なしで転送とマークされていないものは、使用または無視するものです。

API フォーマット

ゲートウェイは、Claude Code クライアントに対して以下の API フォーマットのうち少なくとも 1 つを公開する必要があります。クライアントはフォーマットを選択し、下の表の「選択方法」列にある変数を使って Claude Code をゲートウェイに向けます。

Google Cloud's Agent Platform は Google Cloud の Claude エンドポイントで、以前は Vertex AI と呼ばれていました。その変数名には VERTEX という表記が引き続き使われています。

フォーマット 選択方法 エンドポイント 変更せずに転送するもの
Anthropic Messages ANTHROPIC_BASE_URL /v1/messages、/v1/messages/count_tokens（任意） anthropic-beta および anthropic-version リクエストヘッダー
Amazon Bedrock InvokeModel ANTHROPIC_BEDROCK_BASE_URL と CLAUDE_CODE_USE_BEDROCK=1 /model/{model}/invoke、/model/{model}/invoke-with-response-stream、/model/{model}/count-tokens（任意） anthropic_beta および anthropic_version リクエストボディフィールド
Google Cloud's Agent Platform rawPredict ANTHROPIC_VERTEX_BASE_URL と CLAUDE_CODE_USE_VERTEX=1 :rawPredict、:streamRawPredict、count-tokens:rawPredict（任意） anthropic-beta および anthropic-version リクエストヘッダー、ならびに anthropic_version リクエストボディフィールド

Foundry と Claude Platform on AWS

Microsoft Foundry と Claude Platform on AWS は Anthropic Messages フォーマットを実装しています。Claude Code はそれぞれ専用の変数 ANTHROPIC_FOUNDRY_BASE_URL と ANTHROPIC_AWS_BASE_URL を通じてこれらにルーティングしますが、いずれかの前段に置かれるゲートウェイは上記の Anthropic Messages の行を実装します。Claude Platform on AWS の前段に置かれるゲートウェイは、anthropic-workspace-id ヘッダーも転送する必要があります。このヘッダーは同プラットフォームがすべてのリクエストで必須としているものです。

任意のエンドポイントと起動時のトラフィック

任意のエンドポイントはトークンカウント用のエンドポイントのみです。これらが存在しない場合、Claude Code はコンテキスト使用量を文字数ベースで推定する方法にフォールバックします。

完全な URL ではなく、パスでマッチさせてください。

  • 推論リクエストは /v1/messages?beta=true に POST されます
  • Google Cloud's Agent Platform のメソッドサフィックスは、/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict のように、パブリッシャーモデルのパスに付加されます

ゲートウェイには、何も壊すことなく拒否できるベストエフォートの起動時トラフィックも届きます。Anthropic Messages フォーマットのゲートウェイは HEAD /api/hello という接続ウォームアップ用のプローブを受信します。HTTP プロキシまたはクライアント証明書が設定されている場合、Claude Code はこのプローブを省略します。Amazon Bedrock フォーマットのゲートウェイは GET /inference-profiles?type=SYSTEM_DEFINED リクエストを受信し、設定されたモデルが推論プロファイルである場合は GET /inference-profiles/{profile} による参照も受信します。

ゲートウェイを経由するセッションは、HIPAA 設定の対象外です。どのサインイン方法と接続方法が対象となるかは、開発者のサインイン方法と接続方法を確認するに記載されています。ゲートウェイの背後での HIPAA 設定を参照してください。

fast mode の利用可否チェックはゲートウェイのログには一切現れません。このチェックは ANTHROPIC_BASE_URL に従わず api.anthropic.com を直接呼び出すため、api.anthropic.com への直接の外向き通信をブロックしているネットワークでは、ゲートウェイ経由の推論は動作し続けていても、fast mode が接続エラーを報告することがあります。WebFetch のドメイン安全性チェックも api.anthropic.com を直接呼び出します。これを復旧させる変数については、プロキシや LLM ゲートウェイの背後で fast mode を使用するを参照してください。

ストリーミング

Claude Code はストリーミングの推論応答を、到着したそばからイベントごとに読み取ります。そのため、ゲートウェイがストリームをどのように中継するかによって、ユーザーに表示される内容が変わります。

  • ゲートウェイが応答を完了するまでバッファリングすると、Claude Code は停止してしまいます。
  • Claude Code は、各応答のイベントシーケンス全体が、最後の message_delta および message_stop イベントまで順序どおりに届くことを前提としています。コンテンツブロックが開始された後、その最後の message_delta より前にボディが正常に終了した場合、Claude Code はその応答を接続の切断として扱います。その場合にユーザーに何が表示されるかは The response above may be incomplete で、Claude Code が代わりにリクエストを再発行する条件は自動再試行で説明しています。
  • Amazon Bedrock のガードレールが応答をブロックした場合、Bedrock が送信するイベントは、すでに content_block_stop が到着したコンテンツブロックを参照することがあり、Claude Code はそれらを送信されたとおりに受信することを前提としています。その応答がどのように終了するかは AWS Guardrails で説明しています。
  • Claude Code は、ストリーミングのアイドルタイムアウトを超えて 1 バイトも届かない状態が続くと、ストリーミング応答を中止します。長い思考の一時停止中は、アップストリームの SSE ping イベントがストリーム上の唯一のバイトになることがあるため、それらを除去またはバッファリングするゲートウェイは、応答の途中でこのタイムアウトを発生させる可能性があります。Amazon Bedrock のバイナリイベントストリームのように ping を送信しないアップストリームから変換するゲートウェイも、独自の ping イベントを送出しない限り、同じ空白が生じます。
  • Amazon Bedrock InvokeModel フォーマットでは、Claude Code は /model/{model}/invoke-with-response-stream のレスポンスを、Bedrock が返すバイナリの application/vnd.amazon.eventstream ボディとして読み取ります。そのため、ゲートウェイがそれを Server-Sent Events に変換したり、その Content-Type ヘッダーを書き換えたりすると、解析できなくなります。その場合にユーザーに何が表示されるかはゲートウェイまたはプロキシの背後でのストリーミングエラーで説明しています。

アップストリームとのフォーマットの不一致

クライアントがどのフォーマットを使用するかによって、ゲートウェイが受信する内容が決まります。よくある障害パターンは、クライアントがゲートウェイに送信するフォーマットと、その背後にあるアップストリームプロバイダーが受け付けるフォーマットの不一致です。

  • クライアントが Amazon Bedrock または Google Cloud's Agent Platform のフォーマットを使用する場合、Claude Code は全機能セットのうち、それらのプロバイダーが受け付けるサブセットのみを送信します
  • クライアントが Anthropic Messages フォーマットを使用する場合、ゲートウェイが Amazon Bedrock または Google Cloud's Agent Platform のアップストリームに転送する場合であっても、Claude Code は全機能セットを送信します

この違いを橋渡しするのはゲートウェイの役割です。橋渡しが行われない場合に何が壊れるかについては、機能のパススルーで説明しています。

アップストリームが Amazon Bedrock または Google Cloud's Agent Platform である場合は、代わりにそのプロバイダーのフォーマットを公開することで、橋渡しを回避できます。そのフォーマットのクライアント設定については、ゲートウェイ経由でクラウドプロバイダーにルーティングするを参照してください。

接続方法によるクライアントの動作の違い

開発者がゲートウェイにどのように接続するかによって、Claude Code が送信するモデル ID、anthropic-beta の値、リクエストフィールド、および適用するデフォルトが決まります。ゲートウェイから見えるクライアントの動作は、次の 3 つのいずれかです。

  • Amazon Bedrock または Agent Platform 形式：開発者が CLAUDE_CODE_USE_BEDROCK=1 と ANTHROPIC_BEDROCK_BASE_URL、または CLAUDE_CODE_USE_VERTEX=1 と ANTHROPIC_VERTEX_BASE_URL を設定し、ゲートウェイを指すようにします。Claude Code はそのプロバイダーのモデル ID、リクエストフィールド、デフォルトを使用します。
  • Anthropic Messages 形式：開発者が ANTHROPIC_BASE_URL にゲートウェイを設定します。Claude Code はゲートウェイを Claude API として扱い、転送先のアップストリームを判別できません。
  • Claude apps ゲートウェイへのサインイン：開発者が Claude apps ゲートウェイにサインインします。このゲートウェイは Anthropic Messages 形式を使用しますが、任意のアップストリームにルーティングできるため、Claude Code は Amazon Bedrock と Agent Platform も受け付ける anthropic-beta の値とモデル機能の前提のみを送信します。

接続方法ごとのリクエストとデフォルト

次の表は、3 つの接続方法を 1 行につき 1 つの動作で比較したものです。Microsoft Foundry と Claude Platform on AWS は、Anthropic Messages 形式を使用するものの Claude Code が独自の変数を通じて接続するため、この表には含まれていません。これらについては、Microsoft Foundry と Claude Platform on AWS のページを参照してください。

動作 Amazon Bedrock または Agent Platform 形式 Anthropic Messages 形式 Claude apps ゲートウェイへのサインイン
リクエスト内のデフォルトのモデル ID プロバイダーの形式（Amazon Bedrock の us.anthropic.claude-opus-4-8 など） Anthropic の ID（claude-opus-4-8 など） Anthropic の ID
送信される anthropic-beta の値 Amazon Bedrock と Agent Platform が受け付けるサブセット 機能のパススルーで説明しているすべての値（開発者が CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS を設定している場合を除く） Amazon Bedrock と Agent Platform が受け付けるサブセット
Claude Code が認識しないモデル ID（ゲートウェイのエイリアスなど）に対するリクエストフィールド アダプティブ推論ではなく固定予算での思考を使用し、effort やコンテキスト管理のフィールドは送信しません。会話途中のシステムメッセージは引き続き送信します 現行の Claude モデルが Claude API で受け付けるすべてのフィールド（アダプティブ推論、effort、コンテキスト管理を含む）。Amazon Bedrock または Agent Platform のアップストリームではこれらが拒否される場合があります Amazon Bedrock または Agent Platform 形式と同じ
開発者がオプトインした場合の 1 時間のプロンプトキャッシュ TTL cache_control の ttl フィールドでリクエストされ、ベータ値は使用しません ttl フィールドに加えて anthropic-beta の extended-cache-ttl 値でリクエストされます。この値は転送する必要があります ttl フィールドでリクエストされ、ベータ値は使用しません。1 時間のプロンプトキャッシュを参照してください
バックグラウンドタスクのモデル（ANTHROPIC_DEFAULT_HAIKU_MODEL でモデルを固定している場合を除く） Amazon Bedrock と Agent Platform のページで説明しているとおり、デフォルトの Sonnet モデル、またはメインモデルが選択されている場合はそのメインモデル メインモデル。ただし、ANTHROPIC_API_KEY または apiKeyHelper が Anthropic Console のキーを提供し、ANTHROPIC_AUTH_TOKEN が未設定の場合はデフォルトの Haiku モデル メインモデル

各接続方法でサポートされる機能と、デフォルトで Anthropic に送信されるテレメトリについては、機能の利用可能性と API プロバイダーごとのデフォルトの動作を参照してください。

認識されないモデル ID の設定

開発者がどの接続方法を使用しているかにかかわらず、Claude Code が認識しないモデル ID について想定する内容は、2 つのクライアント側の設定で変更できます。

  • コンテキストウィンドウ：Claude Code は 200K を想定し、ID に [1m] が含まれる場合は 1M を想定します。実際のウィンドウサイズを宣言するには、ゲートウェイまたはカスタムモデル ID のウィンドウを修正するを参照してください
  • 機能：ゲートウェイのエイリアスに、その背後にあるモデルの機能を持たせるには、配布する設定の modelOverrides エントリで、そのモデルの Anthropic ID をエイリアスにマッピングします。ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 変数が適用される場面については、機能のパススルーを参照してください

リクエストヘッダー

Claude Code は API リクエストにこれらのヘッダーを含めます。ヘッダー名はワイヤ上では大文字と小文字を区別しません。anthropic-version および anthropic-beta を変更なしで転送し、アップストリームが AWS 上の Claude Platform の場合は anthropic-workspace-id も転送してください。残りはゲートウェイがルーティング、属性、およびトレース用に使用でき、転送する必要はありません。

ヘッダー 説明
Authorization、x-api-key 開発者のゲートウェイクレデンシャル。設定したクレデンシャル変数に応じて、1 つまたは両方のヘッダーに含まれます
anthropic-version API バージョン。現在は 2023-06-01。Amazon Bedrock および Google Cloud の Agent Platform フォーマットリクエストは、anthropic_version ボディフィールドも含みます。その値はこのヘッダーの値ではなく、プロバイダー方言文字列です
anthropic-beta リクエストの機能値をカンマで区切ったもの。ヘッダーをそのまま転送してください。個別の値をホワイトリストに登録しないでください。セットは Claude Code リリースで変わるためです。開発者が claude.ai ログインで認証する場合（ANTHROPIC_BASE_URL がゲートウェイクレデンシャル変数なしで設定されている場合に可能）、このヘッダーはアップストリームが必要とする OAuth 機能も含み、それを削除するとそれらのリクエストは 401 で失敗します
x-claude-code-session-id 現在の Claude Code セッションの一意の識別子。リクエストボディを解析せずに 1 つのセッションからのすべてのリクエストを集約するために使用してください
x-claude-code-agent-id リクエストを発行したサブエージェントの識別子。セッション内で Claude Code が生成したエージェントからのリクエストにのみ存在します。セッション ID と共に使用して、並列エージェントにコストを属性付けしてください
x-claude-code-parent-agent-id リクエストするエージェントを生成したエージェントの識別子。ネストされたエージェントにのみ存在します

サブエージェント ID は各スポーン時に新しく生成されます。チームメイトエージェント（エージェントチームの名前付きメンバー）は、再接続全体で安定した名前ベースの ID を再利用します。どちらの場合も、ID はエージェントを識別し、人またはデバイスを識別しないため、エージェント ID ヘッダーをユーザー識別子として扱わないでください。

開発者が ANTHROPIC_CUSTOM_HEADERS を設定した場合、それらのヘッダーもリクエストに表示されます。

ゲートウェイヒントヘッダー

Claude Code はルーティングヒントも送信できます。ゲートウェイまたはルーターがリクエストをスケジュール、キャッシュ、または属性付けするために使用できるリクエストごとの事実です。Claude Code v2.1.273 以降が必要です。

リクエストがそれらを含むかどうかは、Claude Code がそれをどこに送信するかによって異なります。

  • Anthropic API への直接接続：デフォルトで送信されます
  • カスタムベース URL：デフォルトでオフです。不明なヘッダーを拒否するプロキシはリクエストを失敗させるためです。それらを受け取るには、開発者向けに CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 を設定してください。例えば、管理設定の env ブロックで設定できます
  • Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、AWS 上の Claude Platform を含む他のバックエンド：CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 が設定されている場合にのみ送信されます

CLAUDE_CODE_GATEWAY_HINT_HEADERS を 0 に設定すると、すべての接続でヘッダーが停止します。

ヘッダーは以下の行にリストされているもののみを含みます。固定語彙、ツール名、期間、およびランダムプロンプト識別子です。プロンプトテキストまたはファイルコンテンツは含まれません。すべての値は印字可能な ASCII です。

ヘッダー 説明
x-claude-code-request-class このリクエストの種類：メイン会話のターンの場合は main、サブエージェントのターンの場合は subagent、ワークフロー内で実行されているエージェントの場合は workflow、会話をコンパクト化する要約リクエストの場合は compaction、セッションタイトル、分類器、および要約などのサイドリクエストの場合は auxiliary。すべてのリクエストで送信されます
x-claude-code-agent-type リクエストを発行したサブエージェントの種類：Explore、Plan、または general-purpose などの組み込みエージェント型名、ユーザー定義エージェントの場合は custom、エージェントチームメンバーがリードのプロセスで実行されている場合は teammate、または フォークの場合は fork。サブエージェント自身のターンにのみ存在します。サブエージェントのコンパクト化またはサイドリクエストはエージェント ID を保持しますが、タイプは含みません。ユーザーが選択したエージェント名は送信されません
x-claude-code-compaction コンテキスト圧縮中に会話を要約するリクエストに存在します。値は何がトリガーしたかを示します。コンテキストウィンドウが容量に近づいた場合は auto、/compact の場合は manual、API がリクエストが長すぎると拒否した場合は reactive。アイドル時の圧縮の場合も値は auto です。他のすべてのリクエストでは存在しません
x-claude-code-context-compacted コンパクト化後の最初のメイン会話リクエストに 1 回存在し、x-claude-code-compaction と同じ値を持ちます。このリクエストの前の会話プレフィックスはもう使用されないため、それをキーとしたキャッシュは削除できます
x-claude-code-prev-tool-durations このリクエストが含む結果のツール呼び出しの測定実行時間。<name>=<ms>;<name>=<ms> として、例えば Bash=742;Read=9。同じ会話のツール呼び出しのバッチ後の次のリクエストで送信されます。メインセッションまたはサブエージェントから送信されます
x-claude-code-prompt-id ユーザープロンプトがリクエストを提供するランダム UUID。1 つのプロンプトを提供するリクエストは値を共有します。これには、プロンプトが開始したサブエージェントのターンが含まれます。プロンプトに属性付けされていないリクエストはそれを省略します。セッションのリクエストをプロンプトでグループ化するために使用してください。Claude Code v2.1.283 以降が必要です

x-claude-code-prev-tool-durations を解析する前に、Claude Code が値をどのように構築し、何を除外するかを確認してください。

  • エントリ：実行されたツール呼び出しごとに 1 つ。その結果が収集された順序で、ミリ秒単位です
  • キャップ：Claude Code は最大 32 エントリと 4 KB を送信し、最初のエントリを保持します
  • エンコーディング：ツール名はパーセントエンコードされ、%、;、=、カンマ、スペース、および印字可能な ASCII 外の任意の文字をカバーします
  • 解析：; で分割し、次に = で分割し、各名前をデコードします
  • 不在：コンパクト化呼び出し、サイドリクエスト、および新しいプロンプトの最初のリクエストはそれを含みません。不足しているヘッダーをツールを実行しなかったターンとして読まないでください
  • 時間：各エントリは権限プロンプトとフックを除外し、並列ツール呼び出しは各自の時間を報告するため、エントリはリクエスト間のギャップに加算されません

オープンリストとして転送

ヘッダーとボディフィールドをクローズドリストではなく、オープンリストとして扱ってください。Claude Code はリリース全体で機能を獲得し、新しい anthropic-beta 値、新しいリクエストボディフィールド、および時々新しい anthropic-* または x-claude-code-* ヘッダーとして到着します。

Anthropic フォーマットアップストリームに転送する場合、今日見ている値をホワイトリストに登録するのではなく、anthropic-* リクエストヘッダーとリクエストボディフィールドを変更なしで渡してください。観察されたリストに固定されたゲートウェイは、次の機能のヘッダーまたはフィールドを削除し、それを導入するリリースで壊します。

例外は Amazon Bedrock や Google Cloud の Agent Platform などの非 Anthropic アップストリームです。スキーマの違いを橋渡けするのはゲートウェイの仕事です。機能パススルーを参照してください。

レスポンスヘッダー

Claude Code はこれらのレスポンスヘッダーを読み取り、ストリームの停止を検出し、再試行するかどうかと再試行のタイミングを決定し、使用量制限を表示します。表には各ヘッダーについて返すべき内容を示しています。また、エラーレスポンスボディは未修正のまま転送してください。これにより Claude Code の機能拒否リカバリーがアップストリームのエラーメッセージと一致させることができます。

ヘッダー 返すべき内容と理由
content-type ストリーム化された Anthropic Messages 形式のレスポンスでは text/event-stream を返し、Amazon Bedrock 形式のレスポンスでは application/vnd.amazon.eventstream を未修正のまま返してください。Amazon Bedrock 形式では異なるタイプを返すとリクエストが失敗します
retry-after HTTP 日付ではなく整数秒を返してください。Claude Code は次の自動再試行の前に少なくともその時間待機し、CLAUDE_CODE_RETRY_WATCHDOGセッション外では 60 を超える値は再試行を停止し、エラーを直ちに表示します
x-should-retry アップストリームの値を未修正のまま渡してください。Claude Code はこのヘッダーを失敗したリクエストを再試行するかどうかを決定する際の 1 つの入力として読み取ります。true はレスポンスが再試行可能であることを示し、false は再試行不可能であることを示します。再試行回数、バックオフ、および Claude Code が再試行する失敗については、自動再試行を参照してください
anthropic-ratelimit-unified-* すべてのレスポンスでアップストリームの値を未修正のまま転送してください。Claude Code はこれらを成功したレスポンスで読み取り、claude.ai でサインインしている開発者にプラン制限に対する使用量を表示し、429 では一時的なスロットルからプラン制限または支出上限を区別します。使用量制限を参照してください

システムプロンプト属性ブロック

Claude Code は、クライアントバージョンと会話から派生したフィンガープリントを含む短い属性ブロックをシステムプロンプトの前に付加します。api.anthropic.com エンドポイントは変更されていない状態で最初のシステムブロックとして到着したときに処理前にブロックを削除するため、ファーストパーティプロンプトキャッシングに影響しません。他のアップストリームはプロンプトの一部として受け取ります。

削除は位置に基づいているため、ゲートウェイが system 配列を変更せずに転送する場合にのみ機能します。別のシステムブロックを前に付加したり、配列を並べ替えたり、単一の文字列に変換したりすると、削除が機能しなくなり、ブロックはモデルとプロンプトキャッシュキーに到達します。プロンプトから属性ブロックを除外しながら他のシステムコンテンツを保持するには、以下の方法があります。

  • 受け取った system 配列を正確に転送し、ブロックを最初に保つ：別のシステムブロックを前に付加したり、配列を並べ替えたり、単一の文字列に変換したりすると、削除が機能しなくなり、ブロックはモデルとプロンプトキャッシュキーに到達します。
  • ブロックを独自の配列エントリに保つ：エンドポイントは属性ヘッダーで始まるマージされたブロックを属性全体として扱い、マージされたすべてのコンテンツ（システムプロンプトの残りを含む）を削除します。
  • ゲートウェイがシステムコンテンツを再形成する必要がある場合は、CLAUDE_CODE_ATTRIBUTION_HEADER=0 を設定して Claude Code がブロックを省略するようにしてください。Anthropic とクラウドプロバイダーの Claude エンドポイントは属性用にブロックを読み取るため、ゲートウェイで削除または移動するのではなく、クライアント側で省略してください。

この変数はゲートウェイとサードパーティキャッシング互換性のために存在し、プライバシーコントロールではありません。直接接続では、完全なリクエストはいずれにしても Anthropic API に送信されます。以下の両方が当てはまる場合、Claude Code は変数を 0 に設定した場合でも auto mode 分類器リクエストでブロックを保持します。

分類器リクエストは Claude Code のシステムプロンプトの残りをスキップするため、これらのリクエストではブロックはリクエストボディ内でそれらを Claude Code トラフィックとして識別する唯一のマーカーです。いずれかの条件が失敗した場合、LLM ゲートウェイを通じて、サードパーティプロバイダー上で、またはプロファイルまたはフェデレーション認証情報がアクティブな場合、0 を設定すると分類器リクエストからもブロックが削除されます。v2.1.229 より前では、この例外は存在しませんでした。0 を設定するとそれらの分類器リクエストからブロックが削除され、API がリクエストを拒否したときに、auto mode は分類器に送信するすべてのアクションで失敗しました。

Claude Code v2.1.181 から、リクエストがカスタムベース URL を通じてルーティングされる場合、ブロックは会話の存続期間中安定しているため、完全なリクエストボディをキーとするゲートウェイ側プロンプトキャッシュは無効化せずに機能し、ゲートウェイが転送するすべてのプロバイダーは安定したプロンプトプレフィックスを受け取ります。v2.1.181 より前のバージョンでは、ブロックはリクエストごとのトークンを含み、システムプロンプトの開始を変更しました。それらのバージョンでは、ゲートウェイが以下のいずれかを実装する場合は CLAUDE_CODE_ATTRIBUTION_HEADER=0 を設定してください。

  • リクエストボディをキーとするプロンプトキャッシュを実装します。
  • Amazon Bedrock、Microsoft Foundry、Google Cloud の Agent Platform などのサードパーティプロバイダーにリクエストを転送します。Anthropic Messages 形式またはプロバイダー独自の形式で、変更されるプレフィックスはそのプロバイダー上のプロンプトキャッシュ再利用を削減します。

機能パススルー

Claude Code は ANTHROPIC_BASE_URL ゲートウェイを Anthropic フォーマットエンドポイントとして扱い、api.anthropic.com に送信するベータヘッダーとリクエストボディフィールドを送信します。ただし、直接接続用に予約されている小さな診断とデフォルトのセットは除きます。以下で説明するきめ細かいツールストリーミングデフォルトなど、そのセットはリリースごとに異なるため、その内容に依存しないでください。

きめ細かいツールストリーミングは直接接続デフォルトの 1 つです。リクエストがカスタムベース URL を通じてルーティングされるときはデフォルトでオフになり、開発者が CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING=1 を設定するとゲートウェイはそれを受け取ります。

ベータヘッダーとボディフィールドのペア

機能がボディフィールドを追加する場合、それらはベータヘッダーと組み合わされ、ペアは一緒に移動します。ヘッダーを削除しながらボディを渡すゲートウェイ、または Anthropic フォーマットボディを異なるスキーマのアップストリームに転送するゲートウェイは、400 エラーを生成します。両方の半分が一緒に存在しない場合、機能は静かにオフになります。

リクエストボディをコンテンツ検査のために書き直したり編集したりするゲートウェイは、削除と同じ方法でペアリングを壊すため、変更せずに検査してください。表は機能がペアリングから逸脱する場所を記載しています。

機能 ヘッダーとボディペア 壊れた場合の症状 修復
適応的推論 ベータヘッダーなし。Claude Code は Claude Opus 4.6、Claude Sonnet 4.6、Claude Haiku 5.5、Claude Fable 5 以降のモデルに thinking: {"type": "adaptive"} を送信し、ゲートウェイエイリアスなど認識しないモデル名を、フィールドを受け取る現在のモデルとして扱います thinking フィールドまたは adaptive タグを命名する 400。アップストリームモデルビルドがそれを受け入れない場合 アップストリームをアップグレードしてください。Opus 4.6 および Sonnet 4.6 では、開発者は代わりに CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 を設定できます
コンテキスト管理 コンテキスト管理ベータヘッダーは context_management ボディフィールドと組み合わされます Extra inputs are not permitted を含む 400。ゲートウェイが Anthropic フォーマットリクエストを受け入れるが Amazon Bedrock に転送する場合に一般的です。v2.1.304 以降では、Claude Code はこのペアなしで自動的に再試行します 両方を転送するか、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
拡張コンテキストおよびインターリーブ思考 ベータヘッダーのみ。ボディフィールドなし ヘッダーが削除されると静かに利用不可。アップストリームは機能リクエストを見ません anthropic-beta をそのまま転送してください
ベータツールフィールド ツール関連ベータヘッダーは strict および defer_loading などのツールスキーマフィールドと組み合わされます ボディがヘッダーなしで渡される場合、認識されないツールスキーマフィールドを命名する 400。defer_loading については、ツール検索なしでの再試行を参照してください 両方を転送するか、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
努力および構造化出力 output_config ボディフィールドは努力、構造化出力フォーマット、およびタスク予算設定を含みます。各々は独自のベータヘッダーと組み合わされます output_config を命名する 400。多くの場合 Extra inputs are not permitted。Amazon Bedrock および Google Cloud の Agent Platform アップストリーム上 フィールドとそのヘッダーを一緒に転送するか、開発者に CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定してもらってください。この変数はフォーマットとタスク予算設定を削除しますが、努力は削除しません。フォーマットのみを削除するには、代わりに CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1 を設定できます。これには v2.1.288 以降が必要です
会話中のシステムメッセージ ベータヘッダーなし。Claude Code は Claude Opus 4.8、それ以降にリリースされたモデル、および認識されないモデル ID に対して、一部のリマインダーや添付テキストを messages 内の role: "system" エントリとして送信します Unexpected role "system" などの 400 Claude Code はシステムメッセージなしで再試行します。Claude Opus 4.8 より前にリリースされたモデルのエイリアスでシステムメッセージを停止するには、配布する設定に modelOverrides エントリを追加してください
ターンごとに設定される努力 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.1 では、ベータヘッダーが role: "system" エントリ（システムメッセージ、または空のコンテンツを持つエントリ）上の output_config.effort と組み合わされます ゲートウェイが空のエントリからフィールドを削除すると、messages.N: system content must contain at least one block を含む 400 両方を転送するか、開発者に CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定してもらい、フィールドと空のエントリの送信を停止してください
プロンプトキャッシング ベータペアリングなし。Claude Code は cache_control マーカーを system ブロックおよび messages エントリ（会話の途中で追加される role: "system" エントリを含む）に付加します エラーなし。会話は毎ターン、キャッシュされていない入力として課金されます。usage でキャッシュアクティビティがほとんどまたはまったくない高い input_tokens として表示されます cache_control が表示される場所ならどこでも変更なしで転送し、ブロック形式の system またはメッセージコンテンツをプレーン文字列に変換しないでください
トークンカウント ベータペアリングなし。count_tokens エンドポイントを使用します エラーなし。Claude Code は文字ベースの推定にフォールバックするため、/context は概算カウントを表示します 正確なトークンカウントのためにエンドポイントを公開してください

ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 変数は、プロバイダー設定でのみモデル機能を宣言します：CLAUDE_CODE_USE_BEDROCK、CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_FOUNDRY、および CLAUDE_CODE_USE_MANTLE。ANTHROPIC_BASE_URL ゲートウェイの背後では効果がありません。

自動リトライとエラー転送

アップストリームがこれらの機能のいずれかを拒否した場合、Claude Code は拒否された部分を削除または変更してリクエストを自動的に再試行できます：

  • thinking.type の値 enabled または adaptive がサポートされていないと 400 が示す場合、Claude Code はもう一方のタイプで 1 回再試行し、thinking フィールドは維持します。そのモデルへの以降のリクエストは、Claude Code が終了するまで切り替え後のタイプを使い続けます。v2.1.121 より前では、Claude Code は再試行しなかったため、thinking.type.enabled is not supported が開発者に届いていました
  • アップストリームが messages 内の role: "system" エントリを拒否した場合、Claude Code はそれらの会話中のシステムメッセージを除いて 1 回再試行し、そのテキストを代わりにユーザーメッセージに含めます。会話内の以降のリクエストは、開発者が /clear を実行するか会話が圧縮されるまでその形式を維持します
  • アップストリームが会話中のシステムメッセージの cache_control マーカーのみを拒否した場合、Claude Code はシステムメッセージを維持し、マーカーを移動して 1 回再試行します。その再試行と、Claude Code が終了するまでの以降のリクエストでは、マーカーは messages 内でシステムメッセージではない最後のエントリに付けられます
  • アップストリームが思考署名を拒否する場合（bound to a different conversation という 400 を含む）、Claude Code はリクエストを以前の思考ブロックなしでリトライし、それらを後のすべてのリクエストから除外します。新しい応答には依然として思考が含まれます
  • ゲートウェイまたはそのアップストリームが advisor ツールエントリを tools で認識されないツールタイプとして拒否する場合、Claude Code はそのエントリとその anthropic-beta 値なしでリクエストを 1 回リトライします。その後のそのベース URL へのリクエストは Claude Code が終了するまで advisor を除外し、その時間は /advisor は開発者に利用不可です。Claude Code はこの拒否を Input tag の後にツールタイプを命名するメッセージを含む 400 または 422 レスポンスによって認識します。例えば Input tag 'advisor_20260301' です。v2.1.280 より前では、Claude Code はこの拒否をリトライしませんでした
  • アップストリームが output_config.effort を拒否する場合、Claude Code は努力なしでリクエストを再試行し、Claude Code が終了するまでそのモデルへの以降のリクエストから努力を除外します。Claude Code はこの拒否を、メッセージが Extra inputs are not permitted とともに output_config.effort を挙げている、またはモデルが努力パラメーターをサポートしていないと述べている 400 によって認識します
  • アップストリームが context_management フィールドまたはその anthropic-beta 値を拒否する場合、ゲートウェイにはそれらを除いたリクエストがもう一度届きます。後のリクエストでゲートウェイが再びそれらを受け取り、アップストリームが再び拒否した場合も、同じ再試行が行われます。Claude Code はこの拒否をメッセージによって認識します。たとえば context_management: Extra inputs are not permitted を含むメッセージです。v2.1.304 より前では、Claude Code はこの拒否を再試行しませんでした
  • アップストリームが strict など defer_loading 以外のベータツールフィールドを拒否する場合、400 は開発者に届きます。その前に、ゲートウェイにはツール検索フィールドを除いたリクエストが再び届くことがあります。このようなフィールドの送信を停止するには、開発者に CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定してもらってください

bound to a different conversation 拒否は API の保存された思考チェックから来ます。これは、system、tools、または以前の messages コンテンツが思考を生成したリクエストと異なる場合に失敗します。そのコンテンツのいずれかを書き直すゲートウェイは、拒否自体を引き起こす可能性があります。ライブラリ、プロキシ、およびゲートウェイは、変更なしで渡すべき内容をカバーしています。

この再試行ロジックの大部分はアップストリームのエラー文言に一致するため、エラーレスポンスボディを変更なしで転送してください。アップストリームエラーを独自のエンベロープでラップするゲートウェイは、ステータスコードを保持する場合でも回復パスを壊します。ただし、エンベロープのメッセージが安定した capability_rejected: トークンを含む場合は除きます。Claude apps ゲートウェイはクラウドプロバイダーのエラー文言をそれらのトークンに置き換えます。例えば capability_rejected: prompt_too_long です。

ツール検索なしでの再試行

v2.1.305 以降では、defer_loading フィールドと tool_reference ブロックを含むリクエストは、Claude Code が原因を認識できない 400 または 422 の後に、それらを除いた形で再び届くことがあります。再試行が成功すると、以降のリクエストでもそれらは省略されます。

ゲートウェイ側で何も変更しなくても開発者のリクエストは引き続き機能し、MCP ツールは事前に読み込まれます。Claude Code は後でツール検索を再度試すため、ゲートウェイでは再び拒否されたリクエストとその再試行が見られることがあります。すべてのリクエストからこれらのフィールドを除外するには、開発者に ENABLE_TOOL_SEARCH=false を設定してもらってください。ツール検索自体については、Claude Code はゲートウェイが defer_loading フィールドと tool_reference ブロックをその anthropic-beta 値とともに転送することを想定しています。

プレリリース機能を無効化

ゲートウェイまたはそのアップストリームがプレリリースの anthropic-beta 値やそれと組み合わされるボディフィールドを拒否し、両方の半分を転送できない場合は、開発者に CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定してもらってください。この変数を設定すると、Claude Code はプレリリース機能とそれと組み合わされる anthropic-beta 値の送信を停止します。対象には次のものが含まれます：

  • コンテキスト管理とその context_management ボディフィールド
  • strict や defer_loading などのベータツールスキーマフィールド。標準の name、description、input_schema、cache_control ツールフィールドは残ります
  • 構造化出力の output_config.format フィールド。Claude Code v2.1.287 以降が必要です
  • output_config.task_budget フィールド
  • MCP ツール検索。このため、組織が管理設定を通じて有効に保たない限り、すべての MCP ツールが事前に読み込まれます

この変数はすべての anthropic-beta 値を削除するわけではありません。そのまま残るものには次のものがあります：

  • 拡張コンテキスト、インターリーブ思考、および努力の anthropic-beta 値（クラウドプロバイダーもこれらを受け入れます）
  • 最上位の output_config.effort フィールド。これを拒否するアップストリームについては、自動リトライとエラー転送を参照してください
  • 適応的推論の thinking フィールド（ベータヘッダーはありません）
  • 会話中のシステムメッセージを運ぶ role: "system" エントリ
  • サブスクリプション認証に必要な OAuth の anthropic-beta 値
  • 開発者が ANTHROPIC_BETAS または CLAUDE_CODE_EXTRA_BODY を通じて自分で追加したヘッダー値とボディフィールド

ホストプラットフォームが Claude Code を埋め込み、CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST を設定する場合、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS は Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、または Claude apps ゲートウェイ上のオートモードセッションが 分類器レビューをサーバーに要求するのを停止しません。そのレビューは anthropic-beta 値と safeguards リクエストフィールドを追加します。そこで停止するには CLAUDE_CODE_AUTO_MODE_SERVER=0 を設定してください。

Claude Code v2.1.227 以降では、組織は MCP ツール検索を管理設定を通じてこの変数の下で有効に保つことができます。このオーバーライドが有効な場合に Claude Code が送信する内容は、接続方法によって異なります：

  • HIPAA 設定のない直接接続、または ANTHROPIC_BASE_URL で設定されたゲートウェイを通じて接続している場合、Claude Code はツール検索ベータヘッダー、defer_loading ツールフィールド、および tool_reference ブロックを送信し続けます
  • クラウドプロバイダー、または Claude apps ゲートウェイを通じてサインインしている場合、オーバーライドは効果がありません
  • HIPAA 設定を受け取るセッションでは、上書きは効果がなく、ツール検索はオフのままです

Claude Code が送信する機能セットはリリース全体で増加します。現在のベータヘッダー文字列については、ベータヘッダーリファレンスを参照してください。観察されたリストに固定するのではなく、新しい Claude Code リリースに対してゲートウェイをテストしてください。

モデル検出

ANTHROPIC_BASE_URL が Anthropic Messages フォーマットを公開するゲートウェイを指す場合、Claude Code はスタートアップ時にゲートウェイの /v1/models エンドポイントをクエリし、返されたモデルを /model ピッカーに追加できます。あなたまたはあなたの管理者が modelPicker ラインアップで replaceBuiltInOptions を設定した場合、Claude Code はピッカーから検出されたモデルを非表示にします。

開発者は CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 を設定することで有効にします。独自の環境またはマネージド設定を通じて。検出はデフォルトでオフになっているため、共有 API キーでバックアップされたゲートウェイはすべてのユーザーにキーがアクセスできるすべてのモデルを表示しません。

検出が実行される場合

検出は Anthropic Messages フォーマットにのみ適用されます。以下の場合は実行されません：

  • ANTHROPIC_BASE_URL も設定されている場合でも、任意の CLAUDE_CODE_USE_* プロバイダー変数が設定されている
  • ANTHROPIC_BASE_URL が設定されていないか、api.anthropic.com を指している

検出は 非必須トラフィックがオフになっている 場合でも実行されます。リクエストはゲートウェイのみに送信されるためです。v2.1.257 より前では、非必須トラフィックがオフになっている間は検出は実行されませんでした。

リクエストとレスポンス

リクエストは 3 秒のタイムアウト付きの GET /v1/models?limit=1000 であり、リダイレクトはクレデンシャルがリダイレクトターゲットにリークされないように失敗として扱われます。/v1/models に遅く応答するか、リダイレクトするゲートウェイ（http から https へのリダイレクトでも）は検出を静かに失敗させます。設定されたベース URL で直接エンドポイントを提供してください。

遅いゲートウェイにより長い時間を与えるには、CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS を設定します。この変数には Claude Code v2.1.269 以降が必要です。

Claude Code は検出リクエストを以下の両方のクレデンシャルヘッダーで送信し、値が解決されないヘッダーは省略します。両方のヘッダーを送信するには Claude Code v2.1.248 以降が必要です。以前のバージョンは ANTHROPIC_AUTH_TOKEN が設定されている場合は Authorization のみを送信し、それ以外の場合は x-api-key のみを送信します。

  • Authorization：ANTHROPIC_AUTH_TOKEN をベアラートークンとして、またはそれ以外の場合は apiKeyHelper 値をベアラートークンとして。
  • x-api-key：Claude Code が解決した API キー（ANTHROPIC_API_KEY など）。ヘルパー値が唯一のクレデンシャルである場合、このヘッダーもそれを含むため、値は両方のヘッダーに到達します。

Claude Code は ANTHROPIC_CUSTOM_HEADERS からのすべてのヘッダーも送信します。カスタムヘッダーが空でない値を持つ場合、Claude Code はそれを同じ名前の組み込みヘッダーの代わりに送信し、名前を大文字と小文字を区別せずにマッチングします。

どちらのクレデンシャルヘッダーの値も解決されない場合、Claude Code は検出をスキップし、claude --debug セッションのデバッグログに [gatewayDiscovery] skipped 行を書き込みます。ANTHROPIC_CUSTOM_HEADERS を通じてのみクレデンシャルを提供する場合、Claude Code は検出をスキップします。

Claude Code はレスポンスの data 配列の各エントリから id、オプションの display_name、およびオプションの description を読み取ります：

{
  "data": [
    {
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "description": "Default model for everyday coding tasks"
    },
    { "id": "claude-opus-4-8" }
  ]
}

Claude Code は id が文字列内の任意の場所に claude または anthropic を含むエントリを保持し、大文字と小文字を区別せずにマッチングし、残りを無視します。vertex_ai/claude-sonnet-4-6 または bedrock/anthropic.claude-sonnet-4-5 などのプロバイダープレフィックス付き ID はフィルターを通過します。どちらの部分文字列も含まない ID は通過しません。v2.1.223 より前では、Claude Code は id が claude または anthropic で始まる場合のみエントリを保持し、プロバイダープレフィックス付き ID を非表示にしていました。

ピッカーエントリとキャッシング

ピッカーは、開発者が Claude Code で /model を実行するときに開く対話型モデルリストです。各検出されたエントリは、ゲートウェイが id と異なるものを送信する場合、display_name をその名前として使用します。それ以外の場合、エントリは Claude Code が id を認識する 場合はモデルの名前を表示し、認識しない場合は id を表示します。たとえば、id が my-gateway-claude-sonnet-4-6 で display_name がないエントリは Sonnet 4.6 として表示されます。

検出は availableModels マネージド設定 が許可するモデルのみを追加します。

各エントリはモデルの description も表示し、1 行に折りたたまれます。description がないエントリは代わりに「ゲートウェイから」と表示されます。v2.1.257 より前では、すべての検出されたエントリが「ゲートウェイから」と表示されていました。

検出された ID は、ピッカーに既に存在する行と一致する場合、独自の行を取得しません：

  • 同じ ID：検出された ID は既存の行の ID と正確に一致するか、2 つの ID は同じ Fable バージョンのスペルです。
  • 組み込みエイリアスと同じモデル：検出された明示的な ID が、組み込みエイリアスが現在解決されるモデルを指している場合、ピッカーはエイリアス行のみを表示します。たとえば、sonnet が claude-sonnet-5-5 に解決される間、検出された claude-sonnet-5-5 は sonnet 行に折りたたまれ、検出された claude-sonnet-5 は依然として独自の行を取得します。

結果は ~/.claude/cache/gateway-models.json にキャッシュされます。Windows では %USERPROFILE%\.claude\cache\gateway-models.json。各スタートアップで更新されます。CLAUDE_CONFIG_DIR を設定した場合、キャッシュはそのディレクトリの代わりにそのディレクトリの下に存在します。リクエストが失敗するか、ゲートウェイが /v1/models を実装しない場合、ピッカーは前回のスタートアップからのキャッシュリストまたは組み込みモデルリストにフォールバックします。ゲートウェイが検出フィルターと一致しないエイリアスの下で Claude モデルを提供する場合、開発者は モデル設定 変数を使用してそれらのエイリアスを手動で追加できます。

関連リソース

ゲートウェイドキュメントセットの残りと基礎となる API リファレンス：