将 ChatGPT Codex 接入 XiuRouter

为 ChatGPT 桌面端、Codex CLI 或 IDE 扩展添加 XiuRouter Responses provider。

ChatGPT 桌面端、Codex CLI 和 Codex IDE 扩展读取同一份用户级 ~/.codex/config.toml。三种使用端都走 Responses API，但读取 API Key 和重新启动的方式不同。

先选使用端

使用端	API Key	配置生效
ChatGPT 桌面端 Codex	写入当前用户环境	完全退出 ChatGPT，重开后新建本地任务
Codex CLI	在启动 Codex 的终端设置	从同一终端运行 `codex`，再新建任务
Codex IDE 扩展	在启动 IDE 的终端设置	从该终端启动 IDE，重新加载窗口后新建任务

三种使用端共用下文的 provider 配置。已经在使用 Codex 时，不需要重装。

选择配置方式

首次配置：直接设置 API Key，并在 config.toml 添加模型和 provider。
替换已有：先备份 config.toml；现有模型 ID 在 XiuRouter 可用时可以保留。
对话协助：把不含密钥的配置任务发给仍可运行的 Codex，随后手动设置 Key、重启并新建任务。

前置条件

codex --version 可以正常输出版本。
已创建 XiuRouter API Key。
已确认现有模型 ID 是否在 XiuRouter 当前目录中；首次配置需要选择一个文本模型 ID。
已阅读API 兼容范围。

替换已有时先备份

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

首次配置且文件不存在时，跳过这一步。

设置 API Key

ChatGPT 桌面端

macOS：

launchctl setenv XIUROUTER_API_KEY "YOUR_XIUROUTER_API_KEY"

Windows PowerShell：

[Environment]::SetEnvironmentVariable(
  "XIUROUTER_API_KEY",
  "YOUR_XIUROUTER_API_KEY",
  "User"
)

完全退出 ChatGPT 后再打开。已经运行的任务不会切换 provider。

Codex CLI 或 IDE 扩展

macOS 或 Linux：

export XIUROUTER_API_KEY="YOUR_XIUROUTER_API_KEY"

Windows PowerShell：

$env:XIUROUTER_API_KEY = "YOUR_XIUROUTER_API_KEY"

CLI 从这个终端运行 codex。IDE 扩展从这个终端启动 IDE，再重新加载窗口。不要把真实 Key 写进 config.toml 或项目仓库。

添加 provider

打开 ~/.codex/config.toml，只合并以下配置，不覆盖其他设置：

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 必须是 responses。不要把 Codex 配成 Chat Completions provider 后再期待相同的 Agent 行为。

如果原配置已经有 model，先保留。只有 XiuRouter 没有同名 ID，或首次配置没有模型时，才添加或修改：

model = "YOUR_MODEL_ID"

有用户配置目录权限的 Codex 任务可以帮你合并这段不含密钥的 TOML。API Key、重启和新任务仍需手动完成；不要把“文件已修改”当作路由已经生效。

对话协助

把下面消息发给一个仍使用原连接的 Codex 任务。先把 YOUR_MODEL_ID 换成目标模型：

备份 ~/.codex/config.toml，保留现有设置，只添加 XiuRouter Responses provider，并把模型设为 YOUR_MODEL_ID。不要读取、写入或询问 API Key。修改后只展示 diff，不要启动新任务。

运行只读测试

codex exec \
  --sandbox read-only \
  "运行 pwd，不要修改文件，然后告诉我当前目录。"

桌面端在 ChatGPT 中新建本地 Codex 任务。CLI 从设置 Key 的终端运行上面的命令。IDE 扩展重新加载窗口后新建任务。

确认任务完成，并在 XiuRouter 控制台“检查实际请求”看到同一 Key、/v1/responses、所选模型和成功状态。随后再测试文件修改。

常见失败

现象	处理
`401`	确认当前使用端能读取 `XIUROUTER_API_KEY`，并与 `env_key` 名称一致
模型不在选择器中	在 `config.toml` 写精确模型 ID，重启后新建任务
普通回复成功，工具任务失败	换用已验证工具调用的模型；不要把文本回复当作完整 Agent 兼容证明
请求走错接口	确认 `wire_api = "responses"`，Base URL 以 `/v1` 结尾
长请求中断	确认使用 `router-api.xiu.ai`，不是 `router.xiu.ai`

回滚

恢复 ~/.codex/config.toml.bak，或把顶层 model_provider 改回原值并删除 [model_providers.xiurouter]。再取消对应使用端的 XIUROUTER_API_KEY，完全退出客户端并新建任务。

来源与核对日期

内容核对于 2026-08-31。本地 Codex 任务完成，并在 XiuRouter“检查实际请求”中出现对应 Responses 请求后，基础接入才算完成；工具能力请按实际项目验证。