Connect Codex to XiuRouter | XiuAI 文档中心

Add XiuRouter as a Responses provider for ChatGPT desktop, Codex CLI, or the Codex IDE extension without putting the API key in config.toml.

ChatGPT desktop Codex, Codex CLI, and the Codex IDE extension share the user-level ~/.codex/config.toml. Add a custom XiuRouter provider that uses the Responses wire API, then expose the key to the process separately.

Before you start

codex --version prints a version when you use the CLI or IDE extension.
You have a dedicated XiuRouter API key.
You have selected an exact model ID from the current catalogue.
You have read the XiuRouter compatibility boundaries.

Back up an existing config

cp ~/.codex/config.toml ~/.codex/config.toml.bak

Skip this step when the file does not exist.

Set the API key

For Codex CLI or an IDE launched from the same terminal:

export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"

For ChatGPT desktop on macOS:

launchctl setenv XIUROUTER_API_KEY "YOUR_XIUROUTER_API_KEY"

Quit ChatGPT completely and reopen it after setting the user environment variable. Do not put the real key in config.toml.

Add the provider

Open ~/.codex/config.toml and merge this block without removing other providers:

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"

wire_api must be responses. Current Codex configuration supports Responses as the custom provider protocol; a Chat Completions provider does not preserve the same agent behavior.

If the existing model ID is available in XiuRouter, keep it. Otherwise replace YOUR_MODEL_ID with an exact current ID.

Restart and test

For CLI, run Codex from the terminal that contains XIUROUTER_API_KEY:

codex exec \
  --model YOUR_MODEL_ID \
  --sandbox read-only \
  "Run pwd without changing files, then tell me the directory."

For ChatGPT desktop or the IDE extension, restart the client and create a new local task. Tasks that were already open keep their previous provider.

The check passes when the task completes and XiuRouter’s request verification panel shows the same key, model, a successful status, and /v1/responses.

Common failures

Symptom	Action
`401`	Start Codex from the environment that contains `XIUROUTER_API_KEY`; confirm `env_key` uses the same name
The model is missing from the picker	Set the exact model ID in `config.toml`, restart, and create a new task
Codex warns that model metadata is unknown	Treat it as advisory if the task and recorded request succeed; test tool use before larger edits
Text works but tools fail	Test a model with verified tool calling; a text response alone does not prove full agent compatibility
Requests use the wrong endpoint	Confirm `wire_api = "responses"` and that the base URL ends in `/v1`
Long requests stop	Confirm the base URL uses `router-api.xiu.ai`, not the console domain

Roll back

Restore ~/.codex/config.toml.bak, or set model_provider back to its previous value and remove [model_providers.xiurouter]. Remove the XiuRouter environment variable, restart the client, and create a new task.

Sources and review date

This page was checked against the current Codex configuration reference and XiuRouter Responses integration on August 22, 2026. The configuration was reviewed without placing a real API key in a Codex task or running a billable model request.