Skip to content
Integrations
Integrations

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_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

OptionTypeDefaultWhat it does
providerstringrequired"codex" for this provider.
modelstring"sonnet" (override it)Any model the codex CLI accepts — "gpt-5-codex", "gpt-4.1", etc.
codex_binstring"codex"Path to the codex binary if it is not on $PATH.
permission_modestringnull"auto" maps to the CLI's auto-approve flag. Anything else runs in default mode.
cwdstringworking dirForwarded as -C so Codex treats it as the repository root.
max_turnsint30Hard cap on agent iterations.
max_budget_usdfloatnullCost ceiling. Cost is parsed from CLI metadata when available.
envdict{}Extra environment variables forwarded to the subprocess.
system_promptstringnullCustom system prompt prepended to the loop.
schemamodelnullPydantic 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.

See also