OpenAI — Codex — AgentField

Drive OpenAI Codex from inside agent loops — the optional override for AgentField's default AForge harness — with budget caps, schema-bound output, and subprocess control.

Codex is an optional override. AgentField's harness runs AForge, its own native worker, by default — set provider="codex" when you specifically want Codex driving the loop.

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

Only needed for this provider — the default AForge path installs nothing. Install the codex CLI alongside 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_KEY

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.

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	`"aforge"`	Set to `"codex"` to select this provider. Unset means the AForge default.
`model`	string	empty	Empty means the provider's own default. Set 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 login once for OAuth-based auth, or set OPENAI_API_KEY in the harness environment.
For ChatGPT enterprise routing, follow the @openai/codex configuration.

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.

OpenAI — Codex