Moon Bridge 配置教程：在 Codex 中使用 DeepSeek 模型

概述

Codex 桌面应用从 v0.142 开始仅支持 Responses API（/v1/responses）协议，而 DeepSeek 官方只提供 Chat Completions API（/v1/chat/completions）。两种协议互不兼容，无法直连。

Moon Bridge 是一个轻量本地代理，运行在 Mac 上，负责将 Codex 发出的 Responses 请求实时翻译为 DeepSeek 能理解的 Chat 请求，使得在 Codex 桌面 App 中直接使用 DeepSeek 模型成为可能。

通讯拓扑如下：

Codex 桌面 App → Moon Bridge (127.0.0.1:38440) → DeepSeek API

前置条件

macOS 操作系统
Homebrew 包管理器（用于安装 Go）
DeepSeek API Key（从 DeepSeek 开发者平台获取）

安装步骤

第一步：安装 Go 语言

Moon Bridge 使用 Go 编写，需要先安装 Go 运行环境：

brew install go

验证安装：

go version
# 输出示例：go version go1.22.x darwin/arm64

第二步：克隆 Moon Bridge 仓库

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

第三步：创建配置文件

在项目根目录创建 config.yml，填入 DeepSeek API Key：

mode: "Transform"

server:
  addr: "127.0.0.1:38440"

models:
  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

  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

providers:
  deepseek:
    base_url: "https://api.deepseek.com/anthropic"
    api_key: "sk-你的DeepSeekAPIKey粘贴到这里"
    offers:
      - model: deepseek-v4-flash
      - model: deepseek-v4-pro

routes:
  moonbridge:
    model: deepseek-v4-flash
    provider: deepseek

defaults:
  model: moonbridge
  max_tokens: 65536

配置说明

字段	说明
`server.addr`	Moon Bridge 监听地址，默认使用本地 38440 端口
`models.*`	定义可用模型及其参数，包括上下文窗口、最大输出 Token、推理级别等
`providers.deepseek.base_url`	DeepSeek API 端点，固定为 `https://api.deepseek.com/anthropic`
`providers.deepseek.api_key`	替换为你的真实 API Key
`routes.moonbridge`	默认路由，指定使用的模型和供应商
`defaults.model`	默认生效的模型路由名称
`defaults.max_tokens`	每次请求的最大输出 Token 数

第四步：启动 Moon Bridge

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

启动后 Moon Bridge 将监听 127.0.0.1:38440，暴露兼容 Responses API 的端点。终端需要保持运行，关闭后 Codex 将无法连接。

提示：首次启动需要下载依赖，耗时取决于网络状况。后续启动会直接使用已缓存的模块。

第五步：生成 Codex 配置

保持 Moon Bridge 运行，另开一个终端窗口执行以下命令，自动生成 Codex 配置文件：

# 定义 Codex 配置目录
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

# 获取当前 Moon Bridge 暴露的模型名称
MODEL="$(go run ./cmd/moonbridge --config config.yml --print-codex-model)"

# 生成 Codex 配置
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"

配置生成完毕后，重新打开 Codex 桌面 App，它将自动通过 Moon Bridge 代理连接 DeepSeek。

模型切换

使用 Flash 模型

按上述步骤配置完成后，默认使用 deepseek-v4-flash 模型。如需确认，检查 routes 段：

routes:
  moonbridge:
    model: deepseek-v4-flash    # 使用 Flash 模型
    provider: deepseek

切换到 Pro 模型

将路由中的模型改为 deepseek-v4-pro：

routes:
  moonbridge:
    model: deepseek-v4-pro    # 切换到 Pro 模型
    provider: deepseek

修改后需要重启 Moon Bridge（Ctrl+C 停止，重新运行 go run ./cmd/moonbridge --config config.yml），然后重新打开 Codex 桌面 App。

配置多路由（同时支持 Flash 和 Pro）

如果需要在不修改配置文件的情况下切换模型，可以定义多条路由：

routes:
  flash:
    model: deepseek-v4-flash
    provider: deepseek
  pro:
    model: deepseek-v4-pro
    provider: deepseek

defaults:
  model: flash    # 默认使用 Flash

多路由配置完成后，需要重新执行配置生成命令，让 Codex 识别到多个可用模型。之后即可在 Codex 桌面 App 的模型选择器中自由切换。

后台持久化运行

Moon Bridge 终端不能关闭，否则 Codex 无法连接。建议以下两种方式持久化运行。

方式一：tmux 会话

# 安装 tmux
brew install tmux

# 创建独立会话
tmux new-session -d -s moonbridge 'cd ~/moonbridge && go run ./cmd/moonbridge --config config.yml'

方式二：launchd 开机自启

创建 plist 文件 ~/Library/LaunchAgents/com.moonbridge.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.moonbridge</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/go</string>
        <string>run</string>
        <string>./cmd/moonbridge</string>
        <string>--config</string>
        <string>/Users/你的用户名/moonbridge/config.yml</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/你的用户名/moonbridge</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/moonbridge.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/moonbridge.log</string>
</dict>
</plist>

加载自启服务：

launchctl load ~/Library/LaunchAgents/com.moonbridge.plist

验证配置

启动 Moon Bridge 和 Codex 后，可通过以下方式验证连通性：

检查 Moon Bridge 日志：终端输出应显示服务启动信息，无连接错误。
Codex 桌面 App 状态：打开 Codex，如配置正确，模型选择器中应出现 Moon Bridge 映射的模型名称。
发送测试消息：在 Codex 中发起一次对话，观察 Moon Bridge 终端是否打印请求转发日志。

常见问题

连接被拒绝

确认 Moon Bridge 正在运行：检查 38440 端口是否在监听：

lsof -nP -iTCP:38440 -sTCP:LISTEN

确认 Codex 配置文件中的 base_url 正确指向 http://127.0.0.1:38440/v1。

API 认证失败

检查 config.yml 中的 api_key 是否正确。
确认 DeepSeek 账户余额充足，API Key 未过期。
可在终端直接测试 API 连通性：

curl https://api.deepseek.com/anthropic/v1/models \
  -H "Authorization: Bearer sk-你的DeepSeekAPIKey"

模型不可用

确认 models 段中定义的模型名称与 routes 中引用的名称一致。
多路由配置下，确认 Codex 配置已重新生成。

概述