Skip to content
Tokens
API keys

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.

Works withCodex CLITerminal
On this page
  1. Quick setup with the Tokens CLI
  2. Export TOKENS_API_KEY
  3. Configure ~/.codex/config.toml manually
  4. Switch models
  5. Verify it works
  6. Troubleshooting

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.

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 handles sign-in, key creation and model choice, then writes the Codex provider for you. It needs Node 18 or newer.

curl -fsSL https://tokens.bd/cli/tokens.mjs -o tokens.mjs && node tokens.mjs setup --base-url https://tokens.bd --agents codex

It adds a marked block to ~/.codex/config.toml (or $CODEX_HOME/config.toml) and leaves the rest of the file alone. Running setup again replaces the block in place:

/.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"

[profiles.tokens]
model = "deepseek/deepseek-v4.1-flash"
model_provider = "tokens"

The file holds no secret. Codex reads the key from TOKENS_API_KEY, so export it (next section) and start Codex with codex --profile tokens.

Note

Current Codex docs describe profiles as separate files (~/.codex/<name>.config.toml). If codex --profile tokens reports that the profile doesn't exist, use the manual setup below, which makes Tokens the default provider and needs no profile.

Export TOKENS_API_KEY#

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

# add to ~/.bashrc or ~/.zshrc to keep it
export TOKENS_API_KEY="tok_live_your_key"

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:

/.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. 128000 above is a placeholder.

Switch models#

Change model in config.toml (or under [profiles.tokens] if you use the CLI's block) and restart Codex. Get exact ids from /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 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.

The Tokens CLI skipped Codex. It refuses to touch a file that already has its own [model_providers.tokens] or [profiles.tokens] table outside its marked block. Remove or rename yours, then run setup again.

For 402, 429 and 5xx codes, see Troubleshooting. Include the x-tokens-request-id response header in support tickets.

Was this page helpful?

Still stuck? Open a support ticket

Need help configuring your agent?

Test your connection with the connection tester, or create an API key.

Create API keyTroubleshooting