在 Codex CLI 里配置 Kimi K3：CC Switch 路由完整步骤
数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。
这件事的关键点不在”填个 Base URL”，而在协议：Kimi 官方文档写明 Codex CLI 使用 Responses API，而 Kimi 开放平台提供的是 OpenAI 兼容的 Chat Completions API。所以官方给出的接入路径并不是让 Codex 直连 Kimi，而是中间放一个 CC Switch，由它的本地路由负责转换请求和流式响应。这个设计带来一个必须记住的后果——官方原文说的是，使用 Kimi Provider 时必须保持 CC Switch 和 Codex 路由处于运行状态。也就是说 CC Switch 不是装完就能关掉的配置器，它是链路上一直在跑的一环。关掉它，Codex 这边就断了。
先搞清楚为什么要多一个中间件
很多人第一反应是：既然 Kimi 提供 OpenAI 兼容接口，那 Codex 不也是 OpenAI 家的工具吗，直接指过去不就完了？
问题就出在”OpenAI 兼容”兼容的是哪一套接口。Kimi 官方文档在这份 Codex 指南里说得很直白，Codex CLI 用的是 Responses API，Kimi 开放平台提供的是 Chat Completions。这是两套不同形态的接口，请求体结构和流式返回的组织方式都不一样，中间需要有人做翻译。CC Switch 的本地路由干的就是这件事。
关于 CC Switch 本身，官方文档专门加了一段提示，原话的意思是：CC Switch 是第三方开源工具，不属于 Kimi 开放平台；使用前请根据所在组织的安全与合规要求进行评估，API Key 以及 Codex 的请求和响应将由其本地路由处理。
这段话值得单独读两遍。它说明的是数据流向——你的密钥和全部对话内容都会经过这个第三方进程。个人开发者可能觉得无所谓，但如果你是在公司项目目录里跑 Codex，代码片段会随着请求一起走这条链路。这类判断没法替你做，它属于组织的合规范畴。密钥本身怎么存放、怎么轮换，可以参考API Key 安全管理的通用做法。
准备工作：三件事，缺一件后面都会卡住
官方列出的准备工作是三条，安装和账号相关的操作它明确说按对应官方指引完成、不在那篇里展开：
- 安装 Codex CLI，并且至少启动一次。官方特意写了”至少启动一次”这个要求，照做就行。
- 在 Kimi 开放平台创建并保存 API Key。
- 按 CC Switch 官方指引下载安装适合当前操作系统的版本。
三件都做完，再打开 CC Switch 开始配置。顺序反过来做（比如 Codex 一次没启动过就先去 CC Switch 里配），官方文档没有说明会发生什么，不必自己试着找规律。
第一步：把 Codex 路由打开
在 CC Switch 里进入「设置 > 路由」，做两个动作：
- 开启路由总开关，启动本地路由服务；
- 在路由启用区域里，把 Codex 这一项打开。
这是两个层级的开关：总开关管的是本地路由服务跑不跑，路由启用区域管的是具体给哪个客户端提供转换。两个都得开，只开一个不算配好。
第二步：添加 Kimi Provider
回到 CC Switch 主界面，选顶部的 Codex Tab，点右上角的 + 添加供应商，确认当前位于「Codex 供应商」页面，然后在预设供应商列表里选 Kimi。
基础配置三栏：
- API 请求地址（Base URL）：官方给的是
https://api.moonshot.cn/v1 - API Key：填你在 Kimi 开放平台创建的那个
- 默认模型：
kimi-k3
官方在这里加了一个容易漏的动作——把默认模型改成 kimi-k3 之后，要点加入映射。不点这一下，模型映射关系不会建立。
然后向下滚动，确认高级配置那一组。官方给出的取值是：上游格式选 Chat Completions（需开启路由），提示词缓存路由选自动（推荐），支持思考模式开启，支持推理强度开启，菜单显示名和实际请求模型都填 kimi-k3，上下文窗口填 1048576——这是官方配置表里给的结构性参数，以官方文档当前版本为准。确认无误后点右下角添加。
这几栏高级配置，官方说了什么、没说什么
照抄取值能配通，但有几栏的名字容易让人自行脑补含义。这里把官方写明的和没写的分开摆一遍，出问题时才知道该往哪一侧查。
上游格式选 Chat Completions，正是前面那个协议差异的落点。官方给的取值原文就写着”Chat Completions（需开启路由）“，括号里这句提示和第一步那两个开关是呼应的；至于路由内部具体怎么把 Responses API 的请求译成 Chat Completions，官方在这份指南里没有展开。
支持推理强度这一栏，官方配置表只给了”开启”这个取值，没有说明这个第三方工具的开关与 Kimi API 字段之间是什么对应关系，这里也就不替它解释。能确定的是 Kimi 侧的机制：按官方推理强度文档，Kimi K3 用请求顶层的 reasoning_effort 字段调节推理深度，取值是 low、high、max 三档，默认档以官方文档当前版本为准。文档里还有一条迁移细节值得单独记：从 K2.x 迁移到 K3 时要移除 K2.x 的 thinking 配置，改为按需使用顶层的 reasoning_effort。如果你之前手写过 Kimi 的请求体，旧配置留着可能是隐患。同一页还写明，K3 的多轮对话和工具调用必须把 API 返回的完整 assistant message 原样回传到 messages，包括 reasoning_content 和 tool_calls——这条约束在你自己拼请求体的时候必须照做。
提示词缓存路由这一栏，官方在这份 Codex 指南里只给了推荐取值「自动」，没有展开说明它具体做了什么，所以这里不替它解释。需要注意的是别把它和 Kimi 侧的缓存机制混为一谈：按 Kimi 的上下文缓存文档，Context Caching 对所有请求自动生效，无需修改 API 调用方式、无需手动创建、无需引用缓存 ID、无需管理 TTL，系统会自动识别并缓存高频使用的初始上下文。它还有一个前缀缓存的前提——官方给了一个 prompt tokens 的下限门槛，前一个请求低于该门槛时不会被缓存而是被丢弃，具体数值以官方文档为准。官方给出的命中条件是让知识内容、system prompt 和工具定义保持相对稳定；反过来说，频繁改动系统提示或工具集就会不利于命中。缓存到底怎么算钱，是跨厂商缓存计费机制这类话题，别在 CC Switch 这一层猜。
第三步和第四步：启用，然后必须重启 Codex
添加完回到 Codex 供应商列表，在刚添加的 Kimi Provider 上点启用。启用后官方要求确认三件事：Kimi 是 Codex Tab 中当前启用的 Provider、CC Switch 的本地路由正在运行、Codex 路由开关处于开启状态。
接着是单独的第四步：如果 Codex CLI 已经在运行，先退出当前会话，然后进入需要使用的项目目录重新启动 codex。官方给出的理由是，重新启动是为了让 Codex CLI 加载 CC Switch 写入的最新 Provider 和模型配置。值得注意的是官方把它单列成了完整的第四步，而不是塞进上一步的一句提示里——按文档的组织方式，这是流程的必经环节，不是可选动作。
验证方式官方也给了，是三层递进的：启动后先确认 Codex CLI 顶部显示的模型是 kimi-k3；然后发一个最简单的请求，比如 hello；如果正常返回结果、并且底部状态栏显示 kimi-k3，说明配置已经生效。还有第四层佐证——去看 CC Switch 的路由请求数或请求日志，确认里面出现了新的 Codex 请求。
这一层佐证很实用。因为界面显示模型名只能说明客户端认为自己在用 Kimi，而路由日志里出现新请求，才说明流量真的从这条链路走了。
配完报错，按错误码往回倒推
Kimi 官方错误说明页把状态码按 error type 分得比较细。下面挑出来的这几类，都跟前面几步的配置动作直接相关，值得对着自己填过的字段回看一遍：
401 认证错误。 官方列了两个 error type：invalid_authentication_error，对应 API Key 无效或格式错误；incorrect_api_key_error，对应未提供 Key 或 Key 填错。这里有一条特别容易踩的说明——官方写明 platform.kimi.com（中国站）与 platform.kimi.ai（国际站）的账户、余额和 API Key 完全独立，混用会返回 401，要确认调用端点与 Key 所属平台一致。也就是说，Key 是在哪个平台建的，就得配对应平台的端点，两边不通用。至于 Codex 指南里那个 Base URL 具体归属哪一侧，官方这两处文档没有写在一起，按错误页的要求核对端点与 Key 归属即可。更细的排查顺序可以对照401 和 403 的通用排查思路。
403 权限错误。 permission_denied_error 有几种典型 message，其中一种是调用 IP 不在组织白名单内，官方标注这在国际站比较常见，处理办法是联系管理员添加 IP。
404 资源不存在。 resource_not_found_error 的含义是模型不存在，或者当前账号无权限访问该模型，官方给的检查方向是 model 参数拼写以及账号 tier。对着 CC Switch 排查时，先回去看”实际请求模型”那一栏填的是不是 kimi-k3，再看有没有漏点”加入映射”。
429 要分清是哪一种。 官方在 429 底下列了三类 error type，处理方式完全不同：engine_overloaded_error 是服务节点负载较高，官方明确说这个错误由服务端容量导致，充值或提升 Tier 不能直接消除，正确做法是按 Retry-After 提示等待、降低并发并使用指数退避重试；exceeded_current_quota_error 对应账户欠费停用或 token 额度不足；rate_limit_reached_error 则是触发了组织级的并发、RPM、TPM 或 TPD 限制，官方对这四种分别给了降低并发、按提示等待、降低频率或升级 tier、次日恢复的处理方向。官方在 engine_overloaded_error 的处理说明里专门补了一句”充值或提升 Tier 不能直接消除”——把这句话写进文档，本身就是在提醒别把服务端过载当额度不足去处理。官方的排障建议也是同一个顺序：收到 429 先按 error.type 分辨原因，再决定是退避、降并发还是充值。退避怎么写才不至于雪上加霜，参考429 的通用处理方式。
顺带说清楚一个视频输入的边界
官方在这份 Codex 指南开头就澄清了一件事，因为它很容易被误会成模型不行：Codex CLI 目前支持文本和图片输入，但尚未提供原生视频输入通道，无法把视频文件直接作为多模态输入提交给模型。如果只用 Codex CLI 现有的输入方式分析视频，官方给的办法是先用 ffmpeg 提取关键帧，需要时再结合音频转写后交给模型。
官方紧接着强调，这是 Codex CLI 输入层的限制，并非 Kimi K3 模型的能力限制——Kimi K3 API 原生支持视频输入，按视觉输入的方式直接调用 kimi-k3 就能进行完整的视频理解，不需要手动抽帧。Kimi 的视觉输入文档也印证了这一点，那份文档里明确列出了能够理解视频内容的模型，kimi-k3 在其中。
所以真要做视频相关的活，路径应该是绕开 Codex CLI 直接调 API，而不是在 Codex 里想办法。
最后：这条链路上的三处硬约束
第一，别把 CC Switch 当一次性配置器。官方原文的要求是使用 Kimi Provider 时必须保持 CC Switch 和 Codex 路由处于运行状态，它是常驻在链路上的转换层，关掉进程或停掉路由，这条链路就断了。
第二，改完配置不重启 Codex CLI。官方把”退出当前会话、进项目目录重启”写成了独立的第四步，并写明理由是让 Codex CLI 加载 CC Switch 写入的最新配置。
第三，验证只看界面显示的模型名。模型名显示对了只能说明客户端读到了配置，去 CC Switch 看一眼路由请求数有没有涨，才是真的确认流量走通了。
配通之后，成本这条线要另外拉一遍。这条链路上没有任何一环会替你控制用量：CC Switch 只做协议转换，Codex 那边发多少请求就走多少。Kimi 官方文档里与成本直接相关的机制有两条——Context Caching 的自动命中条件，以及 429 里 exceeded_current_quota_error 对应的余额与额度检查，前者决定重复上下文能不能少算钱，后者是账户见底时的信号。具体单价与缓存的计费方式，官方都指向定价页面的计费说明，本文不列数字。