Changing an API base URL is not enough to prove that Codex is using the provider you intended.
Codex is an agentic client.
It needs more than a model that can return text.
The provider must support the Responses API behavior Codex relies on, the API key must reach the process that launches Codex, the selected model must be available to that key, and the final request must arrive at the expected endpoint.
This guide shows a conservative setup for a custom Responses API provider, using XiuRouter as the concrete example.
The same verification method applies to other compatible gateways.
The configuration has four separate decisions A working Codex provider configuration answers four questions: Which model should Codex request?
Which named provider should Codex use?
Which base URL should receive the request?
Which environment variable contains the API key?
Keep those decisions explicit.
A minimal user-level configuration looks like this: Use a model ID that is currently visible to your account.
Do not copy a model name from an old screenshot or another user's configuration and assume your key can access it.
The important line is: Codex uses the Responses API for its native agent workflow.
A provider that only accepts Chat Completions requests may be useful for other clients, but it is not automatically a drop-in Codex provider.
OpenAI's Codex configuration reference also defines , , and as separate provider settings.
Treat them as separate failure boundaries when debugging.
Keep the API key out of The configuration should name an environment variable, not contain the secret: For a terminal session: For Codex Desktop on macOS, the application may not inherit variables from your terminal shell.
Set the variable in the launch environment, then fully quit and reopen Codex: This distinction matters.
A correct key in can still produce a if the desktop application was launched outside that shell.
Do not print the key during diagnosis.
Check whether the variable exists and whether the request succeeds, not the secret value itself.
Start with a reversible configuration Do not overwrite a working provider before the new route has passed a real task.
Keep the previous provider block in the file and change only the active and lines.
That gives you a fast rollback if the custom route fails during a longer agent run.
It is also safer to test the new provider in project-level configuration before promoting it to your user-wide default.
OpenAI documents project configuration in , while user defaults live in .
The practical rule is: project config for a bounded test; user config after the provider has passed; old provider retained until rollback is no longer needed.
A successful launch is not a successful integration After Codex starts, run a small read-only task that requires tool use.
For example: Inspect this repository, identify the test command, and summarize the main modules.
Do not modify files.
This is more useful than asking the model to say hello.
A plain text response proves only that one request returned text.
A repository inspection exercises the agent loop, tool instructions, streaming, and follow-up turns without creating a destructive side effect.
Then verify the request on the provider side.
For XiuRouter, the usage record should show: the intended API key; the intended model; the Responses path; a successful status; usage and cost recorded for the request.
The expected path is: If no corresponding record appears, do not assume the request used the new provider.
Codex may still be using an older active configuration, or the application may not have inherited the environment variable.
Diagnose failures by boundary Check the process environment first.
Was Codex launched after the environment variable was set?
Does the variable name exactly match ?
Is the key valid for the current account?
Is a project-level configuration overriding the user-level provider?
For Codex Desktop, quit the application completely after changing the launch