Skip to main content
The codex_local adapter runs OpenAI’s Codex CLI locally. It supports session persistence via previous_response_id chaining and skills injection through the global Codex skills directory.

​
Prerequisites

  • Codex CLI installed (codex command available)
  • OPENAI_API_KEY set in the environment or agent config

​
Configuration Fields

​
Session Persistence

Codex uses previous_response_id for session continuity. The adapter serializes and restores this across heartbeats, allowing the agent to maintain conversation context.

​
Skills Injection

The adapter symlinks AoA skills into the global Codex skills directory (~/.codex/skills). Existing user skills are not overwritten.

​
Environment Test

The environment test checks:
  • Codex CLI is installed and accessible
  • Working directory is absolute and available (auto-created if missing and permitted)
  • Authentication signal (OPENAI_API_KEY presence)
  • A live hello probe (codex exec --json - with prompt Respond with hello.) to verify the CLI can actually run

​
Runtime-decision bridge (W5c)

The runtime-decision bridge puts a human in the loop for risky runtime permissions. When an agent is supervised, a codex run that proposes a risky shell command or a file-change patch pauses, surfaces an approval in the AoA Hub (“Waiting on you”), and waits for a founder to allow or deny before the CLI proceeds. This is the codex counterpart of the claude_local bridge (Decision #106 / sibling Decision #105); see also docs/architecture/decisions.md and the protocol reference docs/adapters/codex-appserver-protocol.md.

​
Turning it on (default OFF)

Supervision is off by default and only activates when all four conditions hold:
  1. Instance kill-switch: the server env AOA_RUNTIME_DECISION_ROUTING=1.
  2. Adapter: the agent’s adapter is codex_local (the resolver allow-lists claude_local + codex_local).
  3. Local execution: the agent runs on the local execution target (Docker / remote-sandbox targets can’t reach the loopback broker and stay on the default path).
  4. Per-agent opt-in: runtimeConfig.runtimeDecisionRoutingEnabled = true on the agent.
If any condition is missing, the run takes the normal unsupervised path — no behavior change.

​
Two execution paths

Codex uses app-server only when supervised because it is the only codex mode that exposes a blocking approve/deny callback; exec cannot host the bridge. Supervision is chosen per run — toggling it on an agent at worst starts a fresh session thread, it never errors an in-flight run.

​
Approval UX

  • A pending approval appears in the AoA Hub as a “Waiting on you” row.
  • Allow lets the command/patch proceed; allow-always approves and remembers the choice for the rest of the session; deny rejects it (codex reports the command/patch as rejected by the user).
  • Coverage: both shell commands (item/commandExecution/requestApproval) and file-change patches (item/fileChange/requestApproval). Benign, trusted commands auto-approve and never prompt.
  • Fail-closed timeout: if no one responds within 5 minutes, the run is denied automatically (fail-safe deny) and the row stays visible in the hub so you can see what was missed. For unattended/overnight work, keep agents unsupervised or use trust rules rather than relying on the timeout.
  • Permission-only: the bridge gates permissions. Codex “ask the user a question” prompts (item/tool/requestUserInput) are not yet routed and are deferred to a future workstream.

​
Security posture

  • Out-of-tree writes are declined automatically — a file-change whose target resolves outside the agent’s working directory is rejected without ever surfacing as an approvable prompt (the founder can’t accidentally approve a path-escape write).
  • OPENAI_API_KEY is never leaked to the app-server child. The tracked-child spawn strips it from the inherited environment, so supervised runs neither expose the key nor accidentally switch billing modes.
  • A cancelled run tears down cleanly — the pending approval is denied, the child process is signalled, and the turn unwinds without hanging.
The full JSON-RPC framing, approval-policy matrix, decision-enum mapping, token-usage shape, and cross-path resume behavior are documented in docs/adapters/codex-appserver-protocol.md.