WorkBuddy2API-Hub 部署教程:把国际版 / 国内版账号池接成 OpenAI 兼容网关(v2.0.1)

摘要
WorkBuddy2API-Hub 把腾讯 WorkBuddy 国际版与国内版账号封装成 OpenAI 兼容 API 的自托管网关,自带 Web 面板、多 API Key 权限与自动签到。本文基于 v2.0.1 讲清 Docker / 便携包 / OpenWrt 三种部署与客户端接入。
WorkBuddy2API-Hub 是一个自托管的账号池网关:把腾讯 WorkBuddy 国际版(workbuddy.ai)与国内版(codebuddy.cn)的账号,封装成标准的 OpenAI 兼容接口,顺带把多账号轮换、代理出口隔离和自动签到一起做了。它解决的是同一类麻烦——官方只给客户端,不给开放 API,本地那些只认 base_url + api_key 的工具就用不上你的账号。
本文基于 v2.0.1(2026-11-07 发布,MIT 协议,Python 3.9+)的源码与 Release 产物,在 NAS 上把网关真跑了一遍,把三条部署路线、账号接入、客户端配置和几个容易踩的坑一次讲清。
一、它能做什么
双域 + 第三出口:国际版(www.workbuddy.ai)、国内版(codebuddy.cn)独立调度,另有进程内直连的华为云 CodeArts 出口,不用再单独跑桥接服务。
协议兼容:
/v1/chat/completions、/v1/responses(Codex 用)、/v1/models,外加实验性的 Anthropic Messages,Claude Code 这类客户端可以直接接。多账号池:OAuth 快速导入、自动故障转移、配额轮转、会话粘滞,长会话不会每轮换号把前缀缓存冲掉。
出口隔离:每个账号可以绑定独立的 HTTP / SOCKS5 代理槽(支持账号密码认证),登录 IP 和调用 IP 保持一致,配合设备指纹隔离降低风控命中率。
多 API Key 权限分发:一个网关可以发多个 Key,分别绑定出口、限定模型白名单(支持
deepseek*这类通配符)和账号白名单,还能设额度护栏。自动化福利:国内版加油站签到、猫猫旅行、连登管家与抽奖、成长任务一键做;国际版每日活跃打卡;CodeArts 自动签到。
Web 面板:模型清单、账号、用量、请求记录、运行日志、设置都在一个页面里,改完即时生效。
部署形态全:GHCR 多架构镜像、免装环境的便携包、OpenWrt 的
.ipk/.apk安装包。
边界先说清楚:这是非官方客户端,项目自己也在 README 里挂了风险提示——2026-10-23 起上游明显收紧了对非官方客户端的识别与拦截。别拿主账号上,别共享,也别做转售。
二、部署前准备
一台常开的机器就行:NAS、软路由、小主机都可以。需要的东西不多:
运行环境:Docker(推荐),或者 Python 3.9+;源码跑起来是纯标准库依赖。
端口:默认
8788,面板和 API 共用这一个端口。网络:国内版一般直连可用;国际版如果网络不通,就在面板里配代理槽,让账号走出口。
账号:WorkBuddy / CodeBuddy 账号,建议专门准备小号。
三条路线怎么选:
路线 | 适合谁 | 优点 | 代价 |
|---|---|---|---|
Docker / Compose | 有 NAS、服务器 | 一条命令起、升级简单 | 需要 Docker 环境 |
便携包(zip) | Windows / macOS 桌面 | Windows 自带精简运行时,免装 Python | 需要手动解压、手动启动 |
OpenWrt 包 | 软路由用户 | 开机自启,全家共享 | 只适合路由器架构 |
从 Release 页下载的话,v2.0.1 一共 5 个资产,官方给了 SHA-256:
下完先校验,别嫌麻烦:
三、Docker 部署(推荐)
第 1 步:起容器
镜像在 GHCR,公开可拉,多架构(linux/amd64 + linux/arm64)都有,标签既有 latest 也有 v2.0.1。生产环境建议钉版本号:
项目也提供了官方一键脚本,图省事可以直接跑;国内网络访问 GitHub 不顺时用 gh-proxy 那条:
公网部署或要挂反向代理时,在管道前加 WB_DEPLOY_MODE=public bash,再套 Nginx / Caddy / Cloudflare Tunnel 做 TLS。
第 2 步:确认启动日志
启动成功时日志会打出实际监听地址、当前出口和出站身份,格式大致是这样(这是我在 Linux 上跑出来的原文,端口换成了 8799):
panel : password is still the default 'admin' 这行也是在提醒你——第一件事是去面板改密码。
第 3 步:打开面板
浏览器访问 http://<主机IP>:8788/,默认密码 admin。登录后建议先做三件事:
设置里改面板密码;
想清楚要不要对局域网开放(
WB_DEPLOY_MODE=lan是默认值,监听0.0.0.0);加一个 API Key,别让
/v1/*裸着。
四、不装 Docker:便携包与 OpenWrt
便携包(Windows 最省事)
Windows 包解压后自带精简 Python 运行时(3.12.15),双击 start-wb-proxy.bat 就是后台静默启动,start-wb-proxy-visible.bat 带控制台窗口,方便看日志。macOS / Linux 用 ./start-wb-proxy.sh [端口],需要系统里有 Python 3.9+。
局域网共享模式用 start-wb-proxy-lan.sh(或 .bat),首次启动会自动生成高强度 API Key 并打印在控制台。
源码跑:优先用 -m
同一份代码、同一个账号池,python3 wb_proxy.py 和 python3 -m wb_proxy 的常驻内存差 47–54 MB(作者在 Windows 11 与 aarch64、Python 3.12–3.14 四套环境实测一致)。换成 -m 就白拿这段收益,512 MB 的设备上差不多是 10%。
-m 把当前目录加进 sys.path,脚本方式加的是脚本所在目录,所以务必先 cd。常用参数:
参数 | 作用 |
|---|---|
| 监听端口,默认 8788 |
| 监听所有网卡,并强制开启 API Key |
| 启动时设置面板密码,不用再进面板改 |
| 直接指定 |
| 凭据与用量目录,默认 |
| 导入本机 WorkBuddy 桌面客户端凭据后退出 |
| 只探测端口上有没有实例在跑(退出码 0 = 有,3 = 空闲) |
OpenWrt
Release 里两个包按固件版本选:workbuddy2api_2.0.1-1_all.ipk 给 opkg 系的老路线,workbuddy2api-2.0.1-r1.apk 给 25.x 之后的 apk-tools。
装完不会自动启动,得先设面板密码再启用:
配置在 /etc/config/workbuddy2api(权限 600),账号凭据与用量落在 /etc/workbuddy2api/,postinst 会自动把它加进 sysupgrade.conf 保留列表,刷固件不丢;升级也只替换 /usr/lib/workbuddy2api 下的程序文件。依赖 python3-light、python3-urllib、python3-uuid、python3-openssl、python3-sqlite3、python3-codecs——OpenWrt 把 ssl、sqlite3 和完整编码表拆成了独立包,所以装的时候别用 --nodeps 图快。
五、添加账号与 API Key
加账号
面板 →「账号」→「+ 添加账号 (OAuth)」,选国内版(copilot.tencent.com)或国际版(www.workbuddy.ai),在浏览器里完成官方登录授权,凭据会自动写进 accounts/ 并立刻进池。
远程部署或容器里跑的时候,浏览器回调地址是打不开的:把授权后跳转到的 http://127.0.0.1:.../oauth/callback?... 整条粘回面板的输入框,点「中转回调」即可。Windows 桌面端还可以用「扫描桌面客户端」直接吃本机已有的登录态。

配代理出口
设置 →「出口与网络」→「+ 添加槽位」,填 HTTP / SOCKS5 地址,需要认证就连账号密码一起填。加完之后在账号卡上绑定:这个账号的身份请求和出站调用都会走该槽,避免登录 IP 和调用 IP 对不上。
发 API Key
设置 →「API 与出口」→「+ 添加 API Key」,可以配四件事:
出口绑定:固定走国际版、国内版或 CodeArts;不绑就跟随面板当前出口;
模型限制:白名单支持通配符,比如
deepseek*,违规请求在本机直接 400,不浪费上游额度;账号白名单:限定这个 Key 只能用哪几个号;
额度护栏:按 Key 统计调用次数、Token 消耗与积分。

六、接入客户端
面板里建好 Key 之后,接入就是标准 OpenAI 套路:
Base URL:
http://<主机>:8788/v1(局域网用http://<局域网IP>:8788/v1)API Key:面板里建的那个 Key
模型:以
/v1/models返回的 id 为准
Codex CLI:
Claude Code(Anthropic Messages,实验性):
默认关掉是有原因的:长会话缓存命中率和官方有差距,作者选择保守。要用再开。
主要端点:
接口 | 方法 | 路径 | 说明 |
|---|---|---|---|
聊天补全 | POST |
| 流式 SSE、思维链回填 |
交互式响应 | POST |
| Codex 用的 Responses 协议 |
模型目录 | GET |
| 支持 |
生图 | POST |
| 需在设置里启用媒体模块 |
生视频 | POST |
| 异步任务,另有 |
健康检查 | GET |
| 账号数、就绪模型、出口状态 |
我这边实测:不带任何账号时 /v1/models 依然能返回国际版默认目录 19 个模型(deepseek-v4.1-flash、hy3、gpt-6-astra、grok-4.7、gemini-3.8-flash、kimi-k3.1-pro 等),?realm=cn 也正常 200;而 CodeArts 没启用时 ?realm=codearts 返回 503。也就是说模型清单跟账号是解耦的,面板「模型管理」页里还能看到每个模型的消费倍率、上下文窗口与思考档位。

有个 v2.0.1 的细节值得留意:客户端和 /v1/models 里看到的 deepseek-v4.1-flash,实际发给国际版上游时会改写成 deepseek-v4.1-flash-sg;白名单仍按 base 校验,用量记录里同时保留逻辑模型和计费模型。设 WB_INTL_MODEL_ALIAS=0 可关掉这层映射。
七、面板与账号池调度
面板分九块:总览、网关(模型管理)、账号、用量、自动化、智能体、媒体、设置、日志。日常最常看的是后三块里的「账号」「用量」「日志」。
调度这部分,理解了就知道为什么某个号会「消失」一阵子:
选号:按配额与可用性轮转,失败自动故障转移;
会话粘滞:小账号池的长会话固定同一账号,避免前缀缓存丢失、Token 消耗翻倍;
风控连坐:上游返回 403 / 11140 这类异常行为时,会按区域整体暂停派发,默认暂停 1800 秒;面板有实时倒计时和「立即解除暂停」,时长也能自己改,设 0 就关掉这套保护;
出口隔离:账号级代理槽 + 设备指纹,是这个项目跟「一个 UA 走天下」的同类最大的区别。

日志页会实时显示调度器、账号、模型目录的启动与运行信息,出问题先看这里,比猜快得多。
八、自动签到与福利任务
「任务与福利」页把能自动化的都摆出来了:
国内版:Buddy 加油站签到、猫猫旅行、连登管家与抽奖、成长任务一键领积分;
国际版:每日活跃打卡、网页通道打卡,另有一个「定时自动打卡」总开关;
CodeArts:启用出口后自动签到。
任务在后台调度器里跑(启动日志有一行 [调度器] 后台定时调度器已启动),时间点可以在设置里加,也能恢复随机。想手动补一次就点按钮,结果同样落在运行日志里。
九、验证与日常运维
三行命令确认跑通
/health 返回的字段比较全,我这边空池状态长这样(节选):
池子空的时候调 /v1/chat/completions 会明确报 503,而不是含糊地 500,这点做得挺克制:
备份与升级
备份就两样:accounts/(凭据 + 面板配置)和 usage/(用量流水),打包带走即可迁移。升级用 docker compose pull && docker compose up -d,或者面板里直接「拉取最新镜像并重启」;便携版设置页有检查更新和安装更新,也能开「每天自动检查更新」。
改配置
大部分配置在面板里改完即时生效(模型别名、提示词模式、限额、并发都是热加载);环境变量类的(端口、API Key、payload 上限、Anthropic 开关)改完要重启容器。
十、常见问题
Q:`/health` 是绿的,但客户端一调就 503?
池子里没有可用账号。先确认账号页里号是「可用」状态,再看是不是全在冷却或额度耗尽。空池时网关宁可报 503 也不会静默瞎转。
Q:面板是不是很危险?
默认密码是 admin,默认监听 0.0.0.0。三件事必做:改密码、别把 8788 直接映射到公网、要远程就套反代加 TLS 再叠一层认证。网关本身没有额外的用户体系。
Q:上游返回 `400` / `11-128` 怎么办?
这不是账号问题,先别急着换号轮换。按仓库里的 docs/TROUBLESHOOTING-11-128.md 收集同一请求的身份、最小请求和提示词对照结果;需要取证时开 WB_DUMP_11_128=1(只写脱敏摘要)或 full(含明文出站 body,文件落在 usage/11-128-dumps/)。
Q:请求体大一点就被断?
默认上限 16 MB,用 WB_MAX_PAYLOAD_BYTES 调(支持 1–256 MB)。超限会先回 413 再排空上传,不会直接 reset 连接。
Q:端口被占了,怎么判断是不是本项目?
用 python3 -m wb_proxy --probe-only --port 8788:退出码 0 表示端口上已经有健康实例,3 表示空闲。比 netstat 猜靠谱,能避免叠一层实例导致面板一直是空的。
Q:Claude Code 用起来感觉缓存命中率不高?
Anthropic Messages 是实验性适配,默认关闭;开了也别期待和官方一致,长会话体验有差距是这个协议转换的固有代价。
Q:会不会封号?
会。项目 README 写得很直白:2026-10-23 起上游对非官方客户端的识别与拦截明显收紧,风控、限流或封禁的后果由使用者自己承担。用小号、别共享、别转售,是唯一的降低损失办法。
写在最后
如果你手上正好有几个 WorkBuddy / CodeBuddy 账号,又想把它们接进 Codex、Claude Code 或者任何 OpenAI 兼容客户端,这个项目目前是功能最全的一档:双域调度、代理出口隔离、多 Key 权限、自动签到,别人拆成三四个工具做的事它一个进程包了。代价是它跑在灰色地带,上游一收紧就得跟着改,作者也已经把维护节奏降下来了。
只想尝鲜的话,Docker 起一个、加一个小号、发一个 Key,十分钟内就能验证值不值得留着。真要用起来,先读一遍仓库的风险提示,再决定拿哪个账号上。
相关链接
项目仓库:<https://github.com/ardeyouxipianyi/workbuddy2api-hub>
当前 Release(v2.0.1):<https://github.com/ardeyouxipianyi/workbuddy2api-hub/releases/tag/v2.0.1>
风控排错文档:<https://github.com/ardeyouxipianyi/workbuddy2api-hub/blob/main/docs/TROUBLESHOOTING-11-128.md>
容器镜像:
ghcr.io/ardeyouxipianyi/workbuddy2api-hub
