---
title: "将 Codex 接入 XiuRouter"
description: "为 Codex CLI 和读取同一配置的本地客户端添加 XiuRouter Responses provider。"
image: "https://docs.xiu.ai/og.png"
---

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

# 将 Codex 接入 XiuRouter

Codex 使用 Responses API。你需要在 `~/.codex/config.toml` 新增 XiuRouter provider，并通过环境变量提供专用 API Key。

## 前置条件

- `codex --version` 可以正常输出版本。
- 已创建 XiuRouter API Key。
- 已选择一个当前可用、适合工具调用的文本模型 ID。
- 已阅读[API 兼容范围](/router/api-compatibility)。

## 设置 API Key

在启动 Codex 的同一终端中设置：

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

不要把真实 Key 写进 `config.toml` 或项目仓库。通过 Dock 启动的桌面应用不一定继承终端环境变量；先用 CLI 验证，再决定使用系统级安全存储或启动脚本。

## 添加 provider

打开 `~/.codex/config.toml`，合并以下配置。把 `YOUR_MODEL_ID` 换成 XiuRouter 当前目录中的精确模型 ID：

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

## 先验证 Responses 路由

```bash
curl https://router-api.xiu.ai/v1/responses \
  -H "Authorization: Bearer $XIUROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"model": "YOUR_MODEL_ID",
"store": false,
"input": "请只回复：Responses 已连接"
  }'
```

收到 `200` 后再启动 Codex。模型若不支持 Responses，应更换模型或分组，不要改成不存在的路径。

## 运行只读测试

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

确认命令完成，并在 XiuRouter“使用记录”看到 `/v1/responses` 对应的模型、状态和费用。随后再测试一个只读工具任务，最后才测试文件修改。

## 常见失败

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

## 回滚

把顶层 `model_provider` 和 `model` 改回原值，或删除 `[model_providers.xiurouter]`。现有任务可能保留启动时的 provider；回滚后新建任务再验证。

## 来源与核对日期

本文按 Codex 官方配置参考和 XiuRouter 当前 Responses 路由核对，日期为 2026-08-19。本轮未使用真实 Key 运行 Codex 计费任务，模型工具能力需要你按实际项目验证。

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