为什么需要协议转换
Codex CLI 原生使用 OpenAI 的 Responses API 协议。而智谱、DeepSeek、通义千问等国产大模型的 Coding Plan 接口，普遍基于 Chat Completions 规范（目前国内的厂家我看下里只有火山家和阿里云家的ai是启用responses协议的。使用其他家只支持chat的模型想要接入codex必须借助一个中间件）。协议层不匹配，直连走不通——中间需要一个翻译层（一个中转站）。
方案选型上，CCX 是一个 Go 编写的单二进制 API 网关，支持 Responses / Chat Completions / Gemini 等多协议互转，自带 Web 管理面板、多 Key 轮换和故障熔断。相比自己写转发脚本，功能完整度更高，维护成本也更低。
整体数据流
Codex CLI ──[Responses, model: gpt-5.5]──▶ CCX :3000 ──[协议转换 + 模型映射]──▶ 智谱 API
完整链路拆解：
Codex 以 Responses 格式发送请求，模型名写 gpt-5.5（Codex 内置元数据表中认可的名称）
CCX 接收后，通过 serviceType: openai 将 Responses 转为 Chat Completions 格式
modelMapping 把 gpt-5.5 重写为 glm-5.1
CCX 使用面板中配置的真实 API Key 转发至智谱
智谱的响应经 CCX 还原为 Responses 格式返回给 Codex
环境要求
依赖 最低版本 说明
macOS Apple Silicon (arm64) CCX 提供 darwin-arm64 二进制
Node.js ≥ 22 Codex CLI 运行时
curl 系统自带 用于验证和健康检查
一、部署 CCX
1.1 下载与安装
CCX 目前没有进入 Homebrew 等包管理器，直接从 GitHub Releases 获取二进制：
# 创建运行目录
mkdir -p ~/.ccx/{logs,.config}
# 下载 darwin-arm64 二进制（约 27MB）
curl -L --retry 3 -o ~/.ccx/ccx \
"https://github.com/BenedictKing/ccx/releases/download/v2.6.97/ccx-darwin-arm64"
# 赋予执行权限
chmod +x ~/.ccx/ccx
# 验证
~/.ccx/ccx --version # 期望输出：ccx version 2.6.97
⚠️ 如果下载后文件大小异常（只有几 KB），检查是否有残留的 curl 进程占用了目标文件：lsof ~/.ccx/ccx 定位后 kill 掉再重新下载。
1.2 环境变量
创建 ~/.ccx/.env：
PORT=3000
ENV=production
ENABLE_WEB_UI=true
PROXY_ACCESS_KEY=<你的代理密钥>
ADMIN_ACCESS_KEY=<你的管理密钥>
APP_UI_LANGUAGE=zh-CN
LOG_LEVEL=info
REQUEST_TIMEOUT=120000
两个密钥的用途：
变量 作用 谁在用
PROXY_ACCESS_KEY 代理访问密钥 Codex CLI 通过 Bearer Token 发送
ADMIN_ACCESS_KEY 管理面板登录密码 浏览器打开 CCX 面板时输入
⚠️ .env 含敏感凭据，确保 ~/.ccx/ 目录不会被同步到公开仓库。
1.3 配置开机自启
通过 macOS LaunchAgent 实现 CCX 开机自启 + 崩溃自动重启：
<!-- ~/Library/LaunchAgents/com.ccx.proxy.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.ccx.proxy</string>
<key>ProgramArguments</key>
<array><string>$HOME/.ccx/ccx</string></array>
<key>WorkingDirectory</key><string>$HOME/.ccx</string>
<key>EnvironmentVariables</key>
<dict>
<key>PORT</key><string>3000</string>
<key>ENV</key><string>production</string>
<key>ENABLE_WEB_UI</key><string>true</string>
<key>PROXY_ACCESS_KEY</key><string><你的代理密钥></string>
<key>ADMIN_ACCESS_KEY</key><string><你的管理密钥></string>
<key>APP_UI_LANGUAGE</key><string>zh-CN</string>
<key>LOG_LEVEL</key><string>info</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>StandardOutPath</key><string>$HOME/.ccx/logs/stdout.log</string>
<key>StandardErrorPath</key><string>$HOME/.ccx/logs/stderr.log</string>
</dict>
</plist>
# 注册并启动
launchctl load ~/Library/LaunchAgents/com.ccx.proxy.plist
# 验证服务就绪
curl -s http://127.0.0.1:3000/health | python3 -m json.tool
# 期望：{"status":"ok","version":"2.6.97",...}
二、配置 CCX 上游通道（核心步骤）
浏览器打开 http://localhost:3000 ，用 ADMIN_ACCESS_KEY 登录管理面板。这一步是整个配置的关键——必须把通道添加到正确的协议分类下。
2.1 先搞清楚协议分类
CCX 按协议类型将上游通道隔离到不同分组中：
协议分类 适用客户端
Messages Claude Code
Responses Codex CLI ← 本文目标
Gemini Gemini CLI
Chat 通用 OpenAI 兼容工具
Images 图片生成
关键点：Codex 发出的 /v1/responses 请求只会从 Responses 分组中选渠道。放错分组是第一个坑的根源，后文会详细说。
2.2 添加 Responses 通道
在面板的 Responses 标签页下添加通道，参数如下：
字段 推荐值 说明
Base URL <你的大模型请求路径> 对应大模型厂家的API请求专用端点
API Key <你的大模型API Key> 在 bigmodel.cn 控制台获取
Service Type openai ⚠️ 最关键的选项！控制协议转换行为
Model Mapping 见下方 JSON Codex 模型名 → 智谱模型名
reasoningParamStyle thinking 将 Codex 的 reasoning effort 映射为 thinking 参数
codexToolCompat true 透传 Codex 工具调用相关参数
stripCodexClientTools true 剥离 Codex 私有 tools 字段，避免上游报错
Model Mapping 配置：
{
"gpt-5.5": "glm-5.1",
"gpt-5.4": "glm-5-turbo",
"gpt-5.2-codex": "glm-5-turbo",
"gpt-5.2": "glm-4.7"
}
为什么要做映射？因为 Codex 内置了一份模型元数据表，只认 gpt-* / o* / claude-* 这类名称。直接填 glm-5.1 会命中未知模型分支，触发 fallback 甚至后续处理异常。映射层实现了两端解耦——Codex 用自己认识的 gpt-5.5，实际模型由 CCX 在转发时替换。
三、配置 Codex CLI
3.1 config.toml
这一步可以通过CC-switch来配置，不仅有图形化界面更加方便配置而且还能配置其他工具比如Claude code还有open claw等，详情可以去了解CC-switch。
编辑 ~/.codex/config.toml：
model_provider = "zhipu"
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
[model_providers.zhipu]
name = "GLM Coding Plan (via CCX)"
base_url = "http://127.0.0.1:3000/v1" # ⚠️ 必须带 /v1 后缀（详见踩坑 #5）
env_key = "ZHIPU_API_KEY"
wire_api = "responses"
requires_openai_auth = true
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000
[projects."<你的工作目录>"]
trust_level = "trusted"
关键字段说明：
字段 值 作用
base_url http://127.0.0.1:3000/v1 CCX 地址，必须含 /v1
env_key ZHIPU_API_KEY Codex 从这个环境变量读取认证值
requires_openai_auth true 以 Authorization: Bearer 格式发送
wire_api "responses" 使用 Responses 协议格式
3.2 搞清楚认证链路
这里容易踩坑——ZHIPU_API_KEY 的值到底该填什么？
Codex CCX 智谱
│ │ │
├─ 读 ZHIPU_API_KEY ├─ 校验 Bearer Token ├─ 用面板中存储的 Key 认证
│ = "CCX代理密钥" │ = PROXY_ACCESS_KEY │
│ │ │
└─ Authorization: Bearer <代理密钥> ──▶ ──▶ Authorization: Bearer <真实智谱Key> ──▶
结论：Codex 只需要知道怎么向 CCX 证明身份，真正连接智谱的凭证由 CCX 面板单独管理。所以 ZHIPU_API_KEY 填的是 CCX 的 PROXY_ACCESS_KEY，不是智谱原始 Key。
3.3 配置 Shell 环境变量
# 写入 ~/.zprofile（推荐，zsh 登录时自动加载）
export ZHIPU_API_KEY="<CCX代理密钥>"
写入后执行 source ~/.zprofile 或新开终端生效。
四、验证全链路
按顺序执行三个测试：
# ① CCX 健康检查
curl -s http://127.0.0.1:3000/health
# 期望：{"status":"ok","version":"2.6.97",...}
# ② 端到端非流式测试
curl -s -X POST http://127.0.0.1:3000/v1/responses \
-H "Authorization: Bearer <代理密钥>" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.5","input":"say hi"}'
# ③ 端到端流式测试
curl -s -N -X POST http://127.0.0.1:3000/v1/responses \
-H "Authorization: Bearer <代理密钥>" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-5.5","input":"say hi","stream":true}'
非流式测试正常返回时，注意看响应中的 model 字段——从 gpt-5.5 变成了 glm-5.1，说明 modelMapping 已生效：
{
"id": "resp_xxx",
"model": "glm-5.1",
"output": [
{"type": "reasoning", "summary": [...], "status": "completed"},
{"type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "..."}]}
],
"status": "completed",
"usage": { ... }
}
三个测试都通过后，直接终端输入 codex 开始对话。
五、踩坑实录
以下按实际排查顺序记录遇到的 5 个问题。每个都遵循 现象 → 根因 → 修复 的排查思路。
坑 #1：渠道放错了分组 → NO_RESPONSES_UPSTREAM
现象：CCX 返回 "未配置任何 Responses 渠道"，Codex 无法发起请求。
根因：初次配置时把智谱上游通道添加到了 Messages 分组。但 Codex 发出的 /v1/responses 请求只从 Responses 分组中选渠道——分组不对，自然是空集。
修复：在 Web 面板的 Responses 标签页下重新添加通道，删除 Messages 分组中的错误条目。
教训：动手前先确认目标客户端用的什么协议，再去选对应的 Tab。
坑 #2：serviceType 选错了 → 404 Not Found
现象：All upstream channels are currently unavailable，CCX 日志显示请求打到了 https://open.bigmodel.cn/api/coding/paas/v4/responses 并返回 404。
根因：serviceType 控制的是 CCX 对上游的行为，直接决定了实际请求的端点：
serviceType CCX 行为 实际请求端点
responses 原样透传 Responses payload POST /v4/responses ❌ 智谱没有这个接口
openai 自动转译为 Chat Completions POST /v4/chat/completions ✅
修复：把 serviceType 改为 openai。
教训：国产模型 API 几乎都基于 Chat Completions 规范，尚未跟进 Responses 新协议。接入时 serviceType 统一选 openai。
坑 #3：模型名写错了 → metadata warning
现象：Model metadata for 'GLM-5.1' not found. Defaulting to fallback metadata.
根因：Codex 内置了一份模型元数据表（上下文窗口大小、token 限制等），只覆盖 gpt-* / o* / claude-* 等已知名称。config.toml 里直接写 model = "GLM-5.1" 会命中未知分支，触发 fallback。
修复：Codex 侧用 model = "gpt-5.5"（它认识的名称），CCX 侧通过 modelMapping 翻译为 glm-5.1。两端解耦，各管各的。
坑 #4：环境变量没设 → 启动崩溃
现象：Missing environment variable: 'ZHIPU_API_KEY'.，Codex 启动即退出。
根因：config.toml 中声明了 env_key = "ZHIPU_API_KEY"，但 shell 环境中没有 export 这个变量。
修复：在 ~/.zprofile 中添加 export ZHIPU_API_KEY="<CCX代理密钥>"，然后 source ~/.zprofile。
注意：这个值是 CCX 的代理密钥，不是智谱 Key（参见 3.2 节认证链路图）。
坑 #5：base_url 少写了 /v1 → 流式断连 ⭐
现象：stream disconnected before completion: stream closed before response.completed
这是整个配置过程中最隐蔽的坑——curl 测试全通过，但 Codex 实际对话时流式连接反复中断。
排查特征（典型的「假阳性」）：
测试方式 结果
curl 非流式请求 ✅ 正常
curl 流式请求 (-N) ✅ 正常
Codex 实际对话 ❌ 流断连
最终定位到 base_url 的路径拼接问题：
# ❌ 缺少 /v1，Codex 内部拼接产生异常路径
base_url = "http://127.0.0.1:3000"
# ✅ 显式带 /v1 后缀
base_url = "http://127.0.0.1:3000/v1"
加上 /v1 后流式连接立即恢复。查看 CCX 日志可以看到：不带 /v1 时请求落到了 /responses 而非 /v1/responses，CCX 没匹配到路由就返回了空响应。
教训：curl 通过但客户端 SDK 异常时，优先排查实际的 URL 拼接结果。显式写全路径前缀能规避这类框架级行为导致的隐晦故障。
六、最终配置速查
CCX .env
PORT=3000
ENV=production
ENABLE_WEB_UI=true
PROXY_ACCESS_KEY=<代理密钥>
ADMIN_ACCESS_KEY=<管理密钥>
APP_UI_LANGUAGE=zh-CN
REQUEST_TIMEOUT=120000
CCX Responses 通道（Web 面板配置）
参数 值
分类标签页 Responses
Base URL https://open.bigmodel.cn/api/coding/paas/v4
Service Type openai
Model Mapping {"gpt-5.5":"glm-5.1","gpt-5.4":"glm-5-turbo","gpt-5.2-codex":"glm-5-turbo","gpt-5.2":"glm-4.7"}
reasoningParamStyle thinking
codexToolCompat true
stripCodexClientTools true
Codex config.toml
model = "gpt-5.5"
base_url = "http://127.0.0.1:3000/v1" # 显式 /v1 后缀
env_key = "ZHIPU_API_KEY" # 值 = CCX 代理密钥
wire_api = "responses" # Responses 协议
requires_openai_auth = true # Bearer 认证
错误速查表
错误信息 根因 修复
NO_RESPONSES_UPSTREAM 渠道放错了分组 移至 Responses 标签页
All upstream unavailable (404) serviceType=responses 改为 openai
Model metadata not found 模型名不在 Codex 元数据表 用 gpt-5.x + modelMapping
Missing env variable shell 未 export 变量 ~/.zprofile 中添加 export
stream disconnected base_url 缺少 /v1 补上 /v1 后缀
Invalid access key Bearer token 与 CCX 密钥不匹配 核对 PROXY_ACCESS_KEY
文件布局总览
~/.ccx/
├── ccx # 二进制主程序
├── .env # 端口 / 密码 / 语言配置
├── .config/
│ └── config.json # 运行时配置（Web 面板写入）
└── logs/
├── stdout.log
└── stderr.log
~/Library/LaunchAgents/
└── com.ccx.proxy.plist # 开机自启 + KeepAlive
~/.codex/
└── config.toml # Codex 主配置
~/.zprofile # Shell 环境变量（ZHIPU_API_KEY）
小结
整套方案的核心思路可以归纳为一句话：
Responses 分组 + openai 类型 + gpt-5.x 映射 + base_url 带 /v1 = 全链路打通
四个关键设计决策：
协议适配：CCX 的 serviceType: openai 完成 Responses → Chat Completions 的自动转换
模型解耦：Codex 侧用内置名称 gpt-5.5，CCX 侧通过 modelMapping 翻译为 glm-5.1
认证分离：Codex 只持有 CCX 代理密钥，真实智谱 Key 由 CCX 面板独立管理
路径规范：base_url 显式包含 /v1 前缀，保证流式连接稳定
这套方案的思路是通用的——换 DeepSeek、通义千问、Kimi 等任何兼容 Chat Completions 的模型，只需改 CCX 上游通道的 Base URL 和 Model Mapping 即可，Codex 侧完全不用动。
————————————————
版权声明：本文为CSDN博主「lv99freshman」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/lv99freshman/article/details/161152233