说明:本项目原名
codebuddy2openai。随着架构全面升级并原生支持 Anthropic Messages (/v1/messages) 与 OpenAI Responses (/v1/responses) 协议,本项目已正式更名为 WorkBuddy2API,提供兼顾 OpenAI Chat、Responses 与 Anthropic 三大主流生态的统一本地 API 网关。
无需下载或安装原版腾讯 WorkBuddy 客户端,直接在浏览器中完成网页授权,
将腾讯代码助手能力转换为标准的 OpenAI (/v1/chat/completions)、Anthropic (/v1/messages) 与 Responses (/v1/responses) 三协议接口,
原生直连驱动 Codex CLI、Claude Code CLI、Hermes Agent、Cline、Roo Code、Cherry Studio 等各类主流 Coding Agent 与开发工具!
- 🔄 原生三协议网关支持 (Tri-Protocol Gateway):
- OpenAI Responses 协议 (
POST /v1/responses):采用解耦模块设计(responses_compat.py请求双向转换与 Responses 语义事件流状态机),原生支持 Codex CLI(wire_api="responses")、OpenCode 等长上下文 Agent,支持流式语义事件与非流式响应;SSE 事件完整携带sequence_number/response_id/item_id规范字段;原生支持input_image多模态输入(自动内联为 data URI)。内建可选 Codex 长上下文最小语义闭包投影压缩 (responses_projection.py),默认关闭(safe,保全语义),可经--optimize-context/WORKBUDDY2API_OPTIMIZE_CONTEXT=1/ 请求体optimize_context: true显式开启。 - Anthropic Messages 协议 (
POST /v1/messages):采用解耦模块设计(anthropic_compat.py请求响应双向翻译、anthropic_stream.pySSE 事件状态机),原生直连驱动官方 Claude Code CLI、Cline、Roo Code 等工具,支持流式输出与函数调用(tool_use)。 - OpenAI 对话补全端点 (
POST /v1/chat/completions,GET /v1/models):完整支持标准流式 SSE、原生 tools / tool_calls 函数调用,兼容各类 OpenAI SDK、IDE 插件与智能体。 - DeepSeek 思维链开关注入与多轮一致性回填 (
deepseek_thinking.py):自动对 DeepSeek 模型注入thinking: {"type": "enabled"}与 effort 档位,并在多轮对话中自动为 assistant 历史补齐reasoning_content: "",根除上游11133 model_param_invalid参数报错与思维链静默丢失。
- OpenAI Responses 协议 (
- 🖥️ 独立现代化桌面 GUI (Tauri v2 + 原生深色设计):提供直观的服务看板、端口设置、实时延迟测试与状态指示。
- 🔑 无需安装原版 WorkBuddy:集成浏览器 OAuth 授权全自动轮询流程,直接扫码/验证码登录获取凭据。
- 👥 多账号管理与切换:凭据统一持久化于本地数据库,支持一键切换活跃账号、手动刷新 Token 与账号删除。
- 🔀 多账号智能调度与到期日分层(先烧快过期额度):
- 支持
off(默认关闭)/failover(遇 429 / 6004 自动切号重试)/roundrobin(按请求数轮询分摊); - 按积分到期日分层优先(借鉴 momo0410/workbuddy-switch-gateway):自动提取各账号资产的最早到期日(日粒度 YYYY-MM-DD),优先调度最快过期的账号池,杜绝资产临期作废;同档账号平均轮换,未标记到期日账号保底兜底;
- 账号级冷却隔离(按「账号 + 模型」维度);调度策略运行时热读
settings.json,GUI 改完免重启内核即生效;/api/rate_limit的rotation.config_source字段可观测当前策略来源(hot=已热加载 /default=回退兜底)。
- 支持
- 📊 内嵌真实积分资产看板与夜间限免感知:
- 逆向对接腾讯官方计量计费接口,实时掌握账户剩余积分、资源包配额明细与使用进度条;
- 自然日今日用量统计:自动统计当日请求数(
reqsToday)、消耗 Token 数(tokensToday)与 429 频控次数; - 动态感知官方夜间限免:自动识别
23:00–08:00官方限免时段,前端实时打上 「🌙 夜间限免中」 专属徽章。
- 📈 请求用量可观测性(汇总 + 明细下钻 + 分组分析):
- 多档时间范围:用量页支持 4h / 24h / 今日 / 7d / 30d / 全部 六档切换,统计卡与趋势图同步裁剪;
- 请求明细下钻:逐条展示每次请求的时间、模型、结果、Token 与时延;失败行直接给出错误原因(如
HTTP 429 ...)、重试次数与重试原因,降级行给出请求模型 → 实际模型 · 降级原因完整链路; - 多维筛选与分页:支持模型名(大小写不敏感子串)与结果状态(成功/失败)联合筛选,50 条/页翻页浏览,筛选条件与时间范围联动;
- 按模型分组分布:自动汇总各模型的请求数、成功/失败数、Token 消耗与平均时延,按请求量降序排列;
- 以上数据源为内核写入的
usage.jsonl(--usage-log启用),Rust 侧usage_summary/usage_events命令聚合,前端零依赖手写 SVG 渲染。
- 🤖 Agent 智能体接入引导(只读,不改写客户端配置):
- Codex CLI:在
~/.codex/config.toml中配置wire_api = "responses"与base_url = "http://127.0.0.1:8787/v1"即可原生直连,享受自动上下文投影压缩与原生工具调用支持。 - Claude Code CLI:终端配置
ANTHROPIC_BASE_URL="http://127.0.0.1:8787"与ANTHROPIC_API_KEY="local"即可一键直连驱动官方 Claude Code,双向协议无缝转换并支持流式与工具调用。 - Hermes Agent:提供推荐配置项与一键复制,按说明在 Hermes 的
config.yaml中手动填写(供应商 + 模型别名)。 - ZCode:采用引导式接入——展示接口地址/密钥/模型清单,点击任意值即复制,在 ZCode Desktop → 模型设置 → 添加供应商 中粘贴即可;状态徽章基于本地服务端口真实可达性探测。
- Codex CLI:在
- ⚡ 动态模型矩阵:模型清单自动获取 WorkBuddy 支持的全量模型(含计费倍率、上下文窗口与思考强度配置),随上游动态更新,无需随版本维护静态列表;OpenAI 与 Anthropic 协议均可透明传入相同模型标识;在「模型与接口」页面查看与定制。
- 🛡️ 安全脱敏、流量削峰与请求防护:
- 客户端鉴权密钥(可选):设置页可一键生成 / 复制 / 清空 32 位十六进制随机密钥(CSPRNG 生成),内核以
--api-key生效,之后所有客户端须携带Authorization: Bearer <密钥>或x-api-key: <密钥>,否则返回401 invalid api key;密钥仅在启动时注入(改后需重启内核)。开启「局域网访问」(非回环监听)时必须先设置密钥,否则前端拒绝开启且内核亦拒绝启动(对标router-for-me/EasyCLIProxyAPI的 API 访问管理); - 结构化日志与级别管理:设置页可切换内核日志级别
info(默认,仅请求摘要与耗时)/debug(附加错误响应详情)/trace(完整请求体与响应流,自动脱敏 Token/Key),日志写入converter.log并在「实时日志」页与进程 stdout 合并展示(分区标注);可选开启--log-payloads落盘完整 Prompt / 响应正文(明文,需 trace 级双闸门生效,默认关闭且 UI 明确警示隐私风险)(对标router-for-me/EasyCLIProxyAPI的日志管理);
- 客户端鉴权密钥(可选):设置页可一键生成 / 复制 / 清空 32 位十六进制随机密钥(CSPRNG 生成),内核以
- 🔍 内置 API 调试台:「调试」页保留最近 200 条请求快照(端点/模型/状态/耗时/请求体/响应摘要/错误),点行看详情、基于快照重放复现问题、一键复制 curl(含
YOUR_KEY占位不泄露密钥);快照默认开启、设置页可关,请求体明文落盘(Token/Key 已脱敏),保留条数 10–2000 可调(对标orangeboyChen/codebuddy2api的 API Test/Debug 快照);- 局域网访问(可选):设置页可开启「允许局域网内其它设备访问」(
--host 0.0.0.0),并自动探测本机局域网 IPv4 展示可复制地址(如http://192.168.x.x:8787/v1),供手机 / 平板 / 其它电脑直连;出于安全默认关闭(仅127.0.0.1监听)。无鉴权密钥时前端拒绝开启且内核亦会exit 1——双重守卫确保服务绝不无鉴权暴露(对标router-for-me/EasyCLIProxyAPI的网络设置,但刻意不提供--unsafe-expose放行开关); - 内置
--desensitize敏感词处理机制与客户端身份指纹改写层,改写 Claude Code 身份短语并剔除触发特征,彻底消除系统提示词误触发 11128 安全风控拦截; - 内建请求并发削峰平滑器(
RequestPacer)与后台主动令牌续期器(BackgroundTokenRefresher),削平脉冲请求防止 6004 频控,免除用户被动等待时延; - 413 请求体超限安全防护:对
/v1/chat/completions、/v1/messages与/v1/responses施加严格大小守卫(默认 16MB,支持WORKBUDDY2API_MAX_BODY_MB)。中间件在 ASGIreceive层按块累计,超限立即熔断(不等 body 读完),既防大包拖垮本地内存也防被上游连坐拦截(借鉴linguo2625469/workbuddy2api-panel); - 多模态远程图片自动转 Data-URI:腾讯后端对
image_url仅接受data:image/...;base64,...(直接传 http 链接报错 400)。网关自动异步下载远程图片并内联嵌入,彻底解除视觉模型的多模态输入限制;下载前经 SSRF 守卫(拒绝回环/私网/元数据地址、重定向逐跳复检)并施加单图 8MB 上限(WORKBUDDY2API_MAX_IMAGE_MB)(借鉴neipor/codebuddy-cli2api); - 官方客户端 User-Agent 仿真:出站请求智能仿真官方客户端标识(国内版
CLI/2.63.2 CodeBuddy/2.63.2/ 国际版WorkBuddy/5.5.2...),规避非标 UA 触发 10085 拦截与官网使用端归因失真,亦支持WORKBUDDY2API_USER_AGENT动态配置(借鉴ardeyouxipianyi与turbomind66)。
- 局域网访问(可选):设置页可开启「允许局域网内其它设备访问」(
本地服务默认监听 http://127.0.0.1:8787,提供以下标准 API 与工具端点:
| 协议 / 功能分类 | 接口端点 | 适用客户端 / 场景 | 推荐鉴权 Header |
|---|---|---|---|
| OpenAI Responses 协议 | POST /v1/responses |
Codex CLI, OpenCode, Responses SDK | Authorization: Bearer *** 或 x-api-key: *** |
| Anthropic Messages 协议 | POST /v1/messages |
Claude Code CLI, Cline, Roo Code, Anthropic SDK | x-api-key: *** 或 Authorization: Bearer *** |
| OpenAI 对话补全协议 | POST /v1/chat/completions |
Hermes Agent, Cherry Studio, NextChat, OpenAI SDK | `Authorization: Bearer *** |
| 模型列表探测 | GET /v1/models |
OpenAI 格式标准模型列表(动态拉取上游全部模型) | Authorization: Bearer local |
| 服务健康与探活 | GET /health |
本地健康检测 / 心跳探测(安全收窄,不泄露敏感身份信息) | 无需鉴权 |
| 用量统计与积分概览 | GET /api/usage_summary |
当前账号积分余额、今日用量(请求数/Token/429) | Authorization: Bearer local |
| 频控与冷却状态感知 | GET /api/rate_limit |
上游 6004 频控状态与冷却倒计时(三态感知) + 多账号调度配置来源(rotation.config_source) |
`Authorization: Bearer *** |
| 11128 毒历史自查 | POST /api/desensitize_check |
干跑脱敏诊断:定位哪条 system/assistant 历史带客户端指纹(只报不改) | `Authorization: Bearer *** |
| 请求快照查询 | GET /api/snapshots |
最近请求快照(最新在前,调试 Tab 数据源) | `Authorization: Bearer *** |
flowchart TD
subgraph Client [AI 客户端 / Coding Agent]
Claude[Claude Code CLI / Cline / Roo Code]
Hermes[Hermes Agent]
Other[Cherry Studio / NextChat / OpenAI SDK]
end
subgraph Console ["WorkBuddy2API 桌面控制台 (Tauri v2)"]
GUI["前端 UI (服务看板 / 账号与资产 / Agent 接入 / 模型定制)"]
Core["Rust 后端 (多账号管理 / 配置持久化 / 进程托管 / 状态感知)"]
DB[("本地 accounts.json")]
end
subgraph Proxy ["本地反代网关内核 (端口 8787)"]
Server["FastAPI / Uvicorn 调度层"]
AnthropicLayer["Anthropic 兼容层 (anthropic_compat.py + anthropic_stream.py)<br/>双向协议翻译 / SSE 事件状态机 / tool_use 映射"]
Desensitize["安全脱敏层 (desensitize.py)<br/>客户端指纹精准改写 / 敏感词过滤 / 11128 防御"]
Pacer["流量削峰平滑器 (request_pacer.py)<br/>并发槽位调度 / 防 6004 频控"]
Refresher["主动令牌续期器 (token_refresher.py)<br/>后台异步静默巡检 / 临期自动换票"]
Converter["核心网关转换器 (converter.py)<br/>模型透传 / 上下文注入 / 流式 tool_calls 损坏修复"]
end
subgraph Remote [腾讯官方云端]
Auth[OAuth 授权中心]
Meter[Billing 计费与积分中心]
Copilot[Copilot 模型推理服务]
end
Claude -->|POST /v1/messages| Server
Hermes -->|POST /v1/chat/completions| Server
Other -->|POST /v1/chat/completions| Server
GUI <-->|Tauri IPC Invoke| Core
Core <--> DB
Core -->|进程托管与健康探针| Server
Core -->|OAuth 授权与积分直查| Auth
Core -->|查询资源包额度与每日签到| Meter
Server --> AnthropicLayer
AnthropicLayer --> Converter
Server --> Converter
Converter --> Desensitize
Desensitize --> Pacer
Pacer -->|原生 Bearer Token + X-Device-Token 转发| Copilot
双击桌面生成的 WorkBuddy2API 快捷方式,或直接运行编译产物:
src-tauri/target/release/workbuddy2api.exe- 授权登录:进入「授权新账号」页面,点击开始授权,浏览器将自动唤起腾讯登录页,完成授权后客户端自动保存凭据并切到账号面板。
- 启动服务:在「服务看板」点击「启动服务」,本地将监听
http://127.0.0.1:8787。 - Agent 接入引导:进入「Agent 智能体接入引导」页面,查看 Claude Code、Hermes 或 ZCode 的接入指南与推荐配置,按需复制到各客户端中使用。
- Node.js 24+ 与 npm
- Rust 1.77+ 与 Cargo
- Python 3.10+(需安装依赖
httpx fastapi uvicorn[standard])
# 1. 克隆本项目
git clone https://github.com/3304711297/workbuddy2api.git
cd workbuddy2api
# 2. 安装前端依赖并构建
npm install
npm run build
# 3. 运行 Tauri 开发模式或构建 Release 版本
cd src-tauri
cargo tauri dev # 调试模式
cargo tauri build --no-bundle # Release 编译支持的模型清单自动获取 WorkBuddy 支持的全量模型:启动服务后,控制台「模型与接口」页面会自动从 WorkBuddy 官方后端拉取模型矩阵,包含每个模型的计费倍率、上下文窗口上限与思考强度档位,并支持在页面内定制(修改上下文窗口、调节/关闭思考强度)。
- 双协议透明支持:无论是 OpenAI 端点(
/v1/chat/completions)还是 Anthropic 端点(/v1/messages),均可直接使用相同的模型标识(如glm-5.3-flash、deepseek-v4.1-flash、kimi-k2.7等),网关会自动完成参数规格适配。 - 模型集合随上游动态变化,本文档不再维护静态清单;以控制台「模型与接口」页面实时展示的列表为准。
官方 Claude Code 原生基于 Anthropic Messages 协议工作。只需配置环境变量指向本地网关:
macOS / Linux / WSL (Bash):
export ANTHROPIC_BASE_URL="http://127.0.0.1:8787"
export ANTHROPIC_API_KEY="local"
# 启动 Claude Code,指定 WorkBuddy 模型即可直接开发
claude --model glm-5.3-flashWindows (PowerShell):
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8787"
$env:ANTHROPIC_API_KEY = "local"
claude --model glm-5.3-flashimport anthropic
# 指向本地 WorkBuddy2API 的 Anthropic Messages 端点
client = anthropic.Anthropic(
base_url="http://127.0.0.1:8787",
api_key="local"
)
message = client.messages.create(
model="glm-5.3-flash",
max_tokens=1024,
messages=[
{"role": "user", "content": "你好,请用 Python 写一个支持并发的安全队列。"}
]
)
print(message.content[0].text)from openai import OpenAI
# 本地 WorkBuddy2API 的 OpenAI 兼容端点
client = OpenAI(
base_url="http://127.0.0.1:8787/v1",
api_key="local" # 本地模式固定填写 local
)
response = client.chat.completions.create(
model="glm-5.3-flash",
messages=[
{"role": "user", "content": "你好,请用 Python 写一个支持并发的安全队列。"}
],
temperature=0.7
)
print(response.choices[0].message.content)Anthropic Messages 接口:
curl -X POST http://127.0.0.1:8787/v1/messages \
-H "x-api-key: local" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3-flash",
"max_tokens": 512,
"messages": [{"role": "user", "content": "Hello!"}]
}'OpenAI Chat Completions 接口:
curl -X POST http://127.0.0.1:8787/v1/chat/completions \
-H "Authorization: Bearer local" \
-H "Content-Type: application/json" \
-d '{
"model": "glm-5.3-flash",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": false
}'-
WSL 宿主凭据环境自适应(零配置穿透): 在 Linux / WSL 环境下运行内核时,自动探测并挂载 Windows 宿主已登录的桌面端凭据(
CodeBuddyExtension/Data/Public/auth)与多账号配置(accounts.json),免参数无感工作;亦可通过--wsl显式强制开启。 -
流式 tool_calls 损坏防御机制(解决 upstream Issue #3): 针对腾讯后端在
stream=true且模型生成tool_calls时偶发分片损坏(function.name为空或 arguments 乱码残缺)导致 Claude Code / Codex / DeepSeek Harness 等 Agent 陷入死循环的硬伤,内核内建聚合校验与自动损坏重试,并通过标准平滑伪流式下发,彻底保障 Coding Agent 的调用稳定性。普通纯文本对话保持 100% 原始零延迟直通。 -
X-Device-Token设备风控头(Turing Shield SDK 集成): 内核对腾讯后端的请求会注入设备风控头X-Device-Token,来源是本机已安装 WorkBuddy 桌面端自带的 Turing Shield SDK(turing_helper.cjs自动发现 + 零宽空格脱敏等合规处理协同降低风控误判)。SDK 取不到时自动降级为不带该头,功能不受影响。SDK 自动发现的搜索范围(供应链加固说明):
- 环境变量
WORKBUDDY_TURING_SDK_DIR—— 用户显式指定(最高优先级,指向 turing-sdk 目录或桌面端安装基目录均可); %LOCALAPPDATA%/%APPDATA%/%ProgramFiles%/%ProgramFiles(x86)%/%USERPROFILE%/%HOME%下的WorkBuddy/workbuddy安装目录(严格特征校验:index.cjs入口 +turing_sdk.node原生模块且package.json含 turing 标识,或官方TuringShieldSDK.dll);- 各磁盘根目录(如
D:\WorkBuddy)默认不扫描 —— 这是刻意为之的安全设计:目录名巧合或被植入伪造 SDK 时,宽松扫描 + 直接require会构成本地代码执行风险。若你的桌面端安装在盘根等非常规位置,请显式设置环境变量后重启本客户端:设置后新启动的进程生效;SDK 校验仍会验证入口文件与特征,仅放宽"用户显式信任"的路径来源。setx WORKBUDDY_TURING_SDK_DIR "D:\workbuddy"
- 环境变量
- 本项目基于 HanHan666666/codebuddy2openai 进行深度二次开发与架构重构。
- 架构设计深度借鉴了优秀开源项目 EasyCLIProxyAPI 的桌面端实践思路。
- 以下功能借鉴自社区衍生项目 xiaofan6ya/workbuddy2api 及其增强分支 DistPub/workbuddy2api(均 MIT 开源):
X-Device-Token设备风控头注入(借鉴 xiaofan6ya 版):通过桌面端自带 Turing Shield SDK 取设备 token,turing_helper.cjs自动发现安装位置,降低敏感请求被上游风控识别的概率;- 流式 reasoning 合并器与空 delta 清洗(借鉴 DistPub 版):网关层把零散 reasoning 分片合并为一段再释放,剥离混入
tool_calls参数流的推理内容,避免 AI SDK 出现大量碎片 Thought 块与工具参数 JSON 截断(移植时已修复其上游「键不存在被误判为空串导致纯 reasoning 帧被删」的缺陷); - 脱敏词表扩张(借鉴 DistPub 版):补充竞争品牌词(Claude/Anthropic/OpenAI/Gemini/Kimi/Qwen/Cursor 等),脱敏覆盖角色扩展至
assistant历史回复; - 每日签到(端点逆向成果参考两仓库):
/v2/billing/meter/daily-checkin链路,本项目按自身定位实现为 GUI 手动按钮触发,不做自动定时签到。
- 以下功能与架构思路借鉴自活跃衍生项目 IceeAn/codebuddy2api(当前重写树为 MIT 开源):
- Claude 客户端指纹脱敏与精准改写层(P0 已落地):借鉴其对已知客户端特征句做中性改写的思路(
_rewrite_known_fingerprints),改写 Claude Code 身份短语、移除x-anthropic-billing-header:等触发源,彻底解决上游 11128 安全策略拦截; - 多凭证轮换与账号调度(已交付,2026-09-11):参考其凭据生命周期感知与平滑轮换设计,已交付多账号调度(failover / roundrobin 双模式 + 账号级冷却 + 策略热读免重启)。
- Claude 客户端指纹脱敏与精准改写层(P0 已落地):借鉴其对已知客户端特征句做中性改写的思路(
- 以下安全与协议兼容优秀实践借鉴自开源生态(2026-09 横向对比采纳):
- OpenAI Responses 协议原生端点 (
POST /v1/responses)(借鉴 ShouZhuo0413/codebuddy2api 与 hawklithm/workbuddy2api,MIT):引入responses_compat.py,原生支持 Codex CLI 等长上下文 Agent 的双向协议转换与流式事件状态机; - 按积分到期日分层选号调度(借鉴 momo0410/workbuddy-switch-gateway,MIT):引入日粒度到期日分层,多账号调度优先消耗快要过期的额度,避免资产过期浪费;
- 413 请求体超限安全防护(借鉴 linguo2625469/workbuddy2api-panel,MIT):
converter.py引入大小守卫,秒拒超大报文保护本地与上游; - 官方客户端 User-Agent 规范仿真(借鉴 ardeyouxipianyi/workbuddy2api-intl 与 turbomind66/workbuddy2api-python,MIT):出站请求智能仿真官方客户端标识,并支持环境变量动态自定义。
- OpenAI Responses 协议原生端点 (
- 本工具仅供个人学习、技术研究与工作流效率提升使用,请妥善保管个人授权凭据,遵循腾讯云相关产品服务协议。
本项目基于 MIT License 开源。
本仓库包含从 xiaofan6ya/workbuddy2api、DistPub/workbuddy2api、IceeAn/codebuddy2api、linguo2625469/workbuddy2api-panel、ardeyouxipianyi/workbuddy2api-intl 与 turbomind66/workbuddy2api-python(均 MIT)移植或借鉴的代码,其版权声明、借鉴范围与移植差异详见 THIRD_PARTY_NOTICES.md。