workbuddy2api-hub README

The project's README from github.com/ardeyouxipianyi/workbuddy2api-hub. As one markdown file: README.md.

WorkBuddy2API-Hub — 国际版、国内版多账号网关中枢

Version 1.6.20 Python OpenAI API Dual Realm License Vibe Coding

把腾讯 www.workbuddy.ai（国际版）与 codebuddy.cn（国内版）的原生服务封装成标准 OpenAI 兼容接口（Chat Completions / Responses），并提供默认关闭的实验性 Anthropic Messages 适配；同时补齐多账号调度与运维能力：

⚡ Vibe Coding 产物：本项目为 100% Vibe Coding 协同产物——人类开发者提出架构与业务意图，AI 助手端到端完成逆向分析、链路调度、WAF 指纹脱敏与界面编写。

📌 提交代码贡献前：请先查看并严格遵循贡献手册 CONTRIBUTING.md——提交格式、测试门禁与端到端冒烟要求都在那里（AI / 智能体请特别注意其中的硬性规则节）。

一、快速启动

1. 本机运行

Windows 双击 start-wb-proxy.bat，保持窗口运行；macOS 双击 start-wb-proxy.command（首次被 Gatekeeper 拦截时右键 →「打开」确认一次），或在终端执行 ./start-wb-proxy.sh [端口]（默认 8788）。

启动后：API 地址 http://127.0.0.1:8788/v1，Web 看板 http://127.0.0.1:8788/。首次启动还没有账号，打开看板点「+ 添加账号 (OAuth)」完成授权即自动入库。

绿色包自带的精简 Python 运行时只覆盖 Windows；macOS / Linux 直接使用系统 Python，需要 3.9+（启动脚本找不到内置运行时会明确打印所用的解释器与版本）。Docker 部署自带基础镜像，不受影响。

zip 解压后若提示权限不足，先执行一次：chmod +x start-wb-proxy.sh start-wb-proxy.command start-wb-proxy-lan.sh start-wb-proxy-lan.command allow-firewall.command

2. 面板访问密码

看板需要面板访问密码（默认 admin），它与 API Key 相互独立：密码只用于打开看板，可在「设置」页修改（或启动时 --panel-password 指定），以 PBKDF2-SHA256 摘要存于 accounts/settings.json（不存明文），登录态只留在浏览器会话里。

本机 / 受信局域网自用可带 ?pwd=面板密码 免手输直接进面板（如 http://127.0.0.1:8788/?pwd=admin）；公网暴露时不要用——密码会留在浏览器历史与反向代理日志里。注意它和局域网共享的 ?key= 不同：?key= 只把 API Key 存给 /v1 用，不会自动登录面板。首次登录后请立即改掉默认密码。

3. 局域网共享

4. 多 API Key 与出口绑定

「设置」页可管理多个 Key，每个 Key 独立出口——不同客户端各用各的 Key，国内外流量互不干扰：

5. Docker 部署

预编译双架构镜像（linux/amd64、linux/arm64）发布在 GHCR 与 Docker Hub，无需克隆代码、无需本地编译：

方式一：一键脚本（推荐）

# 官方源（可直连 GitHub 环境）：
curl -fsSL https://raw.githubusercontent.com/ardeyouxipianyi/workbuddy2api-hub/main/quick-deploy.sh | bash

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

NAS（如飞牛 fnOS）普通用户没有 Docker 权限时，把结尾的 bash 换成 sudo bash。再次运行同一条命令即平滑升级，账号与用量数据不受影响。

方式二：NAS / 面板单文件 Compose

在 NAS 或面板的 Compose 界面新建项目并粘贴以下内容保存启动，无需拉取源码：

services:
  wb-proxy:
    image: ghcr.io/ardeyouxipianyi/workbuddy2api-hub:latest   # 或 ardeyouxipianyi/workbuddy2api-hub:latest
    container_name: wb-proxy
    restart: unless-stopped
    ports:
      - "8788:8788"          # 左侧宿主端口可自选；右侧必须与下面的 PORT 一致
    environment:
      - HOST=0.0.0.0
      - PORT=8788
      # - API_KEY=your_secret_key   # 留空则自动生成并打印在启动日志
      - TZ=Asia/Shanghai
    volumes:
      - ./accounts:/app/accounts    # 账号凭证与配置（更新/重建容器不丢）
      - ./usage:/app/usage          # 用量流水日志（更新/重建容器不丢）

更新：面板里点「拉取最新镜像并重启」，或 docker compose pull && docker compose up -d。

方式三：Watchtower 自动静默更新

docker run -d --name wb-proxy-watchtower --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower:latest --interval 86400 --cleanup wb-proxy

补充与排错

6. 测试

python tests/run_all.py            # 全部套件
python tests/run_all.py realm      # 只跑名字里含 realm 的

二、核心特性

1. 模型列表对齐官方桌面端

对官方本地配置清单（50+ 底层模型）做清洗：剔除行内补全专用模型（codewise-*、completion-gf、hunyuan-3b/7b 等）与多云专线变体（*-volc、*-lkeap 等），严格对齐官方 Windows 桌面端，并宣告每个模型的上下文窗口、单次最大输出、视觉支持、工具调用与推理档位。

清单与上游 GET /v3/config 的 agents[cli].models 保持同步（接口不可用时依次回落到桌面端缓存文件、内置快照）；过滤规则：去掉 5 个档位别名与 auto、去掉 -sg / -x 变体、同名的只留 0.00 倍率那一档。上游新上架的模型无需发版即出现在 /v1/models。

同名模型（如 deepseek-v4.1-flash）暂未实现跨国内 / 国际账号的混合轮询：两个区域作为独立出口分别配置与调度，请求只走当前所选网关。这是出站指纹对齐与账号防风控的取舍，待长期实测确认稳定后再补。

2. 设备指纹隔离（derive_id）

国际版与国内版共用同一套算法内核：以账号 UID 结合固定业务盐值单向哈希派生机器码与会话标识——同一账号每次出站都来自同一台虚拟设备（不随机漂移），不同账号之间彼此独立（阻断跨账号关联风控）。

3. 国内版自动化

4. 后台常驻调度器

常驻后台，按固定整点执行自动化运维排程：

5. 限额护栏（设置 → 账号限额）

四条账号级护栏放在同一张表里，每行一条、每列一个作用域：

护栏 作用
保留积分 账号余额低于该值时不再接单，避免余额被用尽后触发上游的提醒短信
每日 Token 限额 账号当日消耗的 token 达到该值时暂停接单，请求自动切到其他账号
每日积分限额 账号当日消费的积分达到该值后只服务免费模型，需要花积分的模型自动切号
按模型每日 Token 限额 账号在单个模型上当日消耗的 token 达到该值时只禁该模型，同账号其他模型照常

6. OpenRouter 价估算（等价 token 花费）

把每条请求的 token 消耗按 OpenRouter 公布的模型价折算成等价金额，回答「这些 token 放在 OpenRouter 上值多少钱」——与账号实际扣除的积分是两个口径，看板里并列显示：

7. 本地网络工具（可选，默认关闭）

Codex App 这类客户端会在 Responses 请求里声明 web_search / web_fetch，而上游没有对应的执行器——声明送上去只会拿到一句 unsupported call。打开「设置 → 本地网络工具」后，网关把那份声明换成自己的同名 function，拦下模型的调用并在本地执行（搜索在 DuckDuckGo / Bing / Wikipedia / Stack Overflow / Google News 之间自动轮换，抓页面抓模型给出的 URL），再把结果喂回模型，最多代跑 3 轮（WB_MAX_WEB_ROUNDS 可调，上限 8）；搜索过程会作为 web_search_call 卡片事件与 url_citation 引用回到客户端。

8. 智能体一键配置

看板「智能体配置」页可检测本机已装的 AI 客户端，一键把它们的配置指向本网关，改前自动备份、随时字节级还原：

客户端 写入位置 协议
Claude Code ~/.claude/settings.json 原生 Anthropic Messages（自动剥 /v1 后缀）
Codex CLI ~/.codex/config.toml、~/.codex/auth.json Responses API
OpenCode ~/.config/opencode/opencode.json OpenAI 兼容（@ai-sdk/openai-compatible）
DSH (DeepSeek Harness) ~/.dsh/settings.yaml、~/.dsh/.credentials.yaml OpenAI 兼容
Crush (Charm Crush) ~/.config/crush/crush.json OpenAI 兼容
ZCode ~/.zcode/v2/provider_config.json OpenAI 兼容（openai-chat-completions；配置前先退出 ZCode，运行中它会重写该文件）

用法：打开看板 →「智能体配置」→ 选 API Key（支持全局默认或绑定特定出口的多 Key）、默认模型与网关地址 → 在检测到的客户端卡片上点「一键配置」；随时可点「一键还原」。

DSH：思考档位与上下文窗口写在哪（~/.dsh/settings.yaml）

一键配置给 DSH 写的每个模型条目都带上网关宣告的规格，DSH 会据此生成它自己的选择器：

    wb-proxy:
      api: openai-completions
      baseURL: http://127.0.0.1:8788/v1
      compat: {thinkingFormat: openai, supportsReasoningEffort: true}
      models:
        - id: deepseek-v4.1-flash
          contextWindow: 1000000     # 客户端认为的上下文容量（压缩 / 截断按它算）
          maxTokens: 128000          # 单次输出上限
          reasoningEfforts:          # 会话里可选的思考档位：键=档位，值=发给网关的拼写
            low: low
            high: high
            max: max

在另一台机器上接入（远程 / 非本机）：看板的一键配置运行在网关进程里，改的是网关所在机器的配置目录——所以它只在网关本机、且用 127.0.0.1 打开看板时可用（远程访问、容器 / OpenWrt 部署下按设计隐藏入口）。客户端装在别的电脑（网关跑在服务器 / NAS / 路由器上）时，改用自带的配置器 CLI：它在客户端所在的机器上运行，写本机配置、只通过 HTTP 从网关取模型表：

# 1. 取配置器（网关直接提供该文件；也可从仓库 / 绿色包复制 wb_agents.py）
curl -fsSL http://<网关地址>:8788/agents/cli -o wb_agents.py

# 2. 一条命令接入（需要 Python 3.9+，Key 在「设置」页生成）
python wb_agents.py list                                   # 本机装了哪些客户端
python wb_agents.py apply --client codex --base-url http://<网关地址>:8788/v1 --key sk-xxxx
python wb_agents.py restore --client codex                 # 随时字节级还原

模块内部设计与新增客户端的方法见 docs/CONTRIBUTING-智能体配置.md。

9. 剩余用量估算（数据看板 → 剩余用量估算）

上游按 24 小时窗口给「账号 × 模型」配额（用满时 429 / code 6004 会带上重置墙钟），但从不告诉你这个窗口的预算是多少。看板新增的「剩余用量估算」区块把它反推出来：

10. 积分获取历史（数据看板 → 积分获取历史）

「积分扣减历史」看的是花掉的部分，这一块补上进账的部分：上游对每个账号返回一份积分包清单（每日活跃奖励的 Bonus Pack、免费套餐、活动包…），每个包带面额、发放时间与到期时间。区块把全部账号的包摊平成一张表、新的在前：

12. 单请求体体积限制（WB_MAX_PAYLOAD_BYTES）

针对携带超长历史、大内联附件或高分辨率图片的请求，网关默认对单次请求体做上限保护（默认 16MB = 16777216 字节），以防止异常巨大的请求挤占内存。若请求体超过上限，网关在解析前即直接返回 HTTP 413（payload too large 并附带 gateway_hint 说明）。

如需调整上限（例如提升至 32MB）：

11. 后台模型重定向（WB_BACKGROUND_MODEL_NAMES / WB_BACKGROUND_MODEL_TARGET）

桌面客户端（Codex 等）的模型选择器只管主对话线程。客户端内置的「模型路由配置」会把后台工作——记忆生成、环境建议、临时内容生成、自动化任务——送到自己硬编码的模型上，UI 里选什么免费模型都改不掉。这些请求带着同一把 Key 打到网关，于是在共享 Key 的部署里悄悄烧付费积分。

网关在唯一的 POST 分发点（选账号之前）把这类模型名改写成免费目标：

改写只动 model 字段，请求体其余部分原样透传；命中与改写都会记一条 alias: background model X -> Y 日志，方便核对。OpenAI 形状的两个路由（/v1/chat/completions、/v1/responses）与 Anthropic 形状的 /v1/messages 都覆盖。不需要时把名单设为空即可关闭。

三、账号添加与管理

打开看板 http://127.0.0.1:8788/，在「账号」区域操作。若上游对某账号的单个模型返回 429，账号行会显示受限模型与预计恢复时间（浏览器本地时间），该账号仍可用于其他模型；模型冷却只在当前进程内保留，重启清空。

方式一：浏览器 OAuth 授权（推荐，免客户端）

  1. 点「+ 添加账号 (OAuth)」；
  2. 选择要登录的区域（国际版 / 国内版），点弹出的官方授权链接并在浏览器完成登录；
  3. 程序自动检测回调，账号自动加入账号池，无需手动复制凭证。

方式二：从本机桌面客户端导入

  1. 让 WorkBuddy 桌面客户端保持运行并已登录（Windows 上网关要从它的进程内存里取解码密钥，这一步不能省）；
  2. 看板点「扫描桌面客户端账号」，弹窗列出本机已登录的国际版 / 国内版账号；
  3. 若提示凭据已加密，先把解码密钥交给网关，再点账号行的「导入」：
    • Windows：点弹窗里的「回收密钥」（只读，实测 1 秒内完成）；
    • macOS / Linux：进程内存回收只在 Windows 上实现，弹窗里会直接给出输入框，粘贴密钥即可（见下）。

关于加密凭据：桌面客户端从 2026-09-24 起把 accessToken / refreshToken 存成 $wbEncrypted 信封，网关按客户端 packages/at-rest-crypto 的同一套方案（AES-256-GCM + WB-AAD 帧头）就地解密，导入的仍是可直接使用的 token；解码密钥编译在客户端原生模块里、磁盘上没有明文。Windows 上可以从正在运行的桌面端进程内存里找回（只读 OpenProcess(PROCESS_VM_READ) + ReadProcessMemory，不向客户端写任何东西）；macOS / Linux 上没有这条路，看板会显示输入框让用户手动粘贴一次——两种方式拿到的密钥都只留在网关进程内存、不落盘不写日志，且都要先过 keyblob 自检（protectorKeyId 对得上、能解出 32 字节主密钥）才生效。

手动粘贴接受两种写法（都不用自己换算）：64 位 hex 的保护密钥，或 44 字符 base64 的 atRestSecretKey。拿不到密钥时，macOS / Linux 上请直接用方式一走浏览器登录。提示权限不足时，以管理员身份启动网关再试一次。

四、客户端配置与接入

Codex CLI / Claude Code（Responses API）

export OPENAI_BASE_URL="http://127.0.0.1:8788/v1"
export OPENAI_API_KEY="你在看板设置中添加并绑定的API_Key"

Claude Code / Anthropic SDK（实验性 Anthropic Messages 适配，默认禁用）

⚠️ 积分风险：默认拒绝调用。 网关对外接受 Anthropic Messages，但对内将请求转换为 WorkBuddy 的 /v2/chat/completions；cache_control 被忽略。已有 #367 报告长会话缓存命中率仅约 11%，单次消耗超过 100 积分。该问题的因果机制仍待定位，故暂时默认禁用整个 Anthropic Messages 入口，而不假装完全兼容。禁用时 /v1/messages、/messages 及对应 count_tokens 入口返回 Anthropic 格式的 HTTP 400（invalid_request_error），请求不会转发至上游。

只有确认理解风险后，才在网关服务端显式设置 WB_ENABLE_ANTHROPIC_MESSAGES=1 并重启。Docker Compose 可在 wb-proxy.environment 中加入 - WB_ENABLE_ANTHROPIC_MESSAGES=1；其他环境则在启动网关前设置此环境变量。客户端配置示例：

export ANTHROPIC_BASE_URL="http://127.0.0.1:8788"
export ANTHROPIC_API_KEY="你在看板设置中添加并绑定的API_Key"

实验性适配包含 system、text、image、document、tool_use、tool_result、tools 与 tool_choice 等字段转换，并将响应包装为 Anthropic 的流式事件序列或非流式消息。这不是向上游的原生 Anthropic 透传。

已知边界：服务端工具（web_search 等）上游不支持，会被丢弃并在 system 里注明；thinking / redacted_thinking 历史块不回放；top_k、cache_control、context_management 与 betas 被忽略；/v1/messages/count_tokens 在显式启用后只提供网关的 CJK 感知估算值，不是官方分词器的精确值。

五、看板与接口一览

访问 http://127.0.0.1:8788/ 使用集成看板：顶部页签默认是「网关与账号 / 数据看板 / 智能体配置 / 设置 / 运行日志」，每个主页面左侧有一条按页面区块现场生成的导航（点击直达、滚动高亮、地址栏带锚点，可收起成窄轨）。

账号多起来之后（国际版十几个），账号列表与「当前禁用」总览会把网关页挤下去。设置页的「账号独立成一个页签」默认关闭，账号区就留在「网关与账号」页（位置与拆分前一致）；打开后它们和签到记录一起成为独立的「账号」页：添加 / 导入 / 导出、启用停用、凭证与积分刷新、代理出口绑定都在那里，顶部页签变成「网关 / 账号 / 数据看板 / 智能体配置 / 设置 / 运行日志」。页内的「签到与活跃记录」读 GET /activity/history，可按区间 / 任务 / 结果 / 账号筛选（筛选在服务端做），一行一次真实尝试，列出 时间 · 账号 · 区域 · 任务 · 来源 · 结果 · 说明，最新在前；超过一页时用「加载更多」往下翻，上限 1000 行——「这个账号昨天到底签成了没有」不用再去调度器日志里翻。

「数据看板」页顶部可切换统计口径：今日 / 本周 / 本月 / 全部历史 / 自定义（本周自周一零点起算、本月自 1 号零点起算，任一侧留空表示不限），切换后 KPI 卡片、账号用量透视表与模型性能表一起切到同一窗口。

方法 路径 说明
GET / Web 用量与任务监控看板
POST /v1/chat/completions 标准 Chat Completions 接口
POST /v1/responses Responses API 协议接口
POST /v1/messages 实验性 Anthropic Messages 适配，默认禁用（HTTP 400）；需显式启用并承担缓存风险
POST /v1/messages/count_tokens 实验性 Anthropic 计数估算接口，随 Messages 入口默认禁用
GET /v1/models 官方对齐模型列表（含能力与规格宣告）
GET /pricing 定价状态：当前生效策略、上次/下次取价时间、未定价清单（分类 + 候选）
POST /pricing/refresh 立即取一次价（需面板会话）
POST /pricing/mapping 手填 / 清除「模型 → OpenRouter id」运行期映射，随后自动取价（需面板会话）
GET /agents 客户端探测概览、支持的模型清单及网关连接地址
GET /agents/cli 智能体配置器源码（供远程机器直接 curl 取用，免面板鉴权；与仓库内 wb_agents.py 逐字节一致）
POST /agents/apply 一键写入客户端配置并备份原件（需面板会话）
POST /agents/restore 一键还原客户端至首次配置前的状态（需面板会话）
GET /tasks 国内版成长任务、连续打卡与猫猫日常状态
POST /tasks/run 触发国内成长任务全自动点亮与领奖
POST /tasks/travel 触发猫猫日常旅行（派出 / 领奖）
GET /scheduler 定时调度器运行状态与排程日志
POST /scheduler/trigger 手动立即执行后台巡检保活
GET /activity/history 账号每日活动历史：签到与每日活跃的每一次真实尝试（range / uid / task / result / limit，最新在前）

| GET | /accounts/credits/grants | 积分获取历史：各账号积分包（发放时间 / 面额 / 剩余 / 到期 / 状态），只读内存快照、不发上游请求 | | GET | /usage/remaining | 剩余用量估算：每个账号 × 模型在当前 24h 窗口的已用 / 预算 / 剩余（预算取撞线账号的平均用量；需面板会话） |

六、版本更新记录 (Changelog)

Unreleased

已发布版本的完整记录（v1.4.5 ~ v1.7.12，含每版的 PR 归属）见 docs/CHANGELOG.md。

七、致谢与引用声明 (Credits & References)

协议兼容、风控规避与任务链路设计过程中，参考并吸纳了以下开源项目的经验与逆向成果：

PR 贡献者（v1.4.5 之前的改动未进上方更新记录，这里一并列出）：

八、免责声明 (Disclaimer)

  1. 本项目为非官方自托管网关，仅供技术研究、逆向协议学习与个人合法授权账号在私有环境测试使用。
  2. 本项目不提供任何账号及额度。请严格遵守官方服务条款，禁止用于任何商业转售、恶意并发或违规滥用。

workbuddy2api-hub (ardeyouxipianyi/workbuddy2api-hub)

reverse-proxy
Searching Database…

1.6K ·GitHub
Workbuddy2api-hub

> zip 解压后若提示权限不足，先执行一次：chmod +x start-wb-proxy.sh start-wb-proxy.command start-wb-proxy-lan.sh start-wb-proxy-lan.command allow-firewall.command

Creator
ardeyouxipianyi
Size
5.2 MB
Stars
1.6K
Updated
CommitOct 17Releasev1.7.12Oct 17
Age
1mo
Commits · 90 Days