OpenAI & Codex

OpenAI API and Codex now use different execution paths:

OpenAI API — Workbench keeps the gateway path. It starts a local HTTP listener that translates Claude’s wire format into the OpenAI Responses API (/v1/responses) so the official claude CLI can talk to OpenAI-shaped endpoints.
Codex — Workbench uses the codex CLI app-server (codex app-server --listen stdio://) and talks JSON-RPC to that process. This path supersedes the old codex-subscription gateway row when Codex is enabled.

Prerequisites

For the OpenAI API backend, make sure Settings > Models > Agent providers is on. OpenAI API remains manual because it needs an API key.

For Codex, make sure Settings > Models > Codex is on. Workbench auto-enables Codex at startup when it detects the codex CLI, unless you have manually turned Codex off. When Codex is on, Settings > Models shows Codex and the chat model picker includes the seeded Codex models immediately.

OpenAI API

For users who specifically want gpt-* or OpenAI reasoning models, or who have prepaid OpenAI credit they’d rather use instead of Claude quota.

Get an API key from platform.openai.com.
In Settings > Models, find the openai-api backend.
Paste the key into the API key field and save.
Click Test — Workbench validates the key against /v1/models.
Click Refresh models — Workbench queries the OpenAI /v1/models endpoint and populates the model list.
Set a default model if desired.
Toggle Enabled on.

The OpenAI API provider appears in the chat header picker alongside Claude.

Codex

Codex reuses the codex CLI’s ChatGPT subscription auth instead of an API key. It is useful if you have a ChatGPT Plus / Pro / Team subscription that includes Codex access and want Workbench to drive Codex natively.

Install the codex CLI

npm install -g @openai/codex
# or
bun install -g @openai/codex

Confirm it is on PATH: codex --version should print a version.

Workbench resolves codex from the app’s enriched PATH plus common user install locations on macOS, Linux, and Windows, including npm shims and native codex.exe installs.

In Settings > Models, find Codex and click Run codex login. Workbench runs codex login for you, which:

Opens your browser to OpenAI’s OAuth page.
Has you sign in with your ChatGPT account.
Stores Codex CLI credentials under ~/.codex/.

You can also select a Codex model and run /login in chat, or run codex login yourself in any terminal.

Configure

In Settings > Models, make sure Codex is on.
Find the Codex backend card.
If you have not signed in yet, click Run codex login.
Workbench refreshes Codex models once in the background at startup when Codex is enabled, so authenticated users usually see account models appear automatically. Click Refresh models for an immediate manual refresh.
Set a default model if desired.
Toggle Enabled on.

Codex Native harness

Codex is a fully independent harness — it does not start the Claude Code CLI or the OpenAI gateway. Workbench communicates with the codex CLI’s built-in app-server mode over JSON-RPC on stdio, so there is no HTTP listener or API translation layer involved.

Runtime behavior

Workbench spawns codex app-server --listen stdio:// in the workspace.
Workbench initializes the app-server over JSON-RPC.
New turns use thread/start and turn/start; mid-turn steering uses turn/steer; stop requests use turn/interrupt.
Fast mode maps to Codex’s priority service tier through app-server serviceTier.
Codex intelligence uses the same user-facing shape as Codex: Low, Medium, High, and Extra High. Workbench maps those levels to app-server turn/start.effort values (low, medium, high, xhigh) and seeds new threads with config.model_reasoning_effort. Empty or stale Codex effort values normalize to High. Codex does not expose a model reasoning on/off toggle in the picker metadata, so Workbench only offers the intelligence levels plus a display-only Show Codex reasoning toggle for reasoning summaries.
Codex notifications are adapted into Workbench chat events for assistant text, reasoning summaries, command execution, MCP tool calls, file changes, token usage, turn completion, failures, and process exit.
Codex app-server approval requests for command execution, file changes, permission escalation, request_user_input, and MCP elicitations are answered over JSON-RPC. Denying one of these Codex approvals sends only a decline decision to Codex; freeform denial feedback is reserved for approval flows that can forward it.

Codex plan mode

Codex has its own plan collaboration mode, separate from Claude Code’s plan approval flow. When plan mode is enabled on a Codex Native session, Codex presents its plan for review before executing changes. This is controlled by the same plan-mode toggle in the chat header, but the underlying mechanism is Codex’s native plan collaboration rather than Claude Code’s plan approval protocol.

Compact routing

The /compact slash command works on Codex Native sessions. Workbench routes /compact to the app-server’s thread/compact/start JSON-RPC method, which triggers Codex’s own context compaction. The result flows back through the same compaction UI used by other harnesses — a Compacting context… status while in flight and a compact-boundary divider on success.

Permission levels map to Codex approval and sandbox settings:

Workbench permission	Codex approval	Codex sandbox
Read-only	`untrusted`	`read-only`
Standard	`on-request`	`workspace-write`
Full access	`never`	`danger-full-access`

Native Codex currently does not expose Claude Remote Control, Claude MCP config injection, or image/file attachments through Workbench. Those controls remain Claude Code-only until the app-server protocol has matching wired surfaces.

Legacy Codex Gateway

The old codex-subscription backend routed ChatGPT subscription auth through Workbench’s OpenAI Responses gateway. It is no longer user-facing in Settings; Codex CLI app-server is the Codex path.

Custom OpenAI-shaped endpoints

The CustomOpenAi backend kind exists in the data model but is not yet exposed in the Settings panel. When that flow lands, the same OpenAI gateway path will work for providers that implement /v1/responses. Providers that only ship /v1/chat/completions will not work behind the gateway until they add the Responses API.

Troubleshooting

Test fails on OpenAI API — the API key is invalid or rate-limited. Re-paste it; check the dashboard at platform.openai.com/usage.

Codex fails to start — confirm codex --version works from the same shell environment and run codex login again.

Agent immediately errors with no model — set a default model in Settings > Models for the selected backend.

OpenAI gateway restart loop — usually caused by the upstream rejecting the translated request. Open the agent’s terminal tab to see stderr from the listener; common causes are a model ID the upstream does not recognize or a request shape the gateway cannot translate.