Configuring Codex

Sessions can run OpenAI's codex instead of Claude. You still drive everything from actor claude — Codex is an agent you assign to sessions, not an interactive entry point (see Agents). Configuration works the same way as for Claude: actor.sh sets defaults, interprets one key, and forwards the rest.

What actor.sh sets and interprets

• sandbox = danger-full-access and a = never (approval policy) are applied by default to every Codex session, so it runs without per-action approval prompts. Override either like any other key.
• use-subscription is interpreted by actor.sh. When true, it removes OPENAI_API_KEY from the agent's environment so Codex uses your subscription login.
• The role prompt is delivered as Codex developer instructions — a -c config override on the collaboration mode — since Codex has no system-prompt flag.

Forwarding flags to codex

Other config keys are forwarded to the codex binary as flags. Codex uses short flag names for some options (for example m for the model, a for the approval policy), which forward as -m / -a; longer keys forward as --<key>.

defaults "codex" {
    config m "gpt-5-codex"
}

Three places to set config

Exactly as for Claude:

1. All Codex sessions — a defaults "codex" block in settings.kdl:

   defaults "codex" {
       use-subscription #true
       config sandbox "danger-full-access"
   }
   

2. A class of session — a role that pins agent "codex" and a config block.

3. One session — --agent codex plus --arg to forward raw flags on actor new:

   actor new migrate --agent codex --arg -m --arg gpt-5-codex \
     --prompt "Port the config loader."
   

The #null cancel marker and the merge precedence work identically to Claude — see Actor Settings.