第3课 考点笔记（助理连接配置）

助理的定义与通信原理

助理的本质：用手机远程驱动电脑上的 WorkBuddy，调用电脑上的所有本地资源（文件、代码环境、技能、连接器）来执行任务。

三段式流程：

1. 你在外，手机发指令（微信、QQ、小程序都行）
2. 云端中转：消息通过腾讯云转发到你的电脑
3. 电脑执行：WorkBuddy 收到指令跑任务，结果推回手机

为什么不直接用手机上的 AI App：文件、代码环境、技能和连接器全在电脑上，手机没有执行环境。助理不是在手机上跑 AI，而是用手机遥控电脑上的 AI——这是核心价值。

四大典型场景：通勤路上、客户现场、半夜灵感、出差办公。共同特征：人不在电脑前，但活必须电脑干。

第一节三关键词：远程触达、固定环境、场景导向。一句话：助理 = 人不在 + 环境固定 + 场景匹配。

三级架构与关键技术

• 架构：手机 → 腾讯云中转 → 电脑上的 WorkBuddy。
• 不能直连的原因：手机在 4G/5G、电脑在局域网，都在 NAT 后面，互相找不到对方；腾讯云中转服务器作为中间人，双方都能主动连它。
• WebSocket 长连接：WorkBuddy 启动时主动向云端发起；HTTP 是问一次答一次，WebSocket 建立后双方可随时互推消息，所以助理能秒回。
• 心跳保活 + 自动重连：每几十秒发一次心跳包；云端收不到心跳判定断连，WorkBuddy 自动重连，全程无需用户操作。

使用助理的四个前提条件

1. 电脑必须开机
2. WorkBuddy 必须在运行
3. 电脑必须连网（有线、WiFi 都行）
4. 电脑不能休眠（休眠会断网，最常见的问题）——WorkBuddy 提供防休眠开关，建议打开

助理与普通任务的区别（高频考点）

三个维度：

助理上下文自动清理的原因：同目录、同会话，不清理上下文越来越长，Token 消耗越来越高。

补充：助理任务在主界面也能创建，不只手机远程发起；典型用法是远程场景，所以叫「助理」而非「远程任务」。

一句话：人在电脑前用主界面更灵活；人不在电脑前用助理远程操控。

安全机制：签名验签与消息加密

两层机制：

1. Token 签名验签（防伪造）：发送方把 Token + 时间戳 + 随机数做 SHA-1 签名附在消息里；接收方用同一 Token 重算签名比对，一致则证明消息来源真实、未被篡改。
2. EncodingAESKey 加密（防窃听）：企微渠道多一层，用 EncodingAESKey 做 AES-CBC 加密，再做 Base64 编码后传输；截获者只能看到乱码。该字段是企微与 WorkBuddy 通信时加解密的密钥。

安全注意事项三条：

1. 不要截图分享（凭据泄漏）
2. 不要提交到 Git（尤其公开仓库，机器人会被接管）
3. 关闭配置页后可能需要重新生成，第一次看到就马上保存

Token 和 AES Key 只存在于凭据型渠道（企业微信助理）；微信助理、小程序、客服号等扫码型渠道的安全由平台底层自动完成，不需要也不能手动配置。

企业微信助理两种接入模式（高频考点）

选型口诀：不确定就直接选长连接；除非公司 IT 明确要求 URL 回调，否则不折腾。

URL 回调只在三种场景考虑：

1. 团队已有统一 Webhook 网关
2. 公司网络限制 WebSocket，长连接频繁掉线
3. 公司有安全审计要求，所有外部访问必须走指定 URL 出口

六大渠道总览（按难度从低到高）

难度一颗星（扫码即用，零凭据）：

1. 微信助理——推荐新手
2. 微信小程序——推荐移动端用户
3. 微信客服号——推荐习惯用客服号的人

难度两颗星（需 App ID + App Secret）：

1. 元宝派——适合腾讯元宝用户
2. QQ——适合 QQ 用户

企业微信助理（分两种情况，易错点）：

6a. 长连接模式：Bot ID + Secret，支持企微扫码一键创建并自动回填，难度降到一颗星 6b. URL 回调模式：Token + AES Key，手动配置，难度三颗星

两大分类（高频考点）：

• 扫码型：微信助理、小程序、客服号 + 企微长连接扫码模式（零凭据或扫码自动回填）
• 凭据型：元宝派、QQ、企微 URL 回调（需手动填 App ID/Secret、Token、AES Key）

配置前置 Checklist（四项）

1. WorkBuddy 已安装并登录 V4.5 或以上版本（低版本可能没有某些渠道入口）
2. 电脑能保持长开（打开防休眠开关）
3. 网络稳定（建议有线或稳定 WiFi，避免公共 WiFi）
4. 对应平台账号已准备好并提前登录

前三项任一不满足，后面全白搭。

渠道一：微信助理

• 本质：绑定在微信账号上的 AI 助理，后端叫 ClawBot（WorkBuddy 内部助理引擎代号，对外统一叫「微信助理」）。
• 六个渠道里唯一 30 秒能跑通的，零凭据。
• 四大特点：零配置（扫码绑定）、即时响应（依赖 WebSocket 长连接）、结果回传（微信消息推回）、多设备同步（换手机不用重新绑定）。
• 接入两步：①主界面左侧边栏「你的助理」（机器人图标）→ 点旁边设置（小齿轮）→ 进入助理集成卡片页（所有渠道统一入口）；②点「微信助理集成」卡片「配置」→ 弹出二维码（有效期约 60 秒，可点刷新）→ 微信扫一扫 → 手机点连接 → 显示绿色「已绑定」。
• 验证：在微信 ClawBot 订阅号对话窗发消息，文件产物保存到 workbuddy/claw 目录。

渠道二：微信小程序

• 定位：移动端原生对话入口 + 任务产物同步窗口。
• 四大特点：原生对话（微信搜索 WorkBuddy 小程序）、零凭据扫码绑定、产物同步（独有：同步任务产物到云端，移动端查看/下载）、自动化首选（自动化任务结果推送到小程序）。
• 产物同步是小程序独有能力，是它与微信助理、客服号的关键差异（高频考点）。
• 接入两步：①WorkBuddy 左下角头像旁的小程序图标 → 弹窗两个开关（第一个控制是否接入小程序对话，第二个控制任务产物是否自动同步，建议都开）；②微信扫码 → 勾选协议 → 授权并继续 → 确认登录账号 → 绑定成功。
• 两大独特能力：
  1. 云端工作：云端沙箱执行，不依赖你的电脑；
  2. 连接电脑：远程操控电脑上的 WorkBuddy 执行。
  • 需要访问电脑本地文件，必须用连接电脑模式（云端沙箱里没有本地文件）。

渠道三：微信客服号

• 适合已有微信客服使用习惯的企业：客户发消息到客服号，WorkBuddy 自动处理回复。
• 微信家族三兄弟对比（高频考点）：

• 接入四步：①侧边栏助理旁设置 → 助理设置；②找「微信客服号集成」卡片点「配置」（别选错卡片）；③点「绑定微信账号」生成二维码 → 本人微信扫码；④等 3~5 秒显示绿色「已绑定」。
• 客服号不支持产物同步到手机（同微信助理）。

渠道四：元宝派

• 本质：在腾讯元宝 App 里创建一个 Bot，让它调用电脑上的 WorkBuddy（凭据型渠道）。
• 关键概念：元宝 App 底部「派」标签可创建 Bot；OpenClaw 协议是元宝官方对接标准；App ID 相当于账号名（公开），App Secret 相当于密码（私密不可泄漏）；本课程用快捷扫码关联，无需手动填凭据。
• 解决问题：元宝是云端 AI 无法访问本地环境，元宝派让元宝 @Bot 触发电脑上的 WorkBuddy，结果返回元宝对话。
• 七步流程：手机元宝侧 ①「派」→「我的 Bot」→「创建 Bot」；②「关联 OpenClaw」→ 方式 3「扫码关联」；③手机显示二维码待扫。电脑 WorkBuddy 侧 ④助理旁设置图标 → 助理设置；⑤找「元宝扫码绑定」卡片显示二维码；⑥手机扫码 → 点「授权关联元宝」；⑦双端显示「已连接」→ 测试连通性。
• 节奏口诀：手机创建 → 电脑扫码 → 双端确认。
• 注意：元宝 App 里关联 OpenClaw 需点「我已操作」确认，否则 WorkBuddy 侧收不到回调。

渠道五：QQ 接入

• 本质：在 QQ 开放平台创建机器人，让它调用电脑上的 WorkBuddy；适合 QQ 群协作（@机器人，结果推送到群）。
• 关键点：开放平台地址 q.qq.com；QQ 账号必须实名认证（平台硬性要求，否则创建不了机器人）；App ID（公开）+ App Secret（私密）。
• 三步流程：
  1. 浏览器访问 q.qq.com/qqbot/openclaw/login.html → QQ 扫码登录 → 创建机器人（未实名会报错）；
  2. 详情页「凭证/开发信息」拿 App ID 和 App Secret——Secret 不支持明文保存，关页面再进变星号，第一时间复制保存；复制别带首尾空格（会校验失败）；
  3. WorkBuddy 左下角头像 → 助理设置 →「QQ 机器人集成」→ 配置 → 选 WebSocket 长连接（推荐）→ 粘贴凭据 → 点「注册」→ 状态变「已连接」。
• 与元宝派的关键差异：QQ 没有双端确认环节，注册成功直接能用（高频考点）。

渠道六：企业微信助理

• 最复杂也最企业级：数据走企微内网，符合安全要求；需要管理员权限（普通员工找 IT 申请）；长连接依赖电脑长开。
• 核心流程：创建机器人 → 选模式 → 配置 → 用。

长连接：手动三步法

1. 创建机器人：work.weixin.qq.com 管理员登录 → 应用管理 → 自建 → 创建机器人；
2. 机器人详情页 → API 配置 → 选「使用长连接」→ 系统生成 Bot ID 和 Secret（Secret 只显示一次，立即保存）；
3. WorkBuddy → 助理设置 → 企业微信助理集成 → 配置 → 选「使用长连接」→ 粘贴凭据 → 注册 → 绿色「已绑定」。

长连接：快捷绑定四步（强烈推荐）

1. WorkBuddy 配置弹窗 → 点「快捷绑定接入」→ 弹出二维码；
2. 手机企业微信 → 右上角加号 → 扫一扫 → 扫电脑上的码；
3. 手机点「一键创建智能机器人」→ 权限确认 →「确认授权」（Bot ID 和 Secret 自动回填）；
4. 回 WorkBuddy 点「注册」→ 显示「已连接」。

授权权限包括：获取对话用户信息、收发单聊和群聊消息、新建和读取文档、新建和读取日程、预约和修改会议、新建和更新待办、获取通讯录成员信息。

长连接小结四点

三步完成；两个凭据（Bot ID + Secret，Secret 只显示一次）；电脑长开（防休眠开关）；WiFi 稳定（频繁断连触发企微侧心跳异常报警）。

三个常见误区（错误选项高频来源）

1. 以为长连接需要公网 IP——错，长连接是客户端主动外联不需要公网 IP，URL 回调才需要；
2. 复制 Secret 带空格——导致鉴权失败；
3. 普通员工尝试创建机器人——只有管理员能创建。

URL 回调四步配置

1. 企微管理后台：机器人详情页 → API 配置 → 选「使用 URL 回调」；
2. Token 和 EncodingAESKey 右侧点「随机获取」→ 生成两个字符串 → 立即复制保存（关闭页面后需重新生成）；
3. WorkBuddy → 助理设置 → 企微助理集成 → 配置 → 切「使用 URL 回调」标签 → 粘贴 Token 和 EncodingAESKey → 注册 → 页面显示 Webhook URL → 完整复制；
4. 回企微后台机器人配置页 →「接收消息 URL」粘贴 Webhook URL → 保存 → 看到「URL 验证成功」绿色提示。

注意：Webhook URL 不要泄露给外部（是消息接收入口，泄露后他人可伪造消息推送）。

验证失败检查三项：①WorkBuddy 是否正常运行；②Token 和 EncodingAESKey 两边是否一致；③Webhook URL 是否完整无遗漏。

通用排查四步法（递进顺序）

1. 检查 WorkBuddy 是不是在跑（最常见）：电脑开机 + WorkBuddy 在运行 + 助理服务已开启。80% 的「配置完没反应」出在这一步。
2. 核对绑定状态：助理设置页面看渠道卡片是否显示「已绑定/已连接」；未绑定则重走流程。
3. 检查凭据（凭据型渠道）：有没有复制错、带空格、填错字段（App ID 填到 Secret 位）、Secret 是否失效（二次查看会重置）。
4. 排查网络：电脑能否访问外网、有无代理/VPN 干扰、WiFi 是否稳定。

四步是递进的：先环境、再配置、最后网络，别一上来就查网络。

三个高频问题

问题一：扫码后没有显示「已绑定」（三个原因）：

1. 扫错账号——扫码微信与 WorkBuddy 登录微信须同一个；
2. 状态同步延迟 3~5 秒——等 5 秒再刷新；
3. 二维码过期——点「刷新二维码」重扫。 通用解法：刷新二维码 → 本人账号扫码 → 等 5 秒看状态。

问题二：绑定成功但发消息没响应（四个原因，按频率排序）：

1. 电脑休眠了（最高频）——唤醒电脑，助理服务自动重连；
2. WorkBuddy 被关掉了——重新打开，确认助理服务运行；
3. 绑定状态异常——解绑后重新扫码绑定；
4. 其他设备占用绑定——新绑定顶掉旧的，当前设备退出微信重新登录再绑定。

问题三：凭据型渠道注册失败：

• 元宝派/QQ 四原因：凭据带空格；App Secret 已失效（需重新生成）；QQ 未实名认证；元宝派没点「我已操作」。
• 企微三原因：长连接 Bot ID/Secret 带空格；URL 回调 Webhook URL 不完整或 Token/AES Key 两边不一致；WorkBuddy 没在运行。
• 最常见原因：凭据带空格。

易混点速记