Codex CLIの出力トークンを絞るconfig.toml設定まとめ ── verbosity・reasoning effort・自動圧縮の使い分け

OpenAIの社内データによると、Codexの出力トークン中央値（1回のやり取りで生成する量の代表値）は2025年11月から2026年6月の7カ月で、Research部門で56倍、Customer Support部門で32倍、Engineering部門で27倍に増えたという。利用者が増えただけでなく、1回のやり取りで生成する量そのものが膨らんでいる。

同じタイミングでCodex CLIに追加された「/fast」モードは生成速度を最大1.5倍に上げる機能だが、出力量そのものは減らさない。速度と出力量は別軸の問題だ。

トークン消費が増えている以上、そもそもの出力量をどう制御するかのほうが実務では重要になる。~/.codex/config.tomlの設定キーを整理しておく。

config.tomlの7つの設定キー

Codex CLIは~/.codex/config.tomlで出力量に関わる設定を細かく指定できる。設定キーは大きく3グループに分かれる。

出力内容の制御

設定項目	値	役割
`model_verbosity`	low / medium / high	最終テキスト出力の詳細度。Responses API系プロバイダのみ有効、Chat Completions系では無視される
`hide_agent_reasoning`	true / false	推論イベント（思考過程の表示）をすべて非表示にする。CIパイプラインで雑音を消したいときや、JSONLダッシュボードが「ツール呼び出しと最終応答だけ」を必要とするときに使う
`show_raw_agent_reasoning`	true / false	モデルが生成する生の推論内容をそのまま表示する。エージェントがなぜそのアプローチを選んだのかをデバッグするときに便利

hide_agent_reasoningとshow_raw_agent_reasoningを両方trueにすると矛盾するが、その場合はhide_agent_reasoningが優先される。

推論プロセスの制御

設定項目	値	役割
`model_reasoning_effort`	minimal / low / medium / high / xhigh	推論に使うトークン量。高いほど精度は上がるが遅く高コストになる
`plan_mode_reasoning_effort`	同上	`/plan`コマンド実行時だけ使う推論レベル。実行時のeffortとは独立に指定できる。未設定なら実行時effortより1段階上のプリセットが自動で使われる
`model_reasoning_summary`	auto / concise / detailed / none	推論過程の要約表示。`none`にすると要約自体を生成しなくなりコスト削減になる

コンテキスト利用効率の制御

設定項目	値	役割
`tool_output_token_limit`	トークン数（推奨12,000）	シェルコマンドやファイル読み込みなど、ツール実行結果を履歴に残す際の上限。低くするとコンテキストは節約できるが、大きなログや長いファイルの中身が途中で切られて見落としが起きる
`model_auto_compact_token_limit`	トークン数	セッションの自動圧縮が発動する閾値。デフォルトはコンテキストウィンドウの85〜90%（出力トークン分を引いた値）。GPT-5.4の標準コンテキストだと約167,000トークン相当。低くすると早めに圧縮されて余裕を保てるが、その分セッション序盤の文脈を失いやすい

自動圧縮が走ると、それまでの会話全体をモデルに要約させ、元の履歴を要約に置き換える。圧縮後は直近で編集したファイルを最大5個・合計5万トークンまで自動で読み直し、作業を再開できるようにオリエンテーション用のメッセージが挿入される。任意のタイミングで/compactを打てば手動でも圧縮できる。

model_verbosityとmodel_reasoning_effortは別の設定だ。前者は「最終回答の書きぶり」、後者は「回答にたどり着くまでの思考の量」を制御する。名前が似ていて混同しやすいが、両方を絞って初めて出力トークン全体が減る。

effortを上げると何倍コストがかかるか

model_reasoning_effortのレベルごとに、mediumを基準にした推論トークンの目安が示されている。

レベル	目安倍率（medium比）	向いているタスク
minimal	約0.1倍	単純なリネーム・フォーマット・1行修正
low	約0.3倍	ボイラープレート生成、定型的なデータ変換
medium（デフォルト）	1倍	通常のインタラクティブな開発作業。OpenAIが「日常使い」として推奨
high	約3〜5倍	複数ファイルのリファクタ、複雑なデバッグ、アーキテクチャの意思決定
xhigh	約8〜15倍	長時間の自律タスク、難しいアルゴリズム問題、セキュリティ監査

この倍率はあくまで目安で、正確な乗数はモデル依存で公開されていない。ただ、xhighがmediumの8〜15倍というオーダー感さえ知っていれば、「とりあえずxhighにしておく」がどれだけ高コストな選択かは分かる。ちなみにGPT-5.1-Codex-Maxは同じmediumのeffortでも、従来より思考トークンを30%少なく使いながら同等以上の性能を出すとされている。モデル側の改善でも効率は変わる。

サブエージェント構成では親と子でeffortを分ける

複数のサブエージェントを使うワークフローでは、effortの使い分けが特に効いてくる。基本パターンは「親エージェント（オーケストレーター）はhigh〜medium、子エージェント（実行役）はlow〜minimal」。

Planner（計画役）: high。計画の質がその後の実装全体に影響するため
Implementer（実装役）: low。タスクがすでに明確に定義されているため
Tester（テスト役）: low。機械的な作業のため
Reviewer（レビュー役）: high。セキュリティ観点の見落としを避けるため

全工程をmediumで統一する場合と比べて、このパターンでトークン消費を50〜70%減らせるという。オーケストレーターがすでに難しい思考を済ませたあとに、実行担当へ明確な指示だけ渡すなら、実行担当は高いeffortを持つ必要がない、という理屈だ。

TUIショートカットとプロファイルでその場調整

TUI v0.128以降では、セッション中にAlt+,で推論レベルを下げ、Alt+.で上げるショートカットが追加された。/effort highのようにスラッシュコマンドで直接指定することもできる。設定ファイルを都度書き換えなくても、簡単なタスクは低いeffortのまま流し、複雑な箇所だけその場で上げるという運用がキーボードだけで完結する。地味だが、いちいち設定ファイルを開き直す手間を考えると効果は大きい。

一回だけ変えたいときは-eフラグでも指定できる。

1
2
codex -e high "Refactor the auth module to use JWT"
codex -e minimal "Add a docstring to this function"

プロファイルで用途別に使い分ける

config.tomlには[profiles.名前]でプロファイルを複数定義できる。用途ごとに設定一式を切り替えられるので、毎回-cや-eで細かく指定する必要がない。具体的な例をいくつか紹介する。

CI/CDパイプライン向け（出力は最小限、雑音なし）：

1
2
3
4
5
6
[profiles.ci]
model_verbosity = "low"
model_reasoning_effort = "medium"
model_reasoning_summary = "none"
hide_agent_reasoning = true
tool_output_token_limit = 8000

設計討論など、じっくり探索したいとき（冗長性・推論の透明性を最大化）：

1
2
3
4
5
6
[profiles.explore]
model_verbosity = "high"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
show_raw_agent_reasoning = true
model_auto_compact_token_limit = 160000

長時間のリファクタリングセッション向け（計画は深く、実行は効率的に）：

1
2
3
4
5
6
7
[profiles.refactor]
model_verbosity = "low"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"
model_reasoning_summary = "concise"
tool_output_token_limit = 10000
model_auto_compact_token_limit = 120000

コストを切り詰めたい個人開発者向け（小型モデル＋最低限の推論）：

1
2
3
4
5
6
7
[profiles.frugal]
model = "gpt-5.4-mini"
model_verbosity = "low"
model_reasoning_effort = "low"
model_reasoning_summary = "none"
hide_agent_reasoning = true
tool_output_token_limit = 6000

codex --profile ci exec "テストスイートを実行し、失敗を報告"のように--profileで呼び分ける。

よくある失敗

effort設定でよくやりがちな失敗は5つある。

すべてをhighで実行してしまう。ルーチンタスクでコストが3〜5倍に膨らむ
プランモードをmediumのままにしてしまう。計画の質は実装全体に複合的な影響を与えるので割に合わない
xhighを既定値にしてしまう。xhighは特定の難問向けの専用ツールで、常用するものではない
プロファイルを使わず毎回-eフラグで指定する。習慣にするならプロファイル化したほうが楽
サブエージェント全部に同じeffortを使う。オーケストレーターはhigh、実行担当はlowという非対称のほうがコスト効率がいい

自分がよくやりそうなのは1番と4番だ。効果が分かっていても、面倒でつい「とりあえずhighのまま」で流してしまう。

使い分けの目安

日常的な単純作業（ファイル整理、簡単なリファクタ）はmodel_reasoning_effortをlow〜medium、model_verbosityもlowで十分なことが多い。込み入った設計判断やデバッグではhigh〜xhighに上げ、model_reasoning_summaryをdetailedにして思考過程を確認する。これが基本の使い分けだと思う。

/fastは「同じ精度のまま速度だけ欲しい」場面向けの機能であり、出力量そのものを減らしたいなら効果がない。速度とコストは別の話だという点は、忘れやすいので分けて考えたほうがいい。

効果を実測する

v0.125以降、codex exec --jsonはターン完了イベントで入力・出力・推論トークン数を報告する。jqで絞り込めば、設定を変えたときの実際の消費量を数字で確認できる。

1
2
codex --profile ci exec --json "src/auth.ts の失敗テストを修正" 2>/dev/null \
  | jq 'select(.type == "turn.completed") | .usage'

同じタスクをプロファイルを変えて何度か流し、出てくる数字を比べれば、自分の作業に対する「effortを上げた分だけの価値があったか」が体感ではなく実測で分かる。

参考

この記事は Claude Sonnet 5 が執筆しました。