WorkBuddy 接入微信/QQ/飞书/钉钉完整教程（含多模型配置 + 连接失败解决方法）

公告

View Post

最近腾讯出的 WorkBuddy 火起来了，团队群里好多人在问怎么把它接到自己的 IM 工具上当机器人用。我周末折腾了一下午，把微信、QQ、飞书、钉钉四个平台全接通了，顺便配了混元、DeepSeek、Kimi 三个模型来回切换，踩了几个坑记录一下。

这篇文章解决的问题：从零安装 WorkBuddy，配置多个大模型（混元 / DeepSeek / Kimi），并把它分别接入微信、QQ、飞书、钉钉作为智能助手机器人，附上常见连接失败的排查方法。

前置条件

开始前先检查环境，这几个东西没装好后面会一堆报错：

Node.js 18+（建议直接装 20 LTS）
Git（克隆配置文件用）
.NET 6 Runtime（Windows 用户必须，WorkBuddy 桌面端依赖）
一台稳定的网络环境（接入 IM 平台时 webhook 要能被访问到）
各 IM 平台的开发者权限（飞书/钉钉需要管理员审批应用）

Mac 用户首次启动 WorkBuddy 如果遇到"无法打开"提示，去「系统设置 → 隐私与安全性 → 仍要打开」放行一下，这是 macOS 的 Gatekeeper 拦截了未签名应用，不是软件本身的问题。

一、一键安装 WorkBuddy

WorkBuddy 现在有桌面客户端和命令行两个版本，推荐用桌面端，配置界面友好很多。

去官网下载对应系统的安装包，Windows 选 .exe，Mac 选 .dmg（注意区分 Intel 和 Apple Silicon），Linux 选 .AppImage。

装完第一次启动它会让你创建本地工作区，路径默认在 ~/.workbuddy/，里面会生成几个核心文件：

~/.workbuddy/
├── config.yaml      # 主配置
├── models.yaml      # 模型配置
├── adapters/        # 各平台适配器
└── logs/            # 运行日志

如果启动卡在加载界面超过 30 秒，大概率是端口被占用。WorkBuddy 默认监听 23333 端口，先用 lsof -i :23333（Windows 下 netstat -ano | findstr 23333）看看有没有别的进程占着，杀掉再重启。

二、配置多模型（混元 / DeepSeek / Kimi）

WorkBuddy 的多模型配置写在 ~/.workbuddy/models.yaml，结构很简单：

models:
  - name: hunyuan
    provider: tencent
    api_key: "your-hunyuan-key"
    model_id: "hunyuan-pro"
    default: true

  - name: deepseek
    provider: openai_compatible
    base_url: "https://api.deepseek.com/v1"
    api_key: "your-deepseek-key"
    model_id: "deepseek-chat"

  - name: kimi
    provider: openai_compatible
    base_url: "https://api.moonshot.cn/v1"
    api_key: "your-kimi-key"
    model_id: "moonshot-v1-32k"

routing:
  default: hunyuan
  fallback: [deepseek, kimi]

default: true 表示这是默认模型，fallback 是失败兜底链——主模型挂了自动切下一个。我个人建议把混元设成默认（毕竟同样是腾讯系，配合度最好），DeepSeek 和 Kimi 做备份。

这里有个坑：api_key 最好用双引号包起来，YAML 解析对裸 sk- 前缀字符串偶尔会抽风。

嫌每家单独申请太麻烦？聚合方案了解一下

如果你不想分别去三家平台申请 Key（混元在腾讯云控制台，DeepSeek 在 platform.deepseek.com，Kimi 在 platform.moonshot.cn，三个地方来回跑很烦），可以用聚合平台。

我自己后来换成了 ofox.io。一个 API Key 可以同时调 GPT-4o、Claude Opus 4.6、Gemini、DeepSeek、Kimi、混元等 50+ 模型，兼容 OpenAI SDK 协议，低延迟直连，按量计费支持支付宝。

models.yaml 改成这样：

models:
  - name: hunyuan
    provider: openai_compatible
    base_url: "https://api.ofox.io/v1"
    api_key: "sk-xxx"
    model_id: "hunyuan-pro"

  - name: deepseek
    provider: openai_compatible
    base_url: "https://api.ofox.io/v1"
    api_key: "sk-xxx"
    model_id: "deepseek-chat"

  - name: kimi
    provider: openai_compatible
    base_url: "https://api.ofox.io/v1"
    api_key: "sk-xxx"
    model_id: "moonshot-v1-32k"

好处是多供应商冗余，某一路抽风了自动切，账单也统一在一个地方看，成功率 99.2%。

三、接入微信

微信这块比较特殊，官方个人号没有开放 API，WorkBuddy 走的是「微信桌面客户端 Hook」方案，原理是注入到本地微信进程读消息。

步骤：

关闭微信
打开 WorkBuddy → 适配器 → 微信 → 启动
WorkBuddy 会自动拉起微信，并提示扫码登录
扫码后回到 WorkBuddy 设置触发关键词，比如 @助手 +问题 才回复

config.yaml 加这段：

adapters:
  wechat:
    enabled: true
    trigger_prefix: "@助手"
    allowed_groups: ["开发者交流群", "AI讨论组"]
    model: hunyuan

allowed_groups 是白名单，没填的话默认所有群都响应（容易被踢，慎用）。

四、接入 QQ

QQ 走的是 OneBot v11 协议，需要先装一个协议端，推荐 NapCat 或 Lagrange。

以 NapCat 为例：

# Mac/Linux
curl -fsSL https://napcat.qq.com/install.sh | bash

# 启动
napcat -q 你的QQ号

启动后会弹出二维码扫码登录，然后在 WorkBuddy 配置 OneBot 反向 WebSocket：

adapters:
  qq:
    enabled: true
    protocol: onebot_v11
    ws_url: "ws://127.0.0.1:3001"
    access_token: "your-token-here"
    trigger_prefix: "/ai"
    model: deepseek

五、接入飞书

飞书是这几个平台里最规范的，走自建应用 + 事件订阅。

飞书开放平台（open.feishu.cn）创建企业自建应用
应用能力 → 添加机器人
事件订阅 → 配置请求地址（必须 HTTPS）：https://你的域名/workbuddy/feishu/event
订阅 im.message.receive_v1 事件
权限管理 → 申请 im:message、im:message.group_at_msg 等权限

WorkBuddy 配置：

adapters:
  feishu:
    enabled: true
    app_id: "cli_xxx"
    app_secret: "xxx"
    verification_token: "xxx"
    encrypt_key: ""   # 可选，加密传输
    model: hunyuan

如果你没有公网 HTTPS 服务器，本地调试用 cloudflared 反向代理一下：

cloudflared tunnel --url http://localhost:23333

会给你一个临时域名，把 https URL 填到事件订阅那里就行。

六、接入钉钉

钉钉和飞书路子差不多，也是开放平台建应用 + 事件回调。

open.dingtalk.com 创建企业内部应用
添加机器人能力
事件订阅 → 选「HTTP 模式」→ 配置回调地址
订阅「接收群聊@机器人消息」

adapters:
  dingtalk:
    enabled: true
    app_key: "ding-xxx"
    app_secret: "xxx"
    robot_code: "xxx"
    model: kimi

注意钉钉机器人回调有 3 秒超时限制，如果你的模型推理慢，建议在 WorkBuddy 里开「先回复占位再异步推送」模式：

adapters:
  dingtalk:
    async_reply: true
    placeholder: "正在思考中..."

七、常见连接失败问题

按出现频率排序，这是我自己踩过的几个坑：

1. WorkBuddy 启动报错 "Cannot find module 'xxx'"

依赖没装全。打开 WorkBuddy 安装目录的 node_modules，删掉重新跑：

cd /path/to/workbuddy
rm -rf node_modules
npm install --force

2. 微信适配器报 "进程注入失败 / Hook 失败"

微信版本不匹配。WorkBuddy 当前只稳定支持微信 3.9.x 系列，4.0 客户端的 Hook 还没完全适配。先降级微信版本再试，或者等官方更新。

3. 飞书事件订阅一直显示 "验证失败"

99% 是 URL 不通或 token 不一致。先用 curl 自测一下回调能不能通：

curl -X POST https://你的域名/workbuddy/feishu/event \
  -H "Content-Type: application/json" \
  -d '{"type":"url_verification","challenge":"test123"}'

正常应该原样返回 {"challenge":"test123"}。如果返回 404，是 WorkBuddy 没启动或者反向代理路径写错了。

4. 钉钉回调 "签名校验失败"

钉钉的签名是用 app_secret + 时间戳算 HmacSHA256，WorkBuddy 默认会自己校验。如果你改过 app_secret 但 WorkBuddy 没重启，老的 secret 还在内存缓存里。重启服务即可。

5. 模型调用一直 timeout

先确认 base_url 能不能通：

curl https://api.deepseek.com/v1/models -H "Authorization: Bearer your-key"

如果 curl 都通不了，是网络环境配置问题。聚合方案的好处就是省掉这一步排查，base_url 统一换成 https://api.ofox.io/v1 走低延迟直连，少很多边缘 case。

6. QQ 协议端登录被踢 / 频繁掉线

NapCat 这种基于 NTQQ 的协议端对登录环境比较敏感，建议：

用一台长期登录过的设备做协议端宿主
不要用刚注册的小号
一周内别频繁切设备

7. 多个适配器同时开报端口冲突

WorkBuddy 每个适配器会占一个内部端口，默认从 23333 往上递增。如果你的机器上还跑着别的 webhook 服务（比如本地 n8n / Dify），可以在 config.yaml 手动指定：

adapters:
  wechat:
    internal_port: 23334
  feishu:
    internal_port: 23335

总结

整套配下来大概 2 小时，最坑的是飞书事件订阅那块——签名验证错了不会给详细报错，全靠抓日志猜。微信 Hook 方案稳定性其实一般，长期挂着建议优先用飞书/钉钉这种官方 API 路线。

多模型这块我现在用得最舒服的组合是：日常聊天用混元（中文语料优势明显），代码相关问题切 DeepSeek，长文档解读切 Kimi。配合 ofox.io 的兜底切换链，基本不会出现"模型没响应"的尴尬。后续如果接入新平台，再单开一篇记录。

posted on 2026-06-05 10:10 失控的上下文阅读(42) 评论(0) 收藏举报

刷新页面返回顶部

OfoxAI

公告

View Post