CCX + CC Switch 接入第三方 API¶

这个方案把“网关”和“切换工具”拆开。

第三方工具风险

CCX 和 CC Switch 都是第三方社区工具，不是 OpenAI 官方工具。使用前请备份本机 Codex 配置目录，不要把 token、账号密码和私有网关地址提交到仓库。

CCX：AI API 代理与协议转换网关，支持 Claude Messages、OpenAI Chat Completions、Codex Responses、Gemini 等入口，也提供 Web 管理界面、渠道编排、故障转移和模型路由。
CC Switch：桌面管理工具，用来管理 Claude Code、Codex、Gemini CLI 等工具的供应商配置、MCP、Skills 和会话，并支持一键切换。

适合你有多个国产模型 API、多个中转服务、多个 Key，或者需要把 Chat Completions 形态转换成 Codex 可用入口的情况。

第 1 步：部署 CCX¶

如果使用 Docker，可以参考 CCX README 中带访问密钥的方式：

docker run -d \
  --name ccx \
  -p 3000:3000 \
  -e PROXY_ACCESS_KEY=your-proxy-access-key \
  -e APP_UI_LANGUAGE=zh-CN \
  -v $(pwd)/.config:/app/.config \
  crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest

启动后打开：

http://localhost:3000

第 2 步：在 CCX 添加渠道¶

在 CCX Web 管理界面里添加你的上游渠道：

选择上游服务类型。
填写国产模型或中转服务的 API Key。
填写 Base URL。
配置模型映射、可用模型或路由规则。
先用 CCX 自带测试功能确认渠道可用。

这里要确认一件事：Codex 需要的是 Responses API 入口。如果上游只有 Chat Completions，CCX 需要负责协议转换。

第 3 步：安装 CC Switch¶

CC Switch 可以用桌面安装包，也可以按你的习惯使用命令行安装。你给出的命令是：

npm install -g cc-switch

安装后初始化：

cc-switch init

初始化时把 CCX 地址作为中转入口，例如：

http://localhost:3000

第 4 步：切换配置并启动 Codex¶

切换到你刚配置好的供应商：

cc-switch use <配置名>

然后重新启动 Codex，让新的 provider 配置生效。

如果 CC Switch 写入的是 ~/.codex/config.toml，建议切换后打开文件核对一次：

当前 model_provider 是否是你刚选择的配置。
base_url 是否指向 CCX。
API Key 是否没有被写进公开仓库。
原有 MCP、Skills、profile 等配置是否还在。

常见问题¶

现象	先检查什么
切换后没有生效	是否完全重启 Codex，`model_provider` 名称是否一致
报认证错误	API Key 是否有效，环境变量是否被当前 shell 继承
报接口路径错误	`base_url` 是否只写到 `/v1`，不要重复拼上 `/responses`
国产模型无法响应	上游是否支持 Responses API；不支持时需要 CCX 这类网关转换
插件或 Skills 配置不见了	切换工具是否覆盖了通用配置，是否有备份或共享配置片段
旧会话不可见	参考配置文件里的 provider 切换排查说明