学习目标

01

阐述助理的核心本质、定位及其与普通任务的差异

02

辨析并选择适合自身场景的远程通信模式（如长连接与 URL 回调）

03

熟练掌握微信、企业微信及 QQ 等核心渠道的助理配置流程

04

了解飞书、钉钉等其他企业级协作平台的接入能力

05

运用标准排查框架，独立解决助理绑定与消息通信中的常见故障

学完本章，你将能把 WorkBuddy 的执行能力装进口袋——人不在电脑前，任务照常落地执行。

7.1

7.1

助理机制与核心原理

助理的本质：桥接跨端消息、解析并路由指令、触发本机任务调度

三大能力边界：远程触达 / 环境固定 / 场景匹配

通信链路：移动端 → 云端中转 → 本机 WorkBuddy（WebSocket 长连接）

核心通信模式对比：WebSocket 长连接 vs URL 回调

助理的本质与能力边界

本质：用户通过移动终端（如手机微信、企业微信等），远程操控部署于本机的 WorkBuddy 实例。

助理承担桥接跨端消息通道、解析并路由用户指令、触发本机任务调度的核心职能。

远程触达

突破物理位置限制，通过手机等随时随地下达指令

环境固定

受限于远程控制特性，任务通常绑定固定工作目录，且保持单一活跃会话状态

场景匹配

适用于“人不在电脑前，但必须由电脑环境执行任务”的特殊情况

能力边界一句话：远程触达是价值，环境固定是约束，场景匹配是边界——助理擅长“遥控”，不替代本地操作。

官方文档《助理（远程任务）》：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Assistant

助理任务 vs 普通任务

差异根源：助理任务要经云端中转与移动端交互，用“受控”（固定目录、单会话、历史保留）换“可远程”。

官方文档《助理（远程任务）》：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Assistant

典型应用场景

助理机制广泛赋能移动办公——四大典型应用场景：

通勤途中任务前置

地铁上通过微信描述当日数据分析脚本需求，到公司后脚本已生成完毕，直接投入使用

客户现场即时响应

会议室演示时需要一份不在U盘里的特定报告，手机指令让工位电脑自动检索并生成汇总材料发到手机

非工作时间异步调度

周末想起非紧急但耗时的抓取任务，无需专程打开电脑，让办公室待机的电脑彻夜执行

异地办公远程管控

出差在外定期检查本地电脑的运行日志或服务器监控状态，并获取异常警报摘要

四个场景的共通点：移动端发令、电脑端执行——人不在电脑前，但任务必须由电脑环境完成。

远程通信原理与运行前提

指令流转链路：移动端 → 云端中转 → 本机 WorkBuddy；各渠道支持 WebSocket 长连接接入，确保指令下达的即时性和可靠性。

01

移动端发指令

通过手机等即时通讯软件下达任务

02

云端中转服务节点

接收指令并转发至本机，保证链路畅通

03

本机 WorkBuddy

解析并路由指令、触发任务调度，结果回传移动端

四个核心使用前提（缺一不可）

① 目标电脑必须处于开机状态

② 电脑端 WorkBuddy 处于运行且已登录的状态

③ 电脑保持持续且稳定的网络连接

④ 电脑不能进入休眠状态（否则网络会断开，WorkBuddy 进程会挂起）

💡 最佳实践：在操作系统电源管理中，把“使计算机进入睡眠状态”设置为“从不”，确保助理随时在线。

配置前自查：① WorkBuddy 已安装并登录 ② 电脑开机常亮 ③ 网络畅通且未被防火墙拦截 WebSocket 端口 ④ 目标平台账号就绪。

核心通信模式对比

安全机制：以企业微信 URL 回调模式为例，消息校验与加密采用平台通用的 Token 签名与 EncodingAESKey 加密机制，确保任务数据在公网流转时不被伪造与窃听。

安全提示：任何渠道配置助理时获取的凭据（如 Secret、EncodingAESKey 等）都具有极高权限，务必妥善保管，切勿通过截图或明文发送给不可信的第三方。

官方文档《WorkBuddy 接入企业微信指南》：https://www.workbuddy.cn/docs/workbuddy/Wecom-Guide

7.2

7.2

微信生态渠道接入指南

官方 6 大 IM 平台 + 元宝派 + 微信小程序 = 8 类渠道

最推荐：微信助理——零配置，扫码即用

微信小程序：云上模式与连接电脑双重执行环境

微信客服号：习惯服务号窗口交互的另一种选择

微信助理（推荐 · 零配置）

01

打开“助理设置”

在 WorkBuddy 客户端中找到“助理设置”面板（左侧边栏 > ⚙️ 设置 > 助理设置）

02

切换至“微信助理”

“微信助理”标签页会生成专属的绑定二维码

03

扫码完成绑定

使用手机微信扫描二维码，确认授权后即可完成绑定

绑定后，移动端可以

发送文字消息启动新任务，或继续“助理”板块中未完成的会话；发送后续指令、回答追问、批准命令执行与文件修改；查看任务输出、差异对比，任务完成或需要关注时在微信中收到通知。

消息类型支持：文字 · 图片（截图或文档照片）· 文件（转发文件）· 语音（需微信语音转文字）。

绑定全程无需填写 App ID/App Secret 等开发凭证——零配置开箱即用。

官方文档《微信助理接入指南》：https://www.workbuddy.cn/docs/workbuddy/WeixinBot-Guide

微信小程序（移动端执行入口）

接入体验与微信助理类似（均为扫码型操作），但提供了更丰富的扩展能力：

产物同步

开启后不仅能在手机端下发指令，还能直接在小程序中查看电脑端生成的报告或代码片段（产物）；具体开关名称以产品实际界面为准

云上模式

使用云端沙箱执行任务，无需依赖个人电脑；直接在小程序内下发任务并查看任务产物

连接电脑（本机模式）

远程操控电脑桌面端；需桌面端开启“允许移动端连接”且两端登录同一账号

两种执行环境对比：云上模式 = 云端沙箱执行，无需电脑在线即可完成并查看产物；连接电脑（本机模式） = 远程操控桌面端，可查看任务、续聊、停止任务。

使用“连接电脑”时，请确保桌面端开启“允许移动端连接”，且两端登录同一账号。

官方文档《WorkBuddy 小程序简介》：https://www.workbuddy.cn/docs/workbuddymini/quick-start/Overview

微信客服号

习惯通过服务号窗口交互的用户，可以选择微信客服号集成：

01

进入面板

进入 WorkBuddy 助理设置面板

02

选择选项卡

选择“微信客服号集成”选项卡

03

获取主账号

点击获取或绑定对应的微信主账号

04

扫码授权

扫描弹出的系统认证二维码完成授权体系对接

微信客服号与微信助理功能相同、绑定流程一致（均为扫码绑定），可根据需要选择其中一种使用。

官方文档《微信客服号接入指南》：https://www.workbuddy.cn/docs/workbuddy/Wechat-Guide

7.3

7.3

腾讯生态其他渠道接入指南

元宝派：凭据型（AppID + Secret）认证，适合定制需求

QQ 机器人：QQ 开放平台创建应用机器人，需开发者实名认证

共同流程：平台侧建应用 → 取 AppID/AppSecret → 回填 WorkBuddy

元宝派接入（凭据型）

元宝派采用凭据型（AppID + Secret）认证方式，适合有一定定制需求的用户，完整流程如下：

01

登录腾讯元宝平台，进入“派”应用管理台

02

创建一个新的 Bot 实例

03

在 Bot 配置中找到关联 OpenClaw 服务的选项

04

获取该 Bot 的专属 AppID 和 AppSecret

05

回到 WorkBuddy 客户端，在元宝派接入通道填入上述凭据

06

点击验证连接

07

回到腾讯元宝 App 的关联页面，点击“我已操作”确认关联，即可开始聊天测试

官方文档《WorkBuddy 接入元宝派指南》：https://www.workbuddy.cn/docs/workbuddy/YuanBaoPai-Guide

QQ 机器人接入

如果你的团队习惯使用 QQ 办公，可以通过 QQ 开放平台接入：

01

创建应用机器人

前往 QQ 开放平台创建应用机器人（此步骤需完成开发者实名认证）

02

获取两项凭据

在应用信息页面获取 AppID 和 AppSecret

03

回填并保存

将两项凭据准确填入 WorkBuddy 的 QQ 助理设置页并保存即可启用

安全提示：QQ 平台的 AppSecret 通常只会在创建时完整显示一次，请务必在此刻将其安全复制并暂存。

同属凭据型渠道：与元宝派一致，先在平台获取 AppID/AppSecret，再回到 WorkBuddy 回填。

7.4

7.4

企业级通信渠道接入指南

企业微信：长连接扫码（推荐）与 URL 回调（高级）双模式

飞书 / 钉钉：开放平台创建自定义机器人应用后回填凭据

统一逻辑：平台建应用 → 取凭据 → 选订阅模式 → 填入 WorkBuddy

企业微信接入（双模式）

企业微信同时支持长连接和 URL 回调两种模式；为降低门槛，WorkBuddy 还提供了基于长连接的快捷扫码绑定。

长连接模式（推荐）

1. 在企业微信管理后台创建自建应用（机器人）

2. 在配置页面选择长连接通信模式，并获取应用的 BotID 和对应的 Secret

3. 在 WorkBuddy 端注册这些凭据完成对接

URL 回调模式（高级）

1. 确保你拥有一台公网 IP 服务器（或进行内网穿透）

2. 在企微后台获取验证用的 Token 和 EncodingAESKey

3. 在 WorkBuddy 端输入这些凭据，系统将生成专用的 Webhook URL 接收地址

4. 将生成的 Webhook URL 粘贴回企业微信机器人创建页“API 配置”区域的 URL 输入框并保存

推荐首选长连接：配置步骤更少，无需再填写 URL、Token 或 EncodingAESKey，也不需回填 Webhook URL。

官方文档《WorkBuddy 接入企业微信指南》：https://www.workbuddy.cn/docs/workbuddy/Wecom-Guide

飞书与钉钉机器人接入

远程操控能力同样支持飞书和钉钉平台，接入逻辑与企业微信类似：

01

创建机器人应用

在飞书开放平台 / 钉钉开发者后台创建自定义机器人应用

02

获取应用凭据

获取对应的 App ID/App Key 及 Secret/App Secret

03

选择订阅模式

根据安全要求选择合适的事件订阅模式（长连接或 Webhook）

04

回填助理面板

将凭据填入 WorkBuddy 相应的助理设置面板即可

凭据核对（配置与排查时）：飞书 App ID、App Secret、Encrypt Key；钉钉 Client ID（AppKey）、Client Secret（AppSecret）。

详细操作步骤建议随时查阅官方文档的最新指南（具体以产品实际界面为准）。

7.5

7.5

常见问题与排查指南

通用四步排查法：运行状态 → 绑定状态 → 凭据有效性 → 网络环境

高频问题：扫码未显示“已绑定” / 消息迟迟无响应 / 凭据保存失败

核心原则：按顺序逐步排查，不跳步；修复后重新下发验证

通用四步排查法

当助理功能异常时，请按顺序执行以下四步：

01

检查 WorkBuddy 是否运行

确认电脑端的应用程序未被误关或发生崩溃

02

核对绑定状态

在助理设置面板中检查对应渠道的状态灯是否显示为“已连接/已绑定”

03

检查凭据有效性

对于凭据型渠道，核实 Secret 是否过期或复制错误

04

排查网络

确保电脑网络正常，且未启用可能拦截流量的全局代理或防火墙规则

按顺序逐步排查、不要跳步：先本地应用，再绑定状态，再凭据有效性，最后网络环境。

官方文档《助理（远程任务）》：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Assistant

高频问题解析

问题 1：扫码后手机端没显示“已绑定”

可能原因

使用错误的账号扫码（如用个人微信扫了企业微信的码）；网络状态延迟；二维码在界面停留过久已失效。

解决对策

刷新 WorkBuddy 界面获取最新二维码，并确认使用正确的 App 扫码。

问题 2：手机发消息后迟迟没有响应

可能原因

最常见：电脑长时间未操作进入休眠；WorkBuddy 进程被杀毒软件误关；其他耗时任务占用所有执行线程。

解决对策

唤醒电脑并修改电源休眠设置；检查后台任务状态，必要时重启 WorkBuddy 客户端。

问题 3：凭据型渠道注册或保存失败

可能原因

复制 AppID/Secret 时首尾带空格；Secret 被平台重置失效；开发者账号未完成实名认证；URL 回调模式下地址填写不完整。

解决对策

仔细核对凭据文本，利用记事本等工具去除不可见字符再粘贴；回调模式确保复制包含 http:// 或 https:// 的完整地址。

高频问题 2 的最常见根因是电脑休眠——先检查电源设置，再看绑定状态与凭据。

远程指令示例（官方实践六：远程遥控 WorkBuddy）

我现在不在电脑前，请继续排查这个项目的报错问题，优先查看最近一次运行日志，并先告诉我原因和处理建议，再告诉我下一步如何完成跨端传输

远程场景三条使用建议

▸ 先给清晰目标：远程场景下避免模糊指令

▸ 减少高风险操作：涉及删除、覆盖、批量移动时，建议先要求预览

▸ 保留关键文件名：跨端操作时明确文件名和目录，能显著提升成功率

官方文档《实践六：远程遥控 WorkBuddy》：https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Practice-Cases/Practice-Six

实验

实验

配套实验：助理连接配置

必做主线：7.1 四前提 → 7.2 微信助理 → 7.5 远程特性 → 7.6 排查演练

可选实验：7.3 微信小程序多端协同（需手机微信与微信小程序）

可选实验：7.4 企业微信接入（需企业微信管理员权限）

★ 必做仅需 WorkBuddy 与手机微信；○ 可选需管理员权限或开发者认证

第 7 章配套实验（labs/ch07-labs.md）

7.1

运行四前提自查

开机/运行/联网/不休眠四前提与防休眠设置

★ 必做

前置：完成 1.1

7.2

微信助理接入

扫码绑定、手机下发任务、结果回传

★ 必做

前置：手机微信

7.3

微信小程序多端协同

云上模式 vs 连接电脑；“允许移动端连接”且同一账号

○ 可选

前置：手机微信、微信小程序

7.4

企业微信接入

长连接扫码绑定；URL 回调（Token/EncodingAESKey + Webhook 回填）

○ 可选

前置：企业微信管理员权限

7.5

远程任务特性验证

助理专属文件夹、上下文保留、单会话限制

★ 必做

前置：完成 7.2

7.6

四步排查法演练

官方 FAQ 排查流程；实践六远程遥控场景

★ 必做

前置：完成 7.2

必做主线：7.1 → 7.2 → 7.5 → 7.6；7.3、7.4 按前置条件选做；7.5/7.6 依赖 7.2。

本章小结

07

1

助理本质：移动端发令、本机 WorkBuddy 执行；固定“助理专属文件夹”、单一活跃会话、完整历史不可清空

2

通信链路：移动端 → 云端中转 → 本机 WorkBuddy；WebSocket 长连接（推荐）与 URL 回调（Token 签名 + EncodingAESKey 加密）二选一

3

八大渠道：微信助理（零配置推荐）、微信小程序、微信客服号、企业微信、QQ、飞书、钉钉与元宝派，遵循“平台建应用 → 取凭据 → 回填面板”通用流程

4

排查四步：运行状态 → 绑定状态 → 凭据有效性 → 网络环境；最常见根因是电脑休眠

5

安全底线：Secret、EncodingAESKey 等凭据权限极高，务必妥善保管，不截图、不明文外发

下一章：第 8 章 定时自动化任务——从“人不在电脑前”到“人完全不在场”，让 WorkBuddy 按你的安排自动运转。

课后思考题

01

助理任务在工作目录和会话管理上，与使用本地界面的普通任务有哪些核心区别？为什么会有这些限制？

02

尝试举出两个在你目前实际工作中，能够利用“助理机制”大幅提升效率的场景。

03

对比 WebSocket 长连接与 URL 回调两种通信模式，简述在什么情况下应当坚决采用 URL 回调模式？

04

如果你的手机通过微信给电脑发送任务指令后没有任何响应，你该如何按照“四步法”进行排查？

建议先独立思考，再回到配套实验动手验证你的答案。