使用 Moon Bridge 将 OpenAI Codex 接入 DeepSeek V4:Responses API 转发层配置实战指南
使用 Moon Bridge 将 OpenAI Codex 接入 DeepSeek V4:Responses API 转发层配置实战指南
Codex 是 OpenAI 官方推出的编程 Agent(支持 CLI 与 App 两种形态),其与模型通信走 OpenAI Responses API,因此接入 DeepSeek 需要一个转发层来完成协议转换与路由。本文基于 awesome-deepseek-agent 仓库中的接入指南 docs/codex.md,以开源项目 Moon Bridge 为转发层,完整讲解从环境安装、config.yml 编写、Codex 配置生成到启动验证与故障排查的全流程。读完本文,你将能在几分钟内让 Codex 使用 DeepSeek-V4-Pro / DeepSeek-V4-Flash 完成编码任务,并理解其中每个配置项的语义。
接入背景:为什么 Codex 需要转发层
Codex 由 OpenAI 开发,使用 OpenAI Responses API 与底层模型通信,而非直接使用 DeepSeek 的 API 协议。要让 Codex 调用 DeepSeek 模型,必须在两者之间插入一个转发层:Codex 把 Responses 请求发给转发层,转发层完成请求转换并路由到 DeepSeek,再把响应回传给 Codex。
本指南是 awesome-deepseek-agent 仓库(README)中"DeepSeek 接入主流 AI Agent 与编程助手工具"系列指南之一,仓库目录表(README.zh-CN.md)将该指南定位为 Codex 工具的官方接入文档。整个请求链路为:
Codex CLI / App
│ OpenAI Responses API 请求
▼
Moon Bridge(本地监听 127.0.0.1:38440)
│ 转换并转发
▼
DeepSeek API(base_url: https://api.deepseek.com/anthropic)
Moon Bridge 以 Transform 模式运行,将 Responses 协议请求转换为 DeepSeek 可处理的调用,并透传模型能力元数据(上下文窗口、推理档位等)。
第一步:安装依赖
搭建环境需要以下组件:
- Node.js 18+:用于安装 Codex CLI。
- Go 1.25+:用于构建并运行 Moon Bridge。
- Codex CLI:OpenAI 官方编程 Agent 的命令行版本。
安装 Codex CLI:
npm install -g @openai/codex
安装后验证两个关键依赖是否就绪:
codex --version
go version
codex --version 确认 CLI 可用,go version 确认 Go 工具链版本满足 Moon Bridge 的构建要求(1.25+)。
第二步:获取 DeepSeek API Key
前往 DeepSeek 开放平台的 API Keys 管理页面,创建一个 API Key 并复制保存。该 Key 将在下一步写入 Moon Bridge 的 config.yml,用于 DeepSeek 侧的鉴权;后续若遇到 401 认证错误,通常就是这一项配置有误。
第三步:配置 Moon Bridge
克隆 Moon Bridge 仓库并进入其目录:
git clone https://github.com/ZhiYi-R/moon-bridge.git
cd moon-bridge
在 Moon Bridge 目录下创建 config.yml,填入你的 DeepSeek API Key:
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-your-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
配置结构逐段解读
这份最小配置采用 Moon Bridge 当前(新版)的配置结构,顶层由 mode、server、models、providers、routes、defaults 六大段组成,各段职责如下:
| 配置段 | 作用 | 本示例关键值 |
|---|---|---|
mode |
运行模式 | "Transform",启用协议转换 |
server.addr |
本地监听地址 | 127.0.0.1:38440 |
models |
对外暴露的模型能力元数据 | deepseek-v4-pro、deepseek-v4-flash |
providers |
上游供应商配置 | DeepSeek 的 base_url 与 api_key |
routes |
请求路由规则 | 路由 moonbridge 指向 deepseek-v4-pro + deepseek |
defaults |
默认模型与默认输出上限 | model: moonbridge、max_tokens: 65536 |
**模型能力元数据段(models)**中的每个模型条目定义了 Codex 侧可见的能力属性:
context_window: 1000000:100 万 token 上下文窗口。这与仓库 CONTRIBUTING.md 中"DeepSeek V4 系列支持 100 万 token 上下文,OpenAI 兼容配置应设置context_window: 1000000"的规范完全一致。max_output_tokens: 384000:单次最大输出 token 数,对应 CONTRIBUTING 中 OpenAI 兼容配置建议的max_tokens: 384000取值。default_reasoning_level: "high"与supported_reasoning_levels:声明默认推理档位及支持的档位集合(high、xhigh),供 Codex 选择推理强度。supports_reasoning_summaries: true与default_reasoning_summary: "auto":启用并默认使用"推理摘要"能力。extensions.deepseek_v4.enabled: true:启用 DeepSeek V4 兼容扩展,这是让模型元数据适配 DeepSeek V4 的关键开关。
**供应商段(providers)**指定上游的真实请求目标:base_url 指向 DeepSeek 的 Anthropic 兼容端点,api_key 填入第二步获取的 Key,offers 声明该供应商可提供的模型。
**路由段(routes)**把对外模型名映射到具体供应商与模型:路由 moonbridge 默认路由到 deepseek-v4-pro(供应商 deepseek)。**默认段(defaults)**设置请求未显式指定时的兜底模型与输出上限。
注意:此配置是接入 Codex 的最小可用集。如果需要图片输入、Web Search 或多 Provider 路由,需参考 Moon Bridge 自带的
config.example.yml扩展对应配置段(例如图片输入依赖 Visual 扩展与额外的视觉 Provider,详见后文"常见问题")。
模型命名与配置一致性
本配置统一使用 deepseek-v4-pro / deepseek-v4-flash 两个当前模型名。仓库 CONTRIBUTING.md 明确要求所有指南使用现行命名(deepseek-chat / deepseek-reasoner 等 V3 旧名已废弃),配置中的模型名、路由名必须与此保持一致,否则 Codex 侧将无法识别模型。
第四步:启动 Moon Bridge
在 Moon Bridge 目录下启动服务:
go run ./cmd/moonbridge --config config.yml
保持该终端持续运行。默认情况下 Moon Bridge 监听 127.0.0.1:38440,对外暴露 OpenAI Responses 兼容端点:
http://127.0.0.1:38440/v1/responses
该端点即后续 Codex 请求的落点,也是本文"验证"环节直接 curl 测试的对象。
第五步:生成 Codex 配置
Codex 需要自己的配置文件才能把请求导向 Moon Bridge。另开一个终端,在 Moon Bridge 目录下执行命令,将 Codex 的 config.toml 与 models_catalog.json 写入 CODEX_HOME_DIR。
如果你已有 Codex 配置,务必先备份当前 config.toml。
macOS / Linux:
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME_DIR"
# 备份当前 config.toml
cp "$CODEX_HOME_DIR/config.toml" "$CODEX_HOME_DIR/config.toml.bak" 2>/dev/null || true
# 创建 config.toml 和 models_catalog.json
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" }
New-Item -ItemType Directory -Force -Path $CODEX_HOME_DIR | Out-Null
# 备份当前 config.toml
if (Test-Path "$CODEX_HOME_DIR\config.toml") {
Copy-Item "$CODEX_HOME_DIR\config.toml" "$CODEX_HOME_DIR\config.toml.bak" -Force
}
# 创建 config.toml 和 models_catalog.json
$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"
命令参数与产物说明
该流程涉及 Moon Bridge 的两个专用 CLI 标志,作用如下:
| 参数 | 作用 |
|---|---|
--print-codex-model |
输出 Moon Bridge 读到的默认 Codex 模型名(默认即路由名 moonbridge) |
--print-codex-config <MODEL> |
按指定模型生成 Codex 的 config.toml 内容 |
--codex-base-url |
指定 Codex 请求的转发目标,即 Moon Bridge 的 /v1 端点 |
--codex-home |
指定 Codex 配置目录(CODEX_HOME_DIR),生成的 models_catalog.json 也会写入此处 |
命令执行后将产生两个文件:
config.toml:Codex 的 Provider 配置,使用wire_api = "responses"声明走 OpenAI Responses 协议,base_url指向http://127.0.0.1:38440/v1。models_catalog.json:Codex 使用的模型能力元数据,包括上下文窗口、推理档位(reasoning levels)与工具支持信息,内容来源于config.yml的models段。
生成之前,可以先单独确认 Moon Bridge 读取到的默认 Codex 模型:
go run ./cmd/moonbridge --config config.yml --print-codex-model
# moonbridge
输出 moonbridge 说明默认模型即路由段定义的名称,与 defaults.model 保持一致。
第六步:启动 Codex
进入你要处理的项目目录,启动 Codex:
cd /path/to/my-project
codex
此时 Codex 会把 OpenAI Responses 请求发送给 Moon Bridge,由 Moon Bridge 路由到 DeepSeek V4。Codex App 也可以复用同一份生成的 Codex 配置(同样的 config.toml 与 models_catalog.json),无需额外生成。
一键启动脚本
Moon Bridge 还提供了面向 Codex CLI 的辅助脚本,可一键完成"构建并启动代理 → 生成 Codex 配置 → 启动 Codex"全流程:
./scripts/start_codex_with_moonbridge.sh --project-directory /path/to/my-project
Windows PowerShell 用户对应使用:
.\scripts\start_codex_with_moonbridge.ps1 -ProjectDirectory C:\path\to\my-project
验证:确认转发链路与推理档位生效
1. 查看可用模型
curl http://127.0.0.1:38440/v1/models
应能列出 moonbridge(或 config.yml 中声明的模型),确认模型元数据已成功注册。
2. 直接发送 Responses 测试请求
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
}'
返回 DeepSeek 的生成结果即代表链路通畅。当 Codex 发出请求后,Moon Bridge 终端应出现 POST /v1/responses 日志行,这是转发生效的直接证据。
3. 验证推理档位透传
在请求体中显式携带 reasoning 字段:
curl http://127.0.0.1:38440/v1/responses \
-H "Content-Type: application/json" \
-d '{
"model": "moonbridge",
"input": "Explain what Moon Bridge does in one sentence.",
"reasoning": {"effort": "high"},
"max_output_tokens": 1024
}'
reasoning.effort: "high" 对应 config.yml 中 supported_reasoning_levels 声明的档位。仓库 CONTRIBUTING.md 同时指出,OpenAI 兼容端点应尽可能在请求体中携带 reasoning_effort 以发挥 DeepSeek V4 的深度思考能力,这里通过 reasoning 字段实现的档位透传即是对该能力的一种落地验证方式。
常见问题排查
| 现象 | 原因与处理 |
|---|---|
connection refused |
Moon Bridge 未启动,或 config.yml 中 server.addr 使用了其他端口,导致 Codex 请求无法到达。确认服务已运行且端口一致。 |
| Codex 看不到模型 | 重新执行第五步;Codex 需要 CODEX_HOME 目录下的 models_catalog.json 才能识别模型能力元数据。 |
配置加载失败:field provider not found |
使用的是旧版 provider.providers 嵌套格式。当前配置结构是顶层 providers、models、routes、defaults 四段,需按本文的 config.yml 结构重写。 |
401 或认证失败 |
检查 config.yml 中 providers.deepseek.api_key 是否正确,与第二步创建的 Key 核对。 |
402 或余额错误 |
检查 DeepSeek 开放平台账户余额是否充足。 |
| 图片输入失败 | 若启用了 Visual 扩展,需要单独配置一个视觉 Provider(如 Kimi)并填入其 API Key;可配置该 Provider,或移除 visual.enabled: true 以禁用 Visual 扩展。 |
资源与延伸阅读
- Moon Bridge:本文使用的转发层项目,负责 Responses 协议转换与模型路由,配置细节以其
config.example.yml为准。 - Codex CLI:OpenAI 官方编程 Agent 的命令行版本(
npm install -g @openai/codex)。 - DeepSeek API 文档:模型能力(1M 上下文、推理档位)与鉴权的官方参考。
上述内容的仓库级背景可进一步参考:README.md(指南总览与工具目录)、README.zh-CN.md(中文版目录)、CONTRIBUTING.md(模型命名、100 万上下文窗口、推理档位等接入规范)。