{
  "id": 4688135,
  "title": "How to Connect Codex to a Custom Responses API Provider and Verify the Route",
  "url": "https://urgent.news/2026/08/31/how-to-connect-codex-to-a-custom-responses-api-provider-and-verify",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-08-31T18:16:44.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/xiuai-lab/how-to-connect-codex-to-a-custom-responses-api-provider-and-verify-the-route-4aah"
  },
  "original_language": "en",
  "account": "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.\n\nTo ensure proper configuration, four key decisions must be explicitly defined:\n1. Which model should Codex request?\n2. Which named provider should Codex utilize?\n3. Which base URL should receive the request?\n4. Which environment variable contains the API key?\n\nA minimal user-level configuration might appear as follows:\n```\nmodel = YOUR_MODEL_ID\nmodel_provider = xiurouter\n[model_providers.xiurouter]\nname = XiuRouter\nbase_url = https://router-api.xiu.ai/v1\nenv_key = XIUROUTER_API_KEY\nwire_api = responses\n```\nIn 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.\n\nOpenAI'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:\n```\nenv_key = XIUROUTER_API_KEY\nexport XIUROUTER_API_KEY = YOUR_KEY\n```\nFor 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.\n\nBegin 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.\n\nTo 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.\n\nIf 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.",
  "summary": "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…",
  "key_points": [
    "Codex requires compatibility with Responses API behavior",
    "Four key decisions: model, provider, base URL, API key",
    "wireapi = responses indicates use of Responses API"
  ],
  "editors_take": null,
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}