approval_policy

Values

Value	What it does
"untrusted"	Auto-runs only known-safe read-only commands; everything else prompts
"on-request"	The model decides when to ask. The config sample calls this the default
"never"	No approval prompts; the sample flags it as risky
"on-failure"	Deprecated. Docs say use on-request for interactive runs, never for non-interactive
{ granular = { ... } }	Table form with per-category prompt toggles

The granular table takes five booleans: sandbox_approval (sandbox escalation prompts), rules (execpolicy prompt rules), mcp_elicitations (MCP elicitation prompts, surfaced instead of auto-rejected), request_permissions (prompts from the request_permissions tool), and skill_approval (skill-script prompts). The reference doesn’t publish defaults for any of them.

# ~/.codex/config.toml
approval_policy = "on-request"

# or pick which prompt categories can surface:
# approval_policy = { granular = { mcp_elicitations = false, skill_approval = true } }

When to change it

Interactive work in a repo you trust: leave on-request alone. CI or any scripted run with nobody at the keyboard: set never, which is the docs’ own replacement guidance for on-failure. Poking at a repo you don’t trust yet: untrusted, so only known-safe read-only commands run without you. If one prompt category is drowning you (MCP elicitations are the usual offender), switch to the granular table and shut off just that one.

Gotchas

never has not reliably silenced MCP tool prompts. #13476 is still open: dozens of Playwright MCP calls each asked for approval despite approval_policy = "never". On Linux, 0.115.0 shipped a regression where bwrap prompted for nearly every command, even find and ls, and approval choices weren’t remembered within a session (#14936, since closed). Windows saw the same pain earlier, with a prompt on every PowerShell command (#2860, closed). So if prompts spike right after an upgrade, check the release notes first — two of these three prompt storms were Codex bugs no config value could fix.

Related settings

• approvals_reviewer decides who answers the prompts this key lets through: user (default) or auto_review, which routes them to the reviewer subagent.
• auto_review.policy holds the Markdown policy text the auto reviewer follows; a managed guardian_policy_config overrides it.
• sandbox_mode is the other half of the pairing: the sandbox limits what a command can touch, this key controls when you get asked.