让 Codex CLI 跑上 DeepSeek：用 LiteLLM 做 Responses↔Chat 协议翻译-平芜编程栈

结论先行：Codex CLI（实测 v0.143.0）只认 OpenAI 的Responses API，而 DeepSeek 只提供Chat Completions。两者协议对不上，直接配必然 404。中间架一层 LiteLLM 代理做协议翻译，Codex 说 Responses、LiteLLM 转成 Chat 转发给 DeepSeek，链路就通了。本文给出的配置和命令可以直接照抄，所有踩过的坑都标在第四节。

一、为什么不能直接配

我一开始也以为改改config.toml就行，结果在三个坑里来回跳：

协议层面不兼容。Codex v0.143.0 把wire_api写死为responses，它发出的每个请求都是POST /v1/responses。DeepSeek 的 OpenAI 兼容端点里只有/v1/chat/completions，没有/v1/responses。直连必 404。
wire_api没有可调空间。新版 Codex 已经把chat选项删了，你设chat它直接拒绝加载配置；设responses配置能加载，但请求照样 404。翻这个字段纯属浪费时间。
key 的字段名也有坑（见 4.1）。

所以根因不是配置写错，是两边协议不兼容，必须有个翻译层。

二、架构

Codex 全程只跟本地127.0.0.1:8787通信，它以为自己在调 OpenAI；LiteLLM 负责把 Responses 语义翻成 Chat，再把 DeepSeek 的回答翻回 Responses。流式（SSE）和工具调用（function_call，Codex 跑命令/改文件就靠这个）都在翻译范围内。

三、前置条件

一个本地空闲端口，本文用8787。
Python 3.12+（用 venv 隔离，别污染全局环境）。
一个 DeepSeek API key（下文记为YOUR_DEEPSEEK_API_KEY）。
Codex CLI 任意只支持responses的版本（v0.143.0 实测通过）。

四、踩坑记录（重点，先看这个再动手）

这些是我实际踩过的，照着避能省至少三轮往返：

4.1env_key不是api_key
Codex 的config.toml里，把整串 key 写进env_key是错的——Codex 会把它当环境变量名去getenv()，于是报Missing environment variable: sk-...。正确做法是直接内联：api_key = "sk-..."。

4.2wire_api = "chat"已被新版 Codex 移除
设成chat会直接报wire_api = "chat" is no longer supported，配置根本加载不了。别试。

4.3wire_api = "responses"直连 DeepSeek 必 404
这是协议根因，不是配置问题。设了能加载，但每个请求都打到 DeepSeek 不存在的/v1/responses，全部 404。翻wire_api无解。

4.4 LiteLLM 模型前缀必须用deepseek/，不能用openai/
这是最阴的一个坑。如果你在litellm_config.yaml里写model: openai/deepseek-v4-flash，LiteLLM 会认为这是个"原生支持 Responses 的 OpenAI 兼容端点"，直接把/responses原样转发给 DeepSeek→ 又 404。只有写model: deepseek/deepseek-v4-flash，LiteLLM 才会启用 Responses→Chat 的翻译逻辑。差一个前缀，天差地别。

4.5 只装litellm不够，要litellm[proxy]
启动代理时若只pip install litellm，会缺backoff等依赖而启动失败。务必装 extras：pip install "litellm[proxy]"。

4.6 Codex 启动时的Model metadata not found警告无害
每次启动都会看到⚠ Model metadata for deepseek-v4-flash not found. Defaulting to fallback metadata。这是因为deepseek-v4-flash是自定义模型，不在 Codex 内置清单里，它走兜底元数据。聊天场景实际无影响，直接忽略。

4.7 代理是常驻后台进程
代理一旦退出（比如启动它的终端/会话关闭），Codex 就 404。下次用 Codex 前先手动把代理拉起来（见 3.3 的启动命令）。

五、实操步骤

5.1 建隔离环境并装依赖

python-mvenv ~/.codex-proxy/venv# Windows~/.codex-proxy/venv/Scripts/pipinstall"litellm[proxy]"uvicorn# macOS / Linux~/.codex-proxy/venv/bin/pipinstall"litellm[proxy]"uvicorn

注意：Windows 的 venv 可执行文件在Scripts/下（如Scripts/litellm.exe、Scripts/pip.exe）；类 Unix 在bin/下。下文脚本按 Windows 路径写，类 Unix 自行替换。

5.2 写 LiteLLM 配置

~/.codex-proxy/litellm_config.yaml：

model_list:-model_name:deepseek-v4-flashlitellm_params:model:deepseek/deepseek-v4-flash# 关键：必须是 deepseek/ 前缀，见 4.4api_key:YOUR_DEEPSEEK_API_KEYdrop_params:truegeneral_settings:disable_auth:true# 本地代理，关掉鉴权telemetry:false

model_name是暴露给 Codex 的模型名，要和 Codex 配置里的model对齐。drop_params: true让 LiteLLM 丢掉 DeepSeek 不认识的参数，避免偶发报错。

5.3 启动代理

写个启动脚本~/.codex-proxy/start-proxy.sh（Windows 版）：

#!/usr/bin/env bashset-eVENV="$HOME/.codex-proxy/venv"CFG="$HOME/.codex-proxy/litellm_config.yaml"exec"$VENV/Scripts/litellm.exe"--config"$CFG"--port8787--host127.0.0.1

后台启动：

nohupbash~/.codex-proxy/start-proxy.sh>~/.codex-proxy/proxy.log2>&1&

等代理就绪（健康接口返回 200 即代表起来了，最多等 40 秒）：

foriin$(seq140);docode=$(curl-s-o/dev/null-w"%{http_code}"http://127.0.0.1:8787/health/liveliness2>/dev/null)["$code"="200"]&&{echo"proxy up after${i}s";break;}sleep1done

停掉代理：taskkill /IM litellm.exe /F（Windows）或pkill -f litellm（类 Unix）。

5.4 改 Codex 配置指向代理

~/.codex/config.toml里 provider 段改成：

model = "deepseek-v4-flash" model_provider = "deepseek" preferred_auth_method = "apikey" [model_providers.deepseek] name = "DeepSeek via local proxy" base_url = "http://127.0.0.1:8787/v1" # 指向本地代理，不是 DeepSeek 官网 api_key = "YOUR_DEEPSEEK_API_KEY" # 代理关了鉴权，这里随便填也能通，但留着不碍事 wire_api = "responses"

base_url从 DeepSeek 官网换成127.0.0.1:8787/v1是核心改动；wire_api保持responses不动。

六、验证（三条 curl 全过才算通）

基础补全——应返回标准 Responses 结构（output内含message+output_text）：

curl-s-XPOST http://127.0.0.1:8787/v1/responses\-H"Content-Type: application/json"\-d'{"model":"deepseek-v4-flash","input":"Reply with exactly one word: hi"}'

工具调用——应返回function_call（name 为ping），这是 Codex 执行命令的关键能力：

curl-s-XPOST http://127.0.0.1:8787/v1/responses\-H"Content-Type: application/json"\-d'{"model":"deepseek-v4-flash","tools":[{"type":"function","name":"ping","description":"return pong","parameters":{"type":"object","properties":{}}}],"input":"call the ping tool"}'

流式（SSE）——应看到response.created→output_item.added→content_part.added事件流：

curl-s-N-XPOST http://127.0.0.1:8787/v1/responses\-H"Content-Type: application/json"\-d'{"model":"deepseek-v4-flash","input":"say hello in 3 words","stream":true}'

三条都正常，直接codex就能用 DeepSeek 干活了。

七、为什么是 LiteLLM 而不是降级 Codex

我也考虑过降级到还支持wire_api = "chat"的旧版 Codex，但那条路等于把自己锁死在旧版本上，以后 Codex 出新能力都用不了。LiteLLM 这层代理的好处是：Codex 永远用最新版，翻译逻辑独立演进，DeepSeek 换成别的 Chat 协议供应商也只是改一行model映射。代价是多跑一个本地进程——对这个场景来说，划算。