本手册基于真实安装过程编写，踩过的坑全部注明。
一、为什么需要 Moon Bridge
Codex 用的是 OpenAI 的 Responses API。 DeepSeek 只提供 Chat Completions API。 两个协议不兼容。
Moon Bridge 做的事情： Codex（Responses API）→ Moon Bridge 翻译 → DeepSeek（Chat API）
所以 Moon Bridge 必须在本地一直跑着，Codex 才能用 DeepSeek。
二、前提环境检查
本手册假设你已有： ● Node.js 18+ （node --version） ● Git （git --version） ● DeepSeek API Key （sk- 开头的一串）
需要额外安装： ● Go 1.25+ （Moon Bridge 的运行环境）
三、第 1 步：安装 Go
下载地址：
https://golang.google.cn/dl/
（注意用 golang.google.cn，别用 go.dev，后者国内下不动）
找到 go1.25.x.windows-amd64.msi → 下载 → 双击安装 → 一路 Next
验证：
Win+R → cmd → 输入 go version
显示 go version go1.25.x windows/amd64 → OK
▸ 重要：装完立刻设置 Go 国内代理
go env -w GOPROXY="https://goproxy.cn,direct"
不设这个，后面 go run 下载依赖会卡住。
（原版 proxy.golang.org 在国内无法访问）
四、第 2 步：安装 Codex CLI
终端输入：
npm install -g @openai/codex
验证：
codex --version
应输出类似 codex-cli 0.136.0
五、第 3 步：克隆 Moon Bridge
GitHub 直连国内经常超时，用 ghproxy 中转。
cd C:\
mkdir Tools 2>nul
cd Tools
git clone https://ghproxy.net/https://github.com/ZhiYi-R/moon-bridge.git
cd moon-bridge
验证：
dir config.yml → 应该看不到（还没创建）
dir cmd\moonbridge → 应该看到 Go 源码
六、第 4 步：创建 config.yml
在 C:\Tools\moon-bridge 目录下新建 config.yml：
（右键 → 新建 → 文本文档 → 重命名为 config.yml）
粘贴以下完整内容——只改 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: "api.deepseek.com/anthropic" api_key: "sk-你的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
保存，关闭。
七、第 5 步：生成 Codex 配置文件
打开终端（CMD 或 PowerShell），执行：
cd C:\Tools\moon-bridge
先测试 Moon Bridge 能不能正常识别模型：
go run ./cmd/moonbridge --config config.yml --print-codex-model
输出 moonbridge → OK。如果这步报依赖下载失败， 检查第 3 步的 GOPROXY 设置了没有。
然后生成 Codex 配置：
go run ./cmd/moonbridge --config config.yml --print-codex-config "moonbridge" --codex-base-url "http://127.0.0.1:38440/v1" --codex-home "%USERPROFILE%\.codex" > "%USERPROFILE%\.codex\config.toml"
▸ 重要：生成后检查 config.toml 第一行
type "%USERPROFILE%\.codex\config.toml"
如果第一行是类似这样的日志（不是 TOML 格式）：
time=2026-06-03T09:58:54 level=INFO msg=配置已加载...
必须删掉这一行！否则 Codex 读配置会报错。
正常情况下 config.toml 应该是这样的：
model = "moonbridge"
model_provider = "moonbridge"
model_context_window = 1000000
model_max_output_tokens = 384000
model_catalog_json = "C:\\Users\\你的用户名\\.codex\\models_catalog.json"
[model_providers.moonbridge]
name = "Moon Bridge"
base_url = "http://127.0.0.1:38440/v1"
wire_api = "responses"
同时确认 models_catalog.json 已生成：
dir "%USERPROFILE%\.codex\models_catalog.json"
八、第 6 步：启动 + 验证
▸ 终端 1：启动 Moon Bridge（保持窗口开着！）
cd C:\Tools\moon-bridge
go run ./cmd/moonbridge --config config.yml
看到类似输出就 OK：
level=INFO msg=配置已加载 ... addr=127.0.0.1:38440
▸ 终端 2：验证 Moon Bridge 在响应
curl http://127.0.0.1:38440/v1/models
应返回 JSON，包含三个模型：
deepseek-v4-pro、deepseek-v4-flash、moonbridge
▸ 终端 2：启动 Codex
cd 你的项目目录
codex
首次进入会有信任对话框 → Accept → 进入对话
输入 /status 查看配置，输入问题测试回复。
九、每次使用流程
-
打开终端 1，启动 Moon Bridge（保持运行） cd C:\Tools\moon-bridge go run ./cmd/moonbridge --config config.yml
-
打开终端 2，启动 Codex cd 你的项目目录 codex
-
用完 Ctrl+C 两次退出 Codex Moon Bridge 终端也 Ctrl+C 关掉
十、踩坑记录（真实遇到过的报错）
坑 1：go run 下载依赖失败 报错：dial tcp 142.250.73.81:443 ... connection failed 原因：proxy.golang.org 在国内被墙 解决：go env -w GOPROXY="goproxy.cn,direct"
坑 2：git clone GitHub 失败 报错：RPC failed; curl 28 Recv failure: Connection was reset 原因：github.com 直连被墙 解决：用 ghproxy.net 中转 git clone ghproxy.net/https://git…
坑 3：config.toml 第一行混入日志 现象：生成的 config.toml 第一行是 time=... level=INFO ... 原因：go run 的日志输出和重定向混在一起了 解决：手动删掉第一行，只保留 model = "moonbridge" 开头
坑 4：Go 的 msi 安装包下载不动 现象：go.dev 和 dl.google.com 都下不了 解决：用 golang.google.cn/dl/ 中国镜像站
坑 5：Codex 启动报 connection refused 原因：Moon Bridge 没启动 解决：回到终端 1，确认 go run 在跑
坑 6：Codex 启动报 config 解析错误 原因：config.toml 里有非 TOML 格式内容（见坑 3） 解决：检查并清理 config.toml
十一、Codex 常用命令速查
codex 启动 Codex /status 查看当前会话和模型 /model 切换模型 /clear 清空对话 /init 扫描项目生成 CODEBUDDY.md /help 所有命令 Ctrl+C 两次 退出
十二、与 Claude Code 的对比
Claude Code Codex + Moon Bridge
───────────────────────────────────────────────────── 配置难度 简单（改 json） 复杂（需 Go + 代理） 启动方式 直接 claude 需先启动 Moon Bridge 稳定性 高 依赖本地代理 功能 Anthropic 原生 OpenAI 生态 建议 日常主力 备选 / 尝鲜
两者可以共存，互不影响。
参考
Moon Bridge：github.com/ZhiYi-R/moo… DeepSeek 官方：api-docs.deepseek.com/zh-cn/guide… Go 中国站：golang.google.cn/
