第一章：连接企业微信机器人
这一章帮你把 Halo 和企业微信打通。打通之后，你的同事在企业微信里给机器人发一条消息，住在 Halo 里的「数字人」会自动看见、自动回复。
不需要懂技术。每一步都告诉你：眼睛该看屏幕的哪里、鼠标该做什么动作、做完之后画面会变成什么样。
1.1 企业微信机器人是什么？
用一个生活里的场景理解
想象你开了一家律师事务所，前台坐着一位接待员叫小王。
- 客户走进事务所、打电话进来 → 小王接收消息
- 小王不懂法律 → 她把问题转给所里的合伙人
- 合伙人给出答复 → 小王再把答复转告客户
小王就是「企业微信机器人」：她只负责传话，不负责思考。
合伙人就是「数字人」：真正动脑子、回答问题的那一位。合伙人住在 Halo 里。
把这两个角色合起来，你就得到一个 24 小时在线、自动回答员工和客户问题的 AI 助手。
为什么需要两个角色？
可能你会想：「为什么不能一个搞定？让企业微信直接装一个 AI 不就行了？」
答案是：企业微信是一个聊天工具，它本身不会思考。Halo 才是装着 AI 大脑的地方。
所以这一章要做两件事：
┌──────────────────────────┐ ┌──────────────────────┐
│ 企业微信里的机器人 │ ←────→ │ Halo 里的数字人 │
│ （前台小王 · 传话） │ 消息 │ （合伙人 · 思考） │
└──────────────────────────┘ └──────────────────────┘
第 1 件事：在企业微信里 第 2 件事：在 Halo 里
把这位"小王"申请出来 把"合伙人"和"小王"绑定完成这两件事之后，整条链路就通了。
你需要准备什么？
在开始之前，请确认你手上有这些东西：
- 一台已经登录企业微信的电脑（手机也行，但电脑操作更方便）
- 企业微信的「管理员」权限——也就是你能登录企业微信的网页后台
- 不知道自己是不是管理员？最简单的判断：用浏览器打开
https://work.weixin.qq.com，如果能看到「管理后台」入口并点进去看到管理界面，你就是管理员 - 如果不是管理员，需要找你公司里管这个的人帮忙（通常是 IT 或 HR）
- 不知道自己是不是管理员？最简单的判断：用浏览器打开
- Halo 软件已经装在你电脑上，并且能正常打开
- 还没装？先看《第零章：安装 Halo 并第一次打开》（暂未编写，可在 Halo 官网下载）
⚠️ 注意：企业微信版本要在 5.0.7 或更新。版本太老的话，下面要找的「智能机器人」入口根本不会出现。检查方法：手机上打开企业微信 → 我 → 设置 → 关于企业微信，看版本号。
1.2 在企业微信里申请一个机器人
这一节，我们要在企业微信的管理后台里，告诉企业微信：「我想要一个机器人」。
申请完成后，企业微信会给你两串字符——记住这两串字符，1.3 节要把它们填进 Halo。
第一步：打开企业微信管理后台
打开你电脑上的浏览器（Chrome、Edge、Safari 都行）
在最上方那条长长的地址栏里，把里面的内容删干净，输入下面这串地址，然后按回车键：
https://work.weixin.qq.com网页打开后，眼睛看屏幕的右上角，会有一个写着「企业登录」或「管理后台」的按钮，鼠标移过去单击它
出现一个二维码，拿出你的手机，打开企业微信 App，点右上角的「+」号，选「扫一扫」，对准电脑屏幕上的二维码扫一下
手机上会弹出一个确认窗口，问你「是否登录管理后台」，点「确认」
做完之后你会看到：电脑浏览器自动跳转到一个新页面，最上方显示你公司的名字，左边是一列菜单。这就是企业微信的管理后台了。
┌────────────────────────────────────────────────────────┐
│ 企业微信管理后台 [你的公司名] [头像] │
├──────────────┬─────────────────────────────────────────┤
│ 首页 │ │
│ 通讯录 │ 主要内容显示在这一大块区域里 │
│ 应用管理 │ │
│ 客户联系 │ │
│ 我的企业 │ │
│ ... │ │
└──────────────┴─────────────────────────────────────────┘第二步：找到「智能机器人」入口
重要提示：企业微信的后台界面会随版本更新调整。如果下面描述的位置和你看到的不完全一样，别慌——核心思路是「找到一个名字叫『智能机器人』或者带『机器人』字样的入口」，不要被位置变化吓住。
方法 A：从左侧菜单进入
- 看屏幕左边的菜单列，找到 应用管理 这一项，单击它
- 页面右边会出现应用列表，往下翻找，找到一个名字叫 智能机器人 的卡片
- 单击 智能机器人 这张卡片
方法 B：直接搜索（如果方法 A 找不到）
部分版本的后台支持搜索。在页面顶部如果能看到一个搜索框，里面输入「智能机器人」回车，结果里点进去也行。
做完之后你会看到：一个新页面，标题写着「智能机器人」，下方可能空空的（你还没创建过任何机器人），右上角或中间会有一个明显的 创建 按钮。
第三步：点击「创建」并选择「API 模式」
这一步是整个第一章里最容易点错的一步，一定要看清楚。
单击页面上那个 创建 按钮
屏幕上会弹出一个小窗口，让你选择创建方式。窗口里通常有几个选项卡片，底部会有一行很小的字，写着类似「API 模式创建」「通过 API 接入」这样的字样
┌─────────────────────────────────────────────┐ │ 创建智能机器人 [×] │ ├─────────────────────────────────────────────┤ │ │ │ [模板1] [模板2] [模板3] │ │ 普通 客服 销售 │ │ │ │ ─────────────────────────── │ │ │ │ ► API 模式创建 ←── 看这里！这一行小字 │ │ │ └─────────────────────────────────────────────┘不要点上面那些大卡片（普通模板、客服模板等等），那些是企业微信自带的简单机器人，跟 Halo 对接不上
要点底部那行小字 API 模式创建
⚠️ 注意：如果你不小心点了上面的大模板创建出来的机器人，回到机器人列表，把它删掉重来即可。
做完之后你会看到：进入一个新页面，让你给机器人起名字、上传头像。
第四步：填写机器人名字和头像
在「机器人名称」输入框里，给你的机器人起个名字。建议起个员工一看就知道是干嘛的名字，比如：
- 「法律小助手」
- 「HR 智能客服」
- 「张三的 AI 秘书」
头像可以上传一张图片，也可以先不传（之后能改）
名字和头像填好之后，找页面下方的 保存 或 创建 按钮，单击它
做完之后你会看到：页面跳转到这个机器人的详情/设置页面。机器人已经创建出来了，但是还没法用——必须再走 1.3 节的步骤。
第五步：进入「API 配置」页面
这一步是为下一节做准备——拿到那两串关键字符。
- 在机器人详情页里，找到一个叫 设置 或 API 配置 的标签/按钮，单击它
- 页面会展开 API 相关的配置选项
如果页面里出现了两个连接方式让你选，记住这一条规则：
| 选项 | 选不选 |
|---|---|
| 使用长连接 | ✅ 选这个 |
| 使用 URL 回调 | ❌ 不要选 |
为什么选长连接？ 你可以理解成：「URL 回调」需要你的电脑有一个公网网址（一般人没有），「长连接」是反过来——是 Halo 主动去连企业微信，普通家用/办公电脑都能用。Halo 目前只支持长连接这一种方式。
选好长连接，点旁边的 确认 或 保存 按钮。
做完之后你会看到：页面上出现两个非常重要的字符串，一个叫 Bot ID，一个叫 Secret。
┌─────────────────────────────────────────────────────┐
│ API 配置 │
├─────────────────────────────────────────────────────┤
│ Bot ID: aib-xxxxxxxxxxxxxxxx [复制] │
│ │
│ Secret: abcDEF123456... [复制] [重置] │
│ │
│ 连接方式: ● 使用长连接 │
│ ○ 使用 URL 回调 │
└─────────────────────────────────────────────────────┘第六步：把 Bot ID 和 Secret 复制保存下来
这一步至关重要，做错了下一节没法继续。
准备一个空的记事本（Windows：开始菜单 → 记事本；Mac：聚焦搜索「文本编辑」）
在企业微信后台的页面上，Bot ID 旁边会有一个 复制 按钮，单击它
切换到记事本，按
Ctrl + V（Windows）或Cmd + V（Mac）粘贴在记事本里，先打一行字标记一下，方便你认：
Bot ID: aib-xxxxxxxxxxxxxxxx回到企业微信后台，Secret 旁边也有 复制 按钮，单击复制
切回记事本粘贴，标记成：
Secret: abcDEF123456......（一长串字母数字）把记事本保存到一个自己能记住位置的地方，文件名比如「机器人凭据.txt」
⚠️ 超级重要——为什么 Secret 必须现在保存
Secret 这串字符，企业微信只会在创建那一刻显示一次。如果你这次没复制下来，下次进来这个页面，Secret 那一栏就会变成几个圆点，看不到原始内容了。
万一真没保存：旁边有 重置 按钮，点它会生成一个新的 Secret。但要小心：重置以后，老的 Secret 立即作废，如果你已经在 Halo 里填过老的，那边连接会断，需要回 Halo 把新的填进去。
现在就保存，省得后悔。
完成 1.2 节后，你手上应该有：
- ✅ 一个在企业微信后台创建好的机器人（带名字和头像）
- ✅ 一个写着
Bot ID和Secret的记事本文件，安全地存在你电脑上
下一节 1.3，我们去 Halo 里把这两串字符填进去。
1.3 把机器人凭据填进 Halo
这一节，我们把 1.2 节拿到的 Bot ID 和 Secret 填进 Halo 软件里。完成之后，Halo 就能听见企业微信里发给那个机器人的消息了。
📝 开始之前：请把 1.2 节保存的「机器人凭据.txt」打开放在桌面边上，等下要用。
第一步：打开 Halo 并进入「设置」页面
双击桌面或开始菜单里的 Halo 图标，把软件打开
Halo 打开之后，眼睛看屏幕顶部栏的最右边——那里有一个看起来像齿轮形状的小图标
┌──────────────────────────────────────────────────┐ │ ○ Halo ⚙️ │ ← 齿轮在这里 ├──────────────────────────────────────────────────┤ │ │ │ 主操作区（不同页面显示不同内容） │ │ │ └──────────────────────────────────────────────────┘把鼠标移到那个齿轮图标上，单击它
做完之后你会看到：整个页面切换到设置界面。顶部变成 ← Settings 的样式，下方分左右两栏——左边是设置菜单列表（AI Model、Message Channels、App Store 等），右边是具体设置内容。
💡 学到一个新名词：这个齿轮图标点开的页面，叫做**「设置」**。本手册后面凡是说「打开设置」，就是指这个动作。就像手机里的「设置」一样，是调整软件各种选项的地方。
第二步：找到「Message Channels（消息通道）」
进入设置后，眼睛看屏幕左侧的子菜单列。
- 在子菜单列表里，往下找一个写着 Message Channels 的项目（如果你的 Halo 是中文界面，写的可能是「消息通道」「消息渠道」之类）
- 单击它
做完之后你会看到：右侧主区域刷新成一长串卡片列表。最上面有个标题写着 Message Channels，下面是一张张卡片，每张卡片代表一种「消息通道」。
💡 学到一个新名词：**「消息通道」**就是 Halo 和外部世界（企业微信、邮件、钉钉等）之间的「门」。每张卡片是一扇不同的门。这一节我们要打开的，是「企业微信智能机器人」那扇门。
第三步：找到正确的卡片——「WeCom Intelligent Bot」
这一步最容易点错——因为列表里有好几张长得很像的卡片，名字都带「WeCom」。请按下面的特征认准。
你要找的卡片：
- 名字：写着 WeCom Intelligent Bot（中文版可能写成「企业微信智能机器人」）
- 图标：图标看起来像一个对话气泡 💬
- 特殊徽标：卡片标题旁边有一个蓝色或紫色的小标签，写着 Bidirectional（双向）
┌─────────────────────────────────────────────────────────────┐
│ 💬 WeCom Intelligent Bot [Bidirectional] Not configured │ ← 这就是它
│ Bidirectional messaging via WeCom AI Bot WebSocket ⚪ │
└─────────────────────────────────────────────────────────────┘
下面这些卡片【不要】点：
┌─────────────────────────────────────────────────────────────┐
│ 📱 WeChat Bot [Bidirectional] ... │ ← 这是「微信」的，不是「企业微信」
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ 💬 WeCom (App Push) [One-way] ... │ ← 这是单向通知卡，只能发不能收
└─────────────────────────────────────────────────────────────┘⚠️ 关键区分：
- **Bidirectional（双向）**徽标 = 既能发也能收消息，这才是我们要的
- **One-way（单向）**徽标 = 只能发通知，收不到员工的回复，不要选这个
- WeChat Bot（带「WeiChat」拼写）= 私人微信号，跟我们说的「企业微信」是两个不同产品，也不要选
认准之后，单击 那张「WeCom Intelligent Bot」卡片的标题区域。
做完之后你会看到：卡片像抽屉一样向下展开，露出里面的内容。如果你之前从没配过，里面会写着 No Bot instances configured. Click the button below to add one.（还没有机器人，点下方按钮添加一个），下方有一个虚线边框的按钮，写着 + Add Bot（添加机器人）。
第四步：点击「Add Bot」添加一个机器人实例
- 看卡片底部那个虚线方框按钮，单击它
做完之后你会看到：卡片里出现了一张新的小卡片（嵌套在大卡片里），并且它已经自动展开了，里面有一堆输入框等你填写。新卡片的标题区域大概长这样：
┌─ WeCom Intelligent Bot ──────────────────────────────────┐
│ ⚪ Not bound │ ← 灰色小圆点 = 未绑定
│ Bot ID: Not set │
│ ───────────────────────────────────────────────── │
│ Enabled [○──] │ ← 开关，先别动
│ │
│ Bot ID * │
│ ┌──────────────────────────────────────────────────┐ │
│ │ aib-xxx │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ Secret * │
│ ┌──────────────────────────────────────────────────┐ │
│ │ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ WebSocket URL │
│ ┌──────────────────────────────────────────────────┐ │
│ │ wss://openws.work.weixin.qq.com │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ Digital Human * │
│ ┌──────────────────────────────────────────────────┐ │
│ │ 🤖 Select digital human ▾ │ │
│ └──────────────────────────────────────────────────┘ │
│ ... │
└──────────────────────────────────────────────────────────┘带 * 红星的字段是必填项。
第五步：填写 Bot ID
- 切到你的「机器人凭据.txt」记事本
- 选中 Bot ID: 下面那一行（类似
aib-xxxxxxxxxxxxxxxx），按Ctrl + C（Mac 是Cmd + C）复制 - 切回 Halo 窗口
- 把鼠标移到 Halo 那个写着 Bot ID 的输入框里，单击一下让光标进去
- 按
Ctrl + V（Mac 是Cmd + V）粘贴
做完之后你会看到：输入框里出现了刚才那串字符。同时小卡片顶部那行原本写着 Bot ID: Not set 的灰字，会变成你刚填的 ID 的前几位。
⚠️ 注意：粘贴的时候，前后不要有空格。如果你看到首尾有空白，用退格键删掉。空格会导致连接失败。
第六步：填写 Secret
- 切回记事本
- 选中 Secret: 下面那一行（一长串字母数字），复制
- 切回 Halo
- 单击 Secret 输入框（注意：这是密码框，输入的内容会自动变成圆点
••••••••，看不到原文，这是正常的） - 粘贴
做完之后你会看到：Secret 输入框里出现一排黑色圆点。看不到原文不代表填错了，这是软件在保护你的密码。
第七步：WebSocket URL —— 直接留空
输入框里如果有占位灰字 wss://openws.work.weixin.qq.com，别管它，那只是提示文字，不是真正的内容。
这个框你什么都不用填，留空就行。 Halo 会自动用默认地址。
💡 什么时候才需要填这个？ 只有当腾讯官方更换地址、或者你们公司用了私有部署版企业微信时才需要。99% 的用户都不用填。
第八步：选择「Digital Human（数字人）」
这一步是把「企业微信里的机器人（前台小王）」和「Halo 里的数字人（合伙人）」绑在一起。
- 单击下拉框 Digital Human（图标是一个 🤖 机器人小图）
- 下拉列表里会显示你 Halo 里已经创建好的所有数字人
- 选一个你想让它来回复消息的数字人
如果下拉列表是空的（只有「Select digital human」这一项）：
意味着你 Halo 里还没有任何数字人。这种情况下，请先暂停 1.3 节的操作，跳到 第二章：创建你的第一个数字人，按那一章把数字人创建出来。然后回到这里继续。
⚠️ 关键规则——一对一绑定：每张「Bot 卡片」只能绑定一个数字人。如果你想让两个不同的数字人各自处理不同的对话，需要在企业微信后台多申请几个机器人（每个有自己的 Bot ID/Secret），然后在 Halo 里多点几次 Add Bot，每个机器人绑一个数字人。
反过来，同一个 Bot ID 绝对不能在两个 Halo 卡片里重复填。如果重复填了，Halo 会在输入框旁边显示一行黄色警告字：「This Bot ID is already in use by another instance.」(此 Bot ID 已被其他实例占用)，连接也会失败。
做完之后你会看到：下拉框里显示出你选中的数字人名字，下方有一行小字「All messages from this Bot will be handled by this digital human」（这个机器人收到的所有消息都将由这个数字人处理）。
第九步：打开「Enabled」开关
回到小卡片最上面那个 Enabled 开关。
- 单击开关右侧的圆形滑块
- 滑块从左滑到右，开关底色变成亮色（一般是蓝色或紫色），说明已开启
做完之后你会看到：
- 开关变蓝
- 卡片头部那个原本灰色的小圆点（⚪ Not bound）会变化：
- 如果 Bot ID 和 Secret 填对了 → 几秒钟内变成绿色 🟢，旁边出现 Connected（已连接）
- 如果填错了 → 会变成琥珀色 🟡，旁边写着 Disconnected（已断开）
连接成功 → 🟢 [数字人名字]
Bot ID: aib-xxxxxxx...
✓ Connected
连接失败 → 🟡 [数字人名字]
Bot ID: aib-xxxxxxx... · Disconnected💡 不用点保存按钮：Halo 是「改了就自动保存」的。你填完一个框，点别处或者按 Tab 切走，约半秒内 Halo 就把这条配置存好了。所以这张卡片没有「保存」按钮——这不是缺漏，是设计如此。
完成 1.3 节后：
- ✅ Halo 设置 → Message Channels 里多了一张机器人小卡片
- ✅ 卡片左上角是绿色小圆点，写着 Connected
- ✅ Bot ID、Secret、Digital Human 都填好了
如果你现在看到的是绿色 Connected，恭喜，整条链路已经打通。可以直接跳到 1.5 节去企业微信里测试了。
如果是琥珀色 Disconnected，先看 1.4 节的排查流程。
1.4 连接失败？按这个清单一项项查
如果 1.3 第九步打开开关后，你看到的是琥珀色 🟡 Disconnected，按下面的顺序检查：
检查 1：Bot ID 有没有粘贴错？
- 单击小卡片让它展开（如果已经展开就跳过）
- 看 Bot ID 那一行
- 它应该以
aib-开头（小写字母 a、i、b、连字符），后面跟一串字母数字 - 对比记事本里的内容，必须完全一致——首尾不能有空格、不能漏字符
检查 2：Secret 有没有粘贴错？
由于 Secret 显示成圆点看不见，没法直接对比。最简单的办法：
- 在 Halo 卡片里，单击 Secret 输入框
- 全选（
Ctrl/Cmd + A）然后按Delete键删干净 - 再回记事本重新复制 Secret，粘贴回 Halo
- 等几秒看左上角圆点会不会变绿
如果重新粘贴还是不行，可能你当初没复制完整。这时只能回企业微信后台重置 Secret（在 1.2 第五步那个页面，Secret 旁边的「重置」按钮），重置完会出新的 Secret，复制回来再填。
⚠️ 重置代价：重置之后老 Secret 立即失效。如果你的旧 Secret 已经在别处用过，那些都得改成新的。
检查 3：企业微信后台的「连接方式」选对了吗？
- 浏览器打开
https://work.weixin.qq.com登录管理后台 - 进入你那个机器人 → API 配置
- 确认下面那个选项选的是 使用长连接，不是「使用 URL 回调」
如果选错成 URL 回调，改成长连接后保存，回到 Halo 等 10 秒，状态会自动刷新成绿色。
检查 4：电脑能正常上网吗？
Halo 是通过你电脑的网络去连企业微信服务器的。如果你电脑断网或者公司有防火墙挡住了 openws.work.weixin.qq.com，就连不上。
简易测试：用浏览器随便打开一个网页（比如 https://work.weixin.qq.com），能正常打开就说明网通了。
如果公司有严格的防火墙：找 IT 部门，让他们开放对 openws.work.weixin.qq.com:443 的出站访问。
检查 5：是不是 Bot ID 和别的实例重复了？
如果 Bot ID 输入框旁边有黄色警告文字（写着「This Bot ID is already in use by another instance」），说明你在 Halo 里至少有两张卡片填了同一个 Bot ID。
解决：决定保留哪张卡片，把另一张右上角的「⋮」菜单点开 → 选 Delete → 确认删除。
1.5 在企业微信里给机器人发消息
到这一步，你已经在 Halo 里看到绿色的 Connected 了。但真正的考验是：从企业微信里发一条消息，能不能收到回复？
这一节带你走完最后一环：在企业微信里找到机器人 → 发一条消息 → 看数字人自动回复。
第一步：在企业微信里找到你的机器人
你在 1.2 节创建的那个机器人（取了名字、配了头像的那个），现在已经"住"在企业微信的通讯录里了。我们要先找到它。
在电脑端企业微信操作：
- 打开电脑上的企业微信客户端（不是浏览器里的管理后台，是那个聊天用的程序）
- 眼睛看软件左侧的图标栏，找到一个看起来像通讯录（小人头 + 一本书的样子）的图标，单击它
- 在通讯录列表里，往下翻，找到一个叫 机器人 或 智能机器人 的分类
- 点开这个分类，里面应该能看到你 1.2 节创建的那个机器人（显示的是你当时起的名字和头像）
- 单击那个机器人的名字
做完之后你会看到：右侧弹出了这个机器人的详情页面或者直接打开了聊天窗口。如果是详情页面，找到 发消息 按钮，单击它进入聊天窗口。
在手机端企业微信操作（也可以）：
- 打开手机上的企业微信 App
- 点底部导航栏的「通讯录」
- 在通讯录页面里找 机器人 分类（可能需要往下滑一滑才能看到）
- 点进去，找到你创建的那个机器人名字
- 点进去后，点 发消息
💡 小知识：如果你通讯录里找不到「机器人」分类，可能是你还没有权限看到它（需要管理员设置可见范围），或者企业微信版本太低。回到 1.2 节检查版本号要求。
第二步：给机器人发一条测试消息
现在你应该已经在和机器人的聊天窗口里了。
在聊天窗口最下方的输入框里，输入一句简单的话，比如：
你好，请做一下自我介绍按 回车键（电脑端）或点 发送 按钮（手机端）
等待几秒钟
做完之后你会看到：
- 如果一切正常，机器人会在几秒内开始回复。你会看到聊天窗口里出现机器人的回复气泡
- 如果你在 Halo 里开了「Streaming（流式输出）」（默认是开的），你还会实时看到数字人的思考过程——消息气泡里的文字会一段一段地蹦出来，就像有人正在打字一样
- 最终会得到一段完整的回复
┌─────────────────────────────────────────┐
│ 与 法律小助手 的聊天 │
├─────────────────────────────────────────┤
│ │
│ 你：你好，请做一下自我介绍 │
│ │
│ 法律小助手：你好！我是你的 AI 助手， │
│ 可以帮你回答问题、处理任务...... │
│ │
│ ┌───────────────────────────────────┐ │
│ │ 输入消息... [发送] │ │
│ └───────────────────────────────────┘ │
└─────────────────────────────────────────┘⚠️ 发了消息但没有收到回复？ 按下面的顺序检查：
- Halo 软件还开着吗？ 机器人靠 Halo 来"思考"，如果 Halo 关了或者电脑休眠了，消息就没人处理。回到电脑上确认 Halo 窗口还在。
- Halo 里的连接状态还是绿色吗？ 打开 Halo → 设置 → Message Channels → WeCom Intelligent Bot → 看那张小卡片左上角的圆点。如果变成琥珀色了，参照 1.4 节重新排查。
- 选了数字人吗？ 小卡片里的 Digital Human 下拉框如果是空的，机器人收到消息也不知道转给谁。选一个数字人。
- 数字人本身能正常工作吗？ 在 Halo 的聊天界面里直接和这个数字人对话试试——如果在 Halo 里也回答不了，说明是数字人本身有问题（比如 API Key 过期了），不是机器人的问题。
第三步：试试群聊里 @ 机器人
除了私聊，机器人也能在企业微信的群聊里使用。但群聊有一条重要规则：
群里的消息，必须 @ 机器人它才能看见。 没有 @ 的消息，机器人完全看不到——这是企业微信的协议限制，不是 Halo 的设置问题。
操作方法：
- 打开一个企业微信群（或者新建一个测试群）
- 把你的机器人拉进群——群设置 → 添加成员 → 在列表里找到机器人名字 → 添加
- 在群聊输入框里，先输入一个
@符号，这时会弹出一个成员列表 - 在列表里找到你的机器人名字，单击它
- 输入框里会自动出现
@法律小助手（蓝色字，后面带一个空格），接着输入你的问题，比如@法律小助手 今天天气怎么样 - 按回车发送
做完之后你会看到：机器人在群里回复了你 @ 它时问的那个问题。
💡 群聊 vs 私聊的区别：
私聊 群聊 机器人能看到的消息 你发的所有消息 只有 @ 它的那条 对话上下文 有完整历史记录 只有当前 @ 的那一条 适合什么 深度问答、连续对话 快速查询、群内通知
第四步：确认「首次 @ 建立联系」
这一步是为将来做准备——如果你以后想让机器人主动给某个群或某个人发消息（比如定时播报），需要先建立联系。
规则很简单：对方（群或个人）至少给机器人发过一次消息（或者在群里 @ 过一次），之后机器人就能主动找他/这个群发消息了。
你刚才在私聊和群里各发了一条消息，联系已经建立了。以后数字人在定时任务里就可以主动给这个群推消息，不需要再做任何额外操作。
完成 1.5 节后：
- ✅ 你在企业微信里和机器人私聊了，收到了回复
- ✅ 你在群聊里 @ 机器人了，也收到了回复
- ✅ 你知道了「必须 @ 才能看见」这条群聊规则
- ✅ 你已经和机器人建立了联系，以后它可以主动给你发消息
下一节 1.6 介绍机器人卡片里的三个进阶设置，帮你更精细地控制机器人的行为。
1.6 进阶设置：回复范围、流式输出、权限控制
到目前为止，你的机器人已经能正常收发消息了。1.3 节填完凭据后，你可能注意到机器人小卡片里还有几个设置项没动过——它们用的都是默认值，基本够用。
但如果你想要更精细地控制：「机器人只在群里回消息，不接私聊」「不要显示思考过程」「限制哪些同事能用高级功能」——那就需要了解这三个设置。
找到这三个设置在哪里
这三个设置就在你 1.3 节填 Bot ID 和 Secret 的那张小卡片里，在 Digital Human 下拉框的下方。
- 打开 Halo → 设置 → Message Channels → 单击 WeCom Intelligent Bot 展开
- 单击你的机器人小卡片让它展开
- 往下滚，在 Digital Human 下面，你会看到三个设置项依次排列：
┌─ 机器人小卡片 ──────────────────────────────────────┐
│ ...（上面是 Bot ID / Secret / WebSocket URL / │
│ Digital Human，1.3 节已经填好了） │
│ ─────────────────────────────────────────────── │
│ │
│ Reply Scope [All messages ▾] │ ← 第一个：回复范围
│ │
│ Streaming [──●] │ ← 第二个：流式输出
│ Shows thinking process in real-time │
│ │
│ Permission Control [●──] │ ← 第三个：权限控制
│ Everyone has full access │
│ │
└──────────────────────────────────────────────────────┘下面分别说明每个设置的含义和使用场景。
设置一：Reply Scope（回复范围）
这个下拉框控制机器人回复哪一类消息。点击下拉框，你会看到三个选项：
| 选项 | 英文显示 | 含义 |
|---|---|---|
| 全部消息 | All messages | 群聊消息和私聊消息都回复（默认值） |
| 仅群聊 | Group chats only | 只在群里被 @ 时回复，有人私聊它就忽略 |
| 仅私聊 | Direct messages only | 只回复私聊消息，群里 @ 它也不理 |
怎么选？
- 大多数情况下：保持默认的 All messages（全部消息） 就好。机器人既能在群里用，也能私聊用。
- 安全考虑：如果你担心任何同事都能私聊机器人获取敏感信息，选 Group chats only（仅群聊）。这样机器人只在特定群里响应，你能控制哪些群有这个机器人。选了仅群聊之后，下拉框下方会出现一行小字提示：「Private messages will be rejected for security」（私聊消息会被拒绝）。
- 个人助理场景：如果机器人只给你一个人用（当私人秘书），选 Direct messages only（仅私聊），防止群里被其他人 @ 触发。
操作方法：单击下拉框，选择你想要的选项。选好后不需要点保存——Halo 自动保存。
设置二：Streaming（流式输出）
这是一个开关（滑块按钮）。控制的是：当数字人在"思考"的时候，企业微信里的聊天气泡是一点一点显示，还是等全想完了再一次性显示出来。
| 状态 | 滑块位置 | 你在企业微信里看到的效果 |
|---|---|---|
| 开启（默认） | 滑块在右边，底色亮 | 消息气泡里的文字实时出现，像有人在打字。如果数字人在调用工具（比如搜索、读文件），你还能看到「正在搜索...」「正在读取...」这样的中间步骤 |
| 关闭 | 滑块在左边，底色灰 | 发消息后什么都不显示，等数字人全部想完、工具也调完了，才一次性把最终回复发出来。中间可能要等十几秒到一分钟，这期间聊天窗口里没有任何动静 |
怎么选？
- 建议大多数情况保持开启。原因是：如果关闭了，发完消息后长时间没反应，用户会以为机器人挂了。
- 关闭适合以下场景：
- 数字人需要调用很多工具（比如先搜索、再读文件、再计算），中间步骤信息很杂乱，不想让用户看到
- 对外展示（比如给客户用），不想暴露 AI 的"思考过程"
操作方法：单击开关的滑块。滑块在右（亮色）= 开启，在左（灰色）= 关闭。
设置三：Permission Control（权限控制）
这是最复杂的一个设置，但也是最重要的——尤其是当你的机器人不是只给自己一个人用，而是要给一群同事用的时候。
先搞清楚「权限控制」在管什么
想象一下：你设置了一个机器人，绑定的数字人可以读写文件、浏览网页、发邮件。如果企业里任何一个人给机器人发消息，这个人就能通过机器人让 AI 做这些事——包括读你电脑上的文件、用你的邮箱发邮件。
权限控制就是解决这个问题的：它让你区分「谁是老板（Owner）」和「谁是访客（Guest）」，然后给访客设一个能力上限。
默认状态：关闭（所有人全权限）
Permission Control 的默认状态是关闭的（开关在左边，灰色），下方小字写着 Everyone has full access（所有人全权限）。
如果你的机器人只有你自己在用，或者你信任所有能接触到这个机器人的人，保持关闭就行，不需要动。
什么时候需要开启？
当你的机器人会被多个同事使用，而你不想让所有人都拥有全部权限时，才需要开启。
典型场景：
- 一个客服机器人给全组人用，但你不希望普通客服能让 AI 执行代码或发邮件
- 一个助手机器人给整个部门用，但只有你（管理员）能让 AI 操作文件
开启后的设置流程（四步走）
第一步：打开总开关
单击 Permission Control 旁边的开关滑块，让它变亮。
做完之后你会看到：开关下方展开了一块新区域，出现了一个文本输入框，标题是 Owner User IDs（管理者用户 ID）。
┌────────────────────────────────────────────────────┐
│ Permission Control [──●] │
│ Restrict access by owner/guest roles │
│ │
│ Owner User IDs │
│ ┌──────────────────────────────────────────────┐ │
│ │ e.g. zhangsan, lisi (comma separated) │ │
│ └──────────────────────────────────────────────┘ │
│ Owners have full access. Others are guests. │
│ │
│ ⚠️ No Owner IDs set. All users are treated as │
│ guests and cannot use any tools — chat only. │
│ │
└────────────────────────────────────────────────────┘⚠️ 特别注意那行黄色警告：如果你开了权限控制却没有填 Owner，效果不是「所有人都是老板」，而是恰好相反——所有人都变成了访客，谁都没有权限使用任何工具。机器人只能纯文字聊天，不能调用任何能力。这是很多人踩的第一个坑。
第二步：填写 Owner User IDs（管理者用户 ID）
这里要填的是企业微信里的用户 ID（userid），不是姓名、不是手机号。
怎么查用户 ID：
- 浏览器打开
https://work.weixin.qq.com登录管理后台 - 点击左侧菜单的 通讯录
- 找到你自己（或你想设为 Owner 的人），单击名字
- 在这个人的详情里，找到 帐号（也叫 userid），复制它
把复制好的 userid 粘贴到 Halo 里的 Owner User IDs 输入框中。如果有多个 Owner，用英文逗号隔开：
zhangsan, lisi, wangwu做完之后你会看到：
- 黄色警告消失了
- 下方多出来一个新的开关：Guest Access（访客权限）
┌────────────────────────────────────────────────────┐
│ Owner User IDs │
│ ┌──────────────────────────────────────────────┐ │
│ │ zhangsan, lisi │ │
│ └──────────────────────────────────────────────┘ │
│ Owners have full access. Others are guests. │
│ │
│ Guest Access [●──] │
│ Guests have no access │
└────────────────────────────────────────────────────┘这时候的状态是：
- 你填的那些 userid（zhangsan、lisi）→ 他们是 Owner，拥有全部权限
- 其他所有人 → 他们是 Guest（访客），目前完全没有工具权限（只能纯文字聊天）
如果这就是你想要的效果（Owner 全权限、其他人只能聊天），到这里就配好了。
第三步：开启 Guest Access（可选）
如果你希望访客也能使用部分功能（而不是完全不能用），需要打开 Guest Access 开关。
单击 Guest Access 旁边的滑块，让它变亮。
做完之后你会看到：下方展开了一大块工具选择区域，标题是 Allowed Tools（允许的工具）。
┌────────────────────────────────────────────────────┐
│ Guest Access [──●] │
│ Guests have limited access │
│ │
│ Allowed Tools │
│ │
│ File Read [Read] [Glob] [Grep] │
│ Network [WebFetch] [WebSearch] │
│ Other [Agent] [TodoWrite] │
│ Advanced [Bash] [Write] [Edit] [NotebookEdit] │
│ │
│ ── Halo Capabilities ── │
│ AI Browser [●──] │
│ Email [●──] │
│ Notifications [●──] │
│ Digital Humans [●──] │
│ File Send [●──] │
│ │
└────────────────────────────────────────────────────┘这里面的每个按钮和开关，默认都是关闭/未选中的——也就是说，即使你打开了 Guest Access，如果一个工具都不勾选，访客还是什么都用不了。
第四步：选择给访客开放哪些工具
工具按类型分了四组：
| 分组 | 包含的工具 | 说明 |
|---|---|---|
| File Read（文件读取） | Read、Glob、Grep | 让 AI 能读取文件和搜索文件，但不能修改 |
| Network（网络） | WebFetch、WebSearch | 让 AI 能搜索网页、访问网址 |
| Other（其他） | Agent、TodoWrite | Agent 是多步骤任务分身，TodoWrite 是任务管理 |
| Advanced（高级） | Bash、Write、Edit、NotebookEdit | 让 AI 能执行命令、写文件、改文件——能力很强，风险也高 |
操作方法：想开放哪个工具，就单击那个工具名字的按钮。按钮亮起来（有颜色）= 已选中，灰色 = 未选中。
下方的 Halo Capabilities（Halo 能力）是另一组控制：
| 能力 | 开关含义 |
|---|---|
| AI Browser | 允许访客让 AI 使用浏览器自动化（打开网页、填表等） |
| 允许访客让 AI 代发邮件 | |
| Notifications | 允许访客让 AI 发通知 |
| Digital Humans | 允许访客让 AI 管理数字人 |
| File Send | 允许访客让 AI 通过聊天发送文件 |
⚠️ 安全建议：
- 如果你不确定该开哪些，保守做法是只开 File Read 和 Network。这样访客能让 AI 查资料、搜索信息，但不能修改文件或执行命令。
- Advanced 组里的 Bash、Write、Edit 权限要谨慎开——拥有这些权限的访客可以让 AI 在你电脑上执行任何命令、写任何文件。
- Email 开关要谨慎——开了之后访客可以让 AI 用你的邮箱发邮件。
💡 如果你后来装了额外的 MCP 服务（一种扩展 AI 能力的插件），这个面板下方还会多出来一个 Installed MCP Servers 区域，每个插件都有单独的开关。初次使用不用管这个。
常见问题
Q：改了 Reply Scope / Streaming / Permission 后需要重启吗？
不需要。这些设置都是即时生效的，改了之后下一条消息就会按新设置来处理。和 Bot ID / Secret 一样，Halo 自动保存，不需要手动点保存按钮。
Q：我设置了「仅群聊」，但有人私聊机器人会怎样？
对方发了消息，但不会收到任何回复。消息被机器人直接忽略了，不会转给数字人。
Q：Permission Control 开了又关会怎样？
关闭后，你之前填的 Owner IDs 和勾选的工具配置不会丢失——Halo 只是暂时不启用这些规则。所有人恢复到全权限状态。等你下次再打开开关，之前的配置还在。
Q：Owner 的 userid 填错了会怎样？
填错的 userid 对应不到任何人，相当于没填。如果所有 userid 都填错了，效果等同于没有 Owner——所有人都变成访客（参见上面的黄色警告）。
Q：能不能给不同的人设不同的权限？
目前不能。权限控制只区分两个角色：Owner（全权限）和 Guest（受限权限）。所有 Guest 的权限是一样的。如果你需要更精细的控制，可以考虑多建几个机器人，每个绑不同的数字人，给不同的人群使用。
本章你已经学到了什么
完成 1.1 ~ 1.6 之后：
- 你知道了「机器人 = 传话员」「数字人 = 大脑」的分工
- 你在企业微信后台亲手创建了一个 API 模式的智能机器人，拿到了 Bot ID 和 Secret
- 你把这两串字符填进了 Halo 的「设置 → Message Channels → WeCom Intelligent Bot」卡片
- 你绑定了一个数字人，让它来负责回复消息
- 你打开了开关，看到状态变成绿色 Connected
- 万一遇到 Disconnected，你也知道按什么顺序排查
- 你在企业微信里亲自给机器人发了消息，收到了回复
- 你学会了在群里 @ 机器人来使用它
- 你了解了三个进阶设置：回复范围控制谁能触发机器人、流式输出控制中间过程是否可见、权限控制区分管理者和访客的功能边界
整条链路已经打通。 接下来你可以去第二章学习如何创建和配置数字人——让机器人背后的"大脑"更聪明、更专业。