---
title: OpenAI & Codex
description: Run Claudette agents through the OpenAI API gateway or through the Codex CLI app-server.
---

OpenAI API and Codex now use different execution paths:

- **OpenAI API** — Claudette 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** — Claudette 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. Claudette 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.

1. Get an API key from [platform.openai.com](https://platform.openai.com/).
2. In **Settings > Models**, find the `openai-api` backend.
3. Paste the key into the **API key** field and save.
4. Click **Test** — Claudette validates the key against `/v1/models`.
5. Click **Refresh models** — Claudette queries the OpenAI `/v1/models` endpoint and populates the model list.
6. Set a default model if desired.
7. 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 Claudette to drive Codex natively.

### Install the codex CLI

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

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

Claudette 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.

### Sign in

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

1. Opens your browser to OpenAI's OAuth page.
2. Has you sign in with your ChatGPT account.
3. 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

1. In **Settings > Models**, make sure **Codex** is on.
2. Find the **Codex** backend card.
3. If you have not signed in yet, click **Run codex login**.
4. Claudette 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.
5. Set a default model if desired.
6. Toggle **Enabled** on.

### Runtime behavior

Codex does not start the Claude Code CLI or the OpenAI gateway. Instead:

1. Claudette spawns `codex app-server --listen stdio://` in the workspace.
2. Claudette initializes the app-server over JSON-RPC.
3. New turns use `thread/start` and `turn/start`; mid-turn steering uses `turn/steer`; stop requests use `turn/interrupt`.
4. Fast mode maps to Codex's priority service tier through app-server `serviceTier`.
5. Codex intelligence uses the same user-facing shape as Codex: `Low`, `Medium`, `High`, and `Extra High`. Claudette 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 Claudette only offers the intelligence levels plus a display-only **Show Codex reasoning** toggle for reasoning summaries.
6. Codex notifications are adapted into Claudette chat events for assistant text, reasoning summaries, command execution, MCP tool calls, file changes, token usage, turn completion, failures, and process exit.
7. 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.

Permission levels map to Codex approval and sandbox settings:

| Claudette 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 Claudette. 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 Claudette'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.

## See also

- [Agent Providers overview](/claudette/features/providers/) — capability matrix and architecture
- [Ollama](/claudette/features/providers/ollama/) — local provider setup
- [Authentication](/claudette/features/authentication/) — credential handling for the default Anthropic backend
