CC Switch + CLIProxyAPI + Codex：在 Codex 中使用 Gemini

梳理通过 CC Switch 与 CLIProxyAPI 将 Gemini 接入 Codex 的完整架构，涵盖地区出口分流、模型 alias 映射、catalog 参数调优与排错链路。

我最初只是想在保留 Codex 使用体验的同时，通过 Google Antigravity OAuth 使用 Gemini。

最后搭出来的结构已经变成一个本地多模型代理环境：

text
Codex
  ↓
CC Switch
127.0.0.1:15721
  ↓
CLIProxyAPI
127.0.0.1:8317
  ├─ Antigravity OAuth → Gemini / Claude
  ├─ OpenAI Compatibility → GPT 等中转模型
  └─ 其他兼容上游

Codex 仍然按 OpenAI Responses API 工作，不需要理解后面的 OAuth、模型真实 ID 或不同上游协议。

需要先说明的是，上述拓扑是我最初采用的单一 Provider 路由（Routing）实践：把 Codex 的请求全局转发给 CLIProxyAPI 以桥接 Gemini。如果需要在 Codex 中同时直接使用 OpenAI 官方模型与第三方 Gemini，则需要使用后文补充的 Aggregation（聚合）模式。

1. 各组件的职责

CC Switch

Codex 实际连接 CC Switch 的本地代理：

text
127.0.0.1:15721

它负责 Provider 切换、API Key 注入以及 Codex model catalog 管理，然后把请求转发给 CLIProxyAPI。

CLIProxyAPI

CLIProxyAPI 是核心代理层：

text
http://127.0.0.1:8317

主要负责：

text
OAuth / 上游认证
模型名称映射
协议转换
模型路由
OpenAI Responses / Chat Completions / Anthropic Messages

主要配置文件：

text
F:/reverse_proxy/CLIProxyAPI/config.yaml

判断模型是否真正可用时，以：

text
GET /v1/models

的返回结果为准。

2. Gemini / Antigravity 的网络问题

CLIProxyAPI 的 Antigravity 流量经过 Clash Verge：

yaml
proxy-url: "http://127.0.0.1:7897"

原因不仅是访问 Google，还包括 OAuth token refresh 和 Antigravity 的地区限制。

实际测试中：

text
香港 / 台湾 / 日本
→ Google 可访问
→ Antigravity: User location is not supported

新加坡
→ 可用

美国 / 英国
→ 可用

所以我单独建立了 Google 策略组，并固定到经过验证的地区节点，避免 Auto 自动漂移到不支持 Antigravity 的出口。

这里最重要的经验是：

Google 能访问，不代表 Antigravity 能使用。

出现 User location is not supported 时，先检查代理出口，不要先重新做 OAuth。

3. 模型 alias

Antigravity 的内部模型 ID 不一定适合直接给 Codex 使用，所以通过 oauth-model-alias 做映射：

yaml
oauth-model-alias:
  antigravity:
    - {name: "gemini-3.8-flash-high", alias: "Gemini 3.8 Flash"}
    - {name: "gemini-pro-agent", alias: "Gemini 3.1 Pro"}
    - {name: "gemini-3-flash", alias: "Gemini 3 Flash"}
    - {name: "claude-sonnet-4-6", alias: "Claude Sonnet 4.6"}
    - {name: "claude-opus-4-6-thinking", alias: "Claude Opus 4.6 Thinking"}

可以简单理解为：

text
alias
→ Codex 看到的名称

name
→ CLIProxyAPI 实际调用的上游模型

OpenAI-compatible 中转则通过：

yaml
openai-compatibility:

接入。

有一个比较隐蔽的坑：

openai-compatibility 条目缺少 base-url 时，可能会被直接忽略，而且日志里没有明显报错。

如果模型突然不出现在 /v1/models 中，先检查这里。

4. Codex /model 菜单

Codex 的模型目录最终生成到：

text
~/.codex/cc-switch-model-catalog.json

模型的 slug 必须和：

text
GET /v1/models

中 CLIProxyAPI 实际暴露的名称一致。

否则就会出现：

text
/model 里能看到模型
→ 选择成功
→ 实际请求失败

当前自定义 modelCatalog 已写入：

text
~/.cc-switch/cc-switch.db

因此 CC Switch 重建 catalog 时，自定义模型不会全部丢失。

官方 Codex 模型与 Gemini 如何共存

在单 Provider 路由模式下，一个常见的困惑是：既然本地保留了 ChatGPT 官方登录凭据，为什么不能在 /model 菜单里直接混用官方 Codex 模型与 Gemini？

这里需要理清三个互相独立的条件：

text
1. /model 菜单中模型可见
→ 本地 catalog 文件或数据库中存在该条目

2. 官方账号已登录
→ Codex 客户端持有 OpenAI / ChatGPT 认证凭据

3. 实际请求正确路由
→ 本地代理层将流量派发给实际拥有该模型的上游服务商

很多读者容易误以为只要在 catalog 中加上了模型条目且账号已登录，Codex 就会根据模型名称自动分流。但在 CC Switch 的 Routing 模式下，所有流量只会被整流转发给当前选定的单一 Provider（即 CLIProxyAPI）。因此即使三个条件各自成立，原方案也无法实现官方 Codex 与 Gemini 的自动按模型分流。

如果希望官方模型与第三方模型在 Codex 中同台出现并按需调度，需要借助 CC Switch 的 Aggregation Mode（聚合模式）。

聚合架构

Aggregation Mode 会将多个 Provider 声明的模型整合进同一份 Codex 模型列表中，并在收到调用请求时，根据模型 ID 自动派发给对应的 Provider：

text
Codex
  ↓
CC Switch · Aggregation
  ├─ OpenAI Official
  │    └─ Codex 官方模型
  │
  └─ CLIProxyAPI
       └─ Gemini / Claude / 其他兼容模型

配置步骤

根据 CC Switch 官方聚合指南，整体配置流程如下：

  1. 保留 OpenAI Official Provider，并确认官方 ChatGPT 登录状态正常有效。
  2. 保留已配置好的 CLIProxyAPI Provider 及其 Gemini OAuth 配置（确保 127.0.0.1:8317 正常响应）。
  3. 打开 CC Switch → Codex → Aggregation，将 OpenAI Official 指定为 Default Provider。
  4. 将 CLIProxyAPI 添加到 Aggregation 聚合列表中，并在其模型列表中勾选或配置实际支持的模型。
  5. 点击 Switch to Aggregation 执行切换，在弹出的模型汇总预览中核对各 Provider 的模型归属后确认生效。
  6. 根据所使用的 Codex 客户端类型，按官方指引完整重启 Codex：CLI 模式需终止后台 daemon 进程（退出终端会话或手动结束残留后台进程）后重新启动；Desktop 客户端需从托盘或系统菜单彻底退出应用后重新打开；VS Code 或编辑器扩展则需通过命令面板重载窗口（Reload Window）或完全重启编辑器。
  7. 重启后在 Codex 中打开 /model 菜单，选择对应模型发送一条简短请求，观察 CC Switch 与 CLIProxyAPI 日志，验证请求是否准确路由到预期上游。

在聚合列表中，为了防止不同 Provider 的同名模型冲突，非默认 Provider 的聚合模型通常带有 ccs- 前缀（例如 ccs-gemini-3.8-flash-high），而 Default Provider（OpenAI Official）的模型保持原始名称。在 Codex 中直接选择带 ccs- 前缀的模型即可调用对应第三方 Provider。

模式对比

为了理清 Direct、Routing 与 Aggregation 三者的区别，可以参考下表：

模式请求如何路由Provider 如何切换是否支持多 Provider 模型同台选择是否支持自动故障转移
Direct（直连）直连 OpenAI 官方服务端，不经过本地代理不支持切换，仅限官方单一渠道否（仅官方模型）否
Routing（路由）全部请求由 CC Switch 转发给当前选定的单一 Provider在 CC Switch 界面手动切换全局 Provider，或按规则分流否（同一时刻所有请求仅走当前选定 Provider）是（支持在主备 Provider 间配置自动故障转移）
Aggregation（聚合）CC Switch 作为聚合层，根据所选模型 ID（及前缀）自动分发到对应 Provider无需切换全局 Provider，通过 /model 选择模型即可分发是（官方模型与第三方模型共存于同一选择列表）否（不支持跨 Provider 的自动故障转移）

关键限制与注意事项

聚合模式解决了模型同台选择的问题，但在实际使用中需要注意以下限制：

  • 不支持自动故障转移：Aggregation 侧重于依据模型静态派发请求，不支持 Routing 模式具备的主备 Provider 自动故障转移能力。
  • 依赖本地代理常驻：聚合模式依然依赖 CC Switch 本地代理（127.0.0.1:15721）及 CLIProxyAPI（127.0.0.1:8317）持续在后台运行。
  • 客户端额度校验限制：如果官方 Codex 账户的可用额度耗尽，某些客户端版本的自身额度检查机制可能在发起请求前直接报错拦截，从而阻止调用第三方模型。
  • 账号合规与安全边界：Aggregation 模式保留官方登录虽然符合日常使用习惯，但仍属于通过本地中间件转发请求，使用时需知悉账号合规要求与潜在风险。
  • 上游服务多重制约：Gemini 能否稳定使用，核心依然受制于 Google Antigravity OAuth 凭据有效期、网络出口地域策略、上游服务限流以及 CLIProxyAPI 对 Responses 协议的转译兼容性。
  • 版本适配差异：不同版本或不同平台的 Codex 客户端在 catalog 刷新和代理配置读取细节上可能略有差异，上述聚合机制与配置依据 CC Switch 官方文档整理，并非所有客户端版本均经过逐一验证。

更多关于聚合模式与配置持久化的细节，可以参考 CC Switch 官方文档：

5. 两个容易忽略的 Codex 模型参数

上下文窗口

复制其他模型的 catalog 配置时，不能只改模型名字。

特别是 Gemini，需要同步检查 context window。

如果 catalog 声明的上下文容量比真实模型小，Codex 可能提前压缩会话；如果声明得过大，则可能把超过实际上游能力的请求发出去。

原则很简单：

Codex catalog 描述的应该是真实上游模型的能力，而不是被复制模板的能力。

Reasoning Summary

之前遇到过一个问题：

text
模型正常工作
正文正常输出
但 Codex 看不到任何思考摘要

根因是 catalog 中：

json
"default_reasoning_summary": "none"

Codex 因此不会请求 reasoning summary。

改成：

json
"default_reasoning_summary": "detailed"

后，可以正常收到：

text
reasoning_summary_text.delta
output_text.delta

同时 config.toml 中保持：

toml
model_reasoning_effort = "high"

需要注意：

text
model_reasoning_effort
→ 控制 reasoning 强度

default_reasoning_summary
→ 控制是否返回可显示的 reasoning 摘要

这不是完整思维链，只是模型提供给客户端展示的 reasoning summary。

另外，default_reasoning_summary 目前不会随着 CC Switch 的 modelCatalog 完整持久化。CC Switch 重写 catalog 后，最好重新检查一次。

修改 catalog 后还需要重启 Codex，因为这个文件只在启动时读取。

6. 常用协议

CLIProxyAPI 当前主要使用：

text
POST /v1/messages
→ Anthropic Messages

POST /v1/chat/completions
→ OpenAI Chat Completions

POST /v1/responses
→ Codex / OpenAI Responses

GET /v1/models
→ 查询当前模型

对 Codex 来说，最重要的是：

text
POST /v1/responses

完整链路基本就是：

text
Codex
  ↓
CC Switch
  ↓
OpenAI Responses
  ↓
CLIProxyAPI
  ↓
Gemini / Claude / GPT / 其他上游

7. 出问题时怎么排查

我现在基本按照这个顺序判断：

text
1. CLIProxyAPI 的 8317 是否正常
        ↓
2. /v1/models 是否存在目标模型
        ↓
3. /v1/responses 能不能直接调用
        ↓
4. 检查 OAuth / 网络 / 上游账号
        ↓
5. 检查 CLIProxyAPI alias
        ↓
6. 检查 Codex catalog slug
        ↓
7. 最后再看 Codex / CC Switch UI

几个典型对应关系：

text
User location is not supported
→ 检查 Clash 出口地区

/v1/models 中模型消失
→ 检查 CLIProxyAPI Provider 配置

/model 有模型但不能调用
→ 检查 slug

模型能回答但没有 reasoning summary
→ 检查 default_reasoning_summary

长对话过早压缩
→ 检查 context window

8. 最终结构

目前整个环境可以概括为：

text
                    Codex
                      ↓
                 CC Switch
                127.0.0.1:15721
                      ↓
                 CLIProxyAPI
                127.0.0.1:8317
          ┌───────────┼───────────┐
          ↓           ↓           ↓
    Antigravity    OpenAI       其他兼容
       OAuth     Compatibility    上游
          ↓           ↓
   Gemini / Claude   GPT 等
          ↓
      Clash Verge
          ↓
   固定可用地区出口

真正需要记住的只有四层：

text
CC Switch
→ Codex Provider、Key 注入、model catalog

CLIProxyAPI
→ OAuth、模型路由、协议转换

Clash
→ 特定上游的网络出口

Codex catalog
→ 模型名称、上下文能力、reasoning 能力

需要指出的是，这里总结的四层拓扑对应的是我最初落地 Gemini 时的单向 Routing 实践。如果需要兼顾官方 Codex 模型的日常调用，建议参考前文介绍的 Aggregation 模式，将 CC Switch 配置为多 Provider 聚合层。

最后，不要把真实 API Key、OAuth 凭据或代理认证信息放进博客和 Git 仓库。

统一使用：

text
<LOCAL_API_KEY>
<UPSTREAM_API_KEY>
<OAUTH_CREDENTIAL>

作为占位符即可。

CC Switch + CLIProxyAPI + Codex：在 Codex 中使用 Gemini

/zh/blog/codex-gemini-cc-switch-cliproxyapi
作者
Feiya SHU
发布日期
更新日期
版权
© 2026 Feiya SHU · 保留所有权利