Codex接入KingFlow兼容API的桥接方案：从协议差异到可运行配置
这篇记录的是 Codex 接入 KingFlow 兼容 API 时的一种桥接思路。它适合本地客户端固定使用 Responses API，而上游服务以 OpenAI 兼容 Chat Completions 方式提供调用的场景。
示例上游地址：https://www.kingflow.ai/v1。本文只讨论配置路径和排查方法，不把它写成平台推荐。
一、为什么需要桥接层
问题通常不在“能不能请求 API”，而在客户端和上游接口的请求形态不完全一致。Codex 新版本可能按 /v1/responses 组织请求；很多兼容服务则更常见 /v1/chat/completions。桥接层的作用是把两边字段、路径、流式返回和工具调用格式做一次转换。
图 1：Codex、桥接层和 KingFlow 兼容 API 的调用关系。
二、配置目标
| 位置 | 示例值 | 说明 |
|---|---|---|
| Codex 侧 API 地址 | http://127.0.0.1:4000/v1 | 指向本机桥接服务 |
| Codex 侧 Key | sk-proxy-local-replace-with-48-char-hex | 本地代理认证用，可自定义 |
| 桥接层上游 Base URL | https://www.kingflow.ai/v1 | 桥接层真正请求的模型服务 |
| 桥接层上游 Key | sk-你的KingFlow密钥 | 从后台密钥页复制 |
三、推荐的环境变量
# .env 示例 PROXY_AUTH_KEY=sk-proxy-local-replace-with-48-char-hex UPSTREAM_BASE_URL=https://www.kingflow.ai/v1 UPSTREAM_API_KEY=sk-你的KingFlow密钥 UPSTREAM_MODEL=从模型列表复制的模型名 PORT=4000变量名称要以你实际使用的桥接项目为准。如果项目使用的是 OPENAI_BASE_URL 或 DEEPSEEK_API_KEY 这类命名，也可以保留原命名，只要含义对应清楚即可。
图 2：桥接方案上线前建议逐项核对。
四、最小验证流程
启动桥接服务，确认控制台显示监听 4000 端口。
用本地地址请求模型列表或发送一条最短对话。
确认桥接日志里能看到请求进入、上游返回、最终响应。
再把 http://127.0.0.1:4000/v1 写入 Codex 或切换工具。
curl http://127.0.0.1:4000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-proxy-local-replace-with-48-char-hex" \ -d '{"model":"你的模型名","messages":[{"role":"user","content":"hello"}]}'五、排查顺序
本地请求不到：先看桥接服务是否启动、端口是否被占用。
本地返回 401：检查 Codex 侧 Key 是否等于 PROXY_AUTH_KEY。
上游返回 401：检查 KingFlow API Key 是否完整。
返回 model_not_found：从模型列表重新复制模型名。
能回复但流式异常：检查桥接层是否支持 SSE 转发。
返回 model_not_found：从模型列表重新复制模型名。
能回复但流式异常：检查桥接层是否支持 SSE 转发。