CLAUDE_CODE_EXTRA_BODYとは — リクエストボディを拡張する環境変数

CLAUDE_CODE_EXTRA_BODYは、Claude Codeが送るすべてのAPIリクエストボディのトップレベルに、指定したJSONオブジェクトをマージする環境変数です。Claude Codeが直接は公開していないプロバイダー固有のパラメーターを渡したいときに使います。何を変えるか、どう書くか、そしてバックグラウンドセッションにどう伝わるかを順に確認します。

CLAUDE_CODE_EXTRA_BODYが変えるもの

設定したJSONオブジェクトが、モデルへのリクエストごとにボディのトップレベルへ追加でマージされます。Claude Code自体が用意していないパラメーターを、サードパーティのAPI互換レイヤーやゲートウェイ向けに渡す用途で使う変数です。

export CLAUDE_CODE_EXTRA_BODY='{"custom_param": "value"}'
claude

似た役割のANTHROPIC_CUSTOM_HEADERSがリクエストヘッダーを拡張するのに対して、CLAUDE_CODE_EXTRA_BODYはリクエストボディを拡張します。ゲートウェイ側の認証や識別はヘッダーで、API呼び出しのパラメーター自体を増やしたいときはボディで、という役割分担です。ヘッダー拡張の書き方はANTHROPIC_CUSTOM_HEADERSとはで扱っています。

なぜ専用オプションでなく環境変数なのか

Claude Codeは、Anthropic APIおよびAmazon Bedrock・Vertex AI・Microsoft Foundryのような主要な提供元向けに、モデル選択・思考の深さ・出力トークン数といった主要なパラメーターを個別の環境変数や設定で公開しています。これらは利用頻度が高く、かつ挙動が提供元をまたいでおおむね共通しているからこそ、専用のオプションとして整備されていると考えられます。一方で、独自のAPI互換レイヤーを持つサードパーティのプロバイダーや、社内で構築したゲートウェイは、Claude Codeが把握していない拡張パラメーターを受け付けることがあります。そうした個別のニーズすべてに専用オプションを用意するのは現実的ではないため、CLAUDE_CODE_EXTRA_BODYは「任意のJSONをそのままボディへ足す」という汎用的な逃げ道として用意されています。典型的な用途は、Anthropic APIと互換のインターフェースを持つが独自の拡張パラメーターも受け付けるサードパーティのプロバイダーやゲートウェイに接続する構成で、Claude Code本体のオプションとして用意されていないパラメーターでも、この変数経由でリクエストボディに含められればプロバイダー側の拡張機能を利用できます(既存フィールドとの衝突については後述の「落とし穴」を参照してください)。専用オプションが増える前に汎用の逃げ道が用意されている構成は、他の環境変数にも見られる考え方で、Claude Code環境変数リファレンスでも同様の分類を確認できます。

バックグラウンドセッションでの伝播

claude agentsや--bgで起動するバックグラウンドセッションに対して、この変数がどう伝わるかにはバージョンによる違いがあります。

CLAUDE_CODE_USE_BEDROCKのようなクラウドプロバイダー選択の変数やANTHROPIC_DEFAULT_*_MODELのエイリアス変数と同じく、CLAUDE_CODE_EXTRA_BODYはディスパッチしたシェルの値をそのまま引き継ぎます。これは、同じくシェルの値を伝えるANTHROPIC_BASE_URLやANTHROPIC_CUSTOM_HEADERSより条件がゆるい伝わり方です。ゲートウェイ系の変数は「supervisorプロセスが起動時に捕捉した環境と一致しているか」「ディスパッチ先が同じディレクトリか」という2条件を満たさないと伝わりませんが、CLAUDE_CODE_EXTRA_BODYにはその制約がありません。バックグラウンドセッションの運用モデル全体はClaude Codeのagent viewで扱っています。

実際に起きた不具合から分かる注意点

CLAUDE_CODE_EXTRA_BODYは過去に、設定したフィールドの内容が原因でエラーになった実例があります。output_config.effortのようなフィールドをこの変数経由で設定すると、effortパラメーターに対応していないモデルや、Vertex AI経由でのサブエージェント呼び出しで400エラーが発生する不具合がv2.1.113で見つかり、修正されました。この事例が示すのは、追加したフィールドが「常にすべてのモデル・すべてのプロバイダー・すべての呼び出し経路(通常のリクエストとサブエージェントのリクエストを含む)で有効とは限らない」という点です。Claude Codeがすでに用意しているオプションと同じ効果を狙ってCLAUDE_CODE_EXTRA_BODYを使うより、Claude Code側の設定やフラグで対応できないか先に確認する方が、こうした経路依存のエラーを避けやすくなります。

落とし穴

• 不正なJSON: 値がパースできないJSONの場合の挙動は公式ドキュメントで明記されていません。意図した拡張が反映されない可能性があるため、設定後は実際にリクエストが通っているかを確認します
• 既存フィールドとの衝突: モデル名やメッセージなど、Claude Codeがすでに設定しているキーと同じ名前をCLAUDE_CODE_EXTRA_BODYで指定した場合、どちらが優先されるかは公式ドキュメントで明記されていません。独自の拡張キーに限定して使うのが安全な運用です
• プロバイダー側が未知のフィールドを拒否する: サードパーティのAPI実装によっては、想定外のトップレベルフィールドを含むリクエストをそのまま拒否することがあります。プロバイダー側の仕様を先に確認してから追加してください
• サブエージェント経由での指定を試みない: この変数はプロセス起動時のリクエスト全体に効く環境変数で、claude agents --jsonのようなセッション単位のスクリプト操作とは層が異なります。セッションを個別に操作する方法はclaude agents --jsonでバックグラウンドセッションを操作するにまとめています

ANTHROPIC_CUSTOM_HEADERSと組み合わせて使う場面

サードパーティのゲートウェイやAPI互換プロバイダーに接続する構成では、CLAUDE_CODE_EXTRA_BODYとANTHROPIC_CUSTOM_HEADERSを同時に使うことがあります。ゲートウェイ側が「このリクエストをどの契約・どのルーティング設定で処理するか」をヘッダーで判定し、モデル呼び出し自体のパラメーターをボディで受け取る、という役割分担です。

export ANTHROPIC_BASE_URL="https://your-provider.example.com"
export ANTHROPIC_CUSTOM_HEADERS="X-Provider-Auth: <認証キー>"
export CLAUDE_CODE_EXTRA_BODY='{"routing_hint": "low-latency"}'

この例では、認証と経路の指定はヘッダー側、モデル呼び出しの挙動に関わるパラメーターはボディ側に分けています。どちらの変数も「Claude Codeが直接は用意していない、プロバイダー固有の要求に応える」という点で共通していますが、対象がヘッダーかボディかで書き方も影響範囲も変わります。

チームで固定する — settings.jsonのenvブロック

サードパーティのAPI互換プロバイダーに接続する構成をチームで共有するなら、各メンバーがシェルへexportするより、プロジェクトのsettings.jsonに書いて配布した方が確実です。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-provider.example.com",
    "CLAUDE_CODE_EXTRA_BODY": "{\"custom_param\": \"value\"}"
  }
}

チーム共有の接続設定は.claude/settings.jsonに、認証キーのようなメンバーごとに異なる値は.claude/settings.local.jsonに分けて書くと、プロバイダー固有の秘密情報をリポジトリにコミットせずに済みます。設定ファイルの階層と優先順位はClaude Code settings.json完全ガイドにまとめています。

よくある質問

CLAUDE_CODE_EXTRA_BODYとANTHROPIC_CUSTOM_HEADERSはどちらを使うべきですか

拡張したいのがHTTPヘッダーならANTHROPIC_CUSTOM_HEADERS、APIリクエストのボディに独自パラメーターを含めたいならCLAUDE_CODE_EXTRA_BODYです。ゲートウェイの認証・識別はヘッダー側で扱うのが一般的です。

settings.jsonのenvブロックに書いても有効ですか

有効です。値をシェルへ都度exportしなくても、プロジェクトのenvブロックに書けば同じ効果になります。書き方の詳細はClaude Code環境変数リファレンスで扱っています。

Amazon BedrockやVertex AI経由でも使えますか

変数自体はAPIリクエストボディへのJSONマージという仕組みなので、接続先のプロバイダーを問わず適用されます。ただしプロバイダー側が未知のフィールドを許容するかどうかは別の話です。

複数のキーを一度に追加できますか

できます。1つのJSONオブジェクトの中に複数のトップレベルキーを含めれば、まとめてボディへマージされます。キーごとに別の環境変数を用意する仕組みではなく、1つの変数に1つのJSONオブジェクトを設定する形です。

JSONの書式が間違っているとエラーになりますか

パースできないJSONを設定した場合の挙動は公式ドキュメントで明記されていません。設定後に想定した拡張が反映されているか、実際のリクエストやプロバイダー側のログで確認しておくのが確実です。

v2.1.206より前のバージョンではどう動きますか

シェルでexportした値がバックグラウンドセッションに伝わらず、supervisorプロセスが起動時に持っていたコピーが使われていました。最新の挙動を前提にする場合は、v2.1.206以降を使っているか確認してください。

まとめ

CLAUDE_CODE_EXTRA_BODYは、Claude Codeの全APIリクエストボディのトップレベルへ任意のJSONをマージする環境変数です。プロバイダー固有のパラメーターを渡す用途に向き、ヘッダーを拡張するANTHROPIC_CUSTOM_HEADERSとは役割が分かれます。v2.1.206以降はディスパッチしたシェルの値がバックグラウンドセッションにもそのまま届き、この点はゲートウェイ関連の変数より条件がゆるくなっています。