开源多账号反代网关WorkBuddy2API-Hub:完全解析WorkBuddy国际国内双区AI编程中枢
开源多账号反代网关WorkBuddy2API-Hub:完全解析WorkBuddy国际国内双区AI编程中枢
WorkBuddy2API-Hub 是一款开源多账号反代网关,把 WorkBuddy 国际版(workbuddy.ai)与国内版(codebuddy.cn)封装成标准 OpenAI 兼容 API 与原生 Anthropic Messages 接口,支持 Codex、Claude Code、DSH 等主流 AI 编程客户端,并提供双区独立调度、Web 看板、限额护栏与每日自动化签到等完整运维能力。
一、WorkBuddy2API-Hub 能解决什么问题?
AI 编程订阅账号普遍存在三类痛点:额度分散在多个账号、客户端协议不统一、国际版与国内版各自为政。WorkBuddy2API-Hub 把这些问题收敛到一个本地进程里:
- 三协议统一出口:
/v1/chat/completions(Chat Completions)、/v1/responses(Codex 专用)、/v1/messages(原生 Anthropic Messages,流式/非流式),任意 OpenAI 兼容客户端改一个 Base URL 即可接入; - 双区域独立路由:国际版与国内版各自独立配置与调度,看板顶部一键切换出口,状态自动落盘;
- 多账号池化调度:同一出口的多个账号自动轮转,单账号触达 429 限流时自动冷却并切换其他账号;
- 纯 Python 标准库实现:零三方依赖,兼容 Python 3.9+,Windows 绿色包双击即用,也提供 Docker 双架构镜像与 OpenWrt 安装包。
核心网关逻辑集中在 wb_proxy.py,Web 看板由单文件 dashboard.html 承载,整个项目无需 pip 安装任何依赖。
二、核心特性清单(新手重点看这里)
| 特性 | 说明 | 关键模块 |
|---|---|---|
| 🌐 双区路由 | 国际版 17 个 / 国内版 14 个官方对齐模型,独立出口互不干扰 | wb_catalog.py |
| 🔑 设备指纹隔离 | derive_id 以账号 UID 单向哈希派生机器码,同账号不漂移、账号间互不关联 |
wb_fingerprint.py |
| 🤖 每日自动化 | 国内版签到/成长任务/猫猫旅行,国际版每日活跃打卡,09:00、21:00、22:00、01:00 固定排程 | wb_scheduler.py |
| 🛡️ 限额护栏 | 保留积分、每日 Token、每日积分、按模型 Token 四条护栏,单账号独立计数,本地 0 点解封 | wb_settings.py |
| 💰 价格估算 | 按 OpenRouter 公布价把 token 折算成等价花费(人民币/美元可切),悬停可看完整定价链 | wb_pricing.py、pricing/pricing.json |
| ⚡ 智能体一键配置 | 自动检测本机 Claude Code / Codex / OpenCode / DSH / Crush / ZCode 并一键指向网关,改前备份、可字节级还原 | wb_agents.py |
| 📊 剩余用量估算 | 从 429 撞线事件反推 24 小时窗口预算,实时显示每个账号×模型的已用/预算/剩余 | wb_logstore.py |
💡 模型目录严格对齐官方桌面端:剔除行内补全专用模型与专线变体,上游新模型无需发版即自动出现在
/v1/models。
三、三种部署方式:从双击到路由器
方式一:本机绿色包(最简单)
解压后双击对应平台的启动脚本,保持窗口运行即可:
- Windows:双击 start-wb-proxy.bat
- macOS / Linux:双击 start-wb-proxy.command,或终端执行
./start-wb-proxy.sh [端口]
启动后 API 地址为 http://127.0.0.1:8788/v1,Web 看板为 http://127.0.0.1:8788/。Windows 绿色包自带精简 Python 运行时;macOS / Linux 使用系统 Python(3.9+)。
方式二:Docker 部署(NAS / 服务器推荐)
预编译镜像同时发布 linux/amd64 与 linux/arm64,无需克隆代码、无需本地编译。直接编辑现成的 docker-compose.yml 并执行 docker compose up -d 即可,两个挂载目录是数据持久化的关键:
volumes:
- ./accounts:/app/accounts # 账号凭证与配置(重建容器不丢)
- ./usage:/app/usage # 用量流水日志
要点速查:
- 未显式指定
API_KEY时启动自动生成高强度随机 Key 并打印在日志里(docker compose logs wb-proxy | grep -i "api key"提取); - 镜像自带
HEALTHCHECK,docker ps可直接看到 healthy / unhealthy; - 更新只需
docker compose pull && docker compose up -d,账号与用量数据不受影响; - 仓库附带的一键脚本 quick-deploy.sh 与 OpenWrt 打包配方 wrt/README.md 也是从这里衍生。
需要源码部署时:
git clone https://gitcode.com/gh_mirrors/wo/workbuddy2api-hub.git
cd workbuddy2api-hub && python3 wb_proxy.py
方式三:局域网共享
Windows 双击 start-wb-proxy-lan.bat,macOS / Linux 执行 ./start-wb-proxy-lan.sh [端口] [Key],Base URL 换成 http://<局域网IP>:8788/v1 即可全家共用,Key 在看板「设置」页统一管理。
四、账号接入:两种方式三步搞定
打开看板 http://127.0.0.1:8788/(默认面板密码 admin,首次登录后请立即修改):
方式一:浏览器 OAuth 授权(推荐)
- 点「+ 添加账号 (OAuth)」;
- 选择区域(国际版 / 国内版),在弹出的官方授权链接中完成浏览器登录;
- 程序自动检测回调,账号自动入库,全程无需复制任何凭证。
方式二:从桌面客户端导入
让 WorkBuddy 桌面客户端保持运行并已登录,看板点「扫描桌面客户端账号」即可列出本机已登录账号。Windows 上网关可直接从运行中的桌面端进程内存回收解码密钥(只读、1 秒内完成);macOS / Linux 则在看板输入框手动粘贴一次密钥即可——密钥只留在进程内存,不落盘、不写日志。
五、客户端接入配置:两行命令完成
Codex CLI(Responses API)
export OPENAI_BASE_URL="http://127.0.0.1:8788/v1"
export OPENAI_API_KEY="看板设置页生成的Key"
Claude Code / Anthropic SDK(原生 Messages API)
export ANTHROPIC_BASE_URL="http://127.0.0.1:8788"
export ANTHROPIC_API_KEY="看板设置页生成的Key"
模型名称直接填 /v1/models 里列出的官方对齐 ID,如 deepseek-v4.1-flash、gpt-6-astra、glm-5.3。更省事的是「智能体配置」页:自动检测本机已安装的 6 类客户端,点「一键配置」把配置指向本网关,改前自动备份、点「一键还原」即可字节级回退(远程机器可用 CLI 版本 wb_agents.py 在客户端所在机器上执行,设计细节见 docs/CONTRIBUTING-智能体配置.md)。
多 Key 与出口绑定:每个 Key 可固定走国际版或国内版、可限定模型(支持 deepseek* 通配),不匹配的请求本机直接返回可读 400,不送达上游、不消耗额度,用量也按 Key 独立归属统计。
六、双区调度的底层机制
- 指纹隔离:国际版与国内版共用同一套
derive_id算法内核——以账号 UID 结合固定业务盐值单向哈希派生机器码与会话标识。同一账号每次出站都来自同一台「虚拟设备」(不随机漂移),不同账号之间彼此独立(阻断跨账号关联风控)。 - 限额护栏:四条护栏放在同一张表里,全局默认 + 可选分版本设置,填
0即关闭(默认全关);某出口全部账号达额时返回429,Retry-After指向本地 0 点恢复。 - 剩余用量估算:上游按 24 小时窗口限流却从不告知预算,网关从「账号撞线时刻的窗口用量」反推预算(接口
GET /usage/remaining),没有撞线记录的组合按最近 24h 用量给出保守下界。 - 价格估算:按 OpenRouter 模型级公布价折算等价花费,输入区分缓存命中/未命中两档单价,调价不改写历史数字;人民币/美元一键切换。
七、看板与接口一览
看板顶部默认包含「网关与账号 / 数据看板 / 智能体配置 / 设置 / 运行日志」页签,「数据看板」支持今日 / 本周 / 本月 / 全部历史 / 自定义五种统计口径。主要接口:
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / |
Web 用量与任务监控看板 |
| POST | /v1/chat/completions |
标准 Chat Completions |
| POST | /v1/responses |
Responses API(Codex) |
| POST | /v1/messages |
原生 Anthropic Messages |
| GET | /v1/models |
官方对齐模型列表 |
| GET | /usage/remaining |
剩余用量估算 |
| POST | /agents/apply / /agents/restore |
客户端一键配置 / 还原 |
| GET | /scheduler |
定时调度器状态与排程日志 |
八、工程质量与项目结构
- 纯标准库、零依赖,CI 覆盖 Python 3.9 / 3.12 × Ubuntu / Windows 矩阵;
- 146 个测试套件(108 个 Python + 38 个 JS),
python tests/run_all.py一键全跑,入口见 tests/run_all.py; - 版本迭代记录完整,已发布版本(v1.4.5 ~ v1.7.4)详见 docs/CHANGELOG.md;
- PR 贡献规范见 CONTRIBUTING.md,发布门禁要求 tag 与源码版本严格一致。
九、谁适合用?
- 🧑💻 重度 AI 编程用户:手握多个 WorkBuddy 账号(国际/国内),希望池化额度、自动轮换;
- 🏠 家庭 / 小团队:Docker 或路由器部署 + 局域网共享,一人配置全家使用;
- 🔧 协议玩家:想把 Codex、Claude Code、DSH 等客户端统一指向一套 OpenAI 兼容端点。
⚠️ 免责声明:本项目为非官方自托管网关,仅供技术研究、协议学习与个人合法授权账号在私有环境测试使用;不提供任何账号及额度,请严格遵守官方服务条款,禁止商业转售与违规滥用。