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

CLAUDE_CODE_MAX_OUTPUT_TOKENSは何を変える変数か

CLAUDE_CODE_MAX_OUTPUT_TOKENSは、Claude Codeがほとんどのリクエストに設定する最大出力トークン数を上書きする環境変数です。既定値とモデルごとの上限は使用中のモデルによって異なり、Claude Codeが認識できないモデルID(ゲートウェイ固有の名前など)では32,000がデフォルトになります。設定した値がモデルの上限を超えていた場合、Claude Codeは自動的に上限まで切り下げます。

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

モデルごとの最大出力トークン

Claude Codeで使えるモデルの出力上限は次のとおりです(同期のMessages API基準)。

CLAUDE_CODE_MAX_OUTPUT_TOKENSにこれらの値より大きい数字を入れても、実際に使われるのはモデルの上限までです。逆に言えば、この変数の役割は「上限までの範囲でどこに天井を置くか」を決めることに限られ、モデル自体の性能を底上げするものではありません。Fable 5・Opus 5・Sonnet 5はいずれも128,000トークンで横並びですが、Haiku 4.5はその半分の64,000トークンです。軽量モデルへ切り替えた直後に長い応答が途切れる場合は、まずこの上限差を疑うと切り分けが早くなります。

設定方法

シェルまたは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側が優先されます。Claude Codeは起動時と設定ファイル変更時にenvの値をプロセス環境へ反映し、シェルから引き継いだ値を上書きするためです。

書く場所は影響範囲で選びます。個人の全プロジェクトに反映させたいだけなら~/.claude/settings.jsonで足ります。プロジェクトのメンバー全員に同じ上限を配りたい場合は、先の例のように.claude/settings.jsonへ書いてリポジトリにコミットします。組織として上限を一律に強制したいなら、管理者が配布するmanaged設定に書く方法もあり、これは個人・プロジェクトどちらの設定よりも優先されます。個人だけそのプロジェクトで例外的に値を変えたい場合は、gitignore済みの.claude/settings.local.jsonを使う選択肢もあります。

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

見落とされがちな副作用がここです。auto-compactionとは、会話が長くなったときに過去のやり取りを自動で要約して詰め直す動作のことです。CLAUDE_CODE_MAX_OUTPUT_TOKENSを引き上げると、1回の応答にコンテキストウィンドウのうち予約される枠が広がります。結果として、compactionが発動するまでに使える実質的なコンテキスト量は減ります。長い応答を出したいからと大きめの値に固定していると、通常より早い段階で会話が要約される形になりやすくなります。

auto-compactionが発動するタイミング自体を調整したいなら、この変数ではありません。CLAUDE_CODE_AUTO_COMPACT_WINDOWや/autocompactコマンドを使います。長時間セッションでのコンテキスト管理はClaude 1Mコンテキストの実務活用で扱っています。

たとえばSonnet 5(128,000トークンが上限)を使うセッションでCLAUDE_CODE_MAX_OUTPUT_TOKENSを意図せず低い値に固定していたとします。大きめのリファクタリングで長いコードを一気に書かせようとすると、応答が途中で打ち切られたように見えることがあります。逆にゲートウェイ経由でモデルIDをClaude Codeが認識できない状態のまま長い出力を求めると、既定の32,000トークンで頭打ちになります。どちらの症状も「モデルの実力ではなくこの変数の値で頭打ちになっている」という共通点があるため、長い応答が不自然に途切れたときはまずこの変数の現在値を疑うと切り分けが早くなります。

MAX_THINKING_TOKENSとの関係

拡張思考(extended thinking)を使っている場合、MAX_THINKING_TOKENSはこの変数が決めた出力上限より1トークンでも大きくならないよう調整されます。この切り下げはClaude Code側が自動で行い、下限は1,024トークンです。つまりCLAUDE_CODE_MAX_OUTPUT_TOKENSを極端に小さくすると、思考に割ける予算もそれに引きずられて狭まります。

Amazon BedrockやGoogle CloudのAgent Platformなど、この自動調整が効かない環境では事情が異なります。MAX_THINKING_TOKENSを出力上限より高く設定してしまうと、max_tokens must be greater than thinking.budget_tokensのエラーで応答が返らなくなります。この症状の具体的な直し方は「Thinking budget exceeds」エラーの原因と対処法にまとめました。

使い分けの目安

モデル上限より変数の値を優先しない設計をどう読むか

CLAUDE_CODE_MAX_OUTPUT_TOKENSが「モデルの上限を超えたら黙って切り下げる」という挙動を選んでいるのは、利用者にとって安全側に倒した設計だと考えられます。仮に上限を超えた値をそのままAPIへ送っていたら、リクエストごとにエラーが返り、動かなくなってから初めて上限を知るという体験になっていたはずです。切り下げる方式なら、多少大きすぎる値を入れても壊れずに「使えるところまで使う」動作になります。値を大きめに書いておいて実害がないのはこのためですが、裏を返せば「意図した上限で動いているか」をエラーでは検知できないということでもあります。長い応答が想定より短く終わる違和感があれば、まず現在のモデルと変数の値を突き合わせて確認するのが確実です。

よくある質問

モデルを切り替えたら値も見直す必要があるか

見直しが必要です。CLAUDE_CODE_MAX_OUTPUT_TOKENSはモデルの上限を超えないよう自動で切り下げられます。ただし逆方向は自動では直りません。低いモデルの上限に合わせて設定していた値を、上限の高いモデルへ切り替えたあとも使い続けると、そのモデル本来の出力量を引き出せません。モデルを変えたタイミングで一度値を見直すと無駄がありません。

出力を短くしてコストを抑えたいだけなら他に方法はあるか

CLAUDE_CODE_MAX_OUTPUT_TOKENSを下げるのも一つの方法です。ただしタスクの複雑さに応じて自動でコストを抑えたいなら、effortレベルをlowやmediumに下げる方が実用的な場面が多くあります。出力トークンの天井を決める本変数と、そこに至るまでの思考の深さを決めるeffortレベルは役割が違うため、状況に応じて併用します。

settings.jsonに書いたのに反映されないときは

まず.claude/settings.local.jsonや組織のmanaged設定など、優先順位の高い別の設定ファイルが同じキーを上書きしていないかを確認します。複数のファイルに同じ環境変数を書いていると、狙った値ではなく優先順位の高いファイルの値が使われます。設定の全体像はClaude Code設定ガイドで確認できます。

まとめ

CLAUDE_CODE_MAX_OUTPUT_TOKENSは1リクエストあたりの最大出力トークンを上書きする環境変数です。実際に効く範囲はモデルごとの上限(Fable 5・Opus 5・Sonnet 5なら128,000、Haiku 4.5なら64,000)までに限られます。値を上げると長い応答を最後まで出力できる一方、コンテキストウィンドウの予約枠が広がりauto-compactionが早まる副作用があります。拡張思考を使う場合はMAX_THINKING_TOKENSの上限とも連動するため、両者をセットで確認するのが安全です。関連する変数の全体像はClaude Code環境変数リファレンス、モデルごとの仕様はClaude Opus 5の使い方と仕様で確認できます。