Codex CLI 安装与配置教程

这篇教程说明如何在 Windows、Mac 和 Linux 上安装 Codex CLI，并把它接到 HRouter：先装 Node.js，再装 Codex，最后编辑 config.toml 和 auth.json。Codex 使用 OpenAI Responses API，所以 Base URL 要带 /v1，并且要把 wire_api 设为 responses。

OpenAI 模型持续更新，准确列表以当前 Key 请求 /v1/models 的结果为准，见查询可用模型。以下用 gpt-5.6-sol 演示。

开始前

一个可用的 HRouter Key，分组包含 OpenAI / Codex 模型。还没有 Key 先看创建 API Key。
Node.js 18 或更高版本（下面第 1 步会安装）。
一个终端：Windows 用 PowerShell，Mac 用 Terminal，Linux 用你习惯的终端。

最省事的做法：HRouter Desktop

用 HRouter Desktop 选择 Codex，输入 Key，点击“识别 Key”，会自动生成下面第 3 步的 config.toml 和 auth.json，并预填模型绑定、上下文窗口和远程压缩开关。装好 Codex 后直接用它即可，可以跳过第 3 步。

连接参数

项目	值
Base URL	`https://hrouter.net/v1`
`wire_api`	`"responses"`
provider 标识	`hrouter`（本地配置名，真正请求仍发送到 HRouter）
provider 的 `name`	`"OpenAI"`，大小写必须精确
Key	写在 `~/.codex/auth.json` 中
模型	当前 Key 返回的 OpenAI / Codex 模型

name = "OpenAI" 是开启 Codex 远程压缩（长对话自动压缩上下文）的开关，写成别的值或大小写不对，长对话就不会触发压缩。

当前常用模型

gpt-5.6-sol
gpt-5.6-luna
gpt-5.6-terra
gpt-5.5
以及 /v1/models 返回的其他 OpenAI 模型

第 1 步：安装 Node.js

Windows

方法一，官网下载：打开 https://nodejs.org/，下载 LTS 版本安装包，按默认选项安装。

方法二，包管理器：

choco install nodejs
scoop install nodejs

Mac

brew install node

没有 Homebrew 的话，也可以在 https://nodejs.org/ 下载 LTS 安装包。

Linux

Debian / Ubuntu：

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

或者使用系统包管理器：

sudo apt update
sudo apt install nodejs npm

验证

node --version
npm --version

第 2 步：安装 Codex

npm install -g @openai/codex --registry=https://registry.npmmirror.com

Linux 上遇到权限问题，可以加 sudo：

sudo npm install -g @openai/codex --registry=https://registry.npmmirror.com

验证安装：

codex --version

第 3 步：配置 HRouter

需要编辑两个文件，它们都在 .codex 目录下，目录或文件不存在就先创建。

系统	目录
Windows	`C:\Users\你的用户名\.codex\`
Mac / Linux	`~/.codex/`

Mac / Linux 创建目录和文件：

mkdir -p ~/.codex
touch ~/.codex/config.toml ~/.codex/auth.json

编辑 config.toml

disable_response_storage = true
model = "gpt-5.6-sol"
model_reasoning_effort = "high"
model_provider = "hrouter"
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.hrouter]
name = "OpenAI"
base_url = "https://hrouter.net/v1"
requires_openai_auth = true
wire_api = "responses"

model_context_window 是上下文窗口大小，model_auto_compact_token_limit 是自动压缩的触发阈值。HRouter Desktop 提供“官方 272K”（272000 / 244800）和“官方 1M”（1000000 / 900000）两档预设，上面用的是 1M 档；模型不支持这么大窗口时选 272K 档。

三处必须对应：

model_provider = "hrouter" 必须和 [model_providers.hrouter] 的节名一致。
name = "OpenAI" 必须一字不差，大写 O、大写 A。
wire_api = "responses" 不要改成别的值。

编辑 auth.json

Key 写在这里，不需要环境变量：

{
  "OPENAI_API_KEY": "sk-xxxxx"
}

把 sk-xxxxx 换成你自己的 Key。文件必须是合法 JSON，键名必须是 OPENAI_API_KEY。

第 4 步：开始使用并验证

进入任意项目目录，运行：

codex

第一次建议先跑一个最短任务：

请只回复：HRouter Codex 已连接

收到回复后，到使用记录里能看到这次请求，说明整条链路已经通了。

在编辑器里使用

先完成上面的命令行配置，确认终端里 codex 正常，再接入编辑器：

常见问题

配置改了没生效？ 确认 auth.json 已保存，并重新打开终端。仍然无效见配置不生效怎么排查。

一直提示 provider 配置错误？ 确认 config.toml 里的节名是 [model_providers.hrouter]，并和 model_provider = "hrouter" 一致。

长对话没有触发远程压缩？ 检查 provider 的 name 是否精确为 OpenAI，大小写敏感。

提示找不到 API Key？ 检查 auth.json 是不是合法 JSON，键名是不是 OPENAI_API_KEY。

看到 exceeded retry limit, last status: 429？ 这是 Codex 把多次重试后的最后一个状态码展示出来，真正的原因在 429 的错误内容里，见 Codex 常见问题和 429 限流与额度。

提示模型不存在或不可用？ 换成当前 Key 返回的 Codex 模型，见 model_not_found。

提示 401？ 见 API 401 报错。