Codex CLI + TOKNADO
How to point Codex CLI at TOKNADO (custom base URL and provider)
Codex CLI reads its settings from ~/.codex/config.toml and lets you define your own model provider with a base URL and an environment variable for the key. That is how you route Codex through an OpenAI-compatible gateway like TOKNADO.
There is one version-dependent detail worth knowing up front: Codex's wire protocol setting. We cover it below so you don't lose an hour to a mismatch.
Start free trial Jump to setup
What you need
- Codex CLI installed and working (
codex --version). - Your TOKNADO endpoint and API key.
- A model ID from your TOKNADO dashboard.
Setup: Codex CLI with TOKNADO
Export your key
Codex reads the key from the environment variable you name in the provider block, so no secret sits in the config file.
export TOKNADO_API_KEY=YOUR_TOKNADO_API_KEYAdd a TOKNADO provider to config.toml
Custom provider IDs can't reuse Codex's built-in IDs (
openai,ollama,lmstudio), so use a distinct name such astoknado.# ~/.codex/config.toml model = "toknado/auto" model_provider = "toknado" [model_providers.toknado] name = "TOKNADO" base_url = "https://toknado.up.railway.app/v1" env_key = "TOKNADO_API_KEY" wire_api = "chat"Run Codex
Start it normally, or select the provider for a single run with
-c.codex # one-off override without editing config.toml codex -c model_provider="toknado" -c model="toknado/auto"Optional: keep OpenAI as default with a profile
If you still use Codex with OpenAI, define a profile and switch with
--profileinstead of changing your defaults.codex --profile toknado
Notes for real-world use
- A quick alternative for testing is the
OPENAI_BASE_URLenvironment variable, which overrides the endpoint for that session. A named provider is cleaner for daily use and team setups. - Codex edits files and runs commands, so one task can mean many requests. Watch the rolling hourly limit on your plan.
- Precedence matters: CLI flags beat profiles, which beat project config, which beats
~/.codex/config.toml. If Codex still hits the wrong host, look for an override higher up the chain.
Troubleshooting Codex CLI + TOKNADO
| Symptom | What to check |
|---|---|
| Still contacting api.openai.com | A profile or project .codex/config.toml is overriding your provider. Check precedence, or pass -c model_provider="toknado". |
| 401 unauthorized | TOKNADO_API_KEY isn't set in the shell Codex runs from. Run echo $TOKNADO_API_KEY and restart the terminal. |
| 404 on requests | Check base_url ends with the API path (usually /v1) and doesn't include /chat/completions. |
| Config error about provider ID | You used a reserved ID. Rename the provider to something like toknado. |
| Model not found | Use the exact model ID shown in the TOKNADO dashboard. |
FAQ
Can Codex CLI use a custom base URL?
Yes. Define a provider under [model_providers.<id>] in ~/.codex/config.toml with base_url and env_key, then set model_provider to its ID.
What is env_key?
The name of the environment variable Codex reads your API key from, so the key isn't stored in the file.
Does Codex need the Responses API?
It depends on the Codex version. Gateways that implement Chat Completions are used with wire_api = "chat" where your version supports it. Verify against your installed version's docs.
How do I switch between OpenAI and TOKNADO?
Use profiles (codex --profile toknado) or the -c model_provider=... override.