---
name: codex-cli-integration
description: Reference for integrating OpenAI Codex CLI (`codex`) as a programmatic coding-agent backend — flags, config layout, MCP injection, and known gotchas.
---
# OpenAI Codex CLI Integration

## When to use
- Adding Codex CLI as a backend in an agent-orchestration system (alongside Claude Code, OpenCode, etc.).
- Spawning Codex non-interactively from another process and capturing structured output.
- Injecting per-session MCP servers or system prompts into Codex without polluting global config.
- Debugging why a Codex flag, config key, or subcommand "isn't working" — likely it has a different name than the obvious guess.

## How to apply
1. **Detect the binary**: `codex --version` → output starts with `codex-cli ` (e.g. `codex-cli 0.134.0`). Parse off the prefix. Install via `npm install -g @openai/codex`.
2. **Non-interactive run**: use `codex exec "<task>"` (NOT `codex run`). For JSON event stream, add `--json` → JSONL on stdout. For unattended automation, add `--dangerously-bypass-approvals-and-sandbox`.
3. **Model selection**: `--model <name>` is a GLOBAL flag — place it *before* the `exec` subcommand: `codex --model gpt-5 exec "..."`.
4. **Config location**: `~/.codex/config.toml` by default; override the whole directory with `$CODEX_HOME`. MCP servers go under `[mcp_servers.<name>]` sections.
5. **Per-session config without touching globals**: write a named profile file at `$CODEX_HOME/<profile-name>.config.toml`, then run `codex --profile <profile-name> exec ...`. The `--profile` flag takes a NAME, not a file path — Codex resolves it to `$CODEX_HOME/<name>.config.toml`. Auth tokens stay in the global `config.toml` and are inherited.
6. **System prompt injection**: the `instructions` config key is documented as "reserved for future use" and currently does nothing. Prepend the system prompt to the task string passed to `codex exec` instead.
7. **Session resume**: `codex exec [flags] resume <SESSION_ID> "<follow-up prompt>"`. Session IDs come from the JSON event stream.
8. **API key**: read from `OPENAI_API_KEY` or `CODEX_API_KEY` env vars.
9. **Cleanup**: when tearing down a session, delete the per-session profile file at `$CODEX_HOME/<profile-name>.config.toml`. Never edit the global `config.toml` for session-scoped state.

## Rules
- Never use `codex run` — the subcommand is `exec`.
- Never put `--model` after `exec` — it is a global flag and must precede the subcommand.
- Never write session-scoped MCP servers into the global `~/.codex/config.toml`; always use a per-session profile file so cleanup is a single `rm`.
- Never pass a file path to `--profile`; pass the bare profile name.
- Never rely on the `instructions` TOML key for system prompts — it's a no-op today. Prepend to the task string.
- Always parse `codex --version` output by stripping the `codex-cli ` prefix before comparing versions.
- Always set `$CODEX_HOME` when running multiple isolated agent instances on one machine so their profile files and session state don't collide.