Skip to main content
codex is the runtime that drives OpenAI’s codex exec CLI: Clawboo installs the codex binary, spawns it per board task in an isolated home, and reshapes its --json event stream into the normalized RuntimeEvent stream every other runtime emits. It is one of the five runtimes, a co-equal peer beside openclaw, clawboo-native, claude-code, and hermes. Codex differs from the other CLI runtimes in two ways that matter operationally: it authenticates through an interactive ChatGPT OAuth login (codex login), not a pasted API key; and it reports no USD cost, so spend is surfaced as token usage with an explicitly estimated, null dollar figure. Because the credential is a ChatGPT account, Codex is also the runtime a ChatGPT-subscription user without any API key runs their whole team on: the onboarding wizard’s OpenAI card offers Sign in with ChatGPT (Recommended, the economical path), deploys every agent on Codex, and designates a Codex agent as the team’s universal leader. Use this page to understand its capabilities, how to install and connect it, how the driver works, and how a Codex agent leads a team.
Authentication posture. Clawboo only ever drives OpenAI’s official CLI, whether you run codex login yourself in a terminal or click Sign in with ChatGPT and let Clawboo’s local server spawn that same command for you. It never performs the OAuth exchange itself, never reads or refreshes the token, and never calls the ChatGPT backend directly: the CLI does its own auth and you authorize in your own browser on OpenAI’s page.

​
What it is

Codex is a wrapped one-shot runtime. It is a thin RuntimeAdapter (@clawboo/adapter-codex) constructed with a per-run driver factory; the real driver spawns codex exec --json as a black-box subprocess, parses its stdout JSON-lines stream best-effort into the adapter’s CodexNativeEvent union, and tears it down at the end of the task. The runtime differences live entirely in the mapper and the driver; the adapter’s trait surface is identical to Claude Code’s. Two properties shape the whole runtime:
  • Whole-block text becomes a synthesized stream. Whether Codex emits incremental output_text.delta frames or one agent_message block per turn is its choice; the driver maps either form to a text native event, and the mapper turns that into a text-delta RuntimeEvent. A block-emitting Codex still surfaces as a (single, synthesized) text-delta; the adapter declares streaming: true regardless.
  • No USD cost. Codex carries token usage but reports no dollar figure. A result with usage therefore yields a cost event with costUsd: null and estimated: true, never a concrete USD, the honest signal that the host’s budget kill-switch sees usage but cannot price the run.
Codex is a peer, not a substitute. Clawboo never migrates a codex agent into any other runtime’s agent (or vice versa); the adapter package ships no cross-runtime agent-file mapping. A team can mix a Codex specialist with agents on any other runtime.

​
Capabilities

The Codex adapter reports the following capabilities. Callers branch on these (never on the runtime id), so they describe what the host may do with a Codex run. Because nativeHome is { scope: 'per-identity', persist: true }, the integration planner materializes a persistent managed CODEX_HOME per agent under Clawboo’s own state dir, which is what makes session resume work: Codex writes its session files there, and a later run can resume them. Your real ~/.codex is never the run home; the driver seeds a copy of its auth.json into the managed home (see authentication). The shared plane (board, memory, tools) is reached through MCP.

​
How to install and connect

The install/connect/disconnect mechanics are shared with the other CLI runtimes and run from the Runtimes panel; see Connecting runtimes for the card UI, the encrypted vault, and the resolution chain. The Codex specifics are below.

​
1. Install the CLI

Codex is installed via npm. From the not-installed state, the card opens POST /api/runtimes/codex/install, a Server-Sent Events stream that runs:
The package is pinned to the current 0.x major so a future 1.0 is never auto-installed. If npm is not found, the stream emits an error event with code NPM_MISSING. The runtime’s health binary is codex, resolved by resolveRuntimeBin over PATH plus the well-known user-install dirs.

​
2. Authenticate with codex login (OAuth)

This is where Codex departs from the other api-key runtimes. Codex authenticates via an interactive ChatGPT OAuth flow, and it cannot be connected with a pasted API key on current versions. The descriptor declares authKind: 'oauth', envVar: null, and headlessAuth: false; there is no vault slot for a Codex credential. POST /api/runtimes/codex/connect is therefore a no-op on storage. It probes the login (codex login status) and returns the CURRENT state, plus the terminal login command when one is still needed:
The card offers a one-click Sign in with ChatGPT: Clawboo’s local server spawns codex login for you (POST /api/auth/cli-login/codex, an SSE stream that relays the CLI’s own user-facing output), the CLI opens your browser and waits on its localhost callback, and you approve there, with nothing to type. When the login lands, the server re-probes the real auth store and the card re-checks itself. If the CLI is missing, the platform is unsupported, or the spawn fails, the card degrades to the copyable codex login command: run it in your own terminal, then click Re-check. The status probe DETECTS an existing login (codex login status is parsed, never the token file), so a user who signed in before ever opening Clawboo reads ready immediately. Once signed in, every spawned run gets a managed CODEX_HOME seeded with a copy of your ~/.codex/auth.json (copy-only, freshness-checked so a rotated refresh token in the managed home is never clobbered; the real ~/.codex is never written). Clawboo never stores a Codex credential in its vault, and disconnect is likewise a no-op for Codex.
The connection state machine reflects this: an installed oauth runtime reads ready when the login probe detects a signed-in Codex, needs-login otherwise; it never reaches ready from a vault key.

​
3. Run a board task

POST /api/runtimes/codex/run drives a board task on Codex end to end: claim → worktree → run → report-up. The driver:
  1. Uses the managed per-agent CODEX_HOME (created 0700 on first run; a run with no agent identity falls back to a throwaway mkdtemp home).
  2. Seeds a copy of your ~/.codex/auth.json into the managed home if the managed copy is missing, unusable, or older than yours (Codex rotates refresh tokens inside the managed home, so a blind re-copy would break it). No usable auth anywhere and no API key → the run fails fast with no Codex credentials provisioned instead of sending an unauthenticated request.
  3. Writes a config.toml pointing Codex’s MCP client at this server’s hosted Tasks, Memory, Tools, and TeamChat servers (the run’s memory scope is appended to the Memory server’s URL only).
  4. Spawns codex exec --json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check [--model <m>] <prompt> — or codex exec resume <session-id> … when a resume handle is provided — with CODEX_HOME set and a process-group leader so the whole tree can be killed on abort.
The bypass flags are deliberate: the worktree is the isolation boundary (and already a git repo), so Codex’s own sandbox and approval prompts are turned off; Clawboo gates externally instead. Clawboo’s own server secrets are scrubbed from the child environment before the untrusted subprocess inherits it; only the explicitly granted env is merged on top.

​
How the driver works

The Codex driver builds on the shared subprocess substrate that all spawned runtimes use. It buffers native events until the adapter subscribes (so frames emitted between start() and the first listener are never dropped), parses stdout line by line, and always synthesizes a terminal result on process exit; so a run’s lifecycle completes even if mid-stream parsing missed the completion event.

​
Event translation

Each stdout line is JSON-parsed and run through a tolerant translator that handles shape drift. codex exec wraps events as { id, msg: { type, ... } }, so the parser reads the inner msg when present:

​
The terminal result

If the stream never produced a result, the driver synthesizes one when the process exits, derived from the exit code and signal:
  • A clean exit (code === 0) → result with ok: true.
  • A deliberate abort kills the process with SIGTERM/SIGKILL (exit code null) → result with aborted: true, mapped to a clean done: aborted terminal rather than a spurious error.
  • Any other non-zero exit → result with ok: false and errorMessage from stderr (or codex exited with code <n>).
The synthesis is idempotent: the subprocess substrate fires onClose from both the error and close events, so the driver marks the terminal as synthesized and a second call returns nothing, never two result terminals.

​
The cost mapping

Codex reports token usage but no USD, so the pure mapper translates a result with usage into a cost event with costUsd: null and estimated: true. The accompanying done event also carries costUsd: null. This is the deliberate asymmetry versus the runtimes that report real dollars; the host gets honest usage counts and an explicit “not priced” signal instead of a fabricated cost.

​
Session resume

The adapter defines a sessionCodec and the driver captures Codex’s session id from the event stream. On a later run the host passes it back as codex exec resume <session-id>, so the run continues the SAME Codex session (its transcript lives in the managed CODEX_HOME). This is what gives a Codex team LEADER conversation continuity: each leader turn resumes the previous one via a per-agent-per-team resume pointer, exactly like the native leader. A cross-runtime pickup still rides the prose handoff note in the worktree like any other runtime, and a resume attempt against a stale id self-heals (the failed run clears the pointer, the next turn starts fresh).

​
Leading a team

A Codex agent can be a team’s universal leader, which is what makes the ChatGPT-subscription onboarding work end to end (no native key, no Gateway — nothing else can lead):
  • Delegation is a tool call. Team-orchestrated Codex runs attach a team_delegate MCP tool (hosted on the TeamChat server, bound to the run’s team). The orchestration engine observes the tool call by NAME and turns it into a real board task — the same signal path every runtime’s leader uses. The tool is attached ONLY on orchestrator-driven team runs, so it can never silently no-op elsewhere.
  • The leader is taught per turn. A coding-runtime leader turn carries a coordination block that teaches team_delegate (answer simple questions directly, delegate real work, one summary after results) — injected in the volatile per-turn context, so it reaches existing agents too.
  • Designation is explicit. A Codex-preferred deploy designates the lead and promotes it to the universal Boo Zero via POST /api/boo-zero/override (only when nothing else resolves — an existing native or OpenClaw Boo Zero is never stomped).

​
Verify it worked

  • GET /api/runtimes should show the codex entry with installed: true once the CLI resolves, authKind: "oauth", envVar: null, and connectionState: "ready" when you are signed in (needs-login otherwise). It never reads ready from a stored vault key.
  • A successful Sign in with ChatGPT re-checks the card for you. After the manual fallback (codex login in your own terminal), click Re-check in the card to re-probe.
  • Run a board task via POST /api/runtimes/codex/run. A clean run returns doneReason: 'success' with costUsd: null and usedWorktree: true.

​
Troubleshooting

Codex shows “Needs login” after a successful codex login. Click Re-check to re-probe (codex login status is parsed; a signed-in Codex reads ready). Codex never reaches ready from a vault key; its auth lives in CODEX_HOME, and connect/disconnect are no-ops on storage.
A run reports costUsd: null. This is correct, not a bug. Codex reports token usage but no USD, so the mapper surfaces cost with costUsd: null, estimated: true. The budget kill-switch sees usage but cannot enforce a dollar cap on a Codex run.
A run fails with no Codex credentials provisioned. The managed CODEX_HOME had no usable auth to seed: run codex login in your terminal (it writes ~/.codex/auth.json, which the next run seeds into the managed home), then retry. Clawboo deliberately fails fast here rather than sending an unauthenticated request.
Last modified on August 8, 2026