主题
Codex CLI 部署
Codex CLI 是 OpenAI 官方的命令行 AI 编码 agent——和 Claude Code 类似的形态：终端里读代码、改文件、执行任务，但底层调 OpenAI 模型（GPT-5 / GPT-5 系列等）。
前置条件
- Node.js 18+：Windows / macOS / Linux 安装指南
- why01 API Key：创建 API Key
- 建 Key 时选对令牌分组：Codex 走
Codex-A/GPT-A分组。分组选错会连不上或报权限，见 分组详解 - 账户余额 > 0：充值
1. 安装 Codex CLI
bash
npm install -g @openai/codex国内 npm 慢先换镜像：
bash
npm config set registry https://registry.npmmirror.com
npm install -g @openai/codex验证：
bash
codex --version也可以用桌面版 / IDE 插件——三种形态共用同一份配置
CLI、VSCode 等 IDE 插件、Windows 桌面版读的都是同一份 ~/.codex/config.toml 和 ~/.codex/auth.json， 配好一个，三个都能用。
Windows 桌面版官方只经微软商店分发（ProductId 9PLM9XGG6VKS），国内常连不上。两条路：
powershell
# 普通窗口，不要用管理员身份——用管理员反而会报 0x80080005
winget install --id 9PLM9XGG6VKS --source msstore --accept-package-agreements --accept-source-agreements⚠️ 别用 winget install Codex——那会解析到一个同名的第三方二维码软件。
商店走不通就侧载我们转载的微软原版包（下载后双击即可，也可 Add-AppxPackage）： OpenAI.Codex_26.730.7989.0_x64.msix（706 MB，SHA-1 7b8150514e91641356b6a90178904cda9d3fdf0a）
装完在开始菜单搜 ChatGPT（不是 Codex，OpenAI 就是这么命名的）。手把手版见 Codex 保姆版。
TIP
Codex 也有 Homebrew 安装方式（macOS）：brew install codex。两种装一个就行。
2. 配置 Codex 指向 why01
Codex 通过 ~/.codex/config.toml 文件配置上游 endpoint。最稳的姿势是定义一个 自定义 model_provider 指向 why01。
创建 / 编辑 ~/.codex/config.toml
toml
model_provider = "why01"
model = "gpt-5.5" # 或你账户实际能用的 OpenAI 模型，按控制台「模型广场」填
[model_providers.why01]
name = "why01"
base_url = "https://s1.why01.top/v1"
env_key = "WHY01_API_KEY"
wire_api = "responses" # 如调用报错说不识别 responses，改成 "chat"toml
model_provider = "why01"
model = "gpt-5.5"
[model_providers.why01]
name = "why01"
base_url = "https://s1.why01.top/v1"
env_key = "WHY01_API_KEY"
wire_api = "responses"env_key = "WHY01_API_KEY" 表示 Codex 会从环境变量 WHY01_API_KEY 里读 key。
用桌面版 / VSCode 插件的，别用 env_key
env_key 只有命令行吃得到。Codex 桌面客户端和 VSCode 插件读不到环境变量—— 它们启动时继承的是系统旧的环境快照，你新设的变量它们看不见，一对话就报 Missing environment variable: 'WHY01_API_KEY'（2026-08-04 实际发生）。
这些情况把 env_key 换成 requires_openai_auth，Key 改放 ~/.codex/auth.json：
toml
[model_providers.why01]
name = "why01"
base_url = "https://s1.why01.top/v1"
wire_api = "responses"
requires_openai_auth = true # ← 代替 env_keyjson
// ~/.codex/auth.json
{ "OPENAI_API_KEY": "sk-你的key" }这套写法命令行、桌面版、插件通吃，也是 cc-switch 生成的写法。改完记得完全退出客户端再打开。
设置环境变量 WHY01_API_KEY
bash
# 加到 ~/.zshrc 或 ~/.bashrc
export WHY01_API_KEY=sk-你的key
source ~/.zshrcpowershell
[Environment]::SetEnvironmentVariable("WHY01_API_KEY", "sk-你的key", "User")
# 关闭所有终端窗口重开才生效3. 启动
进入项目目录：
bash
cd ~/your-project
codex进交互界面后输入需求即可。
4. 验证走 why01
跑完一次任务后到 why01 控制台 → 日志 看最近几分钟有没有 GPT 系列模型的调用记录——有 = 接通。
wire_api 选 responses 还是 chat
Codex 支持两种 OpenAI 协议格式：
wire_api 值 | 走哪条路径 | 适用 |
|---|---|---|
responses | /v1/responses（OpenAI 新版 Responses API） | 上游模型支持 Responses API 时；GPT-5 系建议这个 |
chat | /v1/chat/completions（经典 ChatCompletions） | 上游不支持 Responses API，或频繁报"找不到 endpoint" 时退到这个 |
优先试 responses，报错再切 chat。本站具体哪条路径稳取决于上游渠道实现。
常见问题
启动报 401 Invalid token
先看 auth.json 里装的是什么，别急着重配 Key
用 requires_openai_auth = true 写法的（桌面版 / VSCode 插件推荐写法，cc-switch 生成的也是这种）， Codex 发请求用的是 ~/.codex/auth.json 里的凭证。这个文件里如果装的是 ChatGPT 登录态 （有 "tokens"，或写着 "auth_mode": "chatgpt"），Codex 就会把 ChatGPT 的 token 发给我们， 网关查不到这串，返回 401 Invalid token。这种情况下你把 Key 重新复制粘贴多少遍都没用。
解法：先备份，再把整个文件内容换成你的 Key——别只往里加一行，文件里留着 "auth_mode": "chatgpt" 就还是走 ChatGPT：
bash
cp ~/.codex/auth.json ~/.codex/auth.json.bak # 先备份（Windows 在 %USERPROFILE%\.codex\）json
// ~/.codex/auth.json 改成只剩这一行
{ "OPENAI_API_KEY": "sk-你的key" }⚠️ 不要直接把 auth.json 删掉或挪走：这种写法下你的 Key 就存在这个文件里，挪走了 Codex 一个 Key 都拿不到。 改完完全退出客户端（桌面版连托盘图标一起退）再打开。
按这个顺序排：
~/.codex/auth.json里是不是 ChatGPT 登录态 → 是就按上面换成你的 Key，这是最常见也最反直觉的一条- 用
env_key写法的：检查WHY01_API_KEY是不是真的设进去了：echo $WHY01_API_KEY（Windows PowerShell：$env:WHY01_API_KEY）- 注意环境变量对已经开着的终端不生效，设完要新开窗口
- 桌面版 / 插件读不到环境变量，改用
requires_openai_auth写法（见上文「用桌面版 / VSCode 插件的，别用 env_key」）
- 确认
config.toml里env_key = "WHY01_API_KEY"拼写一致（Codex 大小写敏感） - 确认 Key 未禁用 / 未过期（控制台「令牌管理」）
- 检查令牌分组：这个 Key 的令牌分组要是
Codex-A/GPT-A。分组选错会报权限 / 连不上——去 控制台「令牌管理」 点该 Key「编辑」改分组
懒得逐条排的，用一键体检工具跑一遍：🩺 Codex 体检修复工具（Windows / Mac 都有，会逐项查出坏在哪并当场修好）。
自己验证是不是 Key 的问题，绕开 Codex 直接打一次（把 sk-你的key 换成控制台「令牌管理」里复制的那串）：
bash
curl -sS https://s1.why01.top/v1/responses \
-H "Authorization: Bearer sk-你的key" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.5","input":"hi","stream":false}' | head -c 300curl 通、codex 不通 → 100% 是本地 Codex 配置（重点查 auth.json）；curl 也报 401 → 手里的 Key 和后台那个不是同一串。
报 model_not_found / 无可用渠道
json
{"error":{"code":"model_not_found","message":"分组 Codex-A 下模型 xxx 无可用渠道（distributor）"}}注意状态码是 503，不是 404
本站网关遇到这种情况返回的是 503（2026-08-04 实测）。别被 5xx 误导成"上游故障、与我无关"—— 它其实是你这边配置的问题。
两种原因：
config.toml里的model = "..."写错了名字。改成控制台「模型广场」当前能看到的 OpenAI 系模型名——便宜的 mini 系、主力档、顶级档名字各不同，永远从控制台复制，不要按记忆敲。- 令牌分组不对：这个 Key 得是
Codex-A/GPT-A分组，用Claude-A的 Key 调 GPT 模型就会报这个。
报错 Unsupported endpoint /v1/responses 或类似
切 wire_api = "chat"，再启动一次。
Codex 已经配过 OpenAI 官方账号怎么办
~/.codex/config.toml 里同时存在多个 model_providers 没问题，只看 model_provider = "..." 顶级字段指向哪个就走哪个。在 why01 和 openai 之间切：
toml
model_provider = "why01" # 走本站
# model_provider = "openai" # 走 OpenAI 官方或者运行时临时切：
bash
codex --provider openai # 仅本次走官方想了解官方订阅那条路
各档位分别能用到什么模型、Codex 在哪一档有什么限额，见 OpenAI / ChatGPT。
Codex 怎么计费
和 Claude Code 一样按 token 实际用量算。建议：
下一步
- 想横向比较 → Claude Code 部署 · Gemini CLI 部署
- Codex CLI 官方仓库 → https://github.com/openai/codex