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

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

CLAUDE_CODE_EXTRA_BODYは、Claude CodeのAPIリクエストボディにJSONを追加でマージする環境変数です。用途・書き方・バックグラウンドセッションへの伝播条件をまとめます。

読了目安 約10分

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は拡張する場所が違います。

くらべる

ヘッダーとボディの違い

リクエストヘッダー

ANTHROPIC_CUSTOM_HEADERS

Name: Value形式で書き、複数のヘッダーは改行で区切ります。ヘッダーに使えない文字(曲がった引用符やゼロ幅スペースなど)が入っていると、v2.1.227以降はリクエストがエラーになります。書き方はANTHROPIC_CUSTOM_HEADERSとはにあります。

リクエストボディ

CLAUDE_CODE_EXTRA_BODY

JSONオブジェクトを1つ書き、トップレベルへマージします。API呼び出しのパラメーターそのものを増やしたいときの変数です。

バックグラウンドセッションに値が届く条件

claude agentsや--bgで起動したバックグラウンドセッションは、ディスパッチしたシェルでexportしたCLAUDE_CODE_EXTRA_BODYを引き継ぎます。同じ扱いになるのは、CLAUDE_CODE_USE_BEDROCKのようなクラウドプロバイダーの選択と、ANTHROPIC_DEFAULT_*_MODELのエイリアスです。

ゲートウェイ関連の変数は条件が付きます。シェルでexportしたANTHROPIC_BASE_URLは、ANTHROPIC_CUSTOM_HEADERSや資格情報と一緒に、次の2段の条件を両方満たしたときにだけ届きます。

  • supervisor(バックグラウンドセッションを束ねる常駐プロセス)が、同じゲートウェイをexportしたシェルから起動されている
  • 自分のセッションを←か/backgroundでバックグラウンドへ送る、いまいるディレクトリへ新しいセッションをディスパッチする、いまいるディレクトリで停止中のセッションに接続または返信して起こす、のいずれか

ゲートウェイの値を確実に渡す方法は、シェルでなく設定ファイルのenvブロックに置くことです。バックグラウンドセッションは動かすディレクトリの設定を読むため、envの値がそのまま適用されます。バックグラウンドセッション全体の運用はClaude Codeのagent viewで扱っています。セッションをスクリプトから操作する方法はclaude agents --jsonでバックグラウンドセッションを操作するにあります。

バージョンごとの変更と不具合

この変数に関わる変更は、changelogに3件あります。

バージョン

CLAUDE_CODE_EXTRA_BODYの変更履歴

  1. v2.1.113(2026年4月17日)effort指定が400エラーを起こす不具合を修正

    output_config.effortを載せると、effortに対応しないモデルへのサブエージェント呼び出しやVertex AIで400エラーになっていました。

  2. v2.1.206(2026年7月9日)バックグラウンドセッションにも届くように

    それまでは、シェルでexportした値が無視され、supervisorが引き継いだコピーが使われていました。

  3. v2.1.273(2026年9月15日)/bugと/feedbackの報告から除外

    報告に含まれるのはモデルの挙動に関わる項目(モデル・システムプロンプト・ツール)だけになり、CLAUDE_CODE_EXTRA_BODYのフィールドは載りません。

v2.1.113の例が示すのは、同じキーでも、モデルや呼び出し経路によっては受け付けられない場合があることです。Claude Codeの設定やフラグで同じ効果が出せるパラメーターは、そちらを先に使うという選択肢があります。

ベータ機能を先取りするときの組み合わせ

ANTHROPIC_BETASは、anthropic-betaヘッダーに値を足す環境変数で、複数の値はカンマで区切ります。Claude Codeは必要なベータ値をすでに送っているため、使いどころはAnthropic APIのベータにClaude Codeが対応する前に参加したいときです。--betasフラグがAPIキー認証を要するのに対して、この変数はClaude.aiのサブスクリプションを含むどの認証方式でも使えます。

ベータがヘッダーだけでなくボディのフィールドも求める場合は、ヘッダー側をANTHROPIC_BETAS、ボディ側をCLAUDE_CODE_EXTRA_BODYで足す形になります。ゲートウェイを挟むなら、ヘッダーとボディの両方を通す必要がある点は次の節のとおりです。

ゲートウェイの400は自前のキーか組み込みのキーか

ANTHROPIC_BASE_URLで指したゲートウェイには、Claude Codeがapi.anthropic.comへ送るのと同じベータヘッダーとボディのフィールドが届きます。組み込み機能が足すボディのフィールドはベータヘッダーと対で動くので、片方だけ落とすゲートウェイでは400が返ります。たとえばcontext_managementやoutput_configは、Anthropic形式のリクエストをAmazon Bedrockへ転送するゲートウェイでExtra inputs are not permittedになりやすい組み込みのフィールドです。

ベータや版を運ぶ場所は、ゲートウェイが受け付けるAPI形式で変わります。

API形式選ぶ変数そのまま転送すべき項目
Anthropic Messages選ぶ変数ANTHROPIC_BASE_URLそのまま転送すべき項目anthropic-betaとanthropic-versionのヘッダー
Amazon Bedrock InvokeModel選ぶ変数ANTHROPIC_BEDROCK_BASE_URLとCLAUDE_CODE_USE_BEDROCK=1そのまま転送すべき項目anthropic_betaとanthropic_versionのボディフィールド
Google CloudのAgent Platform rawPredict選ぶ変数ANTHROPIC_VERTEX_BASE_URLとCLAUDE_CODE_USE_VERTEX=1そのまま転送すべき項目anthropic-betaとanthropic-versionのヘッダーと、anthropic_versionのボディフィールド

ゲートウェイの運用側には、Anthropic形式の上流へ転送するなら、見知ったフィールドだけを許可リストで通さないという指針があります。Claude Codeはリリースのたびにヘッダーとボディのフィールドを増やすため、固定の一覧で絞ると次の機能が壊れるからです。CLAUDE_CODE_EXTRA_BODYで足したキーが届かないときも、途中でボディを書き換えるゲートウェイがないかを疑う価値があります。内容検査のために本文を書き換えたりマスクしたりすると、ヘッダーとボディの対が崩れて、削った場合と同じ400になります。

400が出たときの切り分けは、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1が足がかりになります。この変数は、プレリリース機能のヘッダーとそれに対のボディフィールドを送らなくします。ただしANTHROPIC_BETASとCLAUDE_CODE_EXTRA_BODYで自分が足した値は、この変数を設定しても消えずに残ります。

  • 設定すると400が消える: 原因は組み込みのフィールドで、自前のキーは無関係です
  • 設定しても400が続く: 自分で足したキーのほか、この変数が残すoutput_config.effortなども候補です

送られたボディの中身を見る

追加したキーが実際にボディへ載っているかは、生のAPIボディをファイルに書き出して見られます。次の変数でボディが<dir>/<uuid>.request.jsonに省略なく保存されます。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=console
export OTEL_LOG_RAW_API_BODIES="file:$PWD/bodies"
claude

OTEL_LOG_RAW_API_BODIESは、シェル・ユーザー設定・managed settingsのどれかに書きます。プロジェクトとローカルの設定に書いても無視されます。ボディには会話履歴がすべて入るので、検証が済んだら外します。v2.1.274以降は、リクエストとレスポンスのボディイベントが同じrequest_body_idを持つので、どのリクエストにどの応答が返ったかを突き合わせられます。

追加キーを使うときの落とし穴

  • 不正なJSON: パースできない値を入れたときの挙動は、環境変数リファレンスに書かれていません。設定後は、リクエストが通るかを実際に試します
  • 既存フィールドとの衝突: モデル名やメッセージなど、Claude Codeがすでに設定しているキーと同じ名前を指定したときの優先順位も、同じページには載っていません。独自の拡張キーに絞るのが無難です
  • プロバイダーが未知のキーを受け付けるか: 追加したキーを受け付けるかどうかは接続先のAPIが決めます。先にプロバイダー側の仕様を見ておきます
  • 設定ファイルでの引用符: settings.jsonでは値が文字列になるので、JSONの二重引用符は\"とエスケープします

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

サードパーティのAPI互換プロバイダーへの接続をチームで揃えるなら、プロジェクトのsettings.jsonに書いて配る方法があります。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-provider.example.com",
    "ANTHROPIC_CUSTOM_HEADERS": "X-Provider-Auth: <認証キー>",
    "CLAUDE_CODE_EXTRA_BODY": "{\"custom_param\": \"value\"}"
  }
}

共有する接続設定は.claude/settings.json、メンバーごとに違う認証キーは.claude/settings.local.jsonに分けると、秘密の値をリポジトリにコミットせずに済みます。設定ファイルの階層と優先順位はClaude Code settings.json完全ガイドにまとめています。envに置ける変数の一覧はClaude Code環境変数リファレンスを参照してください。

ゲートウェイを併用しているときは、/statusで使われているベースURLと資格情報の出どころを見られます。追加したキーの届き先を疑う前に、接続先そのものを確かめておけます。

シェルでexportする場合とenvブロックでは、効き方が次のように分かれます。

くらべる

シェルのexportとenvブロック

起動したシェルごと

シェルでexport

そのシェルから起動したセッションに効きます。

設定ファイルごと

settingsのenv

同じ名前の変数がシェルにあっても、envの値が上書きします。複数の設定ファイルが同じ変数を持つときは、優先順位が高い側が勝ちます。プロジェクトの設定の値は、フォルダーを信頼してから適用されます。Claude Desktopアプリやself-hosted environmentのrunnerが起動したセッションでは、その起動環境が設定済みの変数について、設定ファイルの値は無視されます。

よくある質問

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

環境変数リファレンスの説明は「すべてのAPIリクエストボディ」へのマージで、接続先は限定されていません。v2.1.113の修正にもVertex AIが含まれています。

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

できます。1つのJSONオブジェクトに複数のトップレベルキーを入れれば、まとめてボディへマージされます。キーごとに変数を分ける仕組みではありません。

まとめ

APIのパラメーターを増やしたいならCLAUDE_CODE_EXTRA_BODY、ヘッダーならANTHROPIC_CUSTOM_HEADERSと、拡張する場所で使い分けます。ゲートウェイ経由で400が出たら、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1で、組み込みのフィールドが原因か自前のキーが原因かを切り分けられます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →