MIT 开源 · v1.0.1 · Python 3.10+ · Docker / ghcr

WorkBuddy/Qoder/Trae 收成一个端口。

三套 AI 客户端各带一套反代网关:三个窗口、三套地址、三遍配置,一个账号挂了客户端只会报错。 本仓库把三家引擎原样收进同一个进程,在上面加一层融合网关 —— 一把合并 Key 按模型与区域自动选路,401/429/502/503/504 自动换到下一家,客户端无感。

在 GitHub 打开↗
  • 8817唯一对外端口
  • 3 家一个 Python 进程
  • 3 协议Chat · Responses · Messages
  • 0 上传数据全在本地
三条线,一个出口 —— 客户端只填一个 base_url
wb · :8811 qd · :8812 trae · :8813 portal 单端口 :8817 /v1 鉴权 · 选路 · 换家 · SSE
客户端配置 · 一次填完
Base URL : http://127.0.0.1:8817/v1
API Key  : mrg-xxxxxxxx  # 面板「网关 Key」里的合并 Key
Model    : auto          # 或任意一家的模型名,门户自己挑路
它同时被叫作: 反向代理 · 反代网关 · API 中转 · 中转站 · 协议适配 · 网关中枢 · 多账号池调度 · 本地 LLM Gateway · Codex / Claude Code 接入层

01 · 问题

同时用三家,成本全在「切换」上。

WorkBuddy、Qoder、Trae 的客户端各自带一套反代网关,各管各的账号、各开各的端口、各有一套看板。单看哪家都合理,三家一起用就变成三件事。

之前三个终端窗口、三套健康检查,出错要一家家翻日志。
现在一个进程 hub/,模块前缀 wb_ / qoder_ / trae_ 天然隔离。
之前客户端里配三遍 base_url,换一家改一次配置。
现在只留 :8817/v1,三家引擎端口只监听 127.0.0.1。
之前某个账号被限流,客户端只收到一个报错,不会自己换家。
现在门户按模型可用性选路,401/429/502/503/504 自动换下一家。
之前三块看板,签到在 A、用量在 B、Key 在 C。
现在一个 React 面板:账号池 / 模型清单 / 指标 / 流水 / Key / 福利 / 设置。
之前怕更新把账号数据冲掉,一直拖着不升。
现在一键更新只覆盖代码,账号 / 用量 / 日志 / 设置在保护名单内。

02 · 收敛

五件麻烦事,收敛成五个「一」。

融合层不加新协议,只做减法:把「三家」对外变成「一家」。

  1. 01

    一个进程

    三家引擎跑在同一个 Python 进程里,模块名前缀 wb_* / qoder_* / trae_* 互不污染。启停、日志、自检都只看一处。

  2. 02

    一个端口

    只有 8817 对外。8811 / 8812 / 8813 属于内部回环,外部连不上 —— 少记三个地址,也少暴露三个面。

  3. 03

    一把 Key

    合并 Key 按「模型在谁家、哪个区可用」选路;401/429/502/503/504 自动换下一家。每把 Key 还能限定可用模型与可用引擎。

  4. 04

    一个面板

    账号池、模型清单、数据指标、请求流水、网关 Key、福利中心、设置与一键更新,同一个 React 看板里看完三家。

  5. 05

    一套协议

    对外统一 OpenAI Chat Completions / Responses 与 Anthropic Messages,含 SSE 流式。/v1/* 与 /api/v1/* 等价,客户端填哪个都行。

03 · 架构

门户在中间:读端聚合,写端选路。

请求路径与看板路径分开走,同一个端口、两套语义。

hub/server.py单进程编排 · 三家引擎 + 门户
客户端 Codex · Claude Code Cherry Studio · ChatBox LobeChat · OpenAI SDK portal · :8817 合并路由 router 模型 → 引擎 / 区域 · 快照与冷却 聚合 API /api/hub/* 一次拿三家 · usage / accounts 静态面板 admin/ React 19 + Vite 看板 鉴权 + SSE 透传 wb 引擎 · :8811WorkBuddy qd 引擎 · :8812Qoder trae 引擎 · :8813Trae 账号池 用量 日志 内部端口只绑定 127.0.0.1,外部不可达 · 数据全部落本地磁盘
写路径

客户端 → 门户(鉴权 + 选路)→ 引擎(选号 + 上游协议)→ 上游

读路径

浏览器 → 门户 /api/hub/*(一次拿三家)→ 引擎 /usage、/accounts

对外协议

POST /v1/chat/completionsOpenAI Chat,支持流式与非流式
POST /v1/responsesResponses API,Codex 走这条
POST /v1/messagesAnthropic Messages,x-api-key 与 Authorization 都认
GET /v1/models三家合并去重,同名只算一个
ANY /api/v1/*与 /v1/* 完全等价的别名
GET /api/hub/*看板聚合:健康、账号、指标、流水、Key

04 · 叫法

同一件事,大家有七八种叫法。

这些词说的都是本项目 —— 按你熟悉的说法读下去就行,每张卡右边是它在 Hub 里的具体实现。

反向代理 / 反代

也写作「反代网关」「把客户端反代成 API」

把带登录态的 AI 客户端,反代成一个能被任意程序调用的 HTTP 接口。 三家引擎本身就是三套反代;Hub 把它们收进一个端口,反代出的接口再多一层统一鉴权与选路。
  • 登录态代理
  • OAuth / PAT 入池
  • 本地回环

API 中转 / 中转站

也写作「模型中转」「统一中转」

一个入口收请求,再决定发给哪家上游,并记账。 合并 Key 就是中转凭证:按模型可用性与区域挑上游,请求流水三家合并留档,Key 级限额四护栏兜底。
  • 合并 Key
  • 上游选路
  • 请求流水

协议适配

也写作「格式转换」「OpenAI 转 Anthropic」

客户端说 OpenAI,上游说 Anthropic,中间得有人翻译。 对外同时暴露 Chat / Responses / Messages 三种形态;SSE 边收边发,已经写向客户端的字节绝不重发。
  • Chat ↔ Messages
  • SSE 流式
  • 工具调用

网关 / 网关中枢

也写作「Gateway」「统一入口」

鉴权、路由、配额、可观测性,都收在同一层。 hub/core/portal.py 是单端口门户:鉴权 + 选路 + SSE 透传 + 聚合 API + 静态面板,全在一个进程里。
  • 单端口
  • Key 作用域
  • 限额护栏

多账号池与签到

也写作「账号轮询」「批量签到」「积分管理」

账号多了要轮着用、要签到保活、要看得出谁快没额度。 三家账号一张表:签到状态、积分增减、出口区域、启停、测试、导入、批量签到;福利中心管每日签到、Token 保活、权益刷新。
  • 每日签到
  • Token 保活
  • 出口区域

故障转移 / 负载均衡

也写作「自动换家」「failover」「轮询」

一家不行就换下一家,别让客户端看见错误。 401 / 429 / 502 / 503 / 504 触发换引擎,路由器带快照与冷却窗口;换家只在还没写出字节时发生。
  • 跨引擎换家
  • 冷却窗口
  • 不重复回答

Codex 与 Claude Code 接入

也写作「给 Codex 用」「接 Claude Code」

两个命令行工具各说一套协议,但都只认一个 base_url。 Codex 走 /v1/responses,Claude Code 走 /v1/messages;同一把合并 Key,三家账号谁在线就用谁。
  • Responses
  • Messages
  • 同 Key

Docker 部署 / 自托管

也写作「容器化」「私有化部署」「NAS 上跑」

不想装 Python,或者想让它 7×24 在家里的机器上跑。 ghcr 镜像一条命令起;宿主机 18791 → 容器门户 8817,数据挂 /app/data;也支持 docker compose。
  • ghcr.io
  • compose
  • 数据卷

05 · 面板

一个看板管三家,不用来回切窗口。

React 19 + Vite 构建,静态产物直接由门户提供,和 API 同源。下面是按 v1.0.1 功能重绘的界面示意(非实盘截图)。

127.0.0.1:8817 · 账号池三引擎 3/3 在线
全部国内国际 批量签到导入导出 共 9 条 · 可用 7
账号引擎出口今日积分签到健康操作
团子wbcn190 万 / 250 万已签到健康启停 · 测试 · 积分明细
夜梦qdint181.2 万 / 400 万已签到健康启停 · 测试 · 积分明细
阿柚traecn3.0 万 / 12 万未签到限流冷却 42s签到 · 测试 · 代理槽位
白露wbint—已签到本地停用启用 · 积分明细

签到状态、积分增减、出口区域绑定、启停与连通性测试在同一页;被限流的账号会显示冷却剩余时间。

另外几页

总览三家健康、合并 Key 数、路由统计、自检入口一眼看完。
请求流水三家日志合到一张表,按级别与引擎过滤,可展开详情并复制请求体。
福利中心每日签到、Token 保活、权益刷新,三家分开列、可批量执行。
设置限额四护栏、面板密码、代理槽位、定价、高级设置(可单独关某家引擎)、版本与更新。

06 · 选路与故障转移

换家这件事,发生在客户端察觉之前。

门户先看模型在谁家、哪个区可用;出错码命中白名单就换下一家,但绝不在已经写出字节之后换。

1

鉴权与解析

校验合并 Key 与作用域:模型不在允许名单里 → 403。

2

模型 → 引擎 / 区域

路由器按模型可用性与区域排序,取当前可用账号;结果带快照缓存。

3

上游 429 / 401

该账号进冷却窗口并标记原因,面板上能看见「限流冷却 42s」这类状态。

4

换下一家

401/429/502/503/504 且尚未写出字节 → 换到另一家引擎重试。

5

流式回写

SSE 边收边发。已经向客户端写出第一个字节后绝不重发,避免同一个回答来两遍。

一次真实的换家 · 请求流水详情客户端只收到 200
→ POST /v1/chat/completions        model=deepseek-v3.2   key=mrg-8f2a…
· route: [wb:cn, qd:cn, trae:int]                 # 三家都声称能跑这个模型
· try 1  wb:cn    429 too_many_requests  180 ms   # 账号进冷却 42 s
· try 2  qd:cn    200 ok · SSE 1.4k tok  2 140 ms # 已写出首字节 → 不再重试
← 200 OK  engine=qd region=cn attempts=2           # 流水里 attempts 会记成 2

07 · 接入

能填 base_url 的地方,就能接三家。

地址只有一个:http://127.0.0.1:8817/v1;密钥用面板「网关 Key」里的合并 Key mrg-…。局域网模式会强制要求 Key。

Codex CLI · Responses 协议
# ~/.codex/config.toml
model = "auto"
model_provider = "wqt"

[model_providers.wqt]
name = "WQT Hub"
base_url = "http://127.0.0.1:8817/v1"
env_key = "WQT_API_KEY"
wire_api = "responses"

export WQT_API_KEY="mrg-xxxxxxxx"

门户的 /v1/responses 与 Chat、Messages 一样会做跨引擎换家;换家失败时客户端只看到最终错误或成功,看不到中间的 429。

08 · 部署

双击一个脚本,或者一条 docker 命令。

首次启动会自建目录、起三家引擎、打印入口地址与合并 Key。面板默认密码 admin,登录后请立刻改。

端口分配
端口用途对外
8817门户:面板 + API是
8811WorkBuddy 引擎否
8812Qoder 引擎否
8813Trae 引擎否
双击 .bat,前台起全部
WorkBuddy x Qoder x Trea-hub.bat

:: 打开面板
start http://127.0.0.1:8817

需要 Python 3.10+;局域网版脚本 …-lan.bat 会强制要求 Key。

09 · 工程与隐私

融合层不加黑盒,也不碰你的数据。

发布前有闸门,同步后有逐字节校验,更新时有保护名单。

数据只落本地

账号、用量、日志、面板设置全在你自己机器上;仓库不含任何真实账号、Key 或用量。.gitignore 硬性排除 accounts/、usage/、logs/、state/、hub/settings.json。默认密码 admin,局域网模式强制 Key。

升级不丢数据

面板「设置 → 版本与更新」检查 GitHub Release 后点一次立即更新:下载 → 只覆盖代码 → 自动重启。账号 / 用量 / 日志 / 设置都在 updater.PROTECTED 里写死跳过。

上游可校验

python hub/tools/sync_upstream.py --wb --qd --trae 同步后由 verify_sync 逐字节比对,除 hub-patch 标记块外必须完全一致 —— 引擎逻辑改没改,逐字节对得上。

发布有闸门

python hub/tools/release_check.py:前端 75 项 + hub 324 项判据(23 个套件)+ 上游一致性 + 重启不丢数据 + 写失败可诊断,全绿才发版。

与三家上游的关系

引擎上游仓库收录方式许可证
wbWorkBuddyardeyouxipianyi/workbuddy2api-hub原样收编,补错误处理块按上游原许可证
qdQodershuishuipingan/qoder2api-hub原样收编,补错误处理块按上游原许可证
traeTraetrae2api-hub原样收编,补错误处理块按上游原许可证
hub融合层本仓库 hub/ · admin/ · docs/门户、路由、聚合、面板MIT

10 · FAQ

接入时最容易卡住的几件事。

只开放 8817 一个端口,怎么区分三家?
门户按「模型在谁家、哪个区可用」选路,再转发到对应引擎的内部回环端口(8811 / 8812 / 8813)。这三个端口只监听 127.0.0.1,外部连不上;客户端只需要一个 base_url。也可以在高级设置里单独关掉某一家引擎。
某个账号或某一家挂了,客户端要改配置吗?
不用。401/429/502/503/504 触发跨引擎换家:门户在还没向客户端写出任何字节的前提下重试下一家,客户端无感。已经写出首字节后绝不重发,避免出现同一个回答来两遍。
合并 Key 和引擎 Key 有什么区别?
引擎 Key 只走那一家、只看得见他家的模型;合并 Key(mrg- 前缀)能看见三家全部模型(同名只算一个),并自动挑路。两把都能设作用域:只用哪些模型、只用哪些引擎,越权返回 403 model_not_allowed 或 503 engine_not_allowed。
Codex 和 Claude Code 能直接接吗?
Codex 走 OpenAI Responses(/v1/responses),Claude Code 走 Anthropic Messages(/v1/messages,x-api-key 与 Authorization 都认)。两者填同一个 base_url:http://127.0.0.1:8817/v1,密钥用面板里的合并 Key。
一键更新会不会覆盖我的账号和用量?
不会。更新只覆盖代码路径,账号、用量、日志、hub/settings.json、state/ 都在 updater.PROTECTED 保护名单里写死跳过,更新完自动重启。发布闸门里专门有一项判据验证「重启不丢数据」。
三家引擎的代码被改过吗?出问题算谁的?
引擎原样收进 hub/engines/,只在固定的 hub-patch 标记块里补了错误处理与提示;verify_sync 逐字节校验标记块之外必须与上游完全一致。三家著作权归各自上游项目,按原许可证使用;融合层(hub/、admin/、docs/)以 MIT 发布。
Docker 里端口怎么映射,数据放哪?
容器内门户固定 8817,宿主机端口自己定:-p 18791:8817;数据挂 -v "$PWD/data:/app/data",容器重建不丢。18789 / 18790 / 18792 是三家引擎的调试端口,只在排查单家问题时才用。也可直接 docker compose up -d。
面板显示某一家「没有返回数据」是怎么回事?
页面顶部会挂黄色横幅,告诉你下面的数字只是半边统计,不是全量。先在顶栏右上角看「三引擎 3/3 在线」是否变红,再到设置 → 系统自检跑一遍逐条 PASS/FAIL,哪一环没接上会直接写出来;想留证据可以生成一段可复制的体检报告。
收费吗?有没有云端服务?
融合层 MIT 开源、免费使用,没有付费档位,也没有任何云端中转服务 —— 整个网关跑在你自己的机器或自己的容器里。上游用量取决于你自己的账号权益。

把三个窗口,减成一个。

克隆就跑,MIT 开源,数据不出本机。有问题欢迎在仓库开 Issue。