Codex CLI 接入 DeepSeek 全方案避坑指南：2026 最新四方案横向对比实战（Responses API 协议冲突终极破解）
Codex CLI 接入 DeepSeek 全方案避坑指南：2026 最新四方案横向对比实战（Responses API 协议冲突终极破解）
📑 目录
- 写在前面：为什么这篇值得你收藏
- 一、问题背景：一句话讲清为什么不能直连
- 二、原理分析：Responses API 与 Chat Completions 的协议鸿沟
- 三、环境准备：四方案通用的前置条件
- 四、四方案横向对比：先看全貌再选型
- 五、方案一：codex-relay —— Windows 党的福音，最简上手
- 六、方案二：Moon Bridge —— 跨平台均衡，自动生成配置最省心
- 七、方案三：codex-chat-bridge —— macOS 老手的 Tool 过滤利器
- 八、方案四：aliyun-codex-bridge —— 想要完整思维链就靠它（含 3 处补丁）
- 九、统一踩坑地图：四方案报错速查
- 十、一键启动与日常使用（Windows 版）
- 十一、安全须知：别让 AI 帮你删库
- 十二、方案选型建议与总结
- 写在最后
你是不是也这样：跟着 2025 年的旧教程,把
base_url改成https://api.deepseek.com/v1,满怀期待地敲下codex,结果换来一屏幕的config could not be loaded、one or more required provider endpoints are unreachable?别怀疑人生,不是你配置写错了——是 Codex CLI 在 2026 年彻底变了协议。本文用四个真实可跑的方案,带你从"连不上"到"真香"。
写在前面：为什么这篇值得你收藏
最近半年,Codex CLI 接入 DeepSeek 是技术社区最火的话题之一。掘金、CSDN、知乎上相关文章动辄几千收藏,但绝大多数只讲单一方案、单一平台,踩坑也是各踩各的。
笔者把社区主流的四种桥接方案（codex-relay / Moon Bridge / codex-chat-bridge / aliyun-codex-bridge）全部在 Windows 11 + macOS 双平台跑通,把所有报错、所有配置、所有"差点放弃"的瞬间,整理成这一篇。看完这一篇,你不需要再看第二篇。
一、问题背景：一句话讲清为什么不能直连
先说结论:新版 Codex CLI 不能通过改 base_url 直连 DeepSeek,无论你配得多仔细。
很多人第一反应是:“DeepSeek 不是兼容 OpenAI 接口吗?Codex 也是 OpenAI 的,直接指过去不就行了?”
——错。这里有个致命的认知偏差:
| 你以为的 | 实际情况 |
|---|---|
| OpenAI 接口 = 一套统一接口 | OpenAI 现在有两套接口 |
| DeepSeek 兼容 OpenAI = 兼容 Codex | DeepSeek 只兼容其中的 Chat Completions |
| Codex 用的是 Chat Completions | 新版 Codex 已经只用 Responses API 了 |
也就是说,DeepSeek 兼容的是 Codex 已经抛弃的那套接口。这就是所有报错的根源。
二、原理分析：Responses API 与 Chat Completions 的协议鸿沟
2.1 两套 API 到底差在哪
OpenAI 目前对外提供两套接口:
| 维度 | Chat Completions API | Responses API |
|---|---|---|
| 路径 | /v1/chat/completions |
/v1/responses |
| 消息结构 | messages 数组(role/content) |
input + 事件流(items) |
| 工具调用 | tool_calls(function 类型) |
Responses 风格工具结构(多种 type) |
| 流式输出 | choices[].delta 增量 |
事件流(reasoning/message/…) |
| 思维链 | 无原生字段 | 原生 reasoning item |
| Codex 支持情况 | v0.130 前支持,现已移除 | v0.130+ 唯一支持 |
2.2 Codex CLI 的"断崖式升级"
Codex CLI 在 v0.130 版本做了一个极为激进的决定:彻底移除 wire_api = "chat" 支持,强制要求 Responses API。到本文写作时的 v0.141.0,这件事已经不可逆。
这带来一个尴尬的局面:
Codex CLI (只说 Responses) ←×→ DeepSeek (只懂 Chat Completions)
鸡同鸭讲,无法直接对话
2.3 破局思路:加一个"翻译官"
既然两边语言不通,那就在中间架一层翻译——让 Codex 以为自己在和 OpenAI Responses 服务对话,翻译层把请求转成 DeepSeek 能懂的 Chat Completions,再把响应翻译回去。
┌──────────┐ Responses API ┌──────────────┐ Chat Completions ┌──────────────┐
│ Codex CLI │ ─────────────────► │ 桥接层(本地) │ ─────────────────► │ DeepSeek API │
│ (TUI界面) │ ◄───────────────── │ 127.0.0.1:端口 │ ◄───────────────── │ api.deepseek │
└──────────┘ Responses 响应 └──────────────┘ Chat 响应 └──────────────┘
这就是社区所有方案的本质。区别只在于:这个翻译官用什么语言写、装在哪、怎么配、能不能完整翻译思维链。下面逐一拆解。
三、环境准备:四方案通用的前置条件
无论选哪个方案,下面这些都要先就位。
3.1 依赖清单
| 依赖 | 最低版本 | 用途 | 各方案是否必需 |
|---|---|---|---|
| Node.js | >= 18(推荐 22) | 运行 Codex CLI | 全部必需 |
| npm | 随 Node.js | 安装 Codex | 全部必需 |
| Python 3 | >= 3.8 | 安装 codex-relay | 仅 codex-relay |
| Go | >= 1.25 | 运行 Moon Bridge | 仅 Moon Bridge |
| Rust | >= 1.85 | 编译 codex-chat-bridge | 仅 codex-chat-bridge |
3.2 一键验证环境
node -v
npm -v
# 按需:
python --version
go version
3.3 安装 Codex CLI 本体
# 跨平台通用
npm install -g @openai/codex
# 验证版本(本文基于 v0.141.0)
codex --version
Windows 用户如果 npm 全局包被塞进 C 盘,建议先改 prefix:
npm config set prefix D:\npm-global
# 然后把 D:\npm-global 加到 PATH 最前面
3.4 获取 DeepSeek API Key
- 访问
https://platform.deepseek.com/ - 注册登录 → 左侧 “API keys” → 创建
- 复制
sk-开头的密钥(只显示一次,务必保存)
⚠️ 关键认知:DeepSeek 的 API Key 是
sk-开头,但别和 OpenAI 的 Key 混用——这是后面鉴权 401 报错的高频原因。
四、四方案横向对比:先看全貌再选型
为了让你少走弯路,先把四个方案摊开比一比。这是本文区别于社区其他单方案文章的核心价值。
| 维度 | codex-relay | Moon Bridge | codex-chat-bridge | aliyun-codex-bridge |
|---|---|---|---|---|
| 实现语言 | Rust(pip 分发) | Go | Rust(npm 分发) | Node.js |
| 安装难度 | ⭐ 最简 | ⭐⭐ 需 Go | ⭐⭐⭐ 需 Rust | ⭐⭐ npm |
| 平台友好 | Windows 最佳 | 跨平台均衡 | macOS/Linux 友好 | 跨平台均衡 |
| 配置生成 | 手动 | 自动生成 | 手动 | 手动 |
| 思维链(reasoning) | 一般 | 支持推理等级 | 需手动过滤 Tool | 需 3 处补丁才完整 |
| 多轮 Agent | ✅ | ✅ | ✅ | ✅(补丁后) |
| 适合人群 | 新手、Win 用户 | 想省事、要功能全 | macOS 老手 | 想深度调参的玩家 |
| 综合释放率 | ~80% | ~85% | ~80% | ~90%(补丁后) |
笔者的选型建议(后面有详细论证):
- Windows + 怕折腾 →
codex-relay(第 5 节) - 跨平台 + 想自动配 →
Moon Bridge(第 6 节) - macOS + 老手 →
codex-chat-bridge(第 7 节) - 想要完整思维链 + 愿意改源码 →
aliyun-codex-bridge(第 8 节)
下面逐个上实战。
五、方案一:codex-relay —— Windows 党的福音,最简上手
5.1 为什么先讲它
codex-relay 是一个轻量级 Rust 写的翻译代理,通过 pip 分发,安装一行命令,启动一行命令。对 Windows 用户特别友好——不用装 Go、不用编译 Rust,Python 一把梭。
5.2 安装
pip install codex-relay
5.3 设置环境变量
方式 A:系统设置(推荐,永久生效)
- 变量名
OPENAI_API_KEY,值填你的 DeepSeek Key - 变量名
DEEPSEEK_BASE_URL,值填https://api.deepseek.com/v1
方式 B:命令行(仅当前会话)
setx OPENAI_API_KEY "sk-你的key"
setx DEEPSEEK_BASE_URL "https://api.deepseek.com/v1"
⚠️
setx之后必须重新打开终端才生效,这是新手最容易忽略的一步。
5.4 启动 relay(推荐命令行参数方式)
codex-relay --upstream https://api.deepseek.com/v1 --api-key 你的Key --port 4446
看到下面这行就成功了:
codex-relay listening on 127.0.0.1:4446 → https://api.deepseek.com/v1
upstream models: deepseek-v4-flash, deepseek-v4-pro
⚠️ 别用环境变量 +
set方式启动:set VAR=value && codex-relay中value末尾的空格会被吞进变量,导致--port解析报invalid digit found in string。这是方案一最大的坑,踩过的人不计其数。
5.5 编写 Codex 配置
文件位置 C:\Users\你的用户名\.codex\config.toml(macOS/Linux 为 ~/.codex/config.toml):
model = "deepseek-v4-flash"
model_provider = "deepseek-relay"
[model_providers.deepseek-relay]
name = "DeepSeek"
base_url = "http://127.0.0.1:4446/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
[model_properties."deepseek-v4-flash"]
context_window = 1048576
max_context_window = 1048576
supports_parallel_tool_calls = true
supports_reasoning_summaries = false
input_modalities = ["text"]
output_modalities = ["text"]
[model_properties."deepseek-v4-pro"]
context_window = 1048576
max_context_window = 1048576
supports_parallel_tool_calls = true
supports_reasoning_summaries = false
input_modalities = ["text"]
output_modalities = ["text"]
5.6 三个绝对不能写错的关键点
| 字段 | 正确值 | 写错的后果 |
|---|---|---|
wire_api |
"responses" |
写成 "chat" → config could not be loaded |
base_url |
http://127.0.0.1:4446/v1 |
直写 DeepSeek 地址 → 协议不兼容报错 |
model |
deepseek-v4-flash |
写 deepseek-chat → 模型名即将停用 |
model_properties |
必须显式配置 | 不配 → 上下文窗口缩水、工具调用异常 |
5.7 验证
codex exec "请用一句话说明当前项目的主要作用"
能正常返回,说明链路通了。日常使用直接 codex 进入交互界面即可。
六、方案二:Moon Bridge —— 跨平台均衡,自动生成配置最省心
6.1 它的杀手锏
Moon Bridge 用 Go 写,最大的优势是能自动帮你生成 config.toml——不用手抄、不用怕拼错。还原生支持 DeepSeek V4 的推理等级(effort)配置,功能最全。
6.2 拉取并准备
git clone https://github.com/ZhiYi-R/moon-bridge.git
cd moon-bridge
6.3 编写 bridge 配置 config.yml
mode: "Transform"
server:
addr: "127.0.0.1:38440"
models:
deepseek-v4-pro:
context_window: 1000000
max_output_tokens: 384000
default_reasoning_level: "high"
supported_reasoning_levels:
- effort: "high"
description: "High reasoning effort"
- effort: "xhigh"
description: "Extra high reasoning effort"
supports_reasoning_summaries: true
default_reasoning_summary: "auto"
extensions:
deepseek_v4:
enabled: true
deepseek-v4-flash:
context_window: 1000000
max_output_tokens: 384000
default_reasoning_level: "high"
supported_reasoning_levels:
- effort: "high"
description: "High reasoning effort"
- effort: "xhigh"
description: "Extra high reasoning effort"
supports_reasoning_summaries: true
default_reasoning_summary: "auto"
extensions:
deepseek_v4:
enabled: true
providers:
deepseek:
base_url: "https://api.deepseek.com/anthropic"
api_key: "sk-你的deepseek-api-key"
offers:
- model: deepseek-v4-pro
- model: deepseek-v4-flash
routes:
moonbridge:
model: deepseek-v4-pro
provider: deepseek
defaults:
model: moonbridge
max_tokens: 65536
6.4 启动 Moon Bridge
go run ./cmd/moonbridge --config config.yml
启动后监听 127.0.0.1:38440,对外暴露 Responses 兼容入口 http://127.0.0.1:38440/v1/responses。
6.5 自动生成 Codex 配置(省心核心)
先备份原配置:
# macOS / Linux
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME_DIR"
cp "$CODEX_HOME_DIR/config.toml" "$CODEX_HOME_DIR/config.toml.bak" 2>/dev/null || true
# Windows PowerShell
$CODEX_HOME_DIR = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force -Path $CODEX_HOME_DIR | Out-Null
if (Test-Path "$CODEX_HOME_DIR\config.toml") {
Copy-Item "$CODEX_HOME_DIR\config.toml" "$CODEX_HOME_DIR\config.toml.bak" -Force
}
一行命令生成配置:
# macOS / Linux
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
MODEL="$(go run ./cmd/moonbridge --config config.yml --print-codex-model)"
go run ./cmd/moonbridge \
--config config.yml \
--print-codex-config "$MODEL" \
--codex-base-url "http://127.0.0.1:38440/v1" \
--codex-home "$CODEX_HOME_DIR" \
> "$CODEX_HOME_DIR/config.toml"
# Windows PowerShell
$CODEX_HOME_DIR = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
$MODEL = go run ./cmd/moonbridge --config config.yml --print-codex-model
go run ./cmd/moonbridge `
--config config.yml `
--print-codex-config "$MODEL" `
--codex-base-url "http://127.0.0.1:38440/v1" `
--codex-home "$CODEX_HOME_DIR" `
| Set-Content -Path "$CODEX_HOME_DIR\config.toml"
生成出来的最小配置长这样(如果你只想手写,照抄即可):
model = "moonbridge"
model_provider = "moonbridge"
model_reasoning_effort = "high"
model_context_window = 1000000
model_supports_reasoning_summaries = true
[model_providers.moonbridge]
name = "Moon Bridge"
base_url = "http://127.0.0.1:38440/v1"
wire_api = "responses"
带写入权限的完整版:
model = "moonbridge"
model_provider = "moonbridge"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[model_providers.moonbridge]
name = "Moon Bridge"
base_url = "http://127.0.0.1:38440/v1"
wire_api = "responses"
6.6 验证三连
# 方法一:直接执行任务
codex exec "请用一句话说明当前项目的主要作用"
# 方法二:curl 打桥接层
curl http://127.0.0.1:38440/v1/responses \
-H "Content-Type: application/json" \
-d '{
"model": "moonbridge",
"input": "Say hello in one short sentence.",
"max_output_tokens": 1024
}'
# 方法三:看 Moon Bridge 终端日志,应该有 POST /v1/responses
七、方案三:codex-chat-bridge —— macOS 老手的 Tool 过滤利器
7.1 适用场景
纯 Rust 实现,通过 npm 分发。它的特色是 --drop-tool-type 参数可以精细过滤 Codex 发出的、DeepSeek 不认的工具类型,适合喜欢精确控制的 macOS/Linux 用户。
7.2 安装
# 先装 Rust(macOS)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env
# 装 bridge(会编译 Rust binary)
npm install -g @heungtae/codex-chat-bridge
7.3 配置 Bridge
创建 ~/.codex/bridge.toml:
[routers.deepseek]
incoming_url = "http://127.0.0.1:19099/v1/responses"
upstream_url = "https://api.deepseek.com/v1/chat/completions"
[routers.deepseek.features]
tool_transform_mode = "passthrough"
7.4 配置 Codex
编辑 ~/.codex/config.toml:
model = "deepseek-v4-flash"
model_provider = "deepseek-bridge"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[model_providers.deepseek-bridge]
name = "DeepSeek V4"
base_url = "http://127.0.0.1:19099/v1"
wire_api = "responses"
api_key = "dummy"
7.5 启动(关键:Tool 过滤)
# 设置 Key
export DEEPSEEK_API_KEY="your-deepseek-api-key"
# 后台启动,过滤掉 DeepSeek 不支持的工具类型
nohup codex-chat-bridge \
--config ~/.codex/bridge.toml \
--api-key-env DEEPSEEK_API_KEY \
--drop-tool-type web_search \
--drop-tool-type code_interpreter \
--drop-tool-type mcp \
--drop-tool-type namespace \
--drop-tool-type custom \
--drop-tool-type web_search_call \
--drop-tool-type browser \
> ~/.codex/bridge.log 2>&1 &
# 测试
codex exec "say hello"
⚠️ 为什么必须
--drop-tool-type:Codex 会发出web_search、code_interpreter、mcp等多种 type 的工具定义,而 DeepSeek 只认function类型。不过滤就会报Failed to deserialize: tools[N].type,这是方案三最典型的坑。
7.6 这套方案的踩坑映射表
| 报错 | 原因 | 解决 |
|---|---|---|
wire_api = "chat" 报错 |
v0.130 移除 Chat 支持 | 必须用 responses |
unknown variant developer |
DeepSeek 不认 developer role |
Bridge 自动映射为 system(版本要新) |
Failed to deserialize: tools[N].type |
DeepSeek 只支持 function |
--drop-tool-type 过滤 |
tools[4].function: missing field name |
Codex 发了无名称工具 | --drop-tool-type |
missing environment variable |
Codex Desktop 无 shell env | 改用 api_key = "dummy" |
八、方案四:aliyun-codex-bridge —— 想要完整思维链就靠它(含 3 处补丁)
8.1 为什么单独拎出来讲
前三方案都能让 Codex 跑起来,但有一个共性短板:DeepSeek 的 reasoning(思维链)在回传时容易被丢弃。aliyun-codex-bridge 这个 Node.js 方案,打上 3 处补丁后能把思维链完整保留,综合释放率冲到 ~90%,是进阶玩家的首选。
8.2 安装
npm install -g aliyun-codex-bridge
8.3 启动(补丁前)
PORT=19099 AI_API_KEY="your-api-key" AI_API_BASE="https://api.deepseek.com/v1" ALLOW_TOOLS=1 \
nohup node ~/.local/lib/node_modules/aliyun-codex-bridge/src/server.js &
Codex 配置:
[model_providers.aliyun-bridge]
name = "DeepSeek V4"
base_url = "http://127.0.0.1:19099"
wire_api = "responses"
api_key = "dummy"
8.4 三处关键补丁(解放思维链)
修改文件:~/.local/lib/node_modules/aliyun-codex-bridge/src/server.js
补丁 1(约 827 行):提取 reasoning item 文本,回传给 DeepSeek
把原来跳过 reasoning 的逻辑:
// Skip Reasoning, FunctionCall, LocalShellCall, etc.
改为提取 reasoning 文本,附加到 assistant 消息的 reasoning_content 字段。
补丁 2(约 870 行):给所有 assistant 消息兜底空 reasoning_content
// 在 finalMessages 赋值后添加:
for (const m of finalMessages) {
if (m.role === 'assistant') {
if (!m.reasoning_content) m.reasoning_content = '';
}
}
补丁 3(约 886 行):启用 thinking 模式的 reasoning 参数透传
// 启用 reasoning 参数透传(开启 thinking 模式)
8.5 补丁前后效果对比
| 指标 | 补丁前 | 补丁后 |
|---|---|---|
| Token 消耗 | ~10K | ~21K(含推理链) |
| Reasoning 保留 | ❌ 被丢弃 | ✅ 完整回传 |
| DeepSeek 思维链 | 空 | 完整运行 |
| 威力释放 | ~70% | ~90% |
8.6 生产环境:开机自启(macOS launchd)
创建 ~/Library/LaunchAgents/com.codex.deepseek-bridge.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.codex.deepseek-bridge</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/node</string>
<string>~/.local/lib/node_modules/aliyun-codex-bridge/src/server.js</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>PORT</key><string>19099</string>
<key>HOST</key><string>127.0.0.1</string>
<key>AI_API_KEY</key><string>your-deepseek-api-key</string>
<key>AI_API_BASE</key><string>https://api.deepseek.com/v1</string>
<key>ALLOW_TOOLS</key><string>1</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
</dict>
</plist>
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codex.deepseek-bridge.plist
九、统一踩坑地图:四方案报错速查
这部分是本文的"保命手册",把四套方案踩过的坑全部汇总。建议收藏,出问题直接 Ctrl+F 搜报错关键词。
9.1 协议层(所有方案通病)
| # | 报错表现 | 根因 | 解决 |
|---|---|---|---|
| 1 | config could not be loaded |
wire_api = "chat" 已废弃 |
改为 wire_api = "responses" |
| 2 | reachability unreachable |
base_url 直指 DeepSeek 官方 | 改指本地桥接层端口 |
| 3 | unknown variant developer |
DeepSeek 不认 developer role |
用较新版本桥接层(自动映射 system) |
| 4 | Failed to deserialize: tools[N].type |
DeepSeek 只支持 function 类型 |
codex-chat-bridge 加 --drop-tool-type;其他方案更新到最新版 |
9.2 模型层
| # | 报错表现 | 根因 | 解决 |
|---|---|---|---|
| 5 | 模型不存在/无法调用 | deepseek-chat 旧名 2026-07-24 停用 |
改用 deepseek-v4-flash / deepseek-v4-pro |
| 6 | 上下文窗口变小、工具调用异常 | 缺少 model_properties |
显式配置 context_window 等属性(见 5.5) |
9.3 环境与启动层
| # | 报错表现 | 根因 | 解决 |
|---|---|---|---|
| 7 | connection refused |
桥接层没启动 / 端口不一致 | 先起桥接层,核对端口 |
| 8 | invalid digit found in string |
set VAR=value && 尾随空格 |
改用 --port 命令行参数 |
| 9 | missing environment variable |
Codex Desktop 无 shell env | 配置里写 api_key = "dummy" |
| 10 | 401 鉴权失败 | Key 混用/多余空格/余额不足 | 核对 DeepSeek Key、账户余额 |
| 11 | 端口被占用启动失败 | 旧进程没关 | taskkill /f /im codex-relay.exe(Win) / kill -9 <pid>(Mac) |
| 12 | bat 脚本中文乱码 | cmd 默认 ANSI 代码页 | 用 GBK 编码保存 bat 文件 |
| 13 | bat 检测不到 API Key | Start-Process 父进程无环境变量 |
用 reg query 从注册表直接读 |
| 14 | PowerShell 5.1 $using 失败 |
PS 5.1 作用域规则差异 | 改用 param($key) + -ArgumentList |
| 15 | Codex 能回答但不能改代码 | 沙盒/权限/项目目录问题 | 配 sandbox_mode = "workspace-write" + approval_policy = "on-request" |
| 16 | 频繁请求报限流 | 狂按回车重试 | 报错后等几秒再试 |
9.4 Windows 专属坑
| # | 坑 | 解决 |
|---|---|---|
| 17 | npm 全局包塞 C 盘 | npm config set prefix D:\npm-global + 调 PATH |
| 18 | PATH 优先级不对 | 把 D 盘路径排到 C 盘 nodejs 前面 |
| 19 | 配置目录找不到 | C:\Users\你的用户名\.codex\config.toml |
十、一键启动与日常使用(Windows 版)
Windows 用户可以做个 codex-start.bat,双击即用:
10.1 脚本职责
- 从注册表
HKCU\Environment读取OPENAI_API_KEY(比%OPENAI_API_KEY%可靠) - 后台启动 codex-relay
- 等待 4 秒 relay 就绪
- 启动 Codex 交互界面
- Codex 退出后自动关闭 relay
10.2 关键提醒
⚠️ bat 文件必须用 GBK 编码保存,否则 cmd 解析中文会各种报错——这是 Windows 党的终极血泪。
10.3 日常使用流程
:: 首次安装(只做一次)
npm install -g @openai/codex
setx OPENAI_API_KEY "sk-你的DeepSeekKey"
setx DEEPSEEK_BASE_URL "https://api.deepseek.com/v1"
pip install codex-relay
:: 编辑 %USERPROFILE%\.codex\config.toml
:: 日常使用
:: 终端1:启动 relay
codex-relay --upstream https://api.deepseek.com/v1 --api-key %OPENAI_API_KEY% --port 4446
:: 终端2:启动 codex
codex
装好 bat 后,直接双击或点桌面快捷方式即可,省去开两个终端的麻烦。
十一、安全须知:别让 AI 帮你删库
Codex 接通后能直接读写你的代码库,权限很大,风险也很大。这几条务必遵守:
11.1 .gitignore 要忽略敏感文件
.env
config.yml
*.bak
.codex/
尤其 config.yml / config.toml 里写了 API Key,千万别提交到 Git。
11.2 改代码前先提交一次
git status
git add .
git commit -m "backup before codex changes"
这样即使 Codex 改崩了,也能 git reset 回滚。
11.3 高危命令要盯紧
rm -rf
curl | sh
powershell -Command
Invoke-Expression
chmod -R
sudo
pip install
npm install
Codex 执行这些前会请求批准(approval_policy = "on-request" 的意义就在这),别无脑按回车,看清楚它要干啥。
十二、方案选型建议与总结
12.1 一句话选型
- 你是 Windows 用户,只想赶紧用起来 →
codex-relay,5 分钟搞定 - 你跨平台开发,讨厌手抄配置 →
Moon Bridge,自动生成最香 - 你是 macOS 老手,喜欢精确控工具 →
codex-chat-bridge,--drop-tool-type玩出花 - 你想要完整思维链,愿意改两行源码 →
aliyun-codex-bridge,释放率 ~90%
12.2 全文核心三句话
- Codex 侧永远用
wire_api = "responses"——别再试chat,已死透。 base_url永远指向本地桥接层——别直写 DeepSeek 官方地址。- 中间必须有翻译层——这是协议鸿沟的唯一解,四方案只是翻译官不同。
12.3 为什么 2025 年的教程全失效了
不是博主们写错了,是 Codex 在 v0.130 来了一次"断崖式升级"。技术圈这种事不少见:框架大版本一升,旧教程集体变废纸。所以学技术要学原理,不是学配置——原理懂了,新版本来了你也能自己推导。
本文把原理(第 2 节)、四方案实战(第 5-8 节)、统一踩坑(第 9 节)全给你了,希望你下次遇到类似的"协议不兼容"问题,能第一反应想到"加个翻译层"这个通用思路。
写在最后
Codex CLI 接入 DeepSeek 这件事,本质上是一个协议适配问题。社区四套方案殊途同归,都是在 Codex 和 DeepSeek 之间架一座翻译桥。理解了这个本质,你就不会被各种花哨的配置项吓到——它们只是翻译官的不同"方言"而已。
如果你在实操中遇到本文没覆盖的报错,欢迎在评论区把错误信息贴出来,笔者会持续更新踩坑地图。点赞收藏不迷路,关注一波防走失,后续会继续更新 AI 编程工具实战系列。
技术没有银弹,但有翻译层。祝你的 Codex 早日和 DeepSeek 喜结连理。 🚀
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
6
0- 0
已为社区贡献4条内容
所有评论(0)