> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xrouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex CLI 接入 XRouter

> 在 Codex CLI 中添加 XRouter 自定义模型供应商，并使用 Responses API 入口。

Codex CLI 可以通过自定义模型供应商接入 XRouter。XRouter 的 Codex 配置使用 OpenAI 兼容地址：

```text theme={null}
https://api.xrouter.dev/v1
```

<Info>
  如果控制台显示了不同 `server_address`，请替换示例中的 `https://api.xrouter.dev`，但保留 `/v1` 后缀。
</Info>

## 前置条件

* 已安装 Node.js 或 Homebrew。
* 已在 XRouter 控制台创建 API Key。
* 已从控制台模型页复制可用的 Codex 或 GPT 系列模型 ID。

## 安装 Codex CLI

<Tabs>
  <Tab title="npm">
    ```bash Terminal theme={null}
    npm install -g @openai/codex
    ```
  </Tab>

  <Tab title="Homebrew">
    ```bash Terminal theme={null}
    brew install codex
    ```
  </Tab>
</Tabs>

安装完成后验证版本：

```bash Terminal theme={null}
codex --version
```

## 设置 API Key

推荐使用环境变量，避免把密钥写入可同步或易误传的文件。

```bash Terminal theme={null}
export XROUTER_API_KEY="sk-your-api-key"
```

你可以把这一行加入 `~/.zshrc`、`~/.bashrc` 或你的密钥管理工具。

## 配置模型供应商

Codex CLI 的配置目录通常是：

| 系统            | 配置目录                         |
| ------------- | ---------------------------- |
| macOS / Linux | `~/.codex/`                  |
| Windows       | `C:\Users\your-name\.codex\` |

如果目录不存在，先运行一次 `codex` 再退出，Codex 会生成配置目录。

编辑 `~/.codex/config.toml`，添加 XRouter provider：

```toml ~/.codex/config.toml theme={null}
model = "your-codex-model-id"
model_provider = "xrouter"

[model_providers.xrouter]
name = "XRouter"
base_url = "https://api.xrouter.dev/v1"
wire_api = "responses"
env_key = "XROUTER_API_KEY"
```

| 字段               | 说明                                          |
| ---------------- | ------------------------------------------- |
| `model`          | 默认模型 ID，从 XRouter 控制台复制                     |
| `model_provider` | 默认供应商 ID，需要与 `[model_providers.xrouter]` 一致 |
| `base_url`       | XRouter 的 OpenAI 兼容地址，带 `/v1`               |
| `wire_api`       | Codex 通信协议，使用 `responses`                   |
| `env_key`        | Codex 从该环境变量读取 API Key                      |

<Tip>
  如果你已经有 Codex 配置，请把 XRouter 片段合并到原有 `config.toml`，不要覆盖已有 MCP、审批或沙箱配置。
</Tip>

## 验证配置

在任意目录运行：

```bash Terminal theme={null}
codex "用一句话介绍你自己"
```

如果收到回复，说明 Codex CLI 已通过 XRouter 连接成功。

## 常用命令

| 命令                            | 说明           |
| ----------------------------- | ------------ |
| `codex`                       | 进入交互式界面      |
| `codex "任务描述"`                | 带初始指令启动      |
| `codex exec "任务描述"`           | 非交互模式，执行后退出  |
| `codex --model your-model-id` | 临时指定模型       |
| `codex --version`             | 查看版本号        |
| `/model`                      | 在交互界面中切换模型   |
| `/approvals`                  | 在交互界面中调整审批模式 |

## 故障排查

<AccordionGroup>
  <Accordion title="启动后弹出 ChatGPT 登录界面">
    通常说明 XRouter 自定义供应商配置没有生效。确认 `model_provider = "xrouter"`，并确认 `[model_providers.xrouter]` 存在。
  </Accordion>

  <Accordion title="出现 401 或 403 错误">
    确认 `XROUTER_API_KEY` 已在当前终端会话中设置，且值是完整 XRouter API Key。`403` 还可能与 Key 状态、模型限制或 IP 限制有关。
  </Accordion>

  <Accordion title="提示 wire_api = &#x22;chat&#x22; 不再支持">
    Codex 的 XRouter provider 应使用 `wire_api = "responses"`。保存后重启 Codex CLI。
  </Accordion>

  <Accordion title="提示连接失败">
    确认 `base_url` 是 `https://api.xrouter.dev/v1` 或控制台 `server_address` 加 `/v1`。如果你使用代理或公司网络，请确认该网络允许访问 XRouter 服务地址。
  </Accordion>

  <Accordion title="模型不可用">
    从 XRouter 控制台复制模型 ID，再写入 `model` 字段。不要直接套用其他平台的模型名。
  </Accordion>
</AccordionGroup>