Developer setup
How to Use ChatGPT and Codex with a Third-Party API: config.toml Setup Guide
Configure Codex and ChatGPT CLI with a custom provider in ~/.codex/config.toml. Understand wire_api responses, set up auth.json, use CC Switch, and troubleshoot errors.
What to Prepare Before Customizing config.toml
OpenAI Codex CLI and desktop tools offer an extensible agent environment for code generation and automated repository refactoring. By configuring a custom model provider in config.toml, developers can route Codex traffic through an independent gateway like API Route to call models listed on the pricing page, including GPT-5 series, Claude Sonnet, and DeepSeek, and audit usage. A dated Claude price comparison is on the blog. This guide does not state a savings percentage.
Before editing configuration files, ensure you have an active API Route key from API Access, check model availability on the pricing page, and verify that the Codex CLI is installed locally. Review the official provider connection protocol alongside the standard OpenAI Chat Completions reference.
Protocol Essentials: Why wire_api Must Be Set to responses
A critical breaking change in modern Codex releases is the complete deprecation of legacy chat protocols. In config.toml, the provider specification requires wire_api = "responses". Setting wire_api = "chat" will cause Codex to fail immediately upon startup with an unsupported wire protocol exception.
Codex relies on OpenAI's stateful Responses API format to stream tool-call invocations, agent steps, and client-side workspace updates. API Route natively terminates and converts Responses API payloads, allowing your client to preserve full agentic functionality without external mapping sidecars.
| Configuration Key | Required Value | Technical Description |
|---|---|---|
| model_provider | "api_route" | Top-level key specifying which provider definition block Codex activates by default. |
| base_url | "https://global.api-route.com/v1" | The gateway endpoint. Note: Do not omit /v1 and do not include a trailing slash. |
| wire_api | "responses" | Mandatory protocol wire format. Legacy "chat" is unsupported in current Codex CLI releases. |
| requires_openai_auth | true | Directs Codex to forward credentials formatted for OpenAI-compatible endpoints. |
| disable_response_storage | true | Optional privacy guard that disables upstream session caching on third-party servers. |
Note that provider blocks defined in a project-local .codex/config.toml are strictly ignored by Codex for security isolation. All custom provider definitions must reside in the global user-level directory.
Step-by-Step: Editing config.toml and auth.json
Depending on your operating system, Codex stores its configuration in the following locations:
- macOS / Linux:
~/.codex/config.tomland~/.codex/auth.json - Windows:
%USERPROFILE%\.codex\config.tomland%USERPROFILE%\.codex\auth.json
First, create the directory if it does not exist, and back up any existing configuration before opening an editor:
mkdir -p ~/.codex
test -f ~/.codex/config.toml && cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.tomlReplace the complete contents of ~/.codex/config.toml with the custom provider definition below:
# ~/.codex/config.toml
model_provider = "api_route"
model = "gpt-5.6-sol"
disable_response_storage = true
[model_providers.api_route]
name = "API Route"
base_url = "https://global.api-route.com/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = falseNext, write your API Route key into ~/.codex/auth.json. Codex reads the bearer token directly from this JSON file:
{
"OPENAI_API_KEY": "sk-your-api-route-key"
}On Unix systems, restrict file permissions so only your user account can read the secrets:
chmod 600 ~/.codex/config.toml
chmod 600 ~/.codex/auth.jsonFor Linux-specific instructions, consult the Codex custom provider documentation.
Alternative: Graphical Import via CC Switch Desktop
If you prefer a graphical interface over manual TOML editing, use the open-source CC Switch desktop manager. CC Switch manages provider profiles across Codex, Claude Code, and other developer tools with zero terminal editing.
- Open API Access, choose your active key, target model, and preferred endpoint node.
- Select Codex as the target application and keep the connection mode on CC Switch.
- Ensure CC Switch is running on your desktop, then click Import to CC Switch.
- Inside CC Switch, navigate to the Codex providers tab and switch the imported
api-routeprofile to Active. - Restart Codex. The
api-routeprovider tag will appear in the lower-left corner of the interface.
CC Switch automatically writes the exact config.toml and auth.json structures outlined above, eliminating manual formatting errors.
Verification and Diagnostic Troubleshooting Matrix
After updating your configuration, run the Codex diagnostic utility to verify connectivity before running production agent loops:
codex doctor
codex "Reply in one sentence: What model are you?"If Codex encounters connection errors, refer to the following troubleshooting matrix:
| Symptom / Error | Underlying Cause | Verification and Remediation |
|---|---|---|
| Unsupported wire_api error | config.toml specifies wire_api = "chat" | Update config.toml to specify wire_api = "responses". Current Codex releases reject "chat". |
| 401 Unauthorized | Missing or malformed key in auth.json | Check ~/.codex/auth.json. Ensure the JSON key is "OPENAI_API_KEY" with a valid API Route secret. |
| 404 Not Found on API calls | Endpoint URL contains extra or missing path segments | Ensure base_url is exactly "https://global.api-route.com/v1" with no trailing slash. |
| Provider ignored / defaults to official | config.toml placed in local project folder | Move settings to user home directory ~/.codex/config.toml. Local project configs block provider blocks. |
| 403 Forbidden / Model disabled | Selected model is not enabled for your API key group | Inspect available models via /v1/models or verify key permissions in API Access. |
Reconcile each test request against usage logs to verify accurate token deductions and latency performance.
Pre-Flight Production Checklist
- Backup Verified: Save
config.toml.bakbefore modifying configuration to allow instantaneous rollback to official OpenAI endpoints. - Free Credit Trial: New accounts automatically receive $0.20 in test credit upon account registration; complete initial smoke testing following the quickstart guide.
- Model Pinning: Explicitly pin tested model identifiers (such as
gpt-5.6-solorclaude-sonnet-4-6) instead of floating generic aliases. - Credential Safety: Never commit
~/.codex/auth.jsonorconfig.tomlinto public Git repositories. - Audit Logs: Monitor real-time request records and token billing in usage logs after completing complex refactoring tasks.
By following this configuration standard, you can leverage Codex CLI with full Responses API fidelity, multi-provider failover, and transparent pay-as-you-go pricing.