Codex の approval_policy でハマった話：on-failure は罠、on-request に直せ

config.toml の approval_policy という設定、ちゃんと理解して使えていますか？

私は WordPress への自動投稿パイプラインを Codex で構築しているとき、最初「on-failure にしておけば、失敗したときだけ確認してくれるし、必要なら sandbox 外の操作も承認を求めてくれるはず」と思い込んでいました。実際にその設定で動かしてみると、権限昇格が必要な処理がまったく期待どおりに動かず、しばらく原因がわかりませんでした。

結論から言うと、approval_policy = "on-request" に変えたら意図どおりに動くようになりました。この記事では、on-failure と on-request の違い、私がハマったポイント、そして再発防止のチェックポイントを整理します。

Codex の基本的な使い方については、Codex プラグインガイドもあわせてご覧ください。

---

approval_policy が直感的に分かりにくい理由

値の名前だけでは承認タイミングが読み取りにくい

approval_policy が取りうる値は、公式ドキュメント（Configuration Reference）によると以下のとおりです。

値	概要
untrusted	すべての操作に承認を求める（最も厳格）
on-request	モデルが必要と判断したときに承認を求める
never	承認を求めない（最も緩い）
on-failure（deprecated）	非推奨。挙動が直感しにくく、現在は使用が推奨されない

名前だけを見ると、on-failure は「失敗したときに聞いてくれる」、on-request は「リクエストがあったときに聞いてくれる」と解釈できそうです。しかし実際の意味合いはそれほど単純ではなく、GitHub Issue でも「UI・config・ドキュメント間で用語が一致していない」という報告が複数あります。つまり、この設定でハマるのは「個人の読み違え」だけが原因ではありません。

公式ドキュメント上は、現在 on-failure は deprecated 扱いで、on-request の使用が推奨されています。

approval_policy と sandbox_mode は役割が別

混同しやすいポイントとして、approval_policy と sandbox_mode は別の軸であることを押さえておく必要があります（Agent approvals & security）。

• approval_policy：「いつ承認を求めるか」のポリシー
• sandbox_mode：「何を制限するか」のサンドボックス設定

たとえば sandbox_mode = "workspace-write" にすれば、ワークスペース外への書き込みは制限されます。しかし、それと承認フローの発火タイミングは別管理です。approval_policy をどう設定するかによって、承認ダイアログが出るかどうか、出るタイミングがいつかが決まります。この二つをセットで理解しないと、「サンドボックスは設定したのに期待した承認が出ない」という状況に陥ります。

---

on-failure と on-request の違いを整理する

現行ドキュメントでの推奨は on-request

公式の Config Basics および Advanced Configuration のサンプルコードでは、基本例として以下の組み合わせが示されています。

[agent]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

つまり、on-request が実質的なデフォルト推奨の扱いです。

on-failure を「必要時に聞いてくれる」と読むとズレる

私が最初に陥った誤解は、「on-failure = 失敗してみて問題があれば承認を求めてくれる、つまり都度昇格してくれる」という解釈でした。

公式ドキュメント上は on-failure の正確な動作は deprecated 扱いで詳細が薄く、「失敗したとき」にどう振る舞うのかが明確ではありません。私の実環境では、on-failure 設定のまま権限昇格が必要なステップを実行したところ、承認ダイアログが一切表示されませんでした。これが仕様上の必然なのか、私の環境固有の挙動なのかはドキュメントからは確認しきれていませんが、実体験として「on-failure では期待した承認導線にならなかった」という事実がありました。

一方、on-request は「モデルが権限昇格が必要と判断したときに承認を求める」というモデルドリブンな設計です。モデルは内部的に require_escalated（権限昇格要求）というメカニズムを通じてシステムに承認を要求しますが、この要求を受け取って承認ダイアログを発火させるのが on-request ポリシーです。on-failure ではこの連携が機能しませんでした。

---

実際に私がハマった流れ

最初は on-failure で十分だと思っていた

Codex を使って WordPress への自動投稿パイプラインを構築しているとき、config.toml を以下のような設定で運用していました。

[agent]
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

「失敗したら確認が出るんでしょ？何か問題あれば聞いてくれるから大丈夫」という感覚で設定したのですが、これが後のハマりの原因でした。

権限昇格リクエストが無反応で sandbox 外実行ができず詰まった

パイプラインの中で、sandbox 外のファイルパスへの書き込みや外部 API 呼び出しを行うステップがありました。このステップで Codex に処理を任せると、承認ダイアログが一切出てこずに処理がスキップされたり、エラーなく失敗したりするという状況が発生しました。

最初はコードのバグを疑ってデバッグしていましたが、どこにも問題が見当たりません。権限昇格リクエストが無反応で、かつエラーもない。「承認が必要なはずなのに、何も聞かれずに終わる」という奇妙な挙動でした。

/status と config.toml を見直して原因を切り分けた

しばらく悩んだ末に /status コマンドで現在の Approval Mode / Sandbox の表示を確認しました。すると approval_policy が on-failure になっていることが改めて目に入りました。

「あれ、これって on-request にすべきじゃないのか？」と思って公式ドキュメントを読み直したところ、on-failure は deprecated という記述を発見。そして Config Basics の基本例がすべて on-request を使っていることに気づきました。原因の仮説が固まったので、config.toml を修正してみることにしました。

---

approval_policy = "on-request" に直してどう解決したか

修正後に期待どおり承認フローが出るようになった

config.toml を以下のように変更しました。

[agent]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

これだけです。コードには一切手を加えていません。修正後に同じパイプラインを実行すると、sandbox 外の操作が必要なステップで承認ダイアログが表示されるようになり、承認すると処理が続行されました。「コードの問題ではなく、設定の問題だった」というのが結論でした。

何を確認すれば再発しないか

1. config.toml の approval_policy が on-request になっているか確認する
2. approval_policy と sandbox_mode をセットで確認する（片方だけ見ない）
3. /status で現在の Approval Mode / Sandbox の状態を確認する
4. deprecated 扱いの値（特に on-failure）は使用しない

---

同じハマり方を避けるチェックポイント

まず approval_policy と sandbox_mode をセットで確認する

config.toml に以下の2行が両方揃っているかを最初に確認するのが最も確実です。

[agent]
approval_policy = "on-request"   # ← on-failure は deprecated
sandbox_mode = "workspace-write"

「承認が出ない」「権限昇格リクエストが無反応になる」という症状が出たら、コードを疑う前にまず config.toml を確認してください。

小さいコマンドで承認導線を先にテストする

権限昇格が必要な操作を本番パイプラインで試す前に、小さい検証タスクで承認ダイアログが出ることを先に確認するのが有効です。たとえば sandbox 外のファイルへの単純な書き込みを試して、承認ダイアログが出るかどうかを確認します。出ない場合は config.toml を確認する、という手順を踏めば、本番パイプラインで無駄なデバッグ時間を使わずに済みます。

---

まとめ

approval_policy の設定は値の名前だけでは挙動を直感しにくく、この設定でハマること自体はドキュメントの不整合もあって珍しくありません（GitHub Issue #3545）。

• on-request が推奨：公式ドキュメントの基本例・応用例はすべて on-request を使っている
• on-failure は deprecated：今から設定するなら使う理由がない
• approval_policy と sandbox_mode は別の軸：セットで理解・設定する
• 「承認が出ない」症状はコードより設定を先に確認：config.toml と /status を最初に見る

同じ設定でハマっている方の参考になれば幸いです。他の生成 AI ツールの活用方法は生成AIカテゴリもあわせてご覧ください。

---

あわせて読みたいおすすめ書籍

Codex・Claude Codeを使ったAI駆動開発をさらに深めたい方には、以下の書籍がおすすめです。

参考・出典

1. Configuration Reference – Codex — OpenAI Developers
2. Agent approvals & security – Codex — OpenAI Developers
3. Config basics – Codex — OpenAI Developers
4. Advanced Configuration – Codex — OpenAI Developers
5. Inconsistency between UI, config file and documentation for approval_policy #3545 — GitHub / openai/codex