Before you begin
- Clawboo running, and Node.js with npm (Clawboo installs Codex with npm, into its own runtimes folder).
- A ChatGPT account whose plan includes Codex. Clawboo never sees your password: Codex’s own sign-in opens OpenAI’s page in your browser.
Set up Codex
Install Codex
@openai/codex@0 into its own runtimes folder and shows npm’s output. The codex command it adds runs on the Node.js Clawboo runs on, needs no sudo, and is not put on your PATH.You should see the row change to Needs login. If Codex is already installed and signed in on this computer, the row reads Connected straight away.The row also shows a command for installing Codex yourself instead. Clawboo uses a codex on your PATH when it has no copy of its own:Sign in with ChatGPT
codex login, which opens OpenAI’s sign-in page in your browser. Approve there; there is no code to type. If no browser window appears, click Open sign-in page.You should see the row read Connected. The same sign-in is on Settings > Providers > ChatGPT subscription > Connect.Put Codex agents on a team
codex, such as ~/clawboo-runtimes/bin/codex login, because the runtimes folder is not on your PATH. Use that path wherever this page says to run codex in a terminal.
What Clawboo controls on Codex
Each agent’s Codex folder
Each Codex agent gets its own Codex home at~/.clawboo/runtimes/codex/<agent id>, created so only your user can open it. Codex keeps the agent’s sessions there, which is how a leader, or the agent’s own chat, continues its thread. Before each run, Clawboo:
- copies your ChatGPT sign-in (
~/.codex/auth.json) into the folder when the copy there is missing, unusable or older than yours. Codex refreshes the copy itself, so Clawboo never overwrites a newer one. - writes the folder’s
config.toml, which lists Clawboo’s MCP servers. Your own~/.codex/config.tomlis not read, and Clawboo never writes to~/.codex.
CLAWBOO_AGENT_USERS, Linux only for now), the folder is under the home of the agent’s own user, and its sign-in is its own, not a copy of yours. The sign-in on the Runtimes page does not pick an agent yet, so give Codex an API key.
Leading a team on Codex
When onboarding deploys your first team on Codex (the Sign in with ChatGPT path), it gives the team a lead: the member with a leader role, or else its first agent. It also promotes that agent to Boo Zero, the leader that coordinates every team. It skips that promotion when you already chose a Boo Zero or have a Clawboo Native one; an OpenClaw Gateway’s default agent is replaced. See Boo Zero.Models
OpenAI decides which models each ChatGPT plan may use, and the list changes, so Clawboo names no Codex model of its own. A Codex run passes no model, and Codex runs your plan’s default. Where Clawboo shows your plan’s models (the ChatGPT groups in the OpenClaw and Hermes model pickers, and the default model the OpenClaw setup writes), it asks your Codex CLI for them: it runscodex app-server in your ~/.codex and reads model/list, falling back to the list Codex last saved there.
An old Codex CLI cannot read your plan’s current models and falls back to the ones it shipped with, which OpenAI refuses. When Clawboo spots that, the Codex row in Settings > Runtimes reads Update needed, and its Update button opens Update Codex, which installs the current @openai/codex@0 into Clawboo’s runtimes folder. A failed update leaves the Codex you had in place.
Permissions and safety
- A worktree is not a sandbox. Only a task-runner run of a task that changes files, with a repository named, works in its own git worktree, which keeps its edits off your main checkout. Everywhere else there is no worktree. A run on a task (one handed out in team chat, one you give from the Board, or a research or review run, which includes every agent Routine you create in the app) starts in the task’s own folder,
teams/<team id>/tasks/<task id>in the work folder (~/clawboo-workby default). Turns that hold no task, such as the lead’s turns and your messages in team chat, and the agent’s own chat start in its team’s folder,teams/<team id>, which every member of the team shares (a task or an agent with no team usesteams/_no-team). The work folder sits outside Clawboo’s data folder, so../..from there does not reach the database. Work an install keeps in the data folder (see The work folder for when that happens) does not get that distance. That folder only sets where it starts: Codex can still read and change any file your user account can, including Clawboo’s database and key vault in~/.clawboo, by their full path. - Clawboo’s approvals do not cover Codex’s own tools. Calls the agent makes through Clawboo’s Tools server (connectors, for example) go through Clawboo’s checks and can ask you first. Codex’s shell commands, file edits and web searches never do. If Codex asks for an approval or an answer mid-run, Clawboo declines, so the run never waits for a person who is not there.
- Clawboo hides some secrets from it, by name only. Before a run, Clawboo removes its own secrets and a fixed list of common credentials (GitHub, npm, cloud, Stripe, Slack and database variables) from the environment Codex inherits. Other variables pass through, and credential files on disk stay readable.
Costs
Codex reports the tokens a run used but no dollar figure, and Clawboo has no price list for Codex models. Clawboo prices the tokens at its default estimate rate ($3 per million input tokens, $15 per million output tokens), records the result as an estimate, and counts it toward your budgets. Codex reports once, as the run ends, so a hard cap that report crosses keeps the finished result and refuses the next run. On a ChatGPT plan you are not billed per token: the estimate is a guide for your budgets, not your bill. See Budgets and spend for how each runtime’s cost reaches your budgets.Sign out
In Settings > Runtimes, click Manage on the Codex row, then Sign out and confirm. Clawboo runs Codex’s owncodex logout, and the row then reads Needs login. Codex keeps no key in Clawboo’s vault, so there is nothing else for Clawboo to delete.
Limits
- Team setup has no model picker for Codex members; runs use your plan’s default model.
- Your own
~/.codexsettings do not apply to Codex agents. - A Codex too old to run
codex app-serverfalls back tocodex exec, which cannot take comments mid-run. - Its cost in Clawboo is always an estimate.
Troubleshooting
Codex reads Needs login after I signed in from a terminal
Codex reads Needs login after I signed in from a terminal
codex login status) whether you are signed in, so a sign-in from any terminal on this computer counts.The codex CLI isn't installed yet. Install it first, then sign in.
The codex CLI isn't installed yet. Install it first, then sign in.
Sign-in timed out. Try again.
Sign-in timed out. Try again.
codex login in a terminal and click Re-check.Sign-in did not complete (exit 1). Run codex login in your terminal, then re-check.
Sign-in did not complete (exit 1). Run codex login in your terminal, then re-check.
codex login in a terminal to see Codex’s own message, finish the sign-in there, then click Re-check.A run fails with no Codex credentials provisioned for managed home
A run fails with no Codex credentials provisioned for managed home
~/.codex. Run codex login in a terminal, then send the message or start the task again. The next run copies the new sign-in into the agent’s folder.Every run fails with: The '...' model is not supported when using Codex with a ChatGPT account
Every run fails with: The '...' model is not supported when using Codex with a ChatGPT account
PATH it gives the npm command. Open Settings > Runtimes, click Update on the Codex row, then Update Codex, or for a Codex you installed yourself run npm install -g @openai/codex@0, then try again. If the run named a model, pick one your plan offers instead, or clear it to use your plan’s default.Comments reach a Codex agent only at its next run
Comments reach a Codex agent only at its next run
Check that it works
- In Settings > Runtimes, the Codex row reads Connected.
- Open the team chat of a team with a Codex member. Type
@, pick that agent, and ask: “Say hello in one sentence.” - You should see a reply under the agent’s name. If the run fails, the chat shows “The run failed:” and the reason; look it up in Troubleshooting.
Under the hood
Under the hood
- Each run starts
codex app-serverwithCODEX_HOMEset to the agent’s Codex folder, sendsinitialize(20-second limit), thenthread/startorthread/resumewithapprovalPolicy: 'never'andsandbox: 'danger-full-access', then oneturn/start. Any request the app-server sends back is answered with an error. - If the app-server cannot start or the handshake fails, the run uses
codex exec --json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check, orcodex exec resume <id>to continue a thread. - A failed run reports the reason the app-server or
codex execgave, unwrapped from OpenAI’s JSON error, rather than the CLI’s log. The app-server also types the cause (codexErrorInfo), which becomes the error’s code, in the words Claude Code uses for the same cause where there is one: a refused login isauthentication_failed, as is a connection refused with HTTP 401 or 403, an HTTP 402 isbilling_error, an HTTP 429 israte_limit, and a plan’s usage limit isusage_limit_exceeded. A refused login waits in Needs you with Fix sign-in; see Error classes.codex exectypes two causes from the failed turn’s own reason: one that says it outgrew the model’s context window (the CLI’s own sentence, or the backend’scontext_length_exceeded) iscontext_overflow, ascontextWindowExceededis on the app-server, and an HTTP 429 or arate_limitcode israte_limit, whatever its words. Its other failures are classified by their text. After an overflow on either path, the next run in team chat or a one-to-one chat starts a fresh session instead of resuming that one. - Your plan’s model list comes from
GET /api/runtimes/codex/models(see the Runtimes API), cached for 10 minutes. - A comment on a running task goes in with
turn/steer. A comment that arrives after the turn ended waits for the agent’s next turn. - Run a board task on Codex directly with
POST /api/runtimes/codex/run; see the Runtimes API. A run without an agent id uses the folder~/.clawboo/runtimes/codex/codex, and itscostUsdis the token estimate.
Related
- Choose a runtime: how Codex compares with the other runtimes.
- Connect AI providers and runtimes: the ChatGPT sign-in, keys and disconnecting.
- What agents can do: permissions and safety for every runtime.
- Budgets and spend: how estimated costs reach your budgets.
- Hermes and OpenClaw: two more runtimes that can run on a ChatGPT plan, each with its own sign-in.
codex exec, which cannot take input mid-run. That happens when the installed Codex has nocodex app-server, or the app-server does not answer within 20 seconds. Update Codex, then try again: click Update on the Codex row in Settings > Runtimes when it offers one, or, for a Codex you installed yourself, runnpm install -g @openai/codex@0.