ContextQMD
Back to Cc Switch

在 Codex 中用 Kimi：CC Switch 本地路由攻略

docs/guides/codex-kimi-routing-guide-zh.md

3.17.07.7 KB
Original Source

在 Codex 中用 Kimi：CC Switch 本地路由攻略

适用版本：CC Switch 3.16.5 及附近版本。本文根据仓库内文档与代码整理，并用 Kimi 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。

为什么需要本地路由

新版 Codex CLI 面向的是 OpenAI Responses API，而 Kimi 开放平台和 Kimi For Coding 实际暴露的都是 OpenAI Chat Completions 形态，也就是 /chat/completions。这两种协议的请求体、流式事件和返回结构不同，直接把 Kimi 的接口地址填进 Codex 配置里，常见结果就是请求 /responses 返回 404，或者流式响应无法被 Codex 正确解析。

Kimi For Coding 官方目前支持的第三方工具是 Claude Code、Roo Code 这类兼容 Anthropic 协议的编程 Agent，并没有覆盖 Codex。所以想在 Codex 里用 Kimi，需要一层协议转换——这正是 CC Switch 本地路由做的事。

CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。

这条链路主要分成四步：

  1. Codex 接管时，本地配置会被写成 http://127.0.0.1:15721/v1，并强制保持 wire_api = "responses"。
  2. Provider 的 meta.apiFormat = "openai_chat" 会告诉路由：真实上游是 Chat Completions。
  3. 路由把 /responses 或 /v1/responses 改写到 /chat/completions，并把 Responses 请求体转换成 Chat 请求体。
  4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。

准备工作

你需要先准备好三样东西：

  • 已安装并能启动的 CC Switch。
  • 已安装 Codex CLI，并至少运行过一次，让 ~/.codex/config.toml 目录结构存在。
  • 一个 Kimi API Key。

Kimi 的 API Key 有两个来源，对应 CC Switch 里两个不同的内置预设：

  • Kimi 开放平台（platform.kimi.com）：按 token 用量计费的 API Key，对应预设 Kimi，OpenAI 兼容 base URL 是 https://api.moonshot.cn/v1，默认模型 kimi-k2.7-code。
  • Kimi For Coding（kimi.com/code）：Kimi 会员 Kimi Code 权益生成的专用 Key，对应预设 Kimi For Coding，base URL 是 https://api.kimi.com/coding/v1，模型统一为 kimi-for-coding。

两个预设都已经按官方信息配好接口地址和模型，请优先使用预设，不需要手动拼接口路径。

第一步：添加 Codex 供应商

打开 CC Switch，切到顶部的 Codex 标签，点击右上角的加号添加供应商。

按你手里 Key 的类型，在内置预设里选择 Kimi（开放平台按量计费）或 Kimi For Coding（会员订阅），然后只需要做两件事：

  • 填入对应的 Kimi API Key。
  • 保存供应商。

预设已经内置 Kimi 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并把 高级选项 里的 上游格式 预设为 Chat Completions（需开启路由）。你可以按需调整默认模型或模型显示名——例如开放平台预设默认是 kimi-k2.7-code，也可以按官方文档换成 kimi-k2.7-code-highspeed；协议转换交给路由层完成即可。

第二步：开启本地路由并接管 Codex

进入设置里的 路由 页面，展开 本地路由，完成两个开关：

  1. 打开 路由总开关，启动本地服务。默认地址是 127.0.0.1:15721。
  2. 在 路由启用 中打开 Codex。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。

接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 Kimi Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。

第三步：切换供应商并重启 Codex

回到 Codex 供应商列表，点击 Kimi 供应商的 启用。如果看到 需要路由 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。

切换后建议重启当前 Codex 终端会话。原因是：

  • Codex 进程可能已经读取过旧的 config.toml。
  • model_catalog_json 生成后，/model 菜单通常需要新进程才能刷新。

进入 Codex 后，可以用 /model 查看当前模型是否来自 Kimi 预设，例如 Kimi K2.7 Code 或 Kimi For Coding。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。

其它 Chat 供应商怎么处理

Kimi、DeepSeek、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 高级选项 里的 上游格式 选为 Chat Completions（需开启路由）。

如果上游直接支持 OpenAI Responses API，把 上游格式 选为 Responses 即可；这时 CC Switch 按 Responses 直连，不做 Chat 转换。

常见问题

Codex 报 404 或找不到 /responses

通常是没有开启 Codex 接管，或者你手动把 Kimi 的 Chat base URL 直接写给了 Codex——Kimi 上游没有 /responses 端点，这样一定会 404。检查 ~/.codex/config.toml 是否指向 http://127.0.0.1:15721/v1。

Kimi 上游报 401 或 403

先确认 Key 和预设是否匹配：开放平台的 Key 只能配 Kimi 预设，Kimi Code 会员权益的 Key 只能配 Kimi For Coding 预设，两套 Key 不能混用。

Kimi 上游报 404

如果用的是内置 Kimi 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 /chat/completions 的完整接口路径。

/model 看不到 Kimi 模型

保存供应商后重启 Codex。CC Switch 会生成 cc-switch-model-catalog.json 并把路径写入 model_catalog_json，但正在运行的 Codex 进程不一定会热加载模型目录。 目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。

开了路由但请求仍走错供应商

确认三处状态一致：Codex 标签下当前供应商是 Kimi；本地路由服务正在运行；路由启用 里 Codex 开关已打开。

可以用官方 OpenAI Codex 账号走本地路由吗

不建议。CC Switch 会在本地路由接管模式下阻止切到官方供应商，因为用代理访问官方 API 可能带来账号风险。路由主要用于第三方、聚合或协议转换场景。

参考链接