CC Switch 本地路由实战：让 Codex CLI 通过协议转换接入 Kimi（Chat Completions 转 Responses）

本文围绕 CC Switch 在 Codex 场景下的"本地路由"能力展开，以 OpenAI Chat Completions 兼容服务 Kimi 为例，讲清楚为什么 Codex CLI 无法直连 Kimi、CC Switch 如何在 127.0.0.1:15721 本地路由中完成 Responses ↔ Chat Completions 的双向协议转换，并给出从添加 Provider 到验证请求的完整操作步骤与常见问题排查方法。适用版本为 CC Switch 3.16.5 及前后版本；读完后你可以独立完成"用 CC Switch 让 Codex 跑在 Kimi 上"的全流程配置，并理解其底层转发链路。

为什么需要本地路由：两种 API 协议不兼容

新一代 Codex CLI 默认基于 OpenAI Responses API（/responses 端点）工作。而 Kimi 开放平台与 Kimi For Coding 实际暴露的接口都是 OpenAI Chat Completions 格式（/chat/completions）。这两种协议在请求体结构、流式（SSE）事件、响应结构上均不相同：如果直接把 Kimi 的 base URL 写进 Codex 配置，通常会出现两类问题：

• 请求打到 Kimi 不存在的 /responses 端点，返回 404；
• 即使请求碰巧成功，Codex 也无法正确解析 Chat 格式的流式响应。

另外一个背景是：Kimi For Coding 官方文档列出的受支持第三方工具是 Claude Code、Roo Code 这类 Anthropic 兼容的编码 Agent，并不包含 Codex。因此要在 Codex 里用 Kimi，中间必须有一层协议转换，这正是 CC Switch 本地路由要解决的问题。

CC Switch 的处理方式是：让 Codex 始终连接本地路由，并保持以 Responses API 形式发起请求。路由内部根据当前 Provider 的上游格式（meta.apiFormat）判断是否需要转换——若是 Chat 格式，则把请求改写为 Chat Completions 发给上游；收到上游响应后，再把 Chat 的 JSON 或 SSE 流转换回 Codex 能理解的 Responses 格式返回。

这条链路可以拆成 4 个步骤：

1. 开启 Codex 路由后，本地 ~/.codex/config.toml 的 base URL 被改写为 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 流转换为 Responses 的 JSON/SSE 返回给 Codex。

前置准备

开始前准备三样东西：

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

Kimi 的 API Key 有两个来源，对应 CC Switch 的两个内置预设（预设定义见 codexProviderPresets.ts）：

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

两类 Key 相互不通用（详见后文 FAQ）。两个预设都已内置官方依据的端点与模型，直接使用预设即可，无需手工拼接端点路径。

从预设源码还能看到一些对协议转换很重要的细节：

• 两个预设的 apiFormat 均为 "openai_chat"，这是路由判定"需要转换"的直接依据；
• 预设携带 modelCatalog：Kimi 预设含 kimi-k2.7-code（262144 上下文、单档 high 思考强度）与 kimi-k3（1048576 上下文、low/high/max 三档）；Kimi For Coding 预设含 kimi-for-coding、kimi-for-coding-highspeed、k3、k3-256k（后两者的默认思考强度显式声明为 high）；
• 预设声明了 codexChatReasoning：thinkingParam: "thinking"、effortParam: "reasoning_effort"、outputFormat: "reasoning_content"。这解释了转换层如何在 Chat 请求体里注入 Kimi 的思考开关与推理强度参数，并在响应中把 reasoning_content 还原为 Codex 的推理信息。

Step 1：添加 Codex Provider

打开 CC Switch，切换到顶部 Codex 标签页，点击右上角加号按钮添加 Provider。

根据你手上 Key 的类型，选择内置预设 Kimi（开放平台、按量计费）或 Kimi For Coding（会员订阅）。这一步只需要做两件事：

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

预设已经内置了 Kimi 的请求地址、默认模型、模型菜单以及 thinking/reasoning 参数，并且高级选项中的"上游格式"也已预设为 Chat Completions（需要路由）。你可以按需调整默认模型与模型展示名，例如开放平台预设默认是 kimi-k2.7-code，也可以按官方文档说明改成 kimi-k2.7-code-highspeed。协议转换完全交给路由层处理即可。

Step 2：开启本地路由，接管 Codex

进入设置的"路由"页面，展开"本地路由"，配置两个开关：

1. 打开"路由总开关"，启动本地服务，默认地址为 127.0.0.1:15721；
2. 在"路由启用"中把 Codex 打开。如果只想路由 Codex，Claude 和 Gemini 的开关保持关闭即可。

开启路由后，CC Switch 会把 Codex 的 live 配置指向本地路由，认证改用占位符管理：真实的 Kimi Key 保留在 CC Switch 的 Provider 配置中，由本地路由在转发时注入，因此 Codex 的 live 配置里不会暴露任何 Key。

这一步在源码中对应两个事实（可在 proxy.rs 中检索验证）：

• Codex live 配置被写入 base_url = "http://127.0.0.1:15721/v1"，同时调用 update_codex_toml_field 把 wire_api 固定为 responses（见 proxy.rs 的配置样例与 proxy.rs 的写入逻辑）；
• 路由服务按路径分发请求：/v1/responses、/v1/chat/completions 等路径都路由到 Codex 上游（见 proxy.rs 的分发注释）。

也就是说，无论上游是什么格式，Codex 侧永远以 Responses 协议和固定地址对话，差异全部由本地路由吸收。

Step 3：切换 Provider 并重启 Codex

回到 Codex Provider 列表，点击 Kimi Provider 的"启用"。如果看到"需要路由"提示，说明该 Provider 必须在路由运行状态下才能使用；若路由未启动，CC Switch 会给出"需要路由服务"的提示。

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

• Codex 进程可能仍在使用旧的 config.toml；
• model_catalog_json 生成后，/model 菜单的刷新通常需要新进程。

进入 Codex 后，用 /model 检查当前模型是否来自 Kimi 预设（例如 Kimi K2.7 Code 或 Kimi For Coding）。由于当前 Codex app 尚不支持多模型选择，会使用配置中的第一个模型作为默认模型。随后发一条小问题，验证以下两点：

• 路由面板中的请求计数增加；
• usage / 请求日志中出现了这条 Codex 请求。

底层实现：协议转换发生在哪些模块

结合源码可以进一步看清转换链路的关键位置：

• 请求路径改写与转发决策：forwarder.rs 中通过 codex_responses_to_chat 标志与 base_url_is_full_endpoint 判定（见 forwarder.rs）决定把 Codex 的 Responses 请求改写到上游的 /chat/completions；
• 请求体转换：transform_codex_chat.rs 提供 responses_to_chat_completions / responses_to_chat_completions_with_reasoning 函数，负责把 Responses 请求体映射为 Chat Completions 请求体，后者负责携带 thinking/reasoning 参数的注入；
• 流式响应转换：Chat 上游返回的 SSE 流由 streaming_codex_chat.rs 与 codex_responses_sse.rs 转回 Codex 期望的 Responses SSE 事件序列；
• 模型目录：CC Switch 会为 Codex 生成模型目录文件 cc-switch-model-catalog.json，并将其路径写入 Codex 配置的 model_catalog_json 字段，/model 菜单即来源于此。

从源码结构看，这套"路径改写 + 请求体转换 + 流式事件双向转换"的设计是通用的：任何 apiFormat = "openai_chat" 的 Codex Provider 都走同一条链路，Kimi 只是其中配置最完整的内置示例之一。

其他 Chat 格式 Provider 的做法

Kimi、DeepSeek、MiniMax、SiliconFlow 等通用 Chat 格式 Provider 在 CC Switch 中都有内置预设，优先使用预设。只有预设中没有的 Provider 才选择自定义配置：按对方文档填入 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 预设，先确认当前 Provider 确实来自预设、且 Codex 路由已启用。只有自定义 Provider 才需要额外检查 base URL——注意 base URL 是服务的根地址，不是带 /chat/completions 的完整端点路径。

/model 里看不到 Kimi 模型

保存 Provider 后重启 Codex。CC Switch 生成 cc-switch-model-catalog.json 并把路径写入 model_catalog_json，但运行中的 Codex 进程不一定会热加载模型目录。同时注意当前 Codex app 不支持多模型选择，配置中的第一个模型即默认模型。

开了路由，请求却发去了别的 Provider

核对三个状态是否一致：Codex 标签页的当前 Provider 是 Kimi；本地路由服务正在运行；"路由启用"中 Codex 开关为打开。

能否通过本地路由使用官方 OpenAI Codex 账号？

不建议。CC Switch 在路由启用期间会阻止切换到官方 Provider——通过代理访问官方 API 可能带来账号风险。路由的定位是服务第三方、聚合类服务与协议转换场景。

参考文档

• CC Switch 用户手册：添加 Provider
• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• Codex Chat 转换实现
• Kimi 预设定义
• 代理服务与 live 配置改写