CC Switch 本地路由实战：让 Codex CLI 无缝接入 Kimi Chat Completions 上游

本文以 CC Switch 官方指南 docs/guides/codex-kimi-routing-guide-en.md 为核心，讲解如何用本地路由（Local Routing）让使用 Responses API 的 Codex CLI 直接调用 Kimi（OpenAI Chat Completions 协议）上游：读完你将掌握两个 Kimi 预设的配置差异、127.0.0.1:15721 本地路由的启用与验证方法，以及协议转换层（Responses → Chat Completions → Responses）的底层实现原理与常见 401/404 故障排查手段。适用于 CC Switch 3.16.5 及邻近版本。

为什么 Codex 接 Kimi 需要本地路由

新一代 Codex CLI 目标端点是 OpenAI Responses API，而 Kimi 开放平台（Kimi Open Platform）与 Kimi For Coding 对外暴露的都是 OpenAI Chat Completions 形态的 /chat/completions 接口。两种协议的请求体、流式事件（SSE 事件类型）和响应结构都不同：如果把 Kimi 端点直接填进 Codex 配置，典型结果是 /responses 路径 404，或流式响应无法被 Codex 正确解析。

另一层背景是：Kimi For Coding 官方支持的第三方工具是 Claude Code、Roo Code 这类 Anthropic 兼容的编码代理，Codex 并不在列表内。要在 Codex 中使用 Kimi，必须有一个协议转换层——这正是 CC Switch Local Routing 的职责。

其核心思路是：Codex 始终认为自己在和 Responses API 说话。本地路由检测到当前激活的上游是 Chat 格式后，先把请求改写为 Chat Completions 转发给 Kimi，再把 Kimi 的 Chat JSON/SSE 响应转回 Responses JSON/SSE 回传给 Codex。

完整链路包含四步：

1. 开启 Codex 路由后，本地配置被写为 base_url = "http://127.0.0.1:15721/v1"，同时保留 wire_api = "responses" 不变；
2. 供应商配置中的 meta.apiFormat = "openai_chat" 告知路由层真实上游是 Chat Completions；
3. 路由把 /responses 或 /v1/responses 改写为 /chat/completions，并把 Responses 请求体转换为 Chat 请求体；
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 流转回 Responses JSON/SSE。

从源码看，这条链路可以逐一对应到实现代码：

• 端点改写发生在代理转发层，目标路径固定为 /chat/completions（参见 forwarder.rs 中 let target_path = "/chat/completions" 及同文件内对 base_url 是否已是完整端点的判断逻辑）；
• 默认监听端口 15721 是数据库 schema 的默认值（参见 schema.rs 中 listen_port INTEGER NOT NULL DEFAULT 15721）；
• 启用路由后写入 Codex 的 config.toml 正是 base_url = "http://127.0.0.1:15721/v1"，仓库中大量测试围绕这一投影行为展开（参见 services/proxy.rs 等测试断言）。

前置准备

开始之前准备三样东西：

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

Kimi 的 Key 来自两个不同渠道，对应 CC Switch 内两个不同的内置预设：

预设	Key 来源	Base URL	默认模型
Kimi	Kimi 开放平台（platform.kimi.com），按 token 计费的 API Key	https://api.moonshot.cn/v1	kimi-k2.7-code
Kimi For Coding	Kimi Code 会员权益生成的专属 Key（kimi.com/code）	https://api.kimi.com/coding/v1	kimi-for-coding

这两个预设已经包含正确的端点与模型细节，优先使用预设，不要手工拼装端点路径。在 codexProviderPresets.ts 中可以看到 Kimi 预设的定义：apiFormat: "openai_chat"、endpointCandidates: ["https://api.moonshot.cn/v1"]，并声明了 kimi-k2.7-code（262144 上下文，推理档位 high）与 kimi-k3（1048576 上下文，档位 low/high/max）的模型目录；Kimi For Coding 预设 则额外开启了 promptCacheRouting: "enabled"（会话级 prompt-cache 路由），模型目录包含 kimi-for-coding、kimi-for-coding-highspeed、k3、k3-256k。

第一步：添加 Codex 供应商

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

根据你持有的 Key 类型，选择内置的 Kimi 预设（开放平台、按量计费）或 Kimi For Coding 预设（会员订阅）。实际操作只需要两件事：

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

预设已包含 Kimi 的请求 base URL、默认模型、模型菜单、thinking/reasoning 参数，并在 Advanced Options 下把 Upstream Format 预设为 Chat Completions (routing required)。如需调整，可修改默认模型或模型显示名——例如开放平台预设默认 kimi-k2.7-code，可按官方文档切换为 kimi-k2.7-code-highspeed。协议转换由路由层负责，无需你关心。

预设还封装了 reasoning 参数的注入方式，这在 codexProviderPresets.ts 中显式声明：supportsThinking: true、supportsEffort: true、thinkingParam: "thinking"、effortParam: "reasoning_effort"、outputFormat: "reasoning_content"。也就是说，路由层会把 Codex 的推理意图翻译成 Kimi 上游可识别的 thinking 开关与 reasoning_effort 字符串，并把上游返回的思考内容从 reasoning_content 字段解析回来。

保存时，供应商写入 ~/.codex/config.toml 的内容由 generateThirdPartyConfig 生成，模板形如：

model_provider = "custom"
model = "kimi-k2.7-code"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "kimi"
base_url = "https://api.moonshot.cn/v1"
wire_api = "responses"
requires_openai_auth = true

注意 wire_api = "responses" 始终保留——Codex 侧永远按 Responses 协议对话，apiFormat: "openai_chat" 只是给路由层看的元数据。

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

进入设置中的 Routing 页，展开 Local Routing，完成两个开关：

1. 打开路由主开关，启动本地服务，默认地址 127.0.0.1:15721；
2. 打开 Routing Enabled 下的 Codex。如果只想让 Codex 走本地路由，Claude 和 Gemini 可以保持关闭。

路由启用后，CC Switch 会把 Codex 的生效配置指向本地路由，并用占位符管理认证：真正的 Kimi Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发请求时注入，因此你不需要在 Codex 的生效配置中暴露密钥。

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

回到 Codex 供应商列表，点击 Kimi 供应商的 Enable。如果看到 Needs Routing 标记（前端文案见 ProviderCard.tsx 与 en.json 中的 "needsRouting": "Needs Routing"），说明该供应商必须在路由运行时使用；路由未启动时，CC Switch 会弹出提示说明需要启动路由服务。

切换后重启当前 Codex 终端会话，原因有二：

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

模型目录由后端生成固定文件 cc-switch-model-catalog.json 并写入 config.toml 的 model_catalog_json 字段（文件名常量见 codex_config.rs）。注意仓库实现中对 model_catalog_json 路径有严格校验：只接受指向配置目录内文件的指针，防止用户目录外的符号链接路径通过检查。

进入 Codex 后用 /model 确认当前模型来自 Kimi 预设，例如 Kimi K2.7 Code 或 Kimi For Coding。目前 Codex 应用不支持多模型选择，默认使用第一个配置的模型。然后发送一条简短测试消息，确认路由面板中请求数增加，或使用/请求日志中出现对应的 Codex 请求。

其他 Chat 格式供应商的处理方式

Kimi、DeepSeek、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 中都已有预设，优先使用预设。只有预设未覆盖的供应商才选择自定义配置：按供应商文档填写 API key、base URL 和模型，并把 Advanced Options 下的 Upstream Format 设为 Chat Completions (routing required)。

如果上游供应商原生支持 OpenAI Responses API（如 codexProviderPresets.ts 中 apiFormat: "openai_responses" 的聚合商用例），则把 Upstream Format 设为 Responses，CC Switch 将直接走 Responses 协议直连，不做 Chat 转换。

常见问题（FAQ）

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：base URL 应是服务根地址，不要带 /chat/completions 完整端点路径（转发层会自行拼接端点）。

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

路由已开启，但请求仍打到错误供应商 确认三个状态一致：Codex 标签页下当前供应商是 Kimi；本地路由服务在运行；Routing Enabled 下 Codex 开关已打开。

能否通过本地路由使用官方 OpenAI Codex 账号？ 不推荐。CC Switch 在本地路由接管期间会阻止切换到官方供应商，因为经由代理访问官方 API 可能带来账号风险（源码中对应 apply_codex_official_proxy_route 一类官方代理路由逻辑，见 codex_config.rs 的测试）。路由主要面向第三方、聚合器与协议转换场景。

参考资料

• CC Switch 用户手册：Add Provider
• CC Switch 用户手册：Proxy Service
• CC Switch 用户手册：App Routing
• Codex-Kimi 路由指南（中文）
• 核心实现：src-tauri/src/proxy/forwarder.rs、src-tauri/src/codex_config.rs、src/config/codexProviderPresets.ts

Kimi 侧的配套文档（开放平台接入指南、Kimi Code 第三方工具接入说明）可在 Kimi 官方站点检索，本文不再列出外部链接；本文所有端点、模型名与参数均以当前仓库内预设定义为准，若上游模型目录有更新，以仓库中 codexProviderPresets.ts 的最新内容为准。