OpenAI Codex CLI

Codex CLI is OpenAI's open-source agentic coding tool. It connects to AgentXchain via the local_cli adapter.

Before you wire Codex into a governed role, read the Authority Model. write_authority, local_cli, and Codex's own approval/sandbox mode are separate axes.

Which adapter?

local_cli — AgentXchain spawns codex as a subprocess for each governed turn.

Prerequisites

• Codex CLI installed (npm install -g @openai/codex)
• OPENAI_API_KEY set in your environment
• agentxchain CLI installed
• Prefer an absolute executable path when possible. On macOS app installs, /Applications/Codex.app/Contents/Resources/codex is the safest default because GUI shells and subprocess spawn contexts do not always share the same PATH.

Configuration

{
  "runtimes": {
    "codex-dev": {
      "type": "local_cli",
      "command": ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"],
      "cwd": ".",
      "prompt_transport": "argv"
    }
  },
  "roles": {
    "dev": {
      "runtime": "codex-dev",
      "mandate": "Implement features and fix bugs",
      "write_authority": "authoritative"
    }
  }
}

Key fields

Field	Value	Why
command	["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"]	exec is Codex's non-interactive entrypoint. --dangerously-bypass-approvals-and-sandbox is the full-authority local CLI mode for unattended governed writes.
prompt_transport	"argv"	The prompt is passed through the {prompt} placeholder as a command-line argument.

Authority mapping

• write_authority: use authoritative when Codex is expected to write directly into the repo.
• Runtime type: local_cli.
• Downstream CLI authority: --dangerously-bypass-approvals-and-sandbox is the required Codex mode for unattended authoritative local writes.
• Non-interactive entrypoint: use codex exec, not top-level codex.

Absolute-path recommendation

If agentxchain doctor says bare codex is not resolvable in the dispatch spawn context, replace the command with the real executable path instead of relying on PATH repair later:

"command": ["/Applications/Codex.app/Contents/Resources/codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"]

Verify the connection

agentxchain connector check
agentxchain connector validate codex-dev

Minimal working example

agentxchain init --governed --template cli-tool --goal "Build a JSON schema validator" --dir my-project -y
cd my-project
agentxchain doctor
agentxchain connector check
agentxchain connector validate codex-dev
agentxchain run

Or use the guided interactive path (prompts for template, name, goal, and folder):

agentxchain init --governed

Then update agentxchain.json with the Codex runtime above, run agentxchain doctor, agentxchain connector check, and agentxchain connector validate codex-dev, then start agentxchain run.

Gotchas

• Do not rely on --full-auto for authoritative unattended runs. Use --dangerously-bypass-approvals-and-sandbox when the governed role is meant to have real local write authority.
• Do not use --quiet in Codex governed commands. On the current Codex CLI, --quiet is rejected; codex exec is the correct non-interactive path.
• Model selection: Codex CLI defaults to a Codex-optimized model. You can override with --model gpt-5.4 if needed, but the default is usually better for coding tasks.
• Working directory: Codex CLI operates on the current working directory. The cwd field ensures it runs in your project root.