OpenAI Codex CLI接入智谱GLM实战：CCX协议转换+5大问题修复指南

原文地址: https://88box.top 生成时间: 2026-05-21 01:00:44

OpenAI Codex CLI 接入国产大模型以智谱 GLM 为例完整实战教程：CCX 协议转换 + 5 个踩坑修复+Mac环境 - hey99 知识搜索引擎

精选文章

OpenAI Codex CLI 接入国产大模型以智谱 GLM 为例完整实战教程：CCX 协议转换 + 5 个踩坑修复+Mac环境

OpenAI Codex CLI 只认 Responses 协议，国产大模型（GLM为例）只给 Chat Completions 接口——两头对不上。本文记录如何用网关打通这条链路，实现 Codex CLI 对接智谱 GLM-5.1 Coding Plan，含 CCX 部署、通道配置、Codex 参数调优，以及 Responses 协议转换、modelMapping 映射、base_url 路径拼接等 5 个实际问题的排查与修复。

更新于 2026-05-20 16:57

OpenAI Codex CLI 只认 Responses 协议，国产大模型（GLM为例）只给 Chat Completions 接口——两头对不上。本文记录如何用

CCX

网关打通这条链路，实现 Codex CLI 对接智谱 GLM-5.1 Coding Plan，含 CCX 部署、通道配置、Codex 参数调优，以及 Responses 协议转换、modelMapping 映射、base_url 路径拼接等 5 个实际问题的排查与修复。

为什么需要协议转换

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 开机自启 + 崩溃自动重启：

<!

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

=

""

写入后执行

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=""

，然后

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 侧完全不用动。