Skip to main content
The Codex runtime drives OpenAI’s codex exec agent as a member of your Clawboo team. Clawboo installs the codex CLI, spawns it per task in a clean isolated environment, and reports results to the shared board. Authentication works differently from every other runtime: instead of pasting an API key, you run codex login in your terminal to complete a ChatGPT OAuth flow. Use Codex when you want to use OpenAI’s models and are comfortable with the interactive OAuth login. Each task runs in its own throwaway home with no state carried over from previous runs.

​
Capabilities

CapabilityValue
Streaming (live text deltas)✅
MCP (Clawboo’s tool servers)✅
Worktrees (isolated git workspace)✅
Resume (session ID captured)✅
Tool approval gates✅
Persistent home across runs❌
Each Codex run gets a fresh ephemeral home. No state, skills, or memory carries forward between tasks. If you need cross-run persistence, see Hermes (persistent home) or Clawboo Native (persistent conversation transcripts).

​
Prerequisites

  • Node.js and npm (bundled with Node) on your PATH.
  • A ChatGPT account for the codex login OAuth flow — no separate API key is needed.

​
Connect from the Runtimes panel

1

Install the Codex CLI

In the Runtimes panel, click Install on the Codex card. Clawboo streams the install progress:
npm install -g @openai/codex@0
The package is pinned to the 0.x major so a future breaking 1.0 release is never auto-installed. The health binary Clawboo checks for is codex.
If the install fails with a permission error, prefer a Node version manager (nvm or fnm) or Homebrew rather than using sudo.
2

Authenticate with codex login

Codex authenticates via ChatGPT OAuth — there is no API key to paste. The Connect button on the card returns the command you need:
{ "ok": true, "connectionState": "needs-login", "loginCommand": "codex login" }
Copy the command and run it in your own terminal:
codex login
This opens a browser window for the ChatGPT OAuth flow. Complete the login, then return to the Clawboo dashboard.
3

Re-check status

After codex login succeeds, click Re-check in the Runtimes panel. The card does not auto-detect the login — you need to trigger a status refresh manually. The card will stay on needs-login until you do.
4

Run a board task

With the runtime ready, dispatch a board task:
curl -X POST http://localhost:18790/api/runtimes/codex/run \
  -H 'Content-Type: application/json' \
  -d '{"taskId":"<task-uuid>","repoPath":"/path/to/repo","kind":"code"}'
Clawboo claims the task, provisions a worktree, creates a throwaway home for Codex to run in, and streams results back to the board.

​
Ephemeral home per run

Every Codex run gets a freshly created CODEX_HOME — a throwaway directory isolated from your default ~/.codex. This isolation is intentional: it prevents one task from inheriting state from a previous one. One consequence: if you ran codex login against your default ~/.codex, that OAuth credential is not visible to Clawboo-spawned Codex runs. Clawboo uses the ephemeral home’s own auth context. This is why the codex login step is part of the Clawboo connect flow — you authenticate in the context Clawboo will use.

​
Streaming output

Codex may emit incremental text deltas or send its response as a single block, depending on the version. Clawboo handles both forms — a whole block is synthesized into a single text-delta event. The runtime reports streaming: true either way.

​
Cost reporting

Codex reports token usage but no dollar amount. Clawboo surfaces costUsd: null and estimated: true on all Codex runs — an honest signal rather than a fabricated estimate. The budget kill-switch can see token usage but cannot enforce a dollar cap on Codex runs.

​
Verify it worked

After codex login and clicking Re-check, GET /api/runtimes should show codex with installed: true and connectionState: "needs-login". Note: Codex never reaches connectionState: "ready" from a stored credential — needs-login is the normal connected state for an OAuth runtime. After running a task, the board task should advance and a report-up summary should appear as a comment.

​
Troubleshooting

The card stays on “Needs login” after you ran codex login. This is expected — the card does not auto-detect the OAuth login. Click Re-check to refresh status.
Runs report costUsd: null. This is correct behavior, not a bug. Codex reports token counts but no USD, so Clawboo marks cost as estimated with a null dollar value.
Runs fail with an auth error even after codex login. Confirm that you ran codex login through Clawboo’s connect flow, which authenticates into the ephemeral home context. A login against your default ~/.codex is not visible to Clawboo-spawned runs.

​
See also