让 Codex 用上 DeepSeek：Moon Bridge 配置完全指南「零门槛上手」

写在前面：本文专为「想体验 Codex 编程助手，但不想或不能用 OpenAI」的朋友准备。全程图文+命令复制，小白也能 30 分钟搞定！

适用版本：本文基于 DeepSeek API 2026年6月版本，deepseek-chat 和 deepseek-reasoner 将于 2026/07/24 弃用，建议迁移到新模型名称。

为什么要搞这个方案？

你可能遇到的痛点：

• 想用 OpenAI 的 Codex CLI（超好用的编程 Agent）
• 但 OpenAI API 贵 / 网络不稳定 / 不想绑卡
• 手上有 DeepSeek API（性价比高，中文友好）
• 但 Codex 只认 OpenAI 接口，不直接支持 DeepSeek

先搞清楚三个核心概念

在动手之前，咱们先花 1 分钟搞清楚今天要装的三样东西各自是干嘛的：

工具	一句话解释	角色
Codex CLI	OpenAI 出的命令行 AI 编程助手，在你的终端里帮你写代码、改代码、回答问题	相当于你终端里的「编程助手」
Moon Bridge	一个协议转换代理，把 OpenAI 的请求翻译成 DeepSeek 能懂的格式	相当于一个「翻译官」
DeepSeek	国产大模型，性价比极高，API 价格便宜到可以随便用	相当于「引擎」，提供 AI 能力

为什么需要 Moon Bridge？

因为 Codex 默认只认 OpenAI 的接口格式，DeepSeek 说的是另一套"语言"，Moon Bridge 就是一个翻译官，让你用 DeepSeek 的价格享受 Codex 的体验。

成本对比：OpenAI 官方模型调用一次可能要几块钱，DeepSeek 可能只要几分钱。

---

第一步：安装必备工具

1.1 安装 Node.js（为安装 Codex 做准备）

macOS用户：

# 如果装了 Homebrew
brew install node

# 没装 Homebrew? 去官网下载安装包
# https://nodejs.org/en/download/

Windows 用户： 直接去 Node.js 官网 下载安装包，一路点「下一步」就行。

Linux 用户：

# Ubuntu / Debian
sudo apt update && sudo apt install nodejs npm -y

# 或者用 nvm（推荐，方便切换版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 18

验证安装：

node --version   # 应该显示 v18.x.x 或更高
npm --version    # 应该显示 9.x.x 或更高

1.2 安装 Go「运行 Moon Bridge」

macOS 用户：

brew install go

Windows 用户： 去 Go 官网 下载 .msi 安装包，一路「下一步」。

Linux 用户：

# 下载（以 go1.26.3 为例，去官网看最新版）
wget https://go.dev/dl/go1.26.3.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.26.3.linux-amd64.tar.gz

# 加到 PATH（加到 ~/.bashrc 或 ~/.zshrc 里）
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

验证安装：

go version   # 应该显示 go1.26.x 或更高

1.3 安装 Codex CLI

npm install -g @openai/codex

验证：

codex --version

---

第二步：获取 DeepSeek API Key

API Key 就像身份证号，让 Moon Bridge 有权限调用 DeepSeek 的服务。

1. 访问 DeepSeek 开放平台
2. 注册/登录账号
3. 点击「创建 API Key」→ 复制保存好（只显示一次！）

把 API Key 记下来，格式类似：sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

---

第三步：配置并启动 Moon Bridge（核心步骤）

3.1 下载 Moon Bridge

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

3.2 创建配置文件

在 moon-bridge 目录下新建一个文件，叫 config.yml，把下面内容复制进去：

⚠️ 注意：把 sk-your-deepseek-api-key 替换成你第二步拿到的真实 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"   # 👈替换成你的真实 Key！
    offers:
      - model: deepseek-v4-pro
      - model: deepseek-v4-flash

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

defaults:
  model: moonbridge
  max_tokens: 65536

这个配置文件在说什么？（小白可跳过）

• mode: "Transform" → Moon Bridge 做翻译官模式
• server.addr → 在本机 38440 端口运行
• models → 告诉 Codex 「我这有个叫 deepseek-v4-pro 的模型，能力很强」
• providers → 告诉 Moon Bridge 「请求转发到 DeepSeek，用这个 API Key」
• routes → 「当 Codex 请求 moonbridge 这个模型时，实际调用 deepseek-v4-pro」

3.3 启动 Moon Bridge

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

看到类似这样的输出：

"HTTP 服务器监听中" addr=127.0.0.1:38440

⚠️ 这个终端不要关！ 让它一直跑着。另开一个终端做后面的步骤。

3.4 测试一下 Moon Bridge 是否正常

新开一个终端，运行：

curl http://localhost:38440/v1/models

如果返回了一堆 JSON 数据，说明 Moon Bridge 跑起来了

再发一条消息试试：

curl http://localhost:38440/v1/responses -H "Content-Type: application/json" -d "{\"model\": \"moonbridge\", \"input\": \"你好，请用一句话介绍你自己。\", \"max_output_tokens\": 100}"

看到返回内容里有 AI 的回复就说明整个链路通了 🎉

---

第四步：配置 Codex CLI 连上 Moon Bridge

4.1 生成 Codex 配置「手动」

还是在 moon-bridge 目录下，运行：

macOS / Linux 用户：

# 1. 设置 Codex 配置目录
CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}"
mkdir -p "$CODEX_HOME_DIR"

# 2. 备份旧配置（首次可跳过）
cp "$CODEX_HOME_DIR/config.toml" "$CODEX_HOME_DIR/config.toml.bak" 2>/dev/null || true

# 3. 生成新配置（核心命令！）
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 用户：

# 1. 设置 Codex 配置目录
$CODEX_HOME_DIR = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$HOME\.codex" }
New-Item -ItemType Directory -Force -Path $CODEX_HOME_DIR | Out-Null

# 2. 备份旧配置
if (Test-Path "$CODEX_HOME_DIR\config.toml") {
  Copy-Item "$CODEX_HOME_DIR\config.toml" "$CODEX_HOME_DIR\config.toml.bak" -Force
}

# 3. 生成新配置
$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"

这一步会在 ~/.codex/ 目录下生成两个文件：

• config.toml — 告诉 Codex 「你的 AI 后端在这里」
• models_catalog.json — 告诉 Codex 「你可以用这些模型」

一键启动脚本「推荐」

两种方式任选其一：手动配置（更透明）或一键脚本（更傻瓜）。新手推荐一键脚本。

Moon Bridge 提供了更方便的启动脚本：

一键构建并启动代理、生成 Codex 配置并启动 Codex。

macOS/Linux 用户：

# 1. 确保在 moon-bridge 目录，且 config.yml 已配置
cd moon-bridge

# 2. 执行脚本（替换为你的项目路径）
./scripts/start_codex_with_moonbridge.sh --project-directory /path/to/your-project

Windows PowerShell 用户：

# 1. 确保在 moon-bridge 目录，且 config.yml 已配置
cd moon-bridge

# 2. 执行脚本（替换为你的项目路径）
.\scripts\start_codex_with_moonbridge.ps1 -ProjectDirectory C:\path\to\your-project

4.2 启动 Codex

进入你想写代码的项目目录，然后启动：

# 进入任意项目目录（或新建测试目录）
mkdir ~/codex-test && cd ~/codex-test

# 启动 Codex
codex

看到 Codex 的交互界面，随便问个问题试试：

> 帮我写一个 Python 的 Hello World

如果 Codex 正常回复了，而且 Moon Bridge 那边的终端出现了 流式请求完成 的日志，恭喜你，大功告成！

---

进阶玩法

开启深度推理

如果你的问题比较复杂，可以让 DeepSeek V4 开启深度推理模式。上面给的配置已经默认开启了 high 级别推理。

想让模型想得更深？把请求里的 reasoning.effort 改成 xhigh：

curl http://localhost:38440/v1/responses -H "Content-Type: application/json" -d "{\"model\": \"moonbridge\", \"input\": \"请分析这段代码的时间复杂度...\", \"reasoning\": {\"effort\": \"xhigh\"}, \"max_output_tokens\": 100}"

xhigh 推理更深但也更慢更贵，日常用 high 就够了。

添加图片理解能力

DeepSeek 本身是纯文本模型，但 Moon Bridge 可以搭配一个视觉模型来处理图片。你需要额外申请一个 Kimi（月之暗面）的 API Key。

在 config.yml 中加入：

# 在已有 config.yml 的 extensions: 块下，添加 visual 子块：
extensions:
  visual:
    config:
      provider: "kimi"
      model: "kimi-for-coding"
      max_rounds: 4
      max_tokens: 2048

models:
  kimi-for-coding:
    context_window: 128000

providers:
  # ... 保留原来的 deepseek ...
  kimi:
    base_url: "https://api.moonshot.ai/anthropic"
    api_key: "sk-your-kimi-api-key"
    offers:
      - model: kimi-for-coding

然后在 deepseek-v4-pro 的 extensions 里加上 visual: { enabled: true }。

添加联网搜索

想模型能搜网页？注册一个免费的 Tavily API Key，然后在 config.yml 顶层加上：

web_search:
  support: "injected"
  tavily_api_key: "tvly-your-api-key"

支持更多模型（如 Qwen / Kimi）

在 config.yml 的 models 和 providers.offers 中添加：

# 示例：添加通义千问（需阿里云兼容接口）
models:
  qwen-max:
    context_window: 32768
    max_output_tokens: 8192
    default_reasoning_level: "medium"
    extensions:
      qwen: { enabled: true }

providers:
  aliyun:
    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    api_key: "${DASHSCOPE_API_KEY}"
    offers:
      - model: qwen-max

开启请求追踪（调试神器）

# config.yml 顶部添加
trace:
  enabled: true
  output_dir: "./data/trace"

重启后，所有请求/响应 JSON 会保存到 data/trace/，方便复盘分析。

---

结语

来回顾一下你刚刚搭好的东西：

🚀 恭喜你！ 现在已经成功让 Codex + DeepSeek 强强联合，既能享受 Codex 的编程体验，又能用高性价比的国产大模型！

下一步你可以：

• 在真实项目里用 Codex 写代码、改 BUG
• 探索 Moon Bridge 的更多功能（图片理解、联网搜索、切换其他模型）
• 把 Codex 当成日常编程搭档，告别复制粘贴 ChatGPT 的日子

---

预告：更简单的一键切换方案（下一篇）

如果你觉得手动编辑 config.yml、管理配置文件有点麻烦，或者想一键在 OpenAI 和 DeepSeek 之间切换，那么请关注下一篇教程：

《CC-Switch 可视化配置：让 Codex 玩转多模型，一键切换 DeepSeek》

CC-Switch 是什么？

• 图形界面：不用写配置文件，点点鼠标就搞定
• 一键切换：DeepSeek、OpenAI、Kimi 等多个供应商随时切换
• 自动管理：自动配置 Codex 的 config.toml 和 auth.json

版本要求：需要 CC-Switch v3.16.0 及以上版本（2026年5月29日发布）才支持 Codex 接入 DeepSeek。

两种方案对比：

方案	适合人群	上手难度	灵活性	版本要求
Moon Bridge（本文）	喜欢手动控制、需要深度定制的用户	⭐⭐⭐	⭐⭐⭐⭐⭐	任意版本
CC-Switch（下篇）	追求简单快捷、想一键切换的用户	⭐	⭐⭐⭐	v3.16.0+