OpenAI Codex CLI 配置 wire_api=responses 协议接入第三方网关完整指南（macOS + Windows）

一、报错背景：装上 Codex 之后第一个迎接你的错误

Codex CLI 装好后跑codex，常见会被两个错误堵在门口：

Error: wire_api = "chat" is no longer supported. Please update your config.toml to use wire_api = "responses".

或者：

Error: 401 Unauthorized

第一个是 Codex CLI 在 2026 年初的重大变更——彻底移除了对wire_api = "chat"的支持，从此只走/v1/responses协议。网上大量 2025 年写的教程还在告诉你填"chat"，按那套配的人开机就报错。

第二个是 OpenAI 账号本身的问题：注册门槛、地区限制、付款卡限制等等。

本文用 OmniModel 作为第三方网关演示一遍正确的wire_api = "responses"配置——既绕开账号墙，又不会被新版协议变更打脸。

二、Codex CLI 与协议版本变更说明

先讲清楚原理。Codex CLI 是 OpenAI 官方在 2025 年推出的命令行编程助手，专为gpt-5.3-codex等代码大模型设计。它的请求路径有两个版本：

/v1/responses协议的设计目的是支持 reasoning model 的思考链流式输出，对比老的chat.completions多了若干字段，并强制走 SSE。这意味着：

• ❌ 仅支持 OpenAI 镜像、做chat.completions转发的网关，已经完全用不了 Codex CLI
• ✅ 必须找到原生实现了/v1/responses端点的网关

OmniModel 作为 AI 模型聚合网关，完整实现了/v1/responses端点和相关 SSE 字段，这也是它能跑 Codex CLI 的前提。

三、第 0 步：拿到 OmniModel 的 API Key

打开 https://www.omnimodel.pro 注册：

控制台首页：

左侧 → 「令牌」 → 「添加新令牌」：

推荐配置：

拿到sk-xxxxxxxx...形式的密钥后存好。

四、安装 Codex CLI

依赖 Node.js 18+（推荐 LTS 20）：

node --version npm --version

未装则：

• macOS:brew install node
• Windows: Node.js — 下载 Node.js® 下载 LTS 包，安装时记得勾 "Add to PATH"

全局安装：

npm i -g @openai/codex

Windows 注意：必须以管理员身份打开 PowerShell 后再装。如果遇到 "不允许执行脚本"，先放开策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输Y确认。

国内拉包慢的话切镜像源：

npm config set registry https://registry.npmmirror.com npm i -g @openai/codex

验证安装：

codex --version # 应输出 v0.100+ 版本号

五、第 1 步：理解 Codex 的配置文件结构

Codex 把所有配置和运行数据集中在用户目录下的.codex/文件夹：

文件清单：

关键设计：Codex 把 API Key 单独抽到auth.json，是为了方便给这一个文件单独加chmod 600权限，避免和其他配置混在一起。

六、第 2 步：编写 config.toml（核心章节）

完整的config.toml包含三个块：顶层配置、Provider 定义、项目信任白名单。

6.1 顶层配置块

model_provider = "omnimodel" # provider 别名，与下方 [model_providers.xxx] 对应 model = "gpt-5.3-codex" # 默认模型 model_reasoning_effort = "high" # 推理深度：low / medium / high disable_response_storage = true # 不在 OpenAI 侧持久化响应（用第三方网关时建议关掉） preferred_auth_method = "apikey" # API Key 模式（区别于 OAuth） requires_openai_auth = true # 必填，v0.100+ 必须放顶层 enableRouteSelection = true # 允许 Codex 自动路由 personality = "pragmatic" # 回答风格

6.2 Provider 定义块

[model_providers.omnimodel] name = "omnimodel" base_url = "https://omnimodel.pro/v1" # ⚠️ 必须带 /v1，不能多不能少 wire_api = "responses" # ⚠️ 当前唯一可用值，不要填 "chat" env_key = "OPENAI_API_KEY" # 从 auth.json 读取 API Key 的字段名

6.3 项目信任白名单（可选）

[projects."/Users/yourname"] trust_level = "trusted" [projects."/Users/yourname/.codex"] trust_level = "trusted"

设为trusted后 Codex 在该目录里不再每次都问"是否信任此项目"。Windows 路径写法是[projects."C:/Users/yourname"]（用正斜杠或转义反斜杠）。

6.4 macOS / Linux 一键生成命令

mkdir -p "$HOME/.codex" cat > "$HOME/.codex/config.toml" <<EOF model_provider = "omnimodel" model = "gpt-5.3-codex" model_reasoning_effort = "high" disable_response_storage = true preferred_auth_method = "apikey" requires_openai_auth = true enableRouteSelection = true personality = "pragmatic" [model_providers.omnimodel] name = "omnimodel" base_url = "https://omnimodel.pro/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" [projects."$HOME"] trust_level = "trusted" [projects."$HOME/.codex"] trust_level = "trusted" EOF

6.5 Windows PowerShell 一键生成命令

$configPath = "$env:USERPROFILE\.codex\config.toml" $home_unix = $env:USERPROFILE -replace '\\','/' $configContent = @" model_provider = "omnimodel" model = "gpt-5.3-codex" model_reasoning_effort = "high" disable_response_storage = true preferred_auth_method = "apikey" requires_openai_auth = true enableRouteSelection = true personality = "pragmatic" [model_providers.omnimodel] name = "omnimodel" base_url = "https://omnimodel.pro/v1" wire_api = "responses" env_key = "OPENAI_API_KEY" [projects."$home_unix"] trust_level = "trusted" "@ New-Item -Path "$env:USERPROFILE\.codex" -ItemType Directory -Force | Out-Null Set-Content -Path $configPath -Value $configContent

七、第 3 步：编写 auth.json

auth.json是个极简的 JSON 文件，只有一个字段：

{ "OPENAI_API_KEY": "sk-你的实际密钥" }

7.1 macOS / Linux

cat > "$HOME/.codex/auth.json" <<'EOF' { "OPENAI_API_KEY": "sk-替换成你的Key" } EOF chmod 600 "$HOME/.codex/auth.json"

最后chmod 600不要省略——它把权限收紧成只有当前用户能读写，避免被同机其他用户偷看密钥。

7.2 Windows

$authPath = "$env:USERPROFILE\.codex\auth.json" $authContent = @{ OPENAI_API_KEY = "sk-替换成你的Key" } | ConvertTo-Json Set-Content -Path $authPath -Value $authContent

Windows 下没有chmod，但 NTFS 默认就是只有用户自己能读写自己%USERPROFILE%下的文件，安全性已经够用。

八、第 4 步：联通性自检（推荐每次配完都跑）

只看配置文件没用，真正打一次 API 才知道有没有配通。

8.1 macOS / Linux

读取 Key 并请求模型列表：

KEY="$(python3 -c 'import json, pathlib; print(json.loads((pathlib.Path.home()/".codex"/"auth.json").read_text())["OPENAI_API_KEY"])')" curl -sS -i "https://omnimodel.pro/v1/models" \ -H "Authorization: Bearer $KEY" | head -n 20

预期输出：

HTTP/2 200 content-type: application/json ... { "object": "list", "data": [ {"id": "gpt-5.3-codex", ...}, {"id": "claude-opus-4-7", ...}, ... ] }

8.2 Windows PowerShell

$authPath = "$env:USERPROFILE\.codex\auth.json" $auth = Get-Content $authPath | ConvertFrom-Json $key = $auth.OPENAI_API_KEY Invoke-RestMethod -Uri "https://omnimodel.pro/v1/models" ` -Headers @{ Authorization = "Bearer $key" } | Select-Object -ExpandProperty data | Select-Object -First 5 id

8.3 状态码对照表

九、第 5 步：启动 Codex

cd ~/your-project codex

进入 TUI 后试个简单指令：

> 解释一下这个项目的目录结构

如果开始流式输出，全跑通了。

常用命令：

调用成本可以在 OmniModel 控制台「日志」页查看：

十、故障排查清单（按报错查表）

报错 A：wire_api = "chat" is no longer supported

直接原因：参考的是 2025 年的老教程，里面填了wire_api = "chat"。

解决：

grep "wire_api" "$HOME/.codex/config.toml" # 应输出 wire_api = "responses"

如果输出是"chat"，编辑器打开config.toml改成"responses"保存。Windows：

notepad "$env:USERPROFILE\.codex\config.toml"

报错 B：stream disconnected before completion

直接原因：/v1/responses走 SSE 长连接，中间被关掉了。

排查顺序：

1. 网络环境对长连接是否友好？公司代理、校园网常有 60 秒超时强杀；
2. 关掉 VPN 试试；
3. 临时切手机热点验证一下是不是当前网络的问题；
4. 都不行的话查日志：

tail -f "$HOME/.codex/log/codex.log"

Get-Content "$env:USERPROFILE\.codex\log\codex.log" -Wait -Tail 50

报错 C：返回的是 HTML 不是 JSON

直接原因：base_url写错，请求落到了 OmniModel 的网站前端而不是 API。

正确：https://omnimodel.pro/v1错误：https://omnimodel.pro（少/v1）错误：https://omnimodel.pro/chatgpt/v1（多了路径）错误：https://omnimodel.pro/v1/（末尾多斜杠，部分情况下也会出问题）

报错 D：401 Unauthorized

排查顺序：

# 1. 确认 Key 不是空 python3 -c " import json, pathlib d = json.loads((pathlib.Path.home()/'.codex'/'auth.json').read_text()) k = d.get('OPENAI_API_KEY', '') print('Key present:', bool(k)) print('Key length:', len(k)) "

Key 长度应该是 51 个字符左右。如果是 0 或者比预期短，说明 Key 没正确写入。

# 2. 用 curl 直接打一次 chat.completions curl -sS "https://omnimodel.pro/v1/chat/completions" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-5.2","messages":[{"role":"user","content":"hi"}]}'

如果这一步返回 200，说明 Key 没问题，问题在config.toml。

# 3. 全部重置 rm "$HOME/.codex/auth.json" cat > "$HOME/.codex/auth.json" <<'EOF' { "OPENAI_API_KEY": "sk-新的Key粘贴这里" } EOF chmod 600 "$HOME/.codex/auth.json"

报错 E：Codex command not found

原因：npm 全局 bin 目录不在 PATH 里。

Mac/Linux：

npm config get prefix # 假设输出 /usr/local # 那么 bin 在 /usr/local/bin # 把它加到 PATH echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc source ~/.zshrc

Windows：

npm config get prefix # 默认是 %APPDATA%\npm # 在系统环境变量 PATH 里手动加上这个路径

十一、安全自检（生产环境必做）

检查 1：auth.json 权限

ls -la "$HOME/.codex/auth.json" # 应显示 -rw-------（即权限 600）

不是 600 的话：

chmod 600 "$HOME/.codex/auth.json"

检查 2：config.toml 里没有硬编码 Key

grep -r "sk-" "$HOME/.codex/config.toml" # 应该没有任何输出

如果有人在config.toml里直接写了 Key（错误做法），grep 会输出对应行。必须把 Key 移到auth.json里。

检查 3：Token 已设置模型限制和 IP 白名单

回 OmniModel 控制台 → 令牌列表 → 编辑该 Token：

• 模型限制：只允许gpt-5.3-codex,gpt-5.4,claude-opus-4-7等你实际使用的，越权请求直接 403
• IP 白名单：填公司公网 IP 或 VPN 出口 IP，泄露也无法被滥用
• 额度上限：本月只给 $50，超了自动停

三层防护下来，即使 Key 不小心 commit 到 GitHub 也能控制损失。

十二、进阶玩法

12.1 把 Codex 当成多模型的统一 CLI

config.toml里改个model字段，下次启动就是新模型：

model = "claude-opus-4-7" # 用 Claude 跑 Codex # 或 model = "gemini-2.5-pro" # 用 Gemini 跑 Codex # 或 model = "deepseek-v4" # 用 DeepSeek 跑 Codex

OmniModel 后端做了协议适配，Codex 的/v1/responses请求会被转换成对应模型的原生格式。实测对比：

12.2 调低 reasoning_effort 省钱

model_reasoning_effort = "high"会触发 reasoning model 的完整思考链，对简单任务是浪费。可调档：

灵活切换，月度账单能砍一半。

12.3 多 Token 隔离项目预算

控制台一次性建多个 Token，每个绑定不同额度上限：

然后切换auth.json即可（或用direnv自动切）。

12.4 充值

OmniModel 支持 多种方式充值。对海外开发者和数字游民友好。

十三、相关阅读

• 🔗 Codex CLI GitHub 仓库
• 📚 OmniModel 官方手册
• 💡 同一个 OmniModel Token 也能配在 Claude Code、Cursor、ChatGPT 客户端等工具上，一个账户走全栈

如果本文帮你跳过了某个坑，欢迎在评论区补充你遇到的具体报错和操作系统版本，给后续读者节约时间。

本文所有命令在 macOS 14 / Windows 11 + Codex CLI v0.100+ 下验证通过。Codex CLI 仍在快速迭代，如果未来版本对配置文件结构有调整，以官方仓库 README 为准。