零成本接入Codex：使用Moon Bridge转发层连接DeepSeek API

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Claude 随心用，限时 5 折。 👉 点击领海量免费额度

最近在尝试使用 OpenAI 的 Codex 智能编程助手时，发现其官方模型调用成本对于个人开发者或小团队来说确实是一笔不小的开销。有没有一种方法，既能享受 Codex 强大的代码生成和对话能力，又能大幅降低成本呢？答案是肯定的。通过一个名为 Moon Bridge 的转发层，我们可以将 Codex 的请求无缝转发到 DeepSeek 的 API，从而以极低的成本使用 Codex。本文将手把手带你完成从环境准备、配置、部署到验证的完整流程，让你轻松实现 Codex 与 DeepSeek 的零代码接入。

本文适合所有对 AI 编程助手感兴趣，希望降低使用成本，并具备基本命令行操作能力的开发者。无论你是想为个人项目寻找一个高性价比的代码助手，还是希望为团队探索更经济的 AI 开发工具方案，这篇教程都能提供清晰的指引。接下来，我们将从核心概念讲起，逐步深入到每一个实操步骤。

1. 背景与核心概念

在开始动手之前，我们有必要先理清几个关键概念，理解我们即将搭建的这套系统是如何工作的。

1.1 什么是 Codex？

Codex 是 OpenAI 推出的一款智能编程代理（Coding Agent），它提供了命令行界面（CLI）和桌面应用程序两种形态。与传统的代码补全工具不同，Codex 被设计成一个可以与你对话、理解项目上下文、并执行复杂编码任务的“AI 结对程序员”。你可以通过自然语言向它描述需求，例如“为这个函数添加错误处理”或“写一个 Flask 的登录 API”，它便能生成相应的代码片段甚至完整的文件。

Codex 的核心优势在于其强大的上下文理解能力和与开发环境的深度集成。然而，其官方后端依赖于 OpenAI 的模型，使用成本较高，且对于国内开发者而言，在访问稳定性和速度上也可能面临挑战。

1.2 什么是 DeepSeek？

DeepSeek 是国内深度求索公司推出的一系列高性能大语言模型，以其出色的代码能力和极具竞争力的价格受到开发者社区的广泛关注。DeepSeek 提供了开放的 API，允许开发者直接调用其模型能力。相较于国际同类服务，DeepSeek 在中文理解、本地化支持以及性价比方面具有显著优势。

1.3 Moon Bridge 的作用：关键的转发层

那么，如何让原本设计为连接 OpenAI 的 Codex，转而使用 DeepSeek 的模型呢？这就是Moon Bridge发挥作用的地方。

Moon Bridge 是一个开源项目，其核心功能是作为一个协议转换与请求转发层。它监听本地的特定端口，当 Codex 客户端（遵循 OpenAI Responses API 规范）发送请求时，Moon Bridge 会接收这些请求，将其转换为 DeepSeek API 能够理解的格式，然后转发给 DeepSeek 的服务器。同样地，它也会将 DeepSeek 返回的结果转换回 Codex 客户端期望的格式。

你可以把 Moon Bridge 想象成一个“智能适配器”或“翻译官”。Codex 说“OpenAI 方言”，DeepSeek 说“DeepSeek 方言”，而 Moon Bridge 精通两者，确保了它们之间的顺畅沟通。整个架构的流程图如下所示：

[Codex CLI/App] --(OpenAI Responses API)--> [Moon Bridge (localhost:38440)] --(DeepSeek API)--> [DeepSeek Cloud]

通过这种方式，我们实现了零代码修改接入。你不需要改动 Codex 客户端的任何一行代码，只需要通过配置，告诉 Codex 你的“OpenAI 兼容服务”地址是本地运行的 Moon Bridge 即可。

2. 环境准备与前置条件

在开始配置之前，请确保你的开发环境满足以下要求。我们将分别针对 macOS/Linux 和 Windows 系统给出说明。

2.1 系统与工具要求

1. Node.js 18+: Codex CLI 是基于 Node.js 开发的，因此需要先安装 Node.js。你可以访问 Node.js 官网 下载安装包，或使用包管理器安装（如brew install node在 macOS 上）。安装后，在终端运行node --version确认版本。
2. Go 1.25+: Moon Bridge 是用 Go 语言编写的，因此需要 Go 环境来运行它。访问 Go 官网 下载并安装。安装后，运行go version确认版本。
3. Git: 用于克隆 Moon Bridge 的代码仓库。通常系统已自带，可通过git --version检查。
4. 终端（Terminal）或 PowerShell: 用于执行命令。
5. 一个有效的 DeepSeek API Key: 这是调用 DeepSeek 模型的凭证。你需要前往 DeepSeek 开放平台 注册账号并创建 API Key。请妥善保管此 Key。

2.2 安装 Codex CLI

打开你的终端，使用 npm（Node.js 的包管理器）全局安装 Codex CLI：

npm install -g @openai/codex

安装完成后，验证是否安装成功：

codex --version

如果安装正确，该命令会输出 Codex 的版本号。

2.3 获取 DeepSeek API Key

1. 访问 DeepSeek 开放平台 。
2. 登录你的账户（如果没有，请先注册）。
3. 在控制台界面，找到“API Keys”或类似的管理页面。
4. 点击“创建新的 API Key”，为其命名（例如“MyCodexIntegration”）。
5. 创建成功后，系统会生成一个以sk-开头的密钥字符串。请立即复制并保存到安全的地方，因为关闭页面后可能无法再次查看完整密钥。

至此，基础环境与凭证准备完毕。接下来，我们将进入核心的配置环节。

3. 配置 Moon Bridge 转发层

Moon Bridge 是我们整个方案的核心枢纽，配置它主要分为三个步骤：获取源码、编写配置文件、启动服务。

3.1 克隆 Moon Bridge 仓库

在终端中，选择一个你喜欢的目录，执行以下命令克隆项目：

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

这会将 Moon Bridge 的源代码下载到当前目录下的moon-bridge文件夹中，并进入该目录。

3.2 创建并编辑配置文件

Moon Bridge 的配置通过一个 YAML 文件（config.yml）来定义。我们需要创建这个文件并填入必要的参数，特别是你的 DeepSeek API Key。

在moon-bridge目录下，使用你喜欢的文本编辑器（如 VSCode、Vim、Nano）创建并打开config.yml文件。

# 例如，使用 nano 编辑器 nano 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

配置文件详解：

• server.addr: 定义了 Moon Bridge 服务监听的地址和端口，默认为本地的38440端口。你可以按需修改。
• models: 定义了 Moon Bridge 向 Codex “宣称”的模型能力。这里配置了deepseek-v4-pro和deepseek-v4-flash两个模型，并设置了巨大的上下文窗口（100万 tokens）和输出长度（38.4万 tokens），以及推理等级等高级特性。extensions.deepseek_v4.enabled: true是关键，它启用了对 DeepSeek V4 模型系列的特殊兼容性支持。
• providers: 定义了真正的模型提供商（Provider）—— DeepSeek。base_url是 DeepSeek 的 API 端点，api_key是你的凭证，offers列出了该提供商实际提供的模型列表。
• routes: 定义了路由规则。这里将名为moonbridge的虚拟模型路由到deepseek提供商的deepseek-v4-pro模型。当 Codex 请求moonbridge模型时，Moon Bridge 就知道该转发给谁。
• defaults: 设置了默认使用的模型和最大 token 数。

保存并关闭配置文件。

3.3 启动 Moon Bridge 服务

在moon-bridge目录下，运行以下命令启动服务：

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

如果一切正常，终端会输出一些启动日志，并显示服务正在127.0.0.1:38440上运行。请保持这个终端窗口打开，不要关闭它，否则服务会停止。

此时，Moon Bridge 已经启动，并在本地38440端口提供了一个兼容OpenAI Responses API的端点：http://127.0.0.1:38440/v1/responses。Codex 客户端将会向这个地址发送请求。

4. 生成并配置 Codex 客户端

现在，我们需要配置 Codex CLI，让它知道不去找 OpenAI，而是找我们本地运行的 Moon Bridge。

4.1 确定 Codex 配置目录

Codex 的配置通常存储在用户主目录下的.codex文件夹中。环境变量CODEX_HOME可以覆盖这个路径。我们接下来的操作会向这个目录写入配置文件。

4.2 生成 Codex 配置文件

我们需要使用 Moon Bridge 提供的一个工具命令，来为 Codex 生成正确的配置文件。这个命令会读取我们刚才写的config.yml，并生成 Codex 能识别的config.toml和models_catalog.json文件。

重要：在生成新配置前，建议备份你现有的 Codex 配置（如果存在）。

打开一个新的终端窗口（保持 Moon Bridge 运行的终端不动），并确保当前目录仍在moon-bridge下。

对于 macOS 或 Linux 用户：

# 1. 设置或获取 Codex 的配置目录路径 CODEX_HOME_DIR="${CODEX_HOME:-$HOME/.codex}" # 2. 创建目录（如果不存在） mkdir -p "$CODEX_HOME_DIR" # 3. （可选）备份现有配置 cp "$CODEX_HOME_DIR/config.toml" "$CODEX_HOME_DIR/config.toml.bak" 2>/dev/null || true # 4. 生成新的配置文件 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" } # 2. 创建目录（如果不存在） New-Item -ItemType Directory -Force -Path $CODEX_HOME_DIR | Out-Null # 3. （可选）备份现有配置 if (Test-Path "$CODEX_HOME_DIR\config.toml") { Copy-Item "$CODEX_HOME_DIR\config.toml" "$CODEX_HOME_DIR\config.toml.bak" -Force } # 4. 生成新的配置文件 $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_HOME_DIR（通常是~/.codex）目录下生成两个文件：

• config.toml: Codex 的主配置文件，其中指定了wire_api = "responses"以及我们 Moon Bridge 的地址。
• models_catalog.json: 模型目录文件，描述了moonbridge这个“模型”的能力（如上下文长度、支持的工具等），Codex 客户端会根据这个文件来展示和启用相应功能。

你可以查看一下生成的config.toml文件内容，确认其中指向了本地服务：

cat ~/.codex/config.toml

你应该能看到类似base_url = "http://127.0.0.1:38440/v1"的配置项。

5. 启动 Codex 并验证连接

万事俱备，现在可以启动 Codex 并测试它是否通过 Moon Bridge 成功连接到了 DeepSeek。

5.1 启动 Codex CLI

1. 打开一个新的终端窗口。
2. 导航到你想要进行编码工作的项目目录。Codex 会分析当前目录的上下文。

   cd /path/to/your/project

3. 直接运行codex命令启动 Codex 交互式界面。

   codex

如果配置一切正确，Codex 会正常启动。你可能会看到 Codex 的欢迎信息或提示符。现在，你可以尝试向它提问或发出编程指令，例如：

/code 写一个Python函数，计算斐波那契数列的第n项。

Codex 会将你的请求发送到http://127.0.0.1:38440/v1/responses（即 Moon Bridge），Moon Bridge 将其转发至 DeepSeek API，获取响应后再返回给 Codex 界面显示。

5.2 验证服务连通性

在启动 Codex 前后，我们可以通过几个简单的命令验证各环节是否正常工作。

1. 检查 Moon Bridge 模型列表：在 Moon Bridge 运行的同时，另开一个终端执行：

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

如果返回一个包含"id": "moonbridge"等信息的 JSON，说明 Moon Bridge 的 API 端点工作正常。

2. 直接向 Moon Bridge 发送测试请求：

curl http://127.0.0.1:38440/v1/responses \ -H "Content-Type: application/json" \ -d '{ "model": "moonbridge", "input": "用一句简短的话介绍你自己。", "max_output_tokens": 1024 }'

如果收到包含 DeepSeek 风格回复的 JSON 响应，则证明 Moon Bridge 到 DeepSeek API 的链路是通的。

3. 观察 Moon Bridge 运行日志：当你通过 Codex 发送请求时，运行 Moon Bridge 的终端窗口会打印出类似POST /v1/responses的访问日志。这是最直接的证据，表明 Codex 的请求已经到达了 Moon Bridge。

5.3 使用一键启动脚本（可选）

Moon Bridge 项目还提供了便捷的一键启动脚本，可以自动完成启动 Moon Bridge、生成配置、启动 Codex 的整个过程。

macOS/Linux:

./scripts/start_codex_with_moonbridge.sh --project-directory /path/to/your/project

Windows PowerShell:

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

这个脚本会处理依赖检查和流程串联，适合快速启动。但对于理解整个架构和排查问题，还是建议按上述分步操作。

6. 常见问题与故障排查

在配置过程中，你可能会遇到一些问题。下面列出了一些常见错误及其解决方法。

如果遇到上述未涵盖的问题，请首先检查：

1. 所有终端窗口：确保 Moon Bridge 服务进程一直处于运行状态。
2. 网络连接：确保你的机器可以正常访问api.deepseek.com。
3. 版本兼容性：确认你的 Node.js、Go、Codex CLI 版本符合要求。
4. 查看日志：Moon Bridge 的运行终端和 Codex 的输出通常会提供详细的错误信息。

7. 最佳实践与进阶配置建议

成功搭建只是第一步，要让这套组合稳定、高效、安全地服务于你的开发工作，还需要注意以下几点。

7.1 安全与密钥管理

• 永远不要提交密钥：config.yml文件中包含你的 DeepSeek API Key。务必将该文件添加到你的.gitignore文件中，避免意外提交到公开仓库。
• 使用环境变量：更安全的方式是通过环境变量传递 API Key。你可以修改config.yml：

  providers: deepseek: base_url: "https://api.deepseek.com/anthropic" api_key: "${DEEPSEEK_API_KEY}" # 从环境变量读取

  然后在启动 Moon Bridge 前设置环境变量：

  export DEEPSEEK_API_KEY=sk-your-real-key-here go run ./cmd/moonbridge --config config.yml

• 最小权限原则：在 DeepSeek 平台创建 API Key 时，如果支持，请仅授予其必要的权限。

7.2 性能与稳定性

• 选择模型：config.yml中我们路由到了deepseek-v4-pro，这是能力最强的模型，但成本也相对较高。对于日常代码补全和对话，deepseek-v4-flash速度更快，成本更低，是性价比之选。你可以在routes部分轻松切换。

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

• 管理上下文长度：虽然我们配置了很大的max_output_tokens，但在实际使用中，过长的输出可能会消耗大量 tokens。可以在 Codex 的交互中，或通过配置文件，合理限制单次请求的最大输出 tokens，以控制成本。
• 服务常驻：如果你频繁使用 Codex，可以考虑将 Moon Bridge 部署为系统后台服务（如使用systemd(Linux)、launchd(macOS) 或nssm(Windows)），避免每次手动启动。

7.3 配置优化与扩展

• 多模型/多提供商：Moon Bridge 支持配置多个模型和提供商。例如，你可以同时配置 DeepSeek 和另一个兼容 OpenAI API 的服务，并在routes中根据规则进行路由。详细配置请参考 Moon Bridge 项目中的config.example.yml文件。
• 使用配置文件目录：可以将config.yml放在独立目录，并通过--config参数指定绝对路径，方便管理。
• Codex App 配置：如果你使用 Codex 的桌面应用程序（App），其配置目录可能与 CLI 不同（通常在~/Library/Application Support/Codex/(macOS) 或%APPDATA%\Codex\(Windows)）。你需要将生成的config.toml和models_catalog.json文件也复制到对应的 App 配置目录中。

7.4 成本监控

• 定期查看用量：养成习惯，定期登录 DeepSeek 开放平台查看 API 调用量和费用消耗。DeepSeek 提供了非常清晰的使用量统计和账单信息。
• 设置预算预警：如果平台支持，可以设置每月预算或用量告警，防止意外超额。

通过本文的详细步骤，你已经成功地将昂贵的 Codex 官方后端替换为了高性价比的 DeepSeek。这套方案不仅显著降低了使用成本，还为国内开发者提供了更稳定、快速的访问体验。从环境搭建、配置详解到故障排查和最佳实践，我们覆盖了从入门到熟练所需的全部知识点。现在，你可以尽情享受 AI 结对编程带来的效率提升，而无需担心高昂的账单了。如果在实践中遇到新的问题，多查看终端日志、善用社区资源（如 Moon Bridge 的 GitHub Issues），大部分技术难题都能找到解决方案。

🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Claude 随心用，限时 5 折。 👉 点击领海量免费额度