让 Codex 桌面版流畅调用国内大模型：codex-cn-bridge 实战配置指南

让 Codex 桌面版流畅调用国内大模型：codex-cn-bridge 实战配置指南

一句话总结：Codex 默认调用 OpenAI 的 Responses API，国内大部分代理网关只支持 Chat Completions API，两者协议不兼容导致 405 报错。codex-cn-bridge作为本地协议转换桥，完美解决这个问题。

一、问题背景

最近我在 macOS 上安装了 OpenAI 的Codex 桌面版，想通过CC Switch接入国内大模型，但一启动就报错：

unexpected status 405 Method Not Allowed: {"detail":"Method Not Allowed"}, url: https://your-gateway.example.com/api/responses

这个错误看起来很迷惑——URL 能通，HTTP 状态码是 405，说明服务器收到了请求，但拒绝了这个 HTTP 方法。明明我配置了OPENAI_BASE_URL，为什么还不行？

二、根因分析：Responses API vs Chat Completions API

2.1 Codex 的协议选择

OpenAI Codex（包括桌面版和 CLI）底层调用的是Responses API，端点为：

POST /v1/responses

这是一个 OpenAI 专有的有状态协议，支持：

• computer-use-preview模型的工具调用
• 特定的 reasoning 输出格式
• previous_response_id会话续传

2.2 国内代理的现实

国内绝大多数代理网关（One API、New API、各类中转服务）只实现了标准的Chat Completions API：

POST /v1/chat/completions

当 Codex 把POST请求发到/api/responses时，服务器回应405 Method Not Allowed——因为它根本没实现这个端点。

这就是矛盾的本质：Codex 说的是 “Responses” 方言，国内网关只懂 “Chat Completions” 普通话。

三、解决方案：codex-cn-bridge

3.1 工具介绍

codex-cn-bridge（GitHub:git-liu835/codex-cn-bridge）是一个开源的本地代理工具，核心功能：

将 OpenAI Responses API 翻译为 Chat Completions API，让 Codex CLI、桌面版、VS Code 插件都能无缝接入国内大模型。

3.2 支持的主流模型

3.3 架构示意图

┌─────────────────┐ Responses API ┌──────────────────────┐ Chat Completions API ┌──────────────┐ │ Codex 桌面版 │ ────────────────────→ │ codex-cn-bridge │ ────────────────────────────→ │ 国内代理网关 │ │ (以为在调OpenAI) │ POST /v1/responses │ (localhost:8765) │ POST /v1/chat/completions │ (中转服务) │ └─────────────────┘ └──────────────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ 国产大模型 │ └──────────────┘

四、安装步骤（macOS）

4.1 下载安装包

从 GitHub Releases 下载最新版本：

curl-L-o/tmp/code-cn-bridge.dmg\"https://github.com/git-liu835/codex-cn-bridge/releases/latest/download/code-CN-Bridge-latest.dmg"

⚠️ 注意：仓库名是codex-cn-bridge，但早期 release 文件名可能含code-CN-Bridge（带空格），以实际 release 页面为准。

4.2 挂载并安装

# 挂载 DMGhdiutil attach /tmp/code-cn-bridge.dmg-nobrowse# 复制到 Applications（具体卷名以实际挂载为准）cp-R"/Volumes/code CN Bridge*/code CN Bridge.app"/Applications/# 卸载 DMGhdiutil detach"/Volumes/code CN Bridge*"# 清理临时文件rm-f/tmp/code-cn-bridge.dmg

4.3 启动应用

open-a"code CN Bridge"

启动后，代理服务会自动在后台运行，默认监听http://127.0.0.1:8765。

五、配置步骤

5.1 配置 codex-cn-bridge

打开 codex-cn-bridge 桌面应用，进入「模型配置」页面：

1. 添加 Provider

   • Provider 名称：自定义（如my-provider）
   • Adapter：根据实际模型选择（如kimi、deepseek、qwen等）
   • Base URL：https://your-gateway.example.com/api/v1（你的代理网关地址）
   • API Key：填入网关的 API Key

2. 添加模型映射

   • Alias（别名）：自定义一个模型别名（如my-model-alias）
   • Target：填写网关侧实际配置的模型名称（如xxx-xxx-code）
   • Provider：选择刚才创建的 Provider
   • 可选：开启enable_thinking和thinking_budget

配置会自动保存到~/.code-cn-bridge.yaml。

5.2 配置 Codex 桌面版

打开 Codex 桌面应用，进入设置/API 配置：

关键点：Codex 不再直接连 CC Switch，而是连本地的 bridge。bridge 负责把请求翻译后再转发给 CC Switch。

六、验证与排错

6.1 检查代理是否运行

lsof-i:8765

看到code-cn-bridge在监听，说明代理正常。

6.2 查看日志

codex-cn-bridge 桌面应用内有「监控日志」页面，可以实时看到：

• 请求/响应状态码
• 耗时
• 错误高亮
• 调试模式下可查看完整请求体和响应体

6.3 常见问题

Q1：Codex 还是报 405？

确认 Codex 的 Base URL 是http://127.0.0.1:8765/v1，不是直接指向 CC Switch。

Q2：模型返回空输出？

检查model_mapping里的target是否和 CC Switch 里配置的模型名一致。比如 CC Switch 里叫kimi-k2.7-code，target 就不能写成kimi-k2.6。

Q3：工具调用报错 400？

这是 Responses API 和 Chat Completions API 的消息格式差异导致的。codex-cn-bridge 最新版（v0.3.2+）已修复dangling tool_calls问题，保持更新即可。

Q4：代理网关和其他 Agent 会受影响吗？

不会。codex-cn-bridge 只监听本地127.0.0.1:8765，其他 Agent 仍然直接访问原网关地址，两者完全独立共存。

七、高级配置

7.1 多 Key 轮换

在 Provider 配置里支持填写多个 API Key（逗号分隔），bridge 会在流式重试时自动切换，避免单 Key 限流：

api_key:"sk-xxx,sk-yyy,sk-zzz"

7.2 模型别名映射

Codex 默认请求gpt-5-code、gpt-5-code-light等模型名，可以通过model_mapping映射到任意国产模型：

model_mapping:"gpt-5-code":target:"你的模型名"provider:my-provider"gpt-5.5":target:"另一个模型名"provider:another-provider

7.3 熔断保护

v0.3.22 新增了 provider 级熔断器：连续 3 次失败 → 断开 30 秒 → 半开探测，避免上游异常时长时间挂起。

八、总结

codex-cn-bridge是目前让 Codex 接入国内模型的最省心方案：

• 有桌面 GUI，不用手写 YAML
• 开箱即用，支持自动更新
• 兼容 Codex CLI、桌面版、VS Code 插件

如果你也遇到类似问题，推荐一试。

参考链接

• codex-cn-bridge GitHub 仓库
• OpenAI Codex 官方文档
• OpenAI Responses API

本文基于 codex-cn-bridge v0.3.22 和 Codex 桌面版实测整理，具体模型和网关信息已脱敏处理。