Codex CLIのサブエージェント待機でトークンを無駄遣いしないための設定

Posted on 2026/09/22

CodexでAstraを使う際、サブエージェントの完了待ちをしているだけなのに利用枠を消費してしまう、という話を見かけました。

モデルそのものの消費量だけでなく、Codexが「まだ終わっていないかな？」と短い間隔でモデルを呼び出し直すことも原因になり得る、という話です。
それなら設定で抑えられるところは抑えておきたい、と思い、Codex CLIの設定を変更しました。

先に書いておくと、今回は設定を追加してCLIが読み込めることを確認したところまでです。
自分の環境で利用枠が何割減った、という効果測定はまだしていません。

確認日は2026-09-22、手元のCodex CLIは 0.155.1 です。

待っているだけなのに、なぜ消費するのか

サブエージェントに作業を任せた親エージェントは、wait_agent で通知を待てます。
ただ、この待機が短時間でタイムアウトすると、親モデルへ制御が戻り、また待機を指示する、という流れになり得ます。

サブエージェントに作業を依頼
  ↓
30秒待機
  ↓
タイムアウトして親モデルを呼び出す
  ↓
まだ作業中なので、もう一度30秒待機
  ↓
……

新しい情報が無いのに、親モデルが同じようなコンテキストを受け取って判断し直すのはもったいないですね。

この問題に関係するIssueとして、Raise the default wait_agent deadline from 30 seconds to 5 minutes #36379 があります。
30秒の既定値を延ばして、タイムアウトだけを理由とするモデルの再呼び出しを減らそう、という提案です。

ただし、入力トークン数が増えた分だけ、そのまま同じ割合で利用枠が減る、とまでは言えません。
キャッシュされた入力なども区別する必要があるので、今回は「不要な呼び出しを減らすための設定」と捉えています。

25分待機しても、完了通知はすぐ返る

最初は「25分も待つ設定にしたら、作業が終わっても25分間返事が来ないのでは？」と思いましたが、そういう意味ではありません。

V2の wait_agent は通知を待つ仕組みです。
サブエージェントの完了やメッセージ、ユーザーからの追加入力があれば、期限前でも待機から復帰します。
例えば3分後に完了通知が来れば、その時点で待機が終わります。

25分というのは、通知が来ない場合に、タイムアウトして親モデルへ制御を戻すまでの時間です。
この挙動は、前述のIssueと、V2のwait_agent実装で確認できます。
リンク先の main は今後変更される可能性があります。

もちろん、子の作業が止まっていて通知も来ない場合には、親が再確認するまでの時間も長くなります。
長くすればするほどよい、というわけでもなさそうです。

config.tomlに追加した設定

ユーザー設定の ~/.codex/config.toml に、次を追加しました。
Windowsで通常の場所を使っている場合は $env:USERPROFILE\.codex\config.toml です。

後から変更理由を思い出せるよう、Issue番号とURLもコメントに残しました。

# 確認日: 2026-09-22 / ローカル確認: Codex CLI 0.155.1
# サブエージェント待機中の短周期ポーリングによる
# 不要なモデル呼び出しを減らすため、V2の待機時間を延長する。
#
# 関連issue（問題報告・改善提案であり、削減効果の保証ではない）:
# #36379: 30秒の既定待機によるモデル再呼び出しと、通知による早期復帰
# https://github.com/openai/codex/issues/36379
# #41875: 待機時間の延長提案と、V1にはV2設定が適用されない点
# https://github.com/openai/codex/issues/41875
#
# 対象はV2のwait_agent。write_stdin等のコマンド待機は対象外。
[features.multi_agent_v2]
enabled = true
wait_agent_enabled = true

# 最低10分・既定25分・最大30分を当環境の初期値として採用。
# 完了・メッセージ等の通知があれば、期限前でも復帰する。
# 通知がない場合の親による再確認は遅くなるため、運用後に見直す。
min_wait_timeout_ms = 600000
default_wait_timeout_ms = 1500000
max_wait_timeout_ms = 1800000

すでに [features.multi_agent_v2] がある場合は、セクションを重複させず既存の設定を編集します。

単位はミリ秒です。
default_wait_timeout_ms はモデルが待機時間を指定しなかった場合の値、min_wait_timeout_ms はモデルが短い時間を指定しても適用される下限です。
今回の設定なら、30秒を指定しても最低10分の待機期限になります。ただし、前述のとおり通知があれば早く戻ります。
max_wait_timeout_ms は指定できる上限で、確認した実装では上限を超える指定はエラーになります。

10分・25分・30分は、今回自分の環境で試す値です。OpenAI公式の推奨値、というわけではありません。

また、これはMulti-Agent V2向けの設定なので、enabled = true も含めています。
Align wait_agent default timeout with prompt-cache TTL (30 min on GPT-5.6+) to cut parent-agent polling cost #41875 では、V1の待機にはV2用の設定が効かない点も指摘されています。

設定後に確認したこと

設定変更前にバックアップを取り、既存の設定を残したまま追記しました。
その後、保存した設定を使って次を実行しています。

codex features list

手元では、次の表示を確認できました。

multi_agent_v2                           stable             true

変更前は false でした。
ここで確認できるのはV2が有効になったことまでで、この表示だけで実際の待機時間や利用枠の削減効果まで検証できるわけではありません。

CLIを再起動して新しいセッションを始め、サブエージェントに作業を依頼した際の待機動作を見ていくつもりです。

すべての待機に効くわけではない

今回の設定は、サブエージェントを待つ wait_agent 向けです。
長いビルドやテストの終了を write_stdin などで確認する処理には適用されません。

こちらにも、Codex CLI repeatedly wakes xhigh to poll deterministic long-running jobs, exhausting finite weekly usage before task completion #45974 という報告がありますが、今回の設定でそれも解決した、という話ではありません。

OpenCodeのような別のツールを使えばどうか、という話も見かけましたが、まずは今使っているCodex側で調整できるところを調整してみることにしました。
効果はこれから確認します。