How to set Codex approval policy

Local coding sessions need a boundary between routine repository work and actions with wider access. The Codex approval policy sets when the agent requests approval before an action.

Personal defaults load from the active Codex home in new processes. A trusted project's configuration, a selected profile, or launch flags can override those defaults, while organization requirements can restrict which policies are allowed.

Approval policy and sandbox mode control different boundaries. Approval prompts govern actions that need permission, while the sandbox limits filesystem and network access. Suppressing prompts does not grant access beyond the sandbox. With on-request, commands already permitted by the sandbox can run without individual approval.

1. Create the active Codex home directory if it is absent.

   $ mkdir -p "${CODEX_HOME:-$HOME/.codex}"

   The default directory is ~/.codex. A nonempty CODEX_HOME selects a different directory; the same expression below opens its config file.

2. Open the active user config file in vi, creating the file only if it is absent.

   $ vi "${CODEX_HOME:-$HOME/.codex}/config.toml"

3. Record the existing top-level approval_policy value before changing it.

   If the key is absent, removing the new line later restores that starting state. An existing value can be restored by replacing the same line.

4. Set the top-level approval_policy to on-request.

   approval_policy = "on-request"

   An existing top-level approval_policy line needs its value replaced, with no duplicate key. If the key is absent, insert the line immediately before the first TOML table header, such as [features] or [projects."/path/to/project"]. If there are no table headers, append it at the end of the file. A line after a table header belongs to that table rather than the top level. Existing sandbox_mode settings and other keys stay as they are.

   On-request lets the agent decide when to ask for approval; commands permitted by the sandbox can run without individual approval. The alternative never suppresses approval requests, so actions needing additional permission fail instead of prompting. Combined with an existing danger-full-access sandbox, never permits commands without either sandbox restrictions or approval prompts.

5. Save the config file.

   In vi, Esc, then :wq and Enter, writes the file and closes the editor. The saved setting applies to new processes; an already-running session retains its current permissions.

6. Confirm that a new Codex process reports approval OnRequest.

   $ codex doctor --summary --ascii --no-color
   ##### snipped #####
   Configuration
     [ok] config       loaded
   ##### snipped #####
     [ok] sandbox      restricted fs + restricted network · approval OnRequest
   ##### snipped #####

   Codex Doctor resolves configuration from the current directory. The config loaded row confirms parsing, and approval OnRequest confirms the effective policy. The filesystem and network description depends on the existing sandbox settings. A different approval value indicates an override or managed restriction; a parse error indicates invalid TOML. Authentication or connectivity failures can make Doctor exit with an error even when these configuration rows pass. No sign-in or model request is needed to inspect the resolved policy.
   Related: How to override Codex configuration for a single run
   Related: How to start a Codex interactive session