接入 Codex

一句话结论：Codex 走 OpenAI Responses 协议。 在 ~/.codex/config.toml 里定义一个指向 ZiAI 的 model_providers 条目，base_url 带 /v1，wire_api = "responses"，密钥放 ~/.codex/auth.json。

项目	值
协议	OpenAI Responses（/v1/responses）
base_url	https://api.ziai.lol/v1 —— 带 /v1
wire_api	responses（唯一合法值）
密钥	~/.codex/auth.json 的 OPENAI_API_KEY，或 env_key 指定的环境变量
配置文件	~/.codex/config.toml（必须用户级）
生效方式	重启终端

硬约束：wire_api 只能是 responses

官方配置参考明确：wire_api 的 responses 是唯一支持的值，省略时也是默认值。 chat（Chat Completions）已从 Codex 中移除。

更坑的是失败方式：配置文件里只要残留任何一个 wire_api = "chat" 的条目， 所有 codex 命令都会在配置加载阶段直接失败 —— 哪怕那个 provider 根本不是当前选中的， 哪怕你只是执行 codex login status。报错形如：

Error loading config.toml: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"`

所以从旧教程迁移过来的用户，第一件事是清理历史配置（见下文专属常见问题）。

前提：安装 Codex CLI

macOS / Linux

npm install -g @openai/codex
codex --version

权限报错时不要用 sudo，改用用户级全局目录：

npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Windows（建议 WSL2）

官方建议在 Windows 上通过 WSL2 使用 Codex 以获得最佳性能：

wsl --install

安装后重启电脑，然后进入 WSL：

wsl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install 22
npm i -g @openai/codex
codex --version

在 WSL 里访问 Windows 盘的项目路径形如 /mnt/c/path/to/your/project。

方式 A：用 CC-Switch 图形化配置 推荐

Codex 的配置文件格式最容易写错（见上面的 wire_api 硬约束），用 CC-Switch 生成最稳妥。 额外好处：如果 ZiAI 上某个模型只有 Chat Completions 通道，CC-Switch 的本地代理能做 Responses ↔ Chat 转换，让 Codex 依然可用。

在 CC-Switch 的 Codex「自定义」供应商里填：

• 端点地址：https://api.ziai.lol/v1
• API Key：你的 ZiAI 密钥
• 模型：点「获取模型」自动拉取，或手填 ID
• 需要本地路由映射：目标模型支持 /v1/responses 时关闭；只有 Chat 通道或模型名非 GPT 系列时打开

CC-Switch ≥ v3.20.1 采用 config-only 切换（密钥随供应商表走，不再依赖 auth.json），这正是 Codex CLI ≥ 0.149 所要求的。

方式 B：手动配置

1. 编辑 ~/.codex/config.toml

# ===== 顶层：指定用哪个 provider 和哪个模型 =====
model = "你的模型ID"
model_provider = "ziai"
model_reasoning_effort = "high"
disable_response_storage = true

# ===== provider 定义：名字必须与上面的 model_provider 一致 =====
[model_providers.ziai]
name = "ZiAI"
base_url = "https://api.ziai.lol/v1"
wire_api = "responses"
supports_websockets = false

2. 放入密钥（二选一）

auth.json（通用做法）

创建 / 编辑 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

配合 provider 里的 requires_openai_auth = true 使用。 建议把文件权限收紧：

chmod 700 ~/.codex && chmod 600 ~/.codex/config.toml ~/.codex/auth.json

env_key（更推荐，密钥不落配置文件）

在 provider 里声明环境变量名（是变量名，不是密钥本身）：

[model_providers.ziai]
name = "ZiAI"
base_url = "https://api.ziai.lol/v1"
wire_api = "responses"
env_key = "ZIAI_API_KEY"
supports_websockets = false

然后在 shell 里导出：

# bash / zsh —— 写进 ~/.bashrc 或 ~/.zshrc 持久化
export ZIAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# PowerShell —— 用户级持久化
[Environment]::SetEnvironmentVariable('ZIAI_API_KEY', 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'User')
# 当前会话立即生效
$env:ZIAI_API_KEY = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

可选：加 env_key_instructions = "到 ZiAI 控制台 /console/token 创建密钥"， 缺失密钥时 Codex 会把这句话显示给用户。

disable_response_storage 是什么

接中转站时建议写入 disable_response_storage = true，作用是禁用 Responses API 的响应存储 （中转站通常不支持 store 与 previous_response_id 语义，关掉可避免相关报错）。

该键未出现在当前 Codex 官方配置参考中。若你的 Codex 版本报「未知配置键」，删掉这一行即可，其余配置不受影响。

model_providers.<id> 键速查

对接 ZiAI 时可能用到的键（完整列表见官方配置参考）：

键	含义	接 ZiAI 时的建议
base_url	API 基础 URL	带 /v1
wire_api	协议，只能是 responses	显式写上，避免歧义
name	显示名称	ZiAI
env_key	提供密钥的环境变量名	推荐用这个而非明文
requires_openai_auth	是否使用 OpenAI 认证（默认 false）	用 auth.json 方式时设 true
supports_websockets	是否支持 Responses API 的 WebSocket 传输	设 false，见下方说明
http_headers	附加的静态 HTTP 头	站点要求额外鉴权头时用
env_http_headers	从环境变量填充的 HTTP 头	同上，避免明文
query_params	附加查询参数	一般不用
request_max_retries	HTTP 请求重试次数（默认 4）	网络不稳时可调整
stream_max_retries	SSE 流中断重试次数（默认 5）	同上
stream_idle_timeout_ms	SSE 流空闲超时（默认 300000，即 5 分钟）	慢模型 / 长思考时调大
experimental_bearer_token	直接写 bearer token	不推荐，官方建议用 env_key

为什么要显式关闭 supports_websockets

新版 Codex 会尝试用 WebSocket 传输 Responses API。ZiAI 目前不支持 WebSocket Responses， 于是请求会打到 wss://api.ziai.lol/v1/responses 并失败，典型报错：

unexpected status 404 Not Found: Invalid URL (GET /v1/responses), url: wss://api.ziai.lol/v1/responses

在 provider 里加 supports_websockets = false，Codex 就会走普通 HTTP + SSE，问题解决。

配置文件位置与优先级

位置	说明
~/.codex/config.toml	用户级。provider 必须写在这里
$CODEX_HOME/profile-name.config.toml	配置档案，用 --profile profile-name 选择
项目内 .codex/config.toml	项目级覆盖，仅在项目被信任时加载

provider 写在项目级会被静默忽略

项目级 .codex/config.toml 不能覆盖计算机本地的提供商、身份验证、通知、配置档案选择与遥测路由等键。 当以下键出现在项目本地配置中时，Codex 会直接忽略它们：

openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、 notify、profile、profiles、experimental_realtime_ws_base_url、otel

表现是「配置看起来完全正确，但请求还是发往 api.openai.com」。请把 provider 配置放在用户级文件里。

用 profile 在多个站点之间切换

不想装 CC-Switch 又要多站切换，可以用配置档案：

~/.codex/config.toml

model_provider = "ziai"
model = "你的模型ID"

[model_providers.ziai]
name = "ZiAI"
base_url = "https://api.ziai.lol/v1"
wire_api = "responses"
env_key = "ZIAI_API_KEY"
supports_websockets = false

再建 $CODEX_HOME/official.config.toml 放官方配置，用 codex --profile official 启动即可切换。 注意 profiles 键本身也属于项目级会被忽略的键，档案文件要放在 $CODEX_HOME 下。

验证

1. 确认 ZiAI 的 Responses 端点可用

   curl https://api.ziai.lol/v1/responses \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     -d '{"model":"你的模型ID","input":"你好"}'

   返回含 output 数组与 status: "completed" 即为正常。

   若返回 404 或「模型不支持」，说明该模型在 ZiAI 上没有 Responses 通道 —— 此时必须走 CC-Switch 的本地路由映射，手改 config.toml 无解。

2. 检查配置能被正确加载

   codex login status

   这条命令不需要真正发请求，但会加载配置 —— 如果配置里有 wire_api = "chat" 残留，这一步就会报错。

3. 启动 Codex

   cd /path/to/your/project
   codex

   首次启动会询问权限策略（是否允许直接修改文件）。进入后用 /model 确认模型，发一句指令测试。

   待补插图Codex 接入 ZiAI 后首次执行任务

   终端里 codex 启动、/model 显示 ZiAI 模型、并成功完成一个小任务；宽 1200，PNG

4. 非交互式端到端验证（可选）

   codex exec "列出当前目录的文件并说明项目结构"

Codex 专属常见问题

现象	原因	解决
所有命令都报 Error loading config.toml	配置里残留 wire_api = "chat"	全局搜 wire_api，把所有 chat 改成 responses 或删掉该条目
404 Invalid URL ... wss://	Codex 尝试 WebSocket 传输，ZiAI 不支持	provider 里加 supports_websockets = false
请求仍发往 api.openai.com	provider 写在了项目级 .codex/config.toml	移到 ~/.codex/config.toml
401 Missing API key	Codex ≥ 0.149 不再从 auth.json 继承环境凭据	用 env_key，或升级 CC-Switch ≥ v3.20.1 后重新切换
404 Not Found	base_url 少了 /v1	补上 /v1
模型不存在 / only supported in v1/responses	该模型在 ZiAI 上只有 Chat 通道	换支持 Responses 的模型，或用 CC-Switch 本地路由映射
/model 里看不到自定义模型	本地路由映射的模型表改动后未重启	重启 Codex（model_catalog_json 只在启动时加载）
调 model_reasoning_effort 无效	上游只支持思考开关、不支持档位	属正常行为；CC-Switch 不会硬传给不接受该参数的上游
长任务中途停止	流式空闲超时（默认 5 分钟）	调大 stream_idle_timeout_ms；走 CC-Switch 转换时升级到 ≥ v3.20.3
未知配置键报错	版本不认识 disable_response_storage	删掉该行

清理历史配置的一条命令（bash）：

grep -n 'wire_api' ~/.codex/config.toml
# 若看到 wire_api = "chat"，改成 "responses"：
sed -i.bak 's/wire_api *= *"chat"/wire_api = "responses"/g' ~/.codex/config.toml

下一步

• 接入 Claude Code —— 另一个终端 Agent，协议不同
• CC-Switch：添加 ZiAI 并切换
• 协议不匹配详解