banner
约 3,900 字
13 分钟

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

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:

纯文本
workbuddy2api-hub-v2.0.1.zip      10,877,334 字节
  sha256 7fa5fe0770a06e389ce492928b8196807503f2264bdf1b5bd4f1b94143638ebf
workbuddy2api_2.0.1-1_all.ipk      1,142,219 字节
  sha256 86d5a00526aeb66dbd0d1b77c23646ae0079b3fa6973c9281a7152cffce70e1b
workbuddy2api-2.0.1-r1.apk         1,135,792 字节
  sha256 0184062a45378e44bb1ef5f95a3f0311c42c898a1989b48c7ea7452d30a3038e
checksums.txt / SHA256SUMS

下完先校验,别嫌麻烦:

bash
sha256sum workbuddy2api-hub-v2.0.1.zip
# 与上面的 7fa5fe07... 逐字符比对

三、Docker 部署(推荐)

第 1 步:起容器

镜像在 GHCR,公开可拉,多架构(linux/amd64 + linux/arm64)都有,标签既有 latest 也有 v2.0.1。生产环境建议钉版本号:

YAML
services:
  wb-proxy:
    image: ghcr.io/ardeyouxipianyi/workbuddy2api-hub:v2.0.1
    container_name: wb-proxy
    restart: unless-stopped
    ports:
      - "8788:8788"          # 左侧宿主端口可改,右侧必须与 PORT 一致
    environment:
      - HOST=0.0.0.0
      - PORT=8788
      - TZ=Asia/Shanghai
      # - API_KEY=your_secret_key   # 留空则自动生成并打印在启动日志
    volumes:
      - ./accounts:/app/accounts   # 账号凭据与面板配置,重建容器不丢
      - ./usage:/app/usage         # 用量流水,重建容器不丢
bash
docker compose up -d
docker compose logs -f --tail=50

项目也提供了官方一键脚本,图省事可以直接跑;国内网络访问 GitHub 不顺时用 gh-proxy 那条:

bash
# 官方源
curl -fsSL https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | bash

# 国内网络 / NAS 加速
curl -fsSL https://gh-proxy.com/https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | sudo bash

公网部署或要挂反向代理时,在管道前加 WB_DEPLOY_MODE=public bash,再套 Nginx / Caddy / Cloudflare Tunnel 做 TLS。

第 2 步:确认启动日志

启动成功时日志会打出实际监听地址、当前出口和出站身份,格式大致是这样(这是我在 Linux 上跑出来的原文,端口换成了 8799):

纯文本
[system] realm      : intl (www.workbuddy.ai)
[system] user-agent : WorkBuddy/5.9.4 workbuddy-ai/5.9.4 CLI/2.165.0
[system] listening  : http://127.0.0.1:8799/v1  (api key: off)
[system] dashboard  : http://127.0.0.1:8799/

panel : password is still the default 'admin' 这行也是在提醒你——第一件事是去面板改密码。

第 3 步:打开面板

浏览器访问 http://<主机IP>:8788/,默认密码 admin。登录后建议先做三件事:

  1. 设置里改面板密码;

  2. 想清楚要不要对局域网开放(WB_DEPLOY_MODE=lan 是默认值,监听 0.0.0.0);

  3. 加一个 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%。

bash
cd /path/to/workbuddy2api-hub        # 必须先进入 wb_proxy.py 所在目录
python3 -m wb_proxy --port 8788

-m 把当前目录加进 sys.path,脚本方式加的是脚本所在目录,所以务必先 cd。常用参数:

参数

作用

--port

监听端口,默认 8788

--lan

监听所有网卡,并强制开启 API Key

--panel-password

启动时设置面板密码,不用再进面板改

--api-key

直接指定 /v1/* 的 Bearer Token

--accounts-dir / --usage-dir

凭据与用量目录,默认 ./accounts、./usage

--import-desktop

导入本机 WorkBuddy 桌面客户端凭据后退出

--probe-only

只探测端口上有没有实例在跑(退出码 0 = 有,3 = 空闲)

OpenWrt

Release 里两个包按固件版本选:workbuddy2api_2.0.1-1_all.ipk 给 opkg 系的老路线,workbuddy2api-2.0.1-r1.apk 给 25.x 之后的 apk-tools。

装完不会自动启动,得先设面板密码再启用:

bash
uci set workbuddy2api.main.panel_password='换个强密码'
uci commit workbuddy2api
/etc/init.d/workbuddy2api enable && /etc/init.d/workbuddy2api start

配置在 /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 消耗与积分。

设置页的 API 与出口分组:Base URL、cURL 与各协议端点示例都能一键复制
设置页的 API 与出口分组:Base URL、cURL 与各协议端点示例都能一键复制

六、接入客户端

面板里建好 Key 之后,接入就是标准 OpenAI 套路:

  • Base URL:http://<主机>:8788/v1(局域网用 http://<局域网IP>:8788/v1)

  • API Key:面板里建的那个 Key

  • 模型:以 /v1/models 返回的 id 为准

Codex CLI:

bash
export OPENAI_BASE_URL="http://127.0.0.1:8788/v1"
export OPENAI_API_KEY="你在面板里建的 Key"

Claude Code(Anthropic Messages,实验性):

bash
# 网关侧先设 WB_ENABLE_ANTHROPIC_MESSAGES=1 再重启,默认是关闭的
export ANTHROPIC_BASE_URL="http://127.0.0.1:8788"
export ANTHROPIC_API_KEY="你在面板里建的 Key"

默认关掉是有原因的:长会话缓存命中率和官方有差距,作者选择保守。要用再开。

主要端点:

接口

方法

路径

说明

聊天补全

POST

/v1/chat/completions

流式 SSE、思维链回填

交互式响应

POST

/v1/responses

Codex 用的 Responses 协议

模型目录

GET

/v1/models

支持 ?realm=intl/cn/codearts

生图

POST

/v1/images/generations

需在设置里启用媒体模块

生视频

POST

/v1/videos

异步任务,另有 /v1/videos/<id> 与 /content

健康检查

GET

/health

账号数、就绪模型、出口状态

我这边实测:不带任何账号时 /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。也就是说模型清单跟账号是解耦的,面板「模型管理」页里还能看到每个模型的消费倍率、上下文窗口与思考档位。

模型管理:国际版 19 个模型的倍率、上下文、能力与思考档位一览
模型管理:国际版 19 个模型的倍率、上下文、能力与思考档位一览

有个 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:启用出口后自动签到。

任务在后台调度器里跑(启动日志有一行 [调度器] 后台定时调度器已启动),时间点可以在设置里加,也能恢复随机。想手动补一次就点按钮,结果同样落在运行日志里。

九、验证与日常运维

三行命令确认跑通

bash
curl -s http://127.0.0.1:8788/health
curl -s http://127.0.0.1:8788/v1/models -H "Authorization: Bearer <你的 Key>" | head -c 300

/health 返回的字段比较全,我这边空池状态长这样(节选):

JSON
{"ok": true, "realm": "intl", "crypto_ok": true, "accounts": 0, "accounts_ready": 0,
 "models_ready": {}, "api_key_required": false,
 "codearts": {"configured": false, "base_url": "https://snap-access.cn-north-4.myhuaweicloud.com"},
 "media": {"enabled": false, "realm": "cn", "identity": "desktop", "slots": 4}}

池子空的时候调 /v1/chat/completions 会明确报 503,而不是含糊地 500,这点做得挺克制:

JSON
{"error": {"message": "no usable account for realm 'intl': every candidate is disabled,
 cooling down, expired, out of upstream quota or parked by a local limit;该区域没有任何账号 - add or enable one at the dashboard (/)",
 "type": "server_error", "code": 503}}

备份与升级

备份就两样: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

END