CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTSとは — ゲートウェイの400を避ける設定

CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTSで止まるもの

CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTSは、Claude Codeが構造化出力(structured outputs)のために送るoutput_config.formatフィールドと、それと対になるanthropic-betaの値を送らなくする環境変数です。1を設定すると有効になります。対象はv2.1.288以降のClaude Codeです。

想定している場面は、ANTHROPIC_BASE_URLで指すLLMゲートウェイの上流が、このフィールドを拒否するケースです。Amazon BedrockやGoogle CloudのAgent Platformを上流にしたゲートウェイでは、output_configを名指しした400が返ることがあります。

止まるのは構造化出力の形式指定だけです。ほかのプレリリース機能は送られ続けます。この性質が、似た名前のCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASとの使い分けの軸になります。

v2.1.288で入った経緯

v2.1.288のchangelogには、セッションタイトル、メモリの呼び出し、プロンプトフックが、Mantleや構造化出力を拒否するゲートウェイの背後で失敗する不具合の修正が載っています。同じ項目に、この環境変数の追加も書かれています。

つまり、会話本体のリクエストではなく、Claude Codeが裏で投げる補助的なリクエストが構造化出力を使っていたことになります。セッションタイトルや記憶の呼び出しが失敗する、という形で症状が出ます。

一つ前のv2.1.287では、CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを設定していても、セッションタイトルとプロンプトフックのリクエストから構造化出力の形式が外れない問題が直っています。Bedrockを背にしたゲートウェイが、これを拒否していました。output_config.formatを外す機能そのものがv2.1.287でEXPERIMENTAL_BETAS側に入り、v2.1.288で単独の変数が加わった流れです。

ゲートウェイの互換性に関わる修正を、changelogの日付つきで並べます。

以前にも似た症状はありました。v2.1.122のchangelogには、Vertex AIやBedrockがinvalid_request_error: output_config: Extra inputs are not permittedを返し、セッションタイトルの生成などが失敗する問題の修正が載っています。セッションタイトルの生成が構造化出力の拒否で失敗する型は、v2.1.288より前にも直されています。

前後のリリースの全体像はv2.1.288のリリースノートにあります。

症状から原因をたどる

構造化出力を使うのは、会話本体ではなく補助リクエストです。症状はコマンドの失敗ではなく、周辺機能の不調として現れます。

• セッションのタイトルが付かない
• メモリの呼び出しが働かない
• プロンプトフックが失敗する

この3つが、400と同時にゲートウェイのログへoutput_configの名前を残していたら、この変数の出番です。本文の会話は普通に進むので、気づくのが遅れがちです。

上流の種類でも出方が変わります。プロトコル解説の表では、output_configを名指しした400が出やすいのは、Amazon BedrockとGoogle CloudのAgent Platformを上流にしたゲートウェイです。context_managementの400が出やすいのも、Anthropic形式のリクエストを受けてBedrockへ転送するゲートウェイです。

Claude Codeが拒否を受けて自動で再試行するのは、一部のフィールドだけです。

構造化出力の形式指定は、再試行の一覧に載っていません。だからこそ、拒否されたら変数で止める選択肢が必要になります。

EXPERIMENTAL_BETASとの違い

どちらを選ぶかは、ゲートウェイが拒否しているものが何かで決まります。

表のとおり、DISABLE_STRUCTURED_OUTPUTSはDISABLE_EXPERIMENTAL_BETASが止める項目のうち、output_config.formatの一つだけを止めます。EXPERIMENTAL_BETASのドキュメントには、MCPツール検索が無効になり、管理設定で維持しない限り全てのMCPツールが先読みされる、という副作用が書かれています。MCPサーバーを多く接続している環境では、この差が効いてきます。

拒否されたフィールドがoutput_config.formatだけだと分かっているなら、狭い変数から試すほうが失う機能が少なくて済みます。原因がはっきりしない400では、先に広い変数で症状が消えるかを見て、その後で狭い変数に絞る進め方もあります。

どちらの変数も、output_config.effortは止めません。effortを拒否する上流には別の仕組みがあり、Claude Codeは拒否を受けるとeffortを外して再試行し、Claude Codeを終了するまでそのモデルへの後続リクエストでも外し続けます。

設定のしかた

シェルから渡す方法と、設定ファイルのenvに書く方法があります。

export CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1
claude

組織で配るなら、settings.jsonのenvキーに書きます。

{
  "env": {
    "CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS": "1"
  }
}

envの値は文字列で書きます。~/.claude/settings.jsonは自分の全プロジェクト、.claude/settings.jsonはプロジェクトの全員、managed settingsは組織全体に効きます。ゲートウェイを使う全員が同じ症状になるなら、managed settingsでの配布が向いています。この変数の説明には、設定ファイルのenvブロックを無視するという注記はありません。環境変数の一般的な置き場所は環境変数の一覧記事にまとめています。

設定する前に確かめたいこと

この変数が必要になる条件は、ゲートウェイの上流がoutput_config.formatを拒否していることです。次の順で切り分けられます。

非対話モードのclaude -p --json-schemaを使う場合は、確認が一つ増えます。このオプションはスキーマに沿ったJSONを結果のstructured_outputフィールドに返す機能で、変数の説明はoutput_config.formatの送信停止だけを述べています。両者の関係は、どちらのドキュメントにも書かれていません。ゲートウェイ越しに--json-schemaを使うなら、変数を入れた状態で実際に流して、結果が返るかを確かめてください。

ゲートウェイ側で直せるなら、そちらが本筋です。ドキュメントは、フィールドとbeta値を対で転送し、ゲートウェイがリクエスト本文を書き換えないことを勧めています。片方だけが欠けると400になり、両方が欠けたときだけ機能が静かに切れるためです。変数は、転送の修正が間に合わないときの回避策という位置づけです。

エラー本文の扱いにも注意が必要です。Claude Codeの再試行は上流のエラー文言を照合して動くため、ゲートウェイは上流のエラーを書き換えずに返す必要があります。独自のエンベロープで包むと、ステータスコードが同じでも回復の経路が壊れます。包む場合は、メッセージにcapability_rejected:で始まる安定した印を入れる決まりです。

ゲートウェイ側で直すときの要点

変数に頼らず転送を直すなら、押さえる点は三つあります。

一つ目は、anthropic-*のリクエストヘッダーとリクエスト本文のフィールドを、許可リストで絞らずそのまま通すことです。Claude Codeはリリースのたびに新しいanthropic-betaの値や本文フィールドを足します。観測した一覧に固定したゲートウェイは、次の機能のヘッダーやフィールドを削り、その機能が入ったリリースで壊れます。ただし、BedrockやAgent Platformのように形式の違う上流では、スキーマの差を橋渡しするのがゲートウェイの仕事です。

二つ目は、本文を書き換えないことです。内容検査のために本文を書き換えたり伏せ字にしたりすると、ヘッダーを削ったときと同じく、本文とヘッダーの対が崩れて400になります。検査は変更なしで行います。

三つ目は、失敗の出方が機能で違う点です。拡張コンテキストとインターリーブ思考は本文のフィールドを持たず、ヘッダーだけで働きます。ヘッダーを削ると、エラーなしで機能が使えなくなります。対になる機能のほうは、片方だけ欠けると400、両方が欠けたときだけ静かに切れます。400が出ない不具合は、気づきにくいぶん厄介です。

構造化出力の形式指定は、この「対」の一つです。output_configの本文フィールドと、それ専用のanthropic-betaの値が一組で動きます。

設定しても直らないとき

この変数が外すのはoutput_config.formatと対のbeta値だけです。次のような400は、別の原因を疑います。

• context_management、strict、defer_loadingといった別フィールドの拒否。CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASの領分です
• output_config.effortの拒否。Claude Code側の再試行が働くため、通常は変数なしで収まります
• thinkingフィールドの拒否。アダプティブ推論にanthropic-betaのペアはなく、Opus 4.6とSonnet 4.6向けの別の変数があります
• ANTHROPIC_BETASやCLAUDE_CODE_EXTRA_BODYで自分が足した値。これらはEXPERIMENTAL_BETASでも外れません

ゲートウェイ側の互換性を全体で見直したいときは、LLMゲートウェイ互換性の解説が症状別の表を持っています。接続の初期設定はゲートウェイへの接続手順から始められます。

まとめ

CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1は、output_config.formatだけを狙って外すための変数です。拒否されているフィールドが構造化出力だけなら、この変数で十分です。複数のフィールドが拒否されるならCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASを検討します。ただし後者はMCPツール検索も止めます。