Skip to main content
Codex CLI 是 OpenAI 的终端编程智能体，可以在命令行中读写文件、运行命令、修复 Bug 并完成编码任务。通过 XRouter，你可以把 Codex CLI 的模型供应商指向 https://api.xrouter.dev/v1，使用 XRouter API Key 调用可用模型。

​
准备工作

在开始之前，请确认：
  • 已安装 Node.js，建议使用最新 LTS 版本。
  • 已在 XRouter 控制台创建 API Key，格式通常为 sk-...。
  • 已确认目标模型在 XRouter 控制台中可用。

​
第一步：安装 Codex CLI

Terminal
npm install -g @openai/codex
如果遇到全局安装权限问题，macOS / Linux 可以按你的本机策略使用 sudo 或切换 Node 版本管理器。
安装完成后验证版本：
Terminal
codex --version
如果输出版本号，说明安装成功。

​
第二步：配置 XRouter API

Codex CLI 通过 ~/.codex/ 目录下的文件管理认证与模型供应商。按下面步骤新增一个 XRouter 自定义供应商。

​
2.1 找到配置目录

系统配置目录
macOS / Linux~/.codex/
WindowsC:\Users\your-name\.codex\
如果目录不存在，先在终端运行一次 codex，再按 Ctrl + C 退出，Codex 会生成配置目录。

​
2.2 配置 API Key

在配置目录下创建或编辑 auth.json，写入 XRouter API Key：
~/.codex/auth.json
{
  "OPENAI_API_KEY": "sk-your-api-key"
}
字段说明
OPENAI_API_KEYXRouter API Key，完整保留 sk- 前缀
auth.json 是本机凭据文件，请不要提交到代码仓库，也不要把真实内容粘贴到公开 issue 或聊天记录中。

​
2.3 配置模型供应商

在配置目录下创建或编辑 config.toml，添加 XRouter 供应商：
~/.codex/config.toml
# 默认使用的模型，请替换为 XRouter 控制台中可用的模型
model = "gpt-5.3-codex"

# 默认供应商，对应下方 [model_providers.xrouter]
model_provider = "xrouter"

[model_providers.xrouter]
name = "XRouter"
base_url = "https://api.xrouter.dev/v1"
wire_api = "responses"
requires_openai_auth = true
字段说明
model默认模型 ID，可从 XRouter 模型页复制
model_provider默认供应商 ID，需要与 [model_providers.xrouter] 一致
nameProvider 显示名称
base_urlXRouter 的 OpenAI 兼容地址，固定为 https://api.xrouter.dev/v1
wire_apiCodex 通信协议，使用 responses
requires_openai_auth设为 true，让 Codex 使用 auth.json 中的 OPENAI_API_KEY
保存两个文件后，重新启动 Codex CLI。
如果你已经在使用其他 Codex 配置，请把 XRouter 片段合并到原有 config.toml，不要直接覆盖已有的 MCP、审批或沙箱配置。

​
第三步：开始使用

​
验证配置

在任意项目目录运行：
Terminal
codex "用一句话介绍你自己"
如果收到回复，说明 Codex CLI 已通过 XRouter 连接成功。

​
交互模式

直接运行 codex 进入交互界面：
Terminal
codex
进入后可以输入任务，例如：
Prompt
请阅读当前项目结构，并列出主要模块。不要修改文件。

​
审批模式

首次运行时，Codex 会让你选择操作审批级别。
模式说明
只读仅允许读取文件，修改和命令需要确认
自动可在工作目录内读写文件、运行命令，适合日常开发
完全访问无需确认即可执行更多操作，请谨慎使用
在交互界面中输入 /approvals 可以调整审批模式。

​
切换模型

在交互界面中输入 /model 切换模型，或修改 config.toml 中的 model 字段后重启 Codex。 也可以在启动时临时指定模型：
Terminal
codex --model gpt-5.4 "检查当前 diff 是否有明显问题。"

​
支持的模型

在 Codex CLI 中，建议优先选择 XRouter 控制台中可用的 Codex 或 GPT 系列编码模型。
模型 ID特点推荐场景
gpt-5.4旗舰模型，综合能力强复杂编码、架构设计
gpt-5.4-mini轻量、响应快日常编码、快速迭代
gpt-5.3-codex面向 Codex 场景优化智能体式编码任务
gpt-5.2稳定均衡常规编码任务
具体可用模型以 XRouter 控制台模型页为准。如果控制台中有更新的 Codex 模型，可以直接替换 config.toml 中的 model。

​
使用环境变量认证

如果你不想使用 auth.json，也可以通过环境变量传入密钥。把供应商配置改成：
~/.codex/config.toml
model = "gpt-5.3-codex"
model_provider = "xrouter"

[model_providers.xrouter]
name = "XRouter"
base_url = "https://api.xrouter.dev/v1"
wire_api = "responses"
env_key = "XROUTER_API_KEY"
然后在 shell 中设置：
Terminal
export XROUTER_API_KEY="sk-your-api-key"

​
常用命令

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

​
常见问题

这通常说明 XRouter 自定义供应商配置没有生效。确认 config.toml 和 auth.json 位于 ~/.codex/，model_provider 为 xrouter，且 auth.json 是合法 JSON。
401 通常表示 API Key 缺失或无效；403 通常表示权限不足、密钥停用或额度问题。请确认 auth.json 中的密钥完整，且 XRouter 控制台中密钥状态正常。
确认 base_url 是 https://api.xrouter.dev/v1。如果你使用代理或公司网络，请确认该网络允许访问 api.xrouter.dev。
新版 Codex CLI 使用 Responses API。请把 wire_api 设置为 responses，保存后重启 Codex。
登录 XRouter 控制台查看 API 调用记录、Token 消耗和余额变化。