Codex CLI 接入 Kimi K3 实战：兼容层配置与502排错指南

把 Codex CLI 接到 Kimi K3，听起来是件小事，实际上一路踩下来全是坑。尤其是当你看到unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses这种报错的时候，会忍不住怀疑人生。这篇文章我就把这套“Responses 兼容层”从原理到配置再到排错，一次性讲清楚。不管你是刚下载完 Codex 装不上、登录不了，还是配好了但请求一直 502，或者被model not supported、auth token is unavailable这类问题卡住，这篇文章的目标就是让你照着我走过的路线，少踩几个坑，尽快把 Kimi K3 跑起来。

先说清楚它是什么、能做什么：Codex 是 OpenAI 那边主推的编程智能体入口，而 Kimi K3 是 Kimi 这边比较新的模型，普通人不会直接把它俩放在一起。但因为 Codex 只认自己的一套接口格式，Kimi 的开放接口又不完全长那样，所以中间需要加一层“兼容层”，把请求翻译成两边都能听懂的话。这套方案适合三类人：想用 Kimi K3 跑 Codex 任务的开发者、在研究怎么把第三方模型接进 Codex 的玩家，以及正在被各种报错折磨的排错困难户。接下来我会从架构、选型、配置、排错四个维度一步步展开。

1. 整体架构拆解：Codex、Kimi K3 与那层“兼容层”到底是什么

1.1 Codex 的接口形态：为什么大家都在谈 /responses

Codex 的接口演进其实挺折腾人的。早期大家接第三方模型，习惯用 OpenAI 风格的/v1/chat/completions，也就是 Chat Completions 协议，很多云厂商的兼容接口都长这样。但 Codex 从某一版开始，主推的是/v1/responses这个新的 Responses API。它跟旧的 Chat Completions 不完全是一回事，多了一些用于智能体循环的结构、指令追踪字段，消息格式也更面向“多轮工具调用”的场景。

这就带来一个很现实的问题：Codex 发出的是POST http://127.0.0.1:15721/v1/responses这种请求，而 Kimi 的 API 端点大概率只实现了/chat/completions。两边协议对不上，你就算把base_url指过去，它也会直接拒绝或者瞎解析。所以社区里的普遍做法是，在 Codex 和 Kimi 之间塞一层“翻译官”，接收 Codex 的 Responses 请求，转换成 Kimi 能理解的格式，再原路返回。这也是“Responses 兼容层”这个名字的由来。

1.2 Kimi K3 的接入难点：协议之外还有鉴权和模型名

Kimi K3 本身是个人模型，接口能力和普通 OpenAI 兼容服务比，少了一块 /responses 支持。另一个麻烦点是模型名。Codex 在配置自定义 provider 时，通常会有一个默认模型名，比如gpt-5.6-sol这种，如果你不去改，直接发给 Kimi，Kimi 肯定会回一句“这个模型我不认识”。这就是热词里那句the 'gpt-5.6-sol' model is not supported when using codex with a...的来历。它不是 Kimi 拒绝你这个人，而是你拿着张三的身份证去李四的窗口办事，人家不认。

所以接入 Kimi K3，至少得解决三件事：一是把 Codex 的请求地址指到兼容层；二是把模型名改成 Kimi K3 这边真正能认的那个名字，比如kimi-k3之类；三是把 Kimi 的 API Key 送到兼容层，由它统一加上鉴权头，再转发到 Kimi 上游。

1.3 一句话理解这个项目的整体链路

整个链路其实只有四段：Codex CLI → 本地兼容层服务（监听 127.0.0.1:15721）→ Kimi API → Kimi K3 模型。Codex 只跟本地兼容层说话，兼容层负责把/responses翻译成/chat/completions，Kimi 只管接收已经翻译好的请求。理解这条链路之后，排错就简单了：任何一环节出问题，都会在 Codex 的报错里体现成不同样子的错误。

我之前碰到过有人直接把 Codex 的base_url填成 Kimi 官方地址，然后怎么调都不通。看了日志才发现 Kimi 返回的是 404，因为路径/v1/responses压根不存在。加了兼容层之后，路径对了，模型名又不对；模型名对了，Key 又没带对。说白了，这层“翻译”不是可选项，而是刚需。

2. 环境准备与前置条件：账号、会员、Codex 本体和兼容层选型

2.1 Kimi 账号与 K3 访问权限

先说账号问题。Kimi K3 并不是所有账号默认都能调用，很多人问“kimi 哪个会员能用 k3”，这个问题其实没有一个万能答案，因为模型开放策略一直在变。最稳妥的做法是登录 Kimi 的开放平台或对应控制台，打开模型列表，看里面有没有 K3 相关的模型标识。如果能看到，说明当前账号或套餐可以调用；如果看不到，那后面所有配置都白搭。

API Key 也要提前准备好。打开控制台创建一个 Key，权限范围选择允许访问 K3 模型的选项，因为有些 Key 是严格限模型范围的。别把 Key 写在 Codex 的配置文件里，建议用环境变量KIMI_API_KEY管理，这样一方面不容易误传，另一方面换账号也方便。

2.2 Codex 本体安装：CLI 和 Windows 桌面版

Codex 的安装方式要看平台。Windows 上如果你用桌面版，很多人会遇到“codex 安装 windows 桌面版未完成”的情况，安装器跑到一半退出去，或者进度条卡死。我试下来最管用的办法是右键安装包选“以管理员身份运行”，然后把杀毒软件的实时防护临时关掉再装。桌面版需要登录，但如果你的目标只是接 Kimi K3，我更推荐直接用 CLI，因为 CLI 的配置更透明。

CLI 安装一般是用官方脚本或包管理器。安装完成后先确认版本，codex --version能看到版本号，接着在命令行里执行codex login。这里有个关键点：如果你完全不想用 OpenAI 的账号体系，只想用 Kimi K3，那么登录这步可能绕不开，但你可以选择 API Key 方式登录，也可以先随便登录一次，然后通过配置文件里的自定义 provider 切到 Kimi。别把 OpenaAI 的模型和 Kimi 的模型混在一个对话里，容易出奇怪的问题。

2.3 兼容层工具选型：自己写还是用现成的

兼容层有两条路：一条是用现成工具，比如社区里有人基于 FastAPI 或 Node.js 写的 OpenAI-to-Responses 转发服务，也有像 cc-switch 这种带图形界面的供应商切换工具。另一条是自己写一个迷你服务，监听 15721 端口，收到/responses请求后拼装成/chat/completions，再转发出去。自己写的好处是逻辑完全可控，坏处是你要自己处理鉴权、超时、错误映射，工作量不小。

我个人的建议是：如果你只是想快速用起来，先用现成工具；如果工具排错排不动了，再自己写一个最小实现来定位问题。因为很多现成工具的报错信息并不友好，像cc switch local proxy failed while handling codex endpoint /responses这句话，它只能告诉你“本地转发服务在处理 /responses 时挂了”，至于为什么挂，你还得去看日志。

2.4 端口规划与本地服务约定

端口选择看起来不起眼，但坑不少。Codex 的报错里会出现15721，这个端口实际上是你启动兼容层时自己定的，不一定非得是 15721。关键是 Codex 配置里的base_url必须跟兼容层监听端口保持一致。我习惯固定用 127.0.0.1 而不是 0.0.0.0，因为这是一台开发机的本地服务，没必要对外暴露。如果端口被占用，服务起不来，Codex 就会觉得连接失败，表现成 502 或连接拒绝。

启动兼容层之前，先用netstat -ano | findstr 15721（Windows）或lsof -i :15721（macOS/Linux）看一眼端口是否已被占用。有时候你之前启动过另一个服务，忘了关，就会导致新服务绑定失败，而 Codex 把请求发到了一个已经死掉的旧进程上，报错日志特别迷惑人。

3. Respons 兼容层配置实操：从 Codex 配置到链路验证

3.1 Codex 的 config.toml 标准写法

Codex 的配置文件通常位于用户目录下的.codex/config.toml。你需要定义一个自定义 model provider，然后把默认模型指到 Kimi K3。下面是一份我实测可用的最小配置：

model = "kimi-k3" model_provider = "kimi" [model_providers.kimi] name = "Kimi K3" base_url = "http://127.0.0.1:15721/v1" env_key = "KIMI_API_KEY" wire_api = "responses"

这段配置有几个重点：base_url一定要写到/v1这个层级，因为 Codex 会在后面拼上/responses；env_key告诉 Codex 从环境变量KIMI_API_KEY里读取 Kimi 的 Key，不要硬编码在配置文件里；wire_api是 Codex 跟这个 provider 通信时使用的协议格式，这里必须写responses，才能触发 Responses API 的请求路径。如果你把wire_api写成chat，Codex 就会改用/chat/completions，那兼容层写的 /responses 转换逻辑就用不上了。

3.2 兼容层上游配置：把 /responses 翻译成 Kimi 能懂的请求

兼容层这边，核心就是“收到 /responses 请求后，转成 /chat/completions”。如果你用现成工具，通常只需要填三个参数：监听端口、Kimi API Key、Kimi 的上游地址。Kimi 的上游地址以官方文档为准，不过大概率要填到/v1。

如果你决定自己写一个最小兼容层，代码思路大概是：先用 FastAPI 或 Flask 在 15721 端口启一个服务，定义POST /v1/responses路由；接收 Codex 的 JSON 请求后，从环境变量里取KIMI_API_KEY，把model、messages、工具定义等关键字段提取出来，重新组装成一个 Chat Completions 的请求体；然后用requests或httpx发到https://api.kimi.example/v1/chat/completions；拿到返回结果后，再映射回 Responses API 的响应结构，返回给 Codex。响应结构里最核心的是output字段，Codex 会从这里提取文本内容和工具调用，映射错了就会导致 Codex 明明收到结果却显示异常。

我建议第一次调试时，兼容层日志要打印完整请求体和上游返回体。别嫌日志多，这一步能让你少猜很多谜。

3.3 环境变量与启动顺序

启动之前，把环境变量准备好。Windows PowerShell 下可以这样设置：

$env:KIMI_API_KEY="你的Kimi Key"

macOS/Linux 下可以临时导出：

export KIMI_API_KEY="你的Kimi Key"

接着先启动兼容层服务，等它打印出“listening on 15721”之类的信息，再用一个最简单的 curl 命令验证上游通不通：

curl http://127.0.0.1:15721/v1/responses \ -H "Content-Type: application/json" \ -d '{"model":"kimi-k3","input":"hello"}'

如果返回正常，再启动 Codex，直接问它一个简单的编程问题，比如“写一个 Python 函数判断闰年”。这一步能同时验证鉴权、模型名、协议转换三个关键点。

3.4 功能验证与协议细节核对

验证的时候，不要只问一句“你好”，那样测试不到工具调用链路。Codex 这类智能体的核心能力是“边思考边调工具”，所以你要给它一个需要写代码再执行的任务，它才会真的发起工具调用请求。如果工具调用链路没走通，可能你问普通问题一切正常，但一问“帮我写个脚本并运行”就报错。

另外注意，Responses API 的请求体结构跟 Chat Completions 有差异，尤其是消息角色和工具定义字段。兼容层在做格式映射时，必须把instructions、input、tools这些字段处理好。我的经验是：如果请求里带tools，在转换到 Chat Completions 时要保留function类型的工具定义及strict参数，否则模型输出的 JSON Schema 可能对不上。

4. 常见报错与排查实录：从 502 到 model not supported 的完整方案

4.1 unexpected status 502 bad gateway：兼容层转发失败

这个报错应该是最常见的了，完整信息是unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses。它的意思是：Codex 成功把请求发到了本地兼容层，但兼容层在向上游转发时失败了，于是随便回了一个 502。别急着改 Codex 配置，先去看兼容层的日志。

我遇到过的原因有四种：一是 Kimi API Key 配置错了或权限不足，上游返回 401，兼容层没处理好就返回 502；二是兼容层服务本身没起来，极少数情况下也会显示连接失败；三是网络问题，比如上游请求超时；四是上传的模型名不对，Kimi 不认kimi-k3这个名字，上游直接拒绝，兼容层也包装成 502。

排查步骤很简单：先用 curl 直接打 Kimi 上游，确认 Key 和模型名是好的；然后再用 curl 打兼容层的/v1/responses，确认转换没问题；最后再用 Codex 发请求。一层一层剥开，问题定位非常快。

4.2 model is not supported：Codex 把模型名传错了

报错长这样：the 'gpt-5.6-sol' model is not supported when using codex with a...。这句话的潜台词是，Codex 请求里带的模型名，压根不是 Kimi 家的。最常见的原因是 config.toml 里的model = "gpt-5.6-sol"没改成 Kimi 的名字，而是沿用了 Codex 默认值。解决办法很直接：把model改成你在 Kimi 控制台里看到的模型标识，然后重启 Codex。注意改完不是退出重进就完事，最好是codex logout之后重新登录，或者干脆重启终端，确保配置重新加载。

还有一种情况：兼容层在转换请求时，图省事直接把 Codex 发来的model字段透传给了 Kimi，而没有替换成 K3 的模型名。这就需要在兼容层代码里做一个模型名映射表，把任意来自 Codex 的不认识的名字，统一改成kimi-k3。别小看这个映射，它能救你一次。

4.3 auth token is unavailable：Codex 登录态丢失

codex auth token is unavailable这个报错，多半跟 Codex 自己的登录态有关，而不是 Kimi 的 Key 有问题。Codex 在某些版本里要求先完成登录才能使用，即使你用的是自定义 provider，它也会在启动时检查本地登录 token。解决办法：运行codex login重新登录，选择 API Key 方式即可。

还有一个容易被忽略的点：如果你设置过环境变量OPENAI_API_KEY，Codex 可能会优先拿这个 Key 去跟 OpenAI 通信，而不是用你自定义的 provider。建议把OPENAI_API_KEY临时清掉，只保留KIMI_API_KEY，避免混淆。如果你刚用 ChatGPT 账号登录过 Codex，而现在切到 Kimi，最好codex logout之后再登录一次，因为旧 token 和新 provider 的鉴权体系是不同的。

4.4 cc-switch local proxy failed：图形化工具翻车实录

cc switch local proxy failed while handling codex endpoint /responses这条报错，我用 cc-switch 的时候碰到过好几回。cc-switch 是一个帮你在多个 API 供应商之间快速切换的工具，它会在本地起一个转发服务，让 Codex 以为自己在和一个稳定的端点通信。问题在于，它原生支持的转发对象大多是标准的 OpenAI 兼容接口，当你让它处理/responses时，有些版本根本不知道该怎么转发。

解决办法有几个方向：第一，把你的 cc-switch 升级到最新版，作者很可能已经补了 Responses 支持；第二，检查 cc-switch 里的供应商配置，base_url是否带了完整的/v1前缀，密钥是否填对了；第三，也是我推荐的做法，别依赖 cc-switch 做转发，直接让 Codex 连到你手动启动的兼容层，这样逻辑更清晰，出问题也好查。

4.5 Windows 安装未完成和其他“打不开”类问题

Windows 上被吐槽最多的就是“codex 安装 windows 桌面版未完成”。我见到的原因主要有三个：一是安装包权限不够，卡在写入阶段；二是杀毒软件把安装进程的文件隔离了；三是旧版本残留导致新版本覆盖失败。处理办法是：以管理员身份运行安装包，临时关闭实时防护，然后清理旧的 Codex 安装目录，比如%LOCALAPPDATA%\Codex和%USERPROFILE%\.codex下的残留文件，再重新安装。

“codex 打不开”、“codex 官网打不开”这类问题，大多数跟本机网络访问有关。先检查系统代理设置、DNS 是否正常，再确认浏览器或终端能访问外部服务。注意，我这里说的是常规网络排查，不是让你去搞任何非常规工具。如果基础网络没问题，换个网络环境试试往往就解决了。桌面版打不开的时候，也可以优先考虑用 CLI，因为 CLI 对系统依赖更少。

4.6 排错速查表

5. 一些不写在文档里的实操心得

这套“Kimi K3 接入 Codex”的流程，我前前后后折腾了差不多一整天，最深的感受是：大多数问题都不是“配置不生效”，而是“协议没对齐”。Codex 用的是 Responses API，Kimi 提供的是 Chat Completions，你光把 URL 改过去是没用的，必须有这么一层转换逻辑。理解了这一点，看到 502 你就不会再一脸懵，而是会去查兼容层日志，看到model not supported就会第一时间去查模型名映射。

还有一个小技巧想分享：兼容层的日志默认级别往往是 info，排错时最好开 debug，把每个请求的 method、path、body 和上游响应时间都打出来。很多报错你以为是在 Codex 那边，其实是在兼容层和 Kimi 之间。日志够详细，一次就能看出是超时、鉴权还是模型名问题。

最后也提醒一句：Kimi K3 的访问权限、接口地址、模型名这些信息，会随平台调整而变化。你看到这篇文章的时间点如果比较晚，配置里某些字段可能需要对照最新的官方文档更新。不过整体架构和排错思路是通用的，只要链路是“Codex → 兼容层 → Kimi K3”，这套方法论就能一直用下去。希望这份接入指南能帮你少走弯路，赶紧把环境跑通。