Moon Bridge 是一个用 Go 编写的协议转换与模型路由代理。三个入口端点原生支持:/v1/messages(Claude Code)、/v1/responses(Codex CLI)、/v1/chat/completions(OpenAI Chat 客户端)。所有请求统一转换为内部 CoreRequest,按配置路由到 Anthropic Messages、Google Gemini(GenAI)、OpenAI Chat Completions 等上游协议。客户端指定不同模型别名时,自动将请求路由到对应上游 Provider 并在协议间自动转换。
🍳 新手先看这里 → CookBook.md:一份按目标找做法的菜谱,5 分钟跑通第一个对话。 官方qq群:1103798316
# 复制配置并编辑 cp config.example.yml config.yml # 修改 config.yml 中的 api_key # 启动 go run ./cmd/moonbridge -config config.yml # 另见 CookBook.md 中的详细使用场景
要求 Go 1.25+。
- 协议转换:三入口(Messages / Responses / Chat Completions)→ Anthropic Messages / Google Gemini / OpenAI Chat,统一管道转换
- 模型路由:通过
routes配置将模型别名映射到不同 Provider 的上游模型名 - 插件扩展:
CorePluginHooks接口,支持请求预处理、响应后处理、流拦截 - 请求跟踪:完整链路记录,每步转换均可追溯
- 用量统计:按会话聚合 token 与费用
- 管理 API:运行时热重载配置(需启用持久化)
- Web Search 注入:自动/注入模式,支持 Tavily、Firecrawl
- Prompt 缓存:explicit / automatic / hybrid 三种模式
所有扩展通过 config.yml 的 extensions 字段启用,支持 Global / Provider / Model / Route 四级作用域。
| 扩展 | 类型 | 功能 |
|---|---|---|
codex_tool_proxy |
ToolInjector | 为 Codex 注入 apply_patch 等工具代理 |
deepseek_v4 |
ReasoningExtractor | DeepSeek V4/V3 thinking/reasoning 提取与转换 |
web_fetch |
ToolInjector + MessageRewriter | 注入 web_fetch(url) 工具,代理侧通过 Jina Reader 抓取网页 Markdown,绕过 Codex 沙箱的 HTTP 限制 |
circuit_breaker |
RequestMutator | 按会话统计连续 tool_use 调用次数,超过阈值注入警告或强制终止,防止模型陷入死循环 |
response_store |
ResponsePostProcessor | 缓存上游响应,当请求携带 previous_response_id 时自动桥接上次 assistant 输出到新请求 Input |
kimi_workaround |
InputPreprocessor | Kimi 模型兼容处理 |
visual |
ContentFilter | 视觉/图片内容过滤 |
db_sqlite / db_d1 |
Provider | SQLite / Cloudflare D1 持久化存储 |
metrics |
RequestCompletionHook | Token 用量与费用统计 |
session_recorder |
RequestCompletionHook | 记录每次请求的模型、token、耗时到 ~/.moonbridge/sessions/YYYY-MM-DD.jsonl |
skill_injector |
CoreRequestMutator | 从 ~/.moonbridge/skills/<name>/SKILL.md 读取技能,关键词匹配后注入 system prompt,无匹配时 fallback 到 Top-3 |
extensions: web_fetch: enabled: true circuit_breaker: enabled: true config: max_consecutive_tools: 20 hard_limit: 30 response_store: enabled: true config: ttl_seconds: 3600 max_entries: 500
| 模式 | 行为 |
|---|---|
Transform(默认) |
接收 Messages / Responses / Chat Completions 三种入口请求 → 协议转换 → 转发到上游 → 反向转换后返回 |
CaptureAnthropic |
接收 Anthropic Messages 请求 → 透明转发到 Anthropic 上游 |
CaptureResponse |
接收 OpenAI Responses 请求 → 透明转发到 OpenAI 上游 |
采用 YAML 格式,核心结构为 models、providers、routes 三段式。完整配置说明见 CONFIGURATION.md。
将 Moon Bridge 地址设为 Codex 的 custom provider:
[model_providers.custom] name = "custom" wire_api = "responses" requires_openai_auth = false base_url = "http://127.0.0.1:38440/v1"
然后在 Moon Bridge 配置的 routes 中定义模型别名映射。
export ANTHROPIC_BASE_URL=http://127.0.0.1:38440/v1 export ANTHROPIC_AUTH_TOKEN=any-value export ANTHROPIC_MODEL=your-alias
docker build -t moonbridge . docker run -p 38440:38440 -v $(pwd)/config.yml:/config/config.yml moonbridge
| 参数 | 默认值 | 说明 |
|---|---|---|
-config |
${XDG_CONFIG_HOME}/moonbridge/config.yml |
配置文件路径 |
-addr |
来自配置文件 | 覆盖监听地址 |
-mode |
来自配置文件 | 覆盖运行模式(Transform/CaptureAnthropic/CaptureResponse) |
-print-addr |
— | 打印配置的监听地址后退出 |
-print-mode |
— | 打印配置的运行模式后退出 |
-print-default-model |
— | 打印默认模型别名后退出 |
-print-codex-model |
— | 打印 Codex 模型后退出 |
-print-codex-config <model> |
— | 为指定模型生成 Codex config.toml 后退出 |
-dump-config-schema |
— | 生成 config.schema.json 后退出 |
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/messages |
POST | Anthropic Messages API 入口(Claude Code 直连) |
/messages |
POST | 同上(无 /v1 前缀) |
/v1/responses |
POST | OpenAI Responses API 入口(Codex CLI 直连) |
/responses |
POST | 同上(无 /v1 前缀) |
/v1/chat/completions |
POST | OpenAI Chat Completions API 入口 |
/v1/models |
GET | 列出可用模型 |
/models |
GET | 同上 |
/api/v1/ |
— | 管理 API(需启用持久化) |
/health |
GET | 健康检查 |
详细 API 文档见 API.md。
通过配置中的 trace.enabled 或特定工作模式启用请求跟踪,将完整请求/响应链路记录到文件。跟踪文件按 session/模型名/类别/序号.json 组织,支持 Chat、Response、Anthropic 三种分类。