利用Moon Bridge将DeepSeek接入OpenAI Codex：低成本AI编程助手实战

你还在为 OpenAI Codex 的官方模型费用发愁吗？或者，你只是想找一个更接地气、成本更可控的智能编码助手，却苦于官方渠道的高门槛和复杂的配置？最近，一个在开发者社区里流传开来的方案，让不少人眼前一亮：用 DeepSeek 的模型，来驱动 OpenAI 的 Codex 客户端。

这听起来像是一个“曲线救国”的野路子，但它背后揭示了一个更本质的问题：我们真正需要的，往往不是某个特定的“官方”服务，而是一个能稳定、高效、低成本地完成编码任务的智能体。当官方路径成本过高或不可用时，通过一个精巧的“转发层”将请求导向另一个强大的模型，就成了一个极具吸引力的工程实践。今天，我们就来彻底拆解这个方案，看看如何从零开始，不写一行代码，将 DeepSeek 接入 Codex，打造一个属于你自己的、高性价比的 AI 编码伙伴。

1. 理解核心：这不是“破解”，而是“协议适配”

在动手之前，我们必须先搞清楚一件事：我们到底在做什么？很多人一看到“接入”、“替换”，就以为是破解或修改了 Codex 的客户端。完全不是。Codex 作为一个客户端，它只负责两件事：1) 理解你的开发上下文（文件、终端、问题）；2) 按照OpenAI Responses API的协议格式，将请求发送出去，并接收响应。

问题的关键在于，Codex 默认只会把请求发往 OpenAI 的官方服务器。我们的目标，是在本地搭建一个“中转站”（即 Moon Bridge），这个中转站能完美“冒充”OpenAI 的服务器，接收 Codex 发来的标准请求，然后将其“翻译”并转发给 DeepSeek 的 API，最后再把 DeepSeek 的响应“包装”成 OpenAI 的格式，返回给 Codex。

所以，整个流程的核心是Moon Bridge这个开源项目。它扮演了协议转换和请求转发的角色。理解了这一点，你就明白了为什么这个方案是可行的，以及后续所有配置步骤的逻辑所在。

2. 环境准备与核心组件安装

整个方案依赖于三个核心组件：Node.js（运行 Codex CLI）、Go（运行 Moon Bridge）以及 DeepSeek 的 API Key。让我们一步步来。

2.1 安装基础运行环境

首先，确保你的系统满足以下条件：

• Node.js 18+: 这是运行 Codex CLI 所必需的。你可以从 Node.js 官网 下载安装包，或者使用nvm等版本管理工具。
• Go 1.25+: 这是编译和运行 Moon Bridge 所必需的。请从 Go 官网 下载并安装。

安装完成后，在终端中验证版本：

node --version go version

2.2 获取 DeepSeek API Key

这是整个方案的“燃料”。你需要一个 DeepSeek 平台的账户和 API Key。

1. 访问 DeepSeek 开放平台 。
2. 注册并登录。
3. 在控制台中找到“API Keys”或类似区域，创建一个新的 API Key。
4. 务必妥善保存这个 Key，它看起来像sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。在接下来的配置中会用到。

注意：DeepSeek API 目前有免费额度，但具体政策和费率可能变动，使用前请务必在平台确认最新计费规则。

2.3 安装 Codex CLI

Codex 提供了命令行工具，这是我们交互的主要界面。通过 npm 全局安装：

npm install -g @openai/codex

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

codex --version

如果能看到版本号输出，说明安装成功。

3. 部署与配置 Moon Bridge 转发层

这是整个方案最核心的一步，我们需要让 Moon Bridge 在本地运行起来，并正确配置它指向 DeepSeek。

3.1 获取并初始化 Moon Bridge

Moon Bridge 是一个开源项目，我们需要将其克隆到本地。

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

3.2 创建配置文件config.yml

在moon-bridge目录下，创建一个名为config.yml的文件。这个文件定义了 Moon Bridge 的行为：监听哪个端口、使用哪些模型、以及如何连接到 DeepSeek。

将以下配置内容粘贴到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 将在本地的127.0.0.1:38440端口启动服务。Codex 稍后会连接这个地址。
• providers.deepseek.base_url: 这里指向的是 DeepSeek 的 API 端点。注意，它使用了/anthropic路径，这是因为 Moon Bridge 可能兼容了多种 API 协议格式。
• routes: 定义了一个名为moonbridge的路由，它将请求导向deepseek-v4-pro模型。这个路由名moonbridge就是稍后 Codex 眼中“模型”的名字。
• models: 这里定义了模型的能力元数据，如上下文窗口大小、支持的推理等级等。这些信息会被 Moon Bridge 用于生成给 Codex 的“模型目录”，让 Codex 知道这个“模型”能做什么。

3.3 启动 Moon Bridge 服务

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

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

如果一切正常，你会看到服务启动的日志，并持续运行，等待连接。请保持这个终端窗口打开。现在，一个本地的“伪 OpenAI API 服务器”已经在http://127.0.0.1:38440/v1就绪了。

4. 配置 Codex 客户端指向本地服务

现在，我们需要“骗过”Codex，让它以为我们本地的 Moon Bridge 就是它要连接的 OpenAI 服务器。

4.1 生成 Codex 配置文件

Moon Bridge 贴心地提供了一个工具，可以自动为 Codex 生成正确的配置文件。我们需要在另一个终端窗口（或新的标签页）中操作，同样在moon-bridge目录下。

首先，确定 Codex 的配置目录。通常，Codex 会在用户主目录下创建.codex文件夹来存放配置。

对于 macOS/Linux 用户：

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 # 生成新配置 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 # 可选：备份现有配置 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"

这两条命令做了几件关键事：

1. --print-codex-model：获取 Moon Bridge 配置中定义的路由模型名（即moonbridge）。
2. --print-codex-config：根据模型名和本地 API 地址，生成 Codex 能识别的config.toml配置文件。这个文件会告诉 Codex 使用wire_api = "responses"模式，并连接到我们本地的http://127.0.0.1:38440/v1。
3. 同时，它还会在CODEX_HOME_DIR中生成一个models_catalog.json文件，其中包含了 Moon Bridge 定义的模型能力信息，这样 Codex 的界面就能正确显示模型支持的功能（如长上下文、推理模式等）。

4.2 验证配置与连接

在启动 Codex 之前，我们可以先做两个快速验证，确保各个环节都畅通。

验证1：检查 Moon Bridge 模型列表在新的终端中运行：

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

你应该能看到一个 JSON 响应，其中包含名为moonbridge的模型信息。这证明 Moon Bridge 服务正常，并暴露了正确的 API 端点。

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

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 }'

如果返回了包含 “hello” 等内容的 JSON，说明 Moon Bridge 到 DeepSeek API 的转发链路是通的。

5. 启动 Codex 并投入实战

所有准备工作就绪，现在可以启动 Codex 了。

1. 打开一个新的终端，导航到你想要进行编码工作的项目目录。

   cd /path/to/your/project

2. 直接运行codex命令。

   codex

如果一切配置正确，Codex 界面应该会正常启动。你可能会注意到，在模型选择或状态信息处，它使用的已不再是 OpenAI 的模型，而是你通过 Moon Bridge 配置的 DeepSeek 模型。

现在，你可以像往常一样使用 Codex：

• 在终端中，用codex命令开启对话模式。
• 在代码编辑器中，它应该能像往常一样提供代码补全和建议（具体取决于 Codex 客户端的集成方式）。
• 尝试提出一个编码问题，观察响应。响应内容应该来自 DeepSeek 模型。

观察 Moon Bridge 的终端窗口，你会看到类似POST /v1/responses的日志行，这表示 Codex 的请求已经被成功接收并转发了。

6. 进阶使用、排错与长期考量

将核心流程跑通只是第一步。要让这个组合稳定、可靠地服务于你的日常开发，还需要考虑更多。

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

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.2 常见问题排查（Troubleshooting）

当你遇到问题时，请按照以下顺序排查：

1. 连接被拒绝 (Connection refused)

   • 症状: Codex 启动失败或无法连接。
   • 排查: 首先确认 Moon Bridge 服务是否在运行（检查第一个终端窗口）。确认config.yml中的server.addr端口（默认 38440）是否与生成 Codex 配置时使用的--codex-base-url端口一致。
   • 解决: 确保 Moon Bridge 进程存活，且端口未被占用。

2. Codex 看不到模型

   • 症状: Codex 启动后提示没有可用模型。
   • 排查: 检查~/.codex/（或%USERPROFILE%\.codex\）目录下是否存在models_catalog.json文件。
   • 解决: 重新执行第 4.1 步的配置生成命令。确保命令指向了正确的CODEX_HOME_DIR。

3. 认证错误 (401) 或计费错误 (402)

   • 症状: Moon Bridge 日志或 Codex 返回权限或额度错误。
   • 排查: 检查config.yml中的api_key是否正确无误。访问 DeepSeek 平台控制台，确认 API Key 有效且账户有充足余额或免费额度。
   • 解决: 更新正确的 API Key 或充值账户。

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

   • 症状: 启动 Moon Bridge 时报错。
   • 排查: 这通常是因为使用了过时格式的config.yml。Moon Bridge 的配置格式可能更新。
   • 解决: 确保你的config.yml结构与本文提供的示例一致，使用了顶层的providers、models、routes、defaults字段。

6.3 长期使用的工程化建议

1. 将 Moon Bridge 作为系统服务运行：每次都手动开一个终端运行go run不是长久之计。可以考虑使用systemd(Linux)、launchd(macOS) 或任务计划程序 (Windows) 将 Moon Bridge 配置为开机自启的后台服务，并配置日志轮转。
2. 管理多个 API Key 或模型：config.yml支持配置多个providers和routes。你可以根据需要设置路由规则，例如将不同的请求导向不同的模型或备用的 API Key，实现简单的负载均衡或降级策略。
3. 关注 DeepSeek API 的更新：DeepSeek 的模型、API 端点或计费策略可能会更新。需要定期关注官方文档，并相应调整 Moon Bridge 的配置（如base_url或模型参数）。
4. 理解成本与监控：虽然 DeepSeek 目前有免费额度，但大量使用仍会产生成本。建议在 DeepSeek 平台设置用量告警，并定期查看 Moon Bridge 的日志，了解使用情况。
5. 备份你的配置：将你调试成功的config.yml和生成 Codex 配置的命令脚本保存下来。这能在系统重装或环境迁移时帮你快速恢复。

7. 总结：从“能用”到“好用”的思考

通过 Moon Bridge 将 DeepSeek 接入 Codex，技术上看是一个漂亮的“协议转换”和“请求转发”案例。它让我们跳出了“必须使用官方指定服务”的框框，获得了模型选择的自由和成本控制的可能。

然而，真正的价值不在于“接上了”，而在于“用得好”。这个方案的稳定性、延迟、功能完整性（如是否完全支持 Codex 的所有高级特性）都依赖于 Moon Bridge 这个中间层的维护程度。它更像是一个由社区驱动的、灵活的胶水方案，而非官方支持的产品。

因此，在决定将其用于核心生产流程前，建议你：

• 充分测试：在你常用的开发场景中测试其响应质量、速度和稳定性。
• 准备备用方案：明确如果此方案失效（例如 Moon Bridge 停止维护、DeepSeek API 大幅变更），你的备选工作流是什么。
• 拥抱变化：开源生态和 AI API 都在快速迭代，保持关注，随时准备调整你的工具链。

最终，工具的价值由它为你解决的问题决定。如果你找到了一个在成本、能力和体验上更优的平衡点，那么这套略显复杂的配置过程，就是值得的。它代表着你不再被动接受给定的选项，而是开始主动塑造属于自己的开发环境。