---
title: "OpenAI Codex CLI"
description: "Use OpenAI's Codex command-line tool as a Cerevisor provider, ChatGPT subscription auth, sandbox modes, and the limits to know about."
slug: guides/providers/openai-codex-cli
section: guides
subsection: providers
canonical_url: https://cerevisor.com/docs/guides/providers/openai-codex-cli
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

The **Codex CLI** provider runs each agent by spawning `codex exec --json` as a subprocess. OpenAI's Codex owns the agentic loop, sandboxing, and auth, Cerevisor handles wave orchestration, dependency tracking, and inter-agent handoff.

The main reason to use it: **you have a ChatGPT Plus or Pro subscription** and don't want to pay per-token for the same model when you're already paying monthly.

## Prerequisites

- Node.js (any recent LTS).
- Codex CLI installed: `npm install -g @openai/codex`.
- A ChatGPT Plus / Pro subscription (or an OpenAI API key; both auth modes are supported, but the subscription path is the typical case).

## Setup wizard

1. **Settings → Providers → + Add provider → Codex CLI.**

The wizard runs six steps:

### 1. Detect
Cerevisor runs `codex --version` to confirm Codex is installed and reachable. On Windows, it auto-resolves the `.cmd` shim that `npm install -g` creates.

### 2. Auth status
Runs `codex login status` to check whether you're already signed in. If you are, skip ahead. If not:

### 3. Device auth
Click **Start device auth**. Cerevisor invokes `codex login --device-auth`. A URL and code appear; copy the code and open the URL in a browser, sign in to ChatGPT, paste the code. The wizard polls `codex login status` every 2 seconds and advances when sign-in completes.

### 4. Keyring config (optional)
On supported platforms, the wizard offers to write Codex's auth into your OS keyring instead of the plain text file. Recommended.

### 5. Smoke test
Cerevisor runs `codex exec --json` with a trivial prompt to confirm everything works end-to-end. The smoke test result is shown.

### 6. Save
The provider becomes available.

## What Codex CLI runs

When an agent uses the Codex CLI provider, Cerevisor invokes:

```
codex exec --json \
  --ephemeral \
  --skip-git-repo-check \
  --cd <project-folder> \
  -c sandbox_mode=<read-only|workspace-write|danger-full-access> \
  -c approval_policy=<untrusted|on-failure|on-request|never> \
  --output-last-message <temp-file> \
  -
```

The prompt is piped via stdin (the `-` positional). `--ephemeral` disables Codex's session-rollout writer (so two Cerevisor agents using Codex don't conflict).

## Sandbox modes

Cerevisor translates your workflow's permissions to Codex's `sandbox_mode`:

| Cerevisor permissions | Codex `sandbox_mode` |
|---|---|
| All filesystem set to Allow + execution set to Allow | `danger-full-access` |
| Workspace writes Allow, outside workspace blocked | `workspace-write` |
| Everything read-only | `read-only` |

## Approval policies

Cerevisor derives `approval_policy` from the same `WorkflowPermissions` (file write + bash execution + web access), not from a single trust-profile selector. The common patterns:

| Cerevisor permissions | Codex `approval_policy` |
|---|---|
| File write + bash + web all Allow | `never` |
| File write Allow, bash blocked or web blocked | `on-failure` |
| Most categories Ask | `on-request` |
| Read-only across the board | `untrusted` |

When in doubt, set the workflow permissions you actually want and let Cerevisor compute the matching Codex flags.

## Known v1 limitations

These are the trade-offs of using Codex as your runner, known limitations, not bugs:

- **Per-tool permission prompts don't interpose.** Cerevisor's `PermissionModal` can't intercept individual tool calls inside Codex's subprocess. Sandbox + approval policy are set up-front.
- **Mid-run conversation resume is not supported.** Codex's `exec` mode is one-shot per prompt. So the contract-retry and verifier-retry paths Cerevisor uses for other providers are disabled for Codex agents: the harness emits `agent_verifier_skipped` with reason `codex-cli-no-resume`.
- **Background features can't use Codex.** The chat builder, run retrospectives, memory crystallization: anything that does `.chat()`, require an Anthropic or OpenAI-compatible provider. Configure one separately for background use.
- **MCP tools added in Cerevisor don't reach Codex.** Codex has its own tool catalog; Cerevisor doesn't inject MCP tools into the subprocess.
- **Cost is reported as `$0.00`.** Subscription billing: Cerevisor has no way to compute per-call cost. The analytics view classifies these sessions as "subscription" so they're distinguishable from per-token runs.

## Switching ChatGPT plans

The Codex CLI is tied to your ChatGPT account. If you upgrade or downgrade your plan, Codex picks up the change automatically, no Cerevisor action needed.

## Windows note

`npm install -g @openai/codex` installs as `codex.cmd` on Windows. Cerevisor auto-resolves the `.cmd` path so `child_process.spawn('codex', ...)` works. If the wizard reports "Codex not found" but `codex --version` works in your terminal, restart Cerevisor, PATH is read at launch.

## macOS note

If you launched Cerevisor from Finder (not Terminal), macOS strips PATH to the system defaults, so even though `which codex` works in your terminal, the launched app might not see it. Cerevisor uses `fix-path` at startup on macOS to repair PATH for the lifetime of the process, so this should be transparent.