CLAUDE_CODE_MAX_OUTPUT_TOKENSとは — 出力トークン上限を変える環境変数

CLAUDE_CODE_MAX_OUTPUT_TOKENSは何を変える変数か

CLAUDE_CODE_MAX_OUTPUT_TOKENSは、Claude Codeがほとんどのリクエストに設定する最大出力トークン数を上書きする環境変数です。既定値とモデルごとの上限は使用中のモデルによって異なります。設定した値がモデルの上限を超えていた場合、Claude Codeは上限まで切り下げます。

触る動機は主に2つです。ひとつは大規模なコード生成や長文ドキュメントを1回の応答で最後まで出したい場合、もうひとつは応答を短く抑えてコストと待ち時間を削りたい場合です。どちらの向きでも、この変数がモデルの物理的な上限を超えて効くことはありません。

手元のClaude Code v2.1.285でclaude --helpを確認すると、出力トークン上限を指定するコマンドラインフラグは見当たりません。設定手段は環境変数と、settings.jsonのenvキーの2つです。

上限はモデルで決まる

値の入れ方より先に確認したいのが、いまのモデルの天井です。この変数は天井の内側でしか動かせません。

Haiku 4.5は上位モデルの半分です。軽量モデルへ切り替えた直後に長い応答が途切れたら、まずこの上限差を疑えます。ゲートウェイ経由でモデルIDを認識できない状態では、明示しない限り32,000で頭打ちになります。どちらも、モデルの実力ではなく上限側の理由で切れている例です。

値の入れ方と、シェルとsettings.jsonが食い違うとき

指定は、シェルのexportか、settings.jsonのenvキーです。

export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
claude

チームに既定値として配るなら、リポジトリの.claude/settings.jsonに書いてコミットします。

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
  }
}

同じ変数をシェルとsettings.jsonの両方に書くと、settings.jsonの値が使われます。envの各エントリをClaude Codeがプロセス環境へ書き込み、シェルから引き継いだ値を置き換えるためです。ただし例外があります。Claude Desktopアプリやセルフホスト環境のランナーが起動したセッションでは、起動側が組んだ環境が優先されます。起動側がすでに設定している変数に限り、settings.jsonのenv値は無視されます。

反映されないときは、優先順位の高い別ファイルが同じキーを上書きしていないかを見ます。設定の全体像はClaude Code設定ガイドにあります。

上げると会話の自動要約(auto-compact)が早まる

見落とされがちな副作用がここです。auto-compactionとは、会話が長くなったときに過去のやり取りを自動で要約して詰め直す動作です。この変数を上げると、1回の応答のために確保されるコンテキストウィンドウの枠が広がり、compactionが起きるまでに使える実質のコンテキストが減ります。

compactionの発動位置そのものを動かしたいなら、この変数の担当ではありません。手段は3つあり、効き方が違います。

• /autocompact(v2.1.221以降): 値をユーザー設定のautoCompactWindowに保存し、現在のセッションにも反映します。managed設定など上位のスコープが同じキーを持つ場合、値は保存されるものの、セッションは上位側の値のままです。
• --autocompactフラグ: その起動だけ有効で、保存済みの設定は変わりません。v2.1.285のclaude --helpには--autocompact <auto|tokens>として「Auto-compact window size (auto, or 100k–1M tokens)」と出ます。
• CLAUDE_CODE_AUTO_COMPACT_WINDOW: 設定されている間は、コマンド・フラグ・設定のどれよりも優先されます。

落とし穴がひとつあります。/autocompactと--autocompactは500kや1Mのような接尾辞を受け付けますが、環境変数が受け付けるのは500000のような素の整数だけです。500kと書くと500と読まれ、下限の100,000に切り上げられます。

/autocompact系と違い、CLAUDE_CODE_MAX_OUTPUT_TOKENSは数値の書き方に寛容です(詳細は末尾の折りたたみ)。長時間セッションの管理はClaude 1Mコンテキストの実務活用で扱っています。

入力と出力の上限が衝突した場合の動きも決まっています。入力にmax_tokensを足した合計がコンテキストの上限を超えてリクエストが拒否されると、Claude Codeはmax_tokensを減らして再試行します。会話そのものがコンテキストをほぼ埋めていて減らしても収まらないときは、再試行をやめてcompactionに切り替えます。値を高く固定しても、その場でエラーになって止まるわけではありません。

思考予算(MAX_THINKING_TOKENS)との関係

拡張思考の予算を決めるMAX_THINKING_TOKENSは、この変数が決めた出力上限より1トークン小さい値までに切り下げられます。下限は1,024トークンです。CLAUDE_CODE_MAX_OUTPUT_TOKENSを極端に小さくすると、思考に回せる予算も狭まります。

ただし、この数字が実際に使われる範囲は限られます。Claude Codeは、適応的推論(adaptive reasoning)のモデルではMAX_THINKING_TOKENSの0以外の値を無視し、モデル側が思考の深さを決めます。Sonnet 5以降、Opus 4.7以降、Fable系は常に適応的推論です。Opus 4.6とSonnet 4.6は、CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1で適応的推論を切ったときだけ固定予算に戻り、そのときこの切り下げが効きます。

Haiku 4.5・Opus 4.5・Sonnet 4.5は適応的推論を持たないため、MAX_THINKING_TOKENSが常に固定予算として使われます。

自動の切り下げがあっても、思考予算が出力上限を上回ると次の400エラーで応答が返らない場合があります。

API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

公式のエラー解説は、対処としてCLAUDE_CODE_MAX_OUTPUT_TOKENSを思考予算より上へ上げることを挙げています。具体的な直し方は「Thinking budget exceeds」エラーの原因と対処法にまとめました。

長い応答が途切れたときの切り分け

まとめ

変数の値を疑う前に、/modelの表示でモデルとIDの認識状態を確かめるのが近道です。値を上げるのは長い出力が要る間だけに絞ると、auto-compactionの前倒しも避けられます。関連する変数はClaude Code環境変数リファレンス、モデルごとの仕様はClaude Opus 5の使い方と仕様にまとめています。Claude Code全体の設定はClaude Codeの完全ガイドから辿れます。