---
title: "Connect Codex to XiuRouter"
description: "Add XiuRouter as a Responses provider for ChatGPT desktop, Codex CLI, or the Codex IDE extension without putting the API key in config.toml."
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# Connect Codex to XiuRouter

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](/en/router/api-compatibility).

## Back up an existing config

```bash
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:

```bash
export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"
```

For ChatGPT desktop on macOS:

```bash
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:

```toml
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`:

```bash
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.

源文件：https://docs.xiu.ai/en/router/integrations/codex/index.mdx