What is Codex CLI?
Codex CLI is OpenAI's coding agent for working with repositories, editing files, running commands, and completing development tasks from the terminal.
This guide explains how to configure Codex CLI with a TokenHub custom API provider. It preserves the Codex workflow while centralizing API keys, compatible models, request logs, and token usage in TokenHub. Codex custom providers use the OpenAI Responses API rather than ordinary Chat Completions, so model selection must account for Responses, streaming, and tool-call behavior. Validate the provider in a non-production repository, begin with inspection and explanation tasks, and only then allow edits or shell commands.
Codex can route model requests through TokenHub's OpenAI compatible API gateway. Keep the official installation flow, then replace only the API key, Base URL, and model ID.
The TokenHub endpoint used by this guide is https://us-api.tokenhub.com/v1/responses.
When to use it
Start in a small repository or test project. First ask the tool to read files, explain code, or produce a plan; only then enable edits, terminal commands, or agent automation.
Install or open the tool
Follow the official Codex documentation to install or open the tool. If menus or command names differ, prefer the current official documentation.
For CLI tools, confirm the executable works before adding TokenHub credentials:
codex --versionPrepare TokenHub credentials
Create a TokenHub API key and choose a model from the TokenHub model list that fits this tool.
export TOKENHUB_API_KEY="sk-..."Keep the key in your local shell, IDE secret storage, or the secure API key field of the tool. Do not commit it to the repository.
Configure TokenHub persistently
Use the tool configuration file or settings page first. This avoids the common problem where a terminal sees the environment variable but the IDE, plugin, or new window does not.
Provider values
| Field | Value |
|---|---|
| Provider | OpenAI Compatible or Custom |
| Base URL | https://us-api.tokenhub.com/v1 |
| API Key | The value of TOKENHUB_API_KEY |
| Model | gpt-4.1 or another TokenHub model ID |
Settings file locations
| Field | Value |
|---|---|
| User config | ~/.codex/config.toml |
| Provider section | model_providers.tokenhub |
| Secret source | env_key = "TOKENHUB_API_KEY" |
model = "gpt-4.1"
model_provider = "tokenhub"
[model_providers.tokenhub]
name = "TokenHub"
base_url = "__API_BASE_URL__/v1"
env_key = "TOKENHUB_API_KEY"
wire_api = "responses"Codex uses the Responses wire API for this provider, so choose a TokenHub model that supports https://us-api.tokenhub.com/v1/responses.
If your installed version writes a slightly different schema, use its interactive setup first, then keep the same TokenHub values: Base URL, API key, and model ID.
If the tool separates chat, edit, apply, and fast models, use the same TokenHub model for the first test. Split models later by cost, latency, and reasoning strength.
Temporary environment variables for debugging
Use temporary variables only to confirm the key, network, and model name. After validation, move the same values into the persistent configuration above.
export TOKENHUB_API_KEY="sk-..."Verify the connection
Test with a read-only prompt first, confirming that the model can read context without changing files. Then test edits, Apply, or agent tasks.
Read the project README and summarize it in three sentences. Do not modify any files.After a successful prompt, check TokenHub request logs for model name, endpoint, token usage, and billing group.
Troubleshooting
| Symptom | Fix |
|---|---|
| 401 or authentication failure | Confirm TOKENHUB_API_KEY is valid and saved in the same terminal, IDE, or client profile. |
| 404 or model not found | Use a model ID that exists in your TokenHub workspace and matches the selected protocol. |
| Wrong endpoint | Keep the Base URL exactly as shown. OpenAI-compatible tools usually need /v1; Claude-compatible tools usually do not. |
| Request timeout | Check network access to https://us-api.tokenhub.com, proxy settings, and workspace allowlists. |
| Tool uses another model | Recheck every chat, edit, apply, fast, and autocomplete model slot. |
Choose a compatible Codex model
Codex CLI custom API FAQ
Why does the Codex Base URL need /v1?
Codex appends the Responses path to the provider base_url, so the TokenHub provider should use the API root followed by /v1.
Can I change wire_api to chat_completions?
Keep wire_api = "responses" for the current Codex custom provider. If the model does not support Responses, choose another model rather than using an unverified protocol value.
Why does Codex still report a missing API key?
Check that env_key in config.toml exactly matches TOKENHUB_API_KEY and start Codex from a new terminal that contains the variable.
How is Codex CLI different from Claude Code?
Both are coding agents, but their custom-provider protocols differ: Codex uses OpenAI Responses while Claude Code uses Anthropic Messages. Compare workflow, tool reliability, context, latency, and cost.
How is Codex usage billed through TokenHub?
TokenHub bills the input, output, and applicable cache usage of the selected model. There is no single Codex CLI model price, so check the current model detail page before use.
References
This setup is based on TokenHub and official documentation, last verified on 2026-09-04.