ByteNoteByteNote
Codex CLI 接入 DeepSeek V4：通过 Moon Bridge 转发层完整指南
字

字节笔记本

2026年5月25日

Codex CLI 接入 DeepSeek V4：通过 Moon Bridge 转发层完整指南

#AI 前沿
API中转
¥120

这篇文章将介绍如何通过 Moon Bridge 将 OpenAI Codex CLI 接入 DeepSeek V4 模型，让 Codex 使用 DeepSeek 的高性能推理能力完成编程任务。整个过程涉及 Moon Bridge 的配置搭建、Codex 配置生成和链路验证。

背景：为什么需要转发层

OpenAI Codex 使用 OpenAI Responses API 与模型通信。如果你希望 Codex 使用第三方模型（如 DeepSeek V4），就需要一个转发层来处理协议转换。Moon Bridge 正是这样一个桥梁——它将 OpenAI Responses API 请求转换为目标模型平台的请求格式，并将响应转换回来。

前置依赖

需要安装以下工具：

  • Node.js 18+：Codex CLI 的运行环境
  • Go 1.25+：Moon Bridge 的编译和运行环境
  • Codex CLI：OpenAI 的编程 Agent
bash
# 全局安装 Codex CLI
npm install -g @openai/codex

# 验证安装
codex --version
go version

获取 DeepSeek API Key

前往 DeepSeek 开放平台 注册账号，创建并复制 API Key。DeepSeek V4 系列提供了 Pro 和 Flash 两个档位的模型，分别适用于深度推理和快速响应场景。

配置 Moon Bridge

Moon Bridge 是一个用 Go 编写的 API 转发层，支持灵活的模型路由和协议转换。

克隆项目

bash
git clone https://github.com/ZhiYi-R/moon-bridge.git
cd moon-bridge

创建配置文件

在项目根目录创建 config.yml，填入 DeepSeek API Key 和模型配置：

yaml
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

配置说明：

  • models：定义模型的元数据，包括上下文窗口（100 万 token）、最大输出 token、推理档位等
  • providers：配置提供商信息，base_url 指向 DeepSeek 的 Anthropic 兼容接口
  • routes：定义路由规则，将 moonbridge 模型路由到 DeepSeek Provider 的 deepseek-v4-pro 模型
  • extensions.deepseek_v4：启用 DeepSeek V4 兼容扩展

如果需要图片输入、Web Search 或多 Provider 路由，可以参考 Moon Bridge 项目中的 config.example.yml 扩展配置。

启动 Moon Bridge

在项目目录下执行：

bash
go run ./cmd/moonbridge --config config.yml

保持这个终端运行。默认监听 127.0.0.1:38440，并提供 OpenAI Responses 兼容接口：

http://127.0.0.1:38440/v1/responses

生成 Codex 配置

另开一个终端，同样在 Moon Bridge 目录下执行以下命令，将 Codex 配置写入 CODEX_HOME 目录。

macOS / Linux

bash
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

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
}

# 创建配置
$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"

这条命令会生成两个文件：

  • config.toml：Codex Provider 配置，使用 wire_api = "responses" 模式
  • models_catalog.json：Codex 使用的模型能力元数据，包含上下文窗口、推理档位和工具支持信息

可以先查看 Moon Bridge 读取到的默认 Codex 模型名：

bash
go run ./cmd/moonbridge --config config.yml --print-codex-model
# moonbridge

启动 Codex

进入要处理的项目目录，启动 Codex：

bash
cd /path/to/my-project
codex

此时 Codex 会把所有 OpenAI Responses API 请求发送给 Moon Bridge（http://127.0.0.1:38440/v1/responses），再由 Moon Bridge 路由到 DeepSeek V4。整个过程对 Codex 完全透明——它认为自己在与 OpenAI API 通信。

Codex App（桌面版）也可以使用同一份生成的配置，无需额外设置。

一键启动脚本

Moon Bridge 提供了面向 Codex CLI 的辅助脚本，可以一键构建启动 Moon Bridge、生成 Codex 配置并启动 Codex：

bash
./scripts/start_codex_with_moonbridge.sh --project-directory /path/to/my-project

Windows PowerShell 用户：

powershell
.\scripts\start_codex_with_moonbridge.ps1 -ProjectDirectory C:\path\to\my-project

验证链路

查看可用模型

bash
curl http://127.0.0.1:38440/v1/models

发送基本测试请求

bash
curl http://127.0.0.1:38440/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonbridge",
    "input": "请用一句话打个招呼。",
    "max_output_tokens": 1024
  }'

当 Codex 发出请求后，Moon Bridge 终端应出现 POST /v1/responses 日志。

测试推理档位

验证推理档位是否正常进入配置：

bash
curl http://127.0.0.1:38440/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "moonbridge",
    "input": "用一句话说明 Moon Bridge 的作用。",
    "reasoning": {"effort": "high"},
    "max_output_tokens": 1024
  }'

常见问题

connection refused

Moon Bridge 未启动，或 config.yml 中的 server.addr 使用了其他端口。检查 Moon Bridge 终端是否在运行，以及端口是否一致。

Codex 看不到模型

重新执行配置生成步骤。Codex 需要 CODEX_HOME 目录下的 models_catalog.json 文件才能识别可用模型。

配置加载失败提示 field provider not found

使用了旧版的 provider.providers 配置格式。当前正确的格式是顶层的 providers、models、routes、defaults 结构。

401 认证失败

检查 config.yml 中的 DeepSeek API Key 是否正确。注意 DeepSeek 平台区分 API Key 类型，确保使用的是有 DeepSeek V4 模型访问权限的 Key。

402 余额不足

登录 DeepSeek 开放平台 检查账户余额。DeepSeek V4 按 token 计费，需要确保账户有足够的额度。

图片输入失败

如果启用了 Visual 扩展，需要单独配置视觉 Provider（如 Kimi）的 API Key。可以单独配置该视觉 Provider，或移除 visual.enabled: true 来禁用 Visual 扩展。

AI 前沿
上一篇

海外工具站：一个跑通的小副业方向（2026 实操指南）

下一篇

Codex CLI 接入 DeepSeek V4：通过 Moon Bridge 转发层完整指南

分享: