使用 Moon Bridge 将 OpenAI Codex 接入 DeepSeek V4:Responses API 转发层配置实战指南

原创2026-09-16 15:56:311,933 阅读
文章标签:文档教程大模型DeepSeek

使用 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 万上下文窗口、推理档位等接入规范)。

登录后查看全文
awesome-deepseek-agent