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.
pip install agentfield
npm install -g @openai/codex
codex login # OAuth in the browser, or set OPENAI_API_KEYCall 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.
from pydantic import BaseModel
from agentfield import Agent, HarnessConfig
class ScaffoldResult(BaseModel):
files_created: list[str]
notes: str
app = Agent(
node_id="scaffolder",
harness_config=HarnessConfig(
provider="codex",
model="gpt-5-codex",
permission_mode="auto", # Codex applies edits without prompting
max_turns=20,
max_budget_usd=0.30,
cwd="./generated",
),
)
@app.reasoner()
async def scaffold_module(spec: str) -> dict:
result = await app.harness(
f"Scaffold a Python module that satisfies this spec:\n\n{spec}",
schema=ScaffoldResult,
)
if result.is_error:
return {"ok": False, "error": result.error_message}
return {
"ok": True,
"files": result.parsed.files_created,
"notes": result.parsed.notes,
"cost_usd": result.cost_usd,
"num_turns": result.num_turns,
}Composition pattern — implement-then-verify
Use Codex for speed, then verify with a careful reviewer. Same harness code, different provider per call.
impl = await app.harness(
f"Implement this feature:\n\n{spec}",
provider="codex",
permission_mode="auto",
schema=ImplResult,
)
if impl.is_error:
raise RuntimeError(impl.error_message)
review = await app.harness(
f"Review these changes for correctness and edge cases:\n\n{impl.parsed.diff}",
provider="claude-code",
permission_mode="plan",
schema=ReviewResult,
)
if review.parsed.severity == "high":
# Loop again with the reviewer's findings as input.
...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.