# Codex CLI

> Add Tokens as a custom model provider in Codex CLI's config.toml, keep the key in an environment variable, and handle models whose upstream doesn't support the Responses API.

Codex CLI is OpenAI's open-source terminal coding agent. It only speaks the OpenAI Responses API, so with Tokens it uses `https://tokens.bd/v1` and sends every request to [/v1/responses](/docs/responses). It has no Anthropic Messages option.

:::warning[Responses support depends on the model]
Tokens forwards `/v1/responses` as is. Whether a request succeeds depends on whether the provider serving that model implements the Responses API, including streaming events and tool calls. Codex works best with models whose upstream supports Responses. If requests fail with one model, try another before changing anything else.
:::

## Quick setup with the Tokens CLI

The [Tokens CLI](/docs/tokens-cli) handles sign-in, key creation and model choice, then writes the Codex provider for you. It needs Node 18 or newer.

:::code-tabs

```bash title="macOS / Linux"
curl -fsSL https://tokens.bd/cli/tokens.mjs -o tokens.mjs && node tokens.mjs setup --base-url https://tokens.bd --agents codex
```

```powershell title="Windows PowerShell"
iwr https://tokens.bd/cli/tokens.mjs -OutFile tokens.mjs; node tokens.mjs setup --base-url https://tokens.bd --agents codex
```

:::

It adds the provider to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) in a marked block and leaves the rest of the file alone. The model goes in a profile, a separate file beside it. Running setup again replaces both:

```toml title="~/.codex/config.toml (written by the Tokens CLI)"
[model_providers.tokens]
name = "Tokens"
base_url = "https://tokens.bd/v1"
env_key = "TOKENS_API_KEY"
wire_api = "responses"
```

```toml title="~/.codex/tokens.config.toml (written by the Tokens CLI)"
model = "deepseek/deepseek-v4.1-flash"
model_provider = "tokens"
```

Neither file holds a secret. Codex reads the key from `TOKENS_API_KEY`, so export it (next section) and start Codex with `codex --profile tokens`. Plain `codex` keeps using your default setup.

:::note[Profiles need a recent Codex]
Codex 0.134.0 moved profiles into separate files. Older versions don't read `tokens.config.toml`, so update Codex, or use the manual setup below, which makes Tokens the default provider and needs no profile. Checked with Codex CLI 0.166.0, November 2026.
:::

## Export TOKENS_API_KEY

Create a key at [/dashboard/keys](/dashboard/keys) if the CLI didn't make one for you ([API keys](/docs/api-keys) explains caps and allow-lists).

:::code-tabs

```bash title="macOS / Linux"
# add to ~/.bashrc or ~/.zshrc to keep it
export TOKENS_API_KEY="tok_live_your_key"
```

```powershell title="Windows PowerShell"
$env:TOKENS_API_KEY = "tok_live_your_key"   # this window
setx TOKENS_API_KEY "tok_live_your_key"     # new windows
```

:::

`setx` only affects terminals opened afterwards, so open a new one before running `codex`.

## Configure ~/.codex/config.toml manually

Install Codex if needed:

```bash
npm install -g @openai/codex
```

On Windows you can also use `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"`.

Codex reads `config.toml` from `CODEX_HOME`, which defaults to `~/.codex` (`%USERPROFILE%\.codex` on Windows). Add the provider and select it with the top-level `model_provider` and `model` keys:

```toml title="~/.codex/config.toml"
model = "deepseek/deepseek-v4.1-flash"
model_provider = "tokens"
# model_context_window = 128000   # optional; placeholder, use the real value

[model_providers.tokens]
name = "Tokens"
base_url = "https://tokens.bd/v1"
env_key = "TOKENS_API_KEY"
wire_api = "responses"
```

Top-level keys must come before any `[table]` in TOML, so put `model` and `model_provider` near the top of the file.

A few rules from the Codex docs:

- The provider id can't be one of the built-ins (`openai`, `ollama`, `lmstudio`). `tokens` is fine.
- `wire_api` must be `"responses"`. The old `"chat"` value is no longer accepted.
- If you set `model_context_window`, take the real number from the model's page in [/models](/models). `128000` above is a placeholder.

## Switch models

Change `model` in `config.toml` (or in `tokens.config.toml` if you used the Tokens CLI) and restart Codex. Get exact ids from [/models](/models), `node tokens.mjs models`, or `GET /v1/models`. Because Responses support varies by upstream, test a new model with the curl call below before committing to it. [Choosing a model](/docs/choosing-a-model) has guidance on picking one for agent work.

## Verify it works

Check that the model answers on the Responses endpoint first:

```bash
curl https://tokens.bd/v1/responses \
  -H "Authorization: Bearer $TOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek/deepseek-v4.1-flash", "input": "Reply with OK", "max_output_tokens": 20}'
```

Then run a one-shot task through Codex:

```bash
codex exec "Reply with OK"
```

Interactively, start `codex` (or `codex --profile tokens`) and check the model and provider in the status line.

## Troubleshooting

**`Error loading config.toml: wire_api = "chat" is no longer supported`.** Change `wire_api` to `"responses"`. Codex removed Chat Completions support.

**400 or 404 from upstream on `/v1/responses`.** The provider behind that model doesn't implement the Responses API, or doesn't implement part of it that Codex uses. Pick another model. The same model may still work fine from tools that use chat completions.

**401 `missing_api_key`.** `TOKENS_API_KEY` isn't set in the shell that launched Codex. After `setx`, open a new terminal. On macOS/Linux, check that your profile file exports it.

**403 `model_not_allowed_on_key`.** The key has an allow-list that doesn't include this model. Allow-lists can't be edited, so create a new key.

**TOML parse error after editing.** A top-level key placed after a `[table]` header belongs to that table. Move `model` and `model_provider` above the first table.

**`--profile tokens cannot be used while config.toml contains legacy ...`.** `config.toml` has a `[profiles.tokens]` table, which older versions of the Tokens CLI wrote. Download `tokens.mjs` again and run setup; it removes the table. If you wrote the table yourself, move its settings to `~/.codex/tokens.config.toml`.

**`Model metadata for ... not found`.** Codex doesn't know Tokens ids, so it warns and uses default limits. Requests still go through. Set `model_context_window` to the model's real value.

**The Tokens CLI skipped Codex.** It refuses to touch a file that has its own `[model_providers.tokens]` or `[profiles.tokens]` table, or `profile = "tokens"`, outside its marked block, or a `tokens.config.toml` it didn't write. Remove or rename yours, then run setup again.

For 402, 429 and 5xx codes, see [Troubleshooting](/docs/troubleshooting). Include the `x-tokens-request-id` response header in support tickets.

---
Page: https://tokens.bd/docs/codex-cli
