OpenAI — Codex
Spawn OpenAI Codex from inside agent loops with budget caps, schema-bound output, and subprocess control.
Spawn OpenAI Codex from inside agent loops. The harness manages the codex subprocess — model choice, permission mode, working directory — so your loop stays focused on retries, scoring, and composition.
Reach for Codex when the work is fast implementation — greenfield code, scaffolding, broad refactors where iteration speed matters more than careful planning.
Quickstart
Install the codex CLI and AgentField. Codex authenticates against your OpenAI account; the harness inherits the environment.
Call the harness
Attach a HarnessConfig to the agent so Codex defaults — model, permission mode, budget, working directory — live in one place. Per-call overrides handle the exceptions.
Composition pattern — implement-then-verify
Use Codex for speed, then verify with a careful reviewer. Same code, different provider per call.
Options
| Option | Type | Default | What it does |
|---|---|---|---|
provider | string | required | "codex" for this provider. |
model | string | "sonnet" (override it) | Any model the codex CLI accepts — "gpt-5-codex", "gpt-4.1", etc. |
codex_bin | string | "codex" | Path to the codex binary if it is not on $PATH. |
permission_mode | string | null | "auto" maps to the CLI's auto-approve flag. Anything else runs in default mode. |
cwd | string | working dir | Forwarded as -C so Codex treats it as the repository root. |
max_turns | int | 30 | Hard cap on agent iterations. |
max_budget_usd | float | null | Cost ceiling. Cost is parsed from CLI metadata when available. |
env | dict | {} | Extra environment variables forwarded to the subprocess. |
system_prompt | string | null | Custom system prompt prepended to the loop. |
schema | model | null | Pydantic class / Zod schema / Go struct. Forces JSON output validated against the schema. |
Authentication
- Run
codex loginonce for OAuth-based auth, or setOPENAI_API_KEYin the harness environment. - For ChatGPT enterprise routing, follow the
@openai/codexconfiguration.
When to choose Codex
- Greenfield scaffolding — building new modules from a short spec.
- High-velocity implementation when stepwise reasoning is less important than throughput.
- Permissive auto-mode workflows where the CLI is allowed to apply edits without per-step confirmation.
- Cost-conscious model choice — Codex's smaller models can be the cheapest "good enough" option.
Pairs well with
- Claude Code — Claude plans + reviews, Codex implements.
- Gemini CLI — Gemini absorbs the whole repo as context, hands Codex a tight spec.
- OpenCode — fall back to a self-hosted open-weight model when budget caps trip.