Pointing Codex CLI at a third-party API: what to watch for
Why Codex CLI is a harder case than a chat client
A chat client needs one thing from an endpoint: a compatible message format. Codex CLI needs more, because it is an agent. It sends tool definitions, expects structured tool calls back, streams, and holds a session across many turns. Each of those is a place where a relay service can be subtly incompatible.
The configuration is not the hard part. Knowing what to test is.
The configuration, briefly
Codex CLI takes an OpenAI-compatible base URL and key, supplied through its configuration file or environment. The values are the same shape as any other OpenAI-compatible client:
- base URL: the endpoint the service provides, including any path prefix it requires
- key: the service's key, presented as a bearer token
- model: the model identifier as the service names it
The one that catches people: the model name. A relay service's model identifiers are its own. Asking for gpt-5 when the service calls it something else returns a 404 or, worse, silently falls back to a different model.
Get the list from the service's /v1/models and use exactly the identifiers it returns.
The authentication shape differs from Claude Code
This trips people up when they run both clients against the same service.
| Client | Variable | Format |
|---|---|---|
| Claude Code | ANTHROPIC_AUTH_TOKEN | Bearer token |
| Codex CLI | OpenAI-style key configuration | Bearer token, but read from a different place |
The practical consequence: setting one does not configure the other, and a service that documents Claude Code setup may not document Codex CLI at all. Test both separately rather than assuming one works because the other does.
What to test, in order
One: does /v1/models list the model you want
The identifier has to match exactly. Confirm it before writing any configuration, and re-check it whenever the service changes its catalogue.
Two: does a streaming response work
Codex CLI streams. Some relay services buffer and return the whole response at once, which breaks the interactive experience or fails outright. Ask for a short streaming completion and see whether tokens arrive incrementally.
A service that does not stream is not usable as a coding agent regardless of everything else.
Three: do tool calls come back correctly
This is the decisive test, as it is for any agent client.
Ask for something that requires a shell command or a file read. If the model responds with prose describing what it would do, tool calls are not being forwarded.
Note that the failure mode here can be subtler than with Claude Code: some relays forward tool calls but rewrite the arguments' JSON shape, so the call arrives malformed. The client reports an argument error rather than a missing tool call.
Four: is the request body accepted without modification
Codex CLI sends a request body with fields that some relays do not expect and strip. If stripping changes behaviour — dropping tool definitions, for example — you get degraded function rather than an error.
Hard to detect directly. The practical test is comparing behaviour against a direct vendor connection on the same task.
Five: does it hold up over a long session
Agent sessions are long and accumulate context. A relay with a lower context ceiling than the vendor will fail partway through, when the session is already expensive to restart.
Test with a task that takes at least fifteen or twenty turns.
Common failure patterns
| Symptom | Likely cause |
|---|---|
| 404 on every request | Wrong model identifier, or the path prefix is missing from the base URL |
| 401 immediately | Key not being read from where Codex CLI expects it |
| Works, then stops mid-session | Context ceiling lower than the vendor's |
| Responses arrive all at once | The relay does not stream |
| Tool calls never appear | Tool use not forwarded |
| Tool calls error out | Arguments rewritten by the relay |
Reasons to prefer a direct vendor connection here
Codex CLI's needs are the ones relay services handle worst. If your work depends on it:
- you need streaming to be genuinely incremental
- you need tool calls forwarded faithfully, including argument shape
- you need a long context ceiling
- you need a session that survives an hour
That combination is what a relay service is least likely to deliver, and what makes switching services disruptive once you have built around one.
If a relay service is the only path available to you, test all five items above before building anything on it, and keep a second configuration ready.
Related reading
- Claude Code with a relay service: full configuration and troubleshooting (guides)
- Give a relay service a health check: a 20-minute verification checklist (guides)
- A relay service starts erroring or slowing down: how to tell whose problem it is (guides)
Was this useful? If you have run into something the article does not cover, tell us and we will verify it and update the text.
Related articles
Video generation behind a relay: three API shapes, four billing traps, one acceptance checklist
MCP through a relay: what works, what never will, and how to test it in ten minutes
A relay selection decision tree: working back from your scenario to a site
Logging and reconciliation: attributing token spend to the project level
Migrating suppliers gradually: replacing an API site without interrupting service
Build your own probe: twenty lines of script to monitor your API suppliers
The models this article mentions are available on these services
Filtered by the model families the article mentions and ordered by overall score and uptime. This is not a recommendation. Click through to see each service's uptime, latency and endpoint verification.
See the full list in the directory, or browse by model family.