How to Connect Codex to a Custom Responses API Provider and Verify the Route

Establishing a custom Responses API provider for Codex requires more than merely updating the API base URL. Codex functions as an agentic client, demanding compatibility with the Responses API behavior, proper API key delivery, availability of the chosen model under that key, and the request reaching the expected endpoint. This guide provides a conservative setup for such a custom provider, using XiuRouter as an example. The same verification process applies to other compatible gateways.

To ensure proper configuration, four key decisions must be explicitly defined:

1. Which model should Codex request?

2. Which named provider should Codex utilize?

3. Which base URL should receive the request?

4. Which environment variable contains the API key?

A minimal user-level configuration might appear as follows:

```

model = YOUR_MODEL_ID

model_provider = xiurouter

[model_providers.xiurouter]

name = XiuRouter

base_url = https://router-api.xiu.ai/v1

env_key = XIUROUTER_API_KEY

wire_api = responses

```

In this setup, the crucial line is `wire_api = responses`, indicating Codex will use the Responses API for its native agent workflow. Note that a provider accepting only Chat Completions may be useful for other clients but is not automatically compatible with Codex.

OpenAI's Codex documentation specifies `base_url`, `env_key`, and `wire_api` as distinct provider settings. Treat these as separate elements to evaluate when debugging. Keep the API key separate from the configuration file and store it in an environment variable instead:

```

env_key = XIUROUTER_API_KEY

export XIUROUTER_API_KEY = YOUR_KEY

```

For Codex Desktop on macOS, ensure the variable is set in the launch environment before reopening the application, as it may not inherit variables from the terminal shell. Never display the key during diagnosis.

Begin with a reversible configuration by retaining the previous provider block and modifying only the active model and model_provider lines. This allows for quick rollback if the new route encounters issues during a longer agent run. Test the new provider within project-level configuration before promoting it to the user-wide default.

Project configuration resides in `.codex/config.toml`, while user defaults are found in `~/.codex/config.toml`. The guideline is: use project config for bounded testing, user config after successful provider integration, and retain the old provider until rollback is unnecessary.

To confirm a successful launch, execute a small read-only task requiring tool use. For instance, inspect a repository, identify the test command, and summarize the main modules. A plain text response demonstrates that one request returned data, but it only proves that the request returned text, not that the agent loop, tool instructions, streaming, and follow-up turns function correctly.

Verify the provider-side request by ensuring the usage record includes the correct API key, intended model, Responses path, successful status, and proper recording of usage and cost.

If the request does not appear in the provider's usage record, Codex might still be using the old configuration, or the application may not have inherited the environment variable. Diagnose failures by isolating the issues at each boundary: incorrect API key, unauthorized access, or a wrongly configured endpoint. Adjust the relevant configuration to resolve the problem.