A local-first multi-agent app development platform, built on PenguinHarness
title: 远程控制 description: 把对话连接到飞书、Telegram、QQ 或微信机器人,在聊天应用里直接和 Agent 对话。
远程控制把一个对话连接到飞书、Telegram、QQ 或微信上的机器人。发给机器人的消息会进入这个对话,效果和在 Web App 里输入完全一样;Agent 的回复也会发回聊天里。连接由 Adelie 主动向消息平台发起,所以不需要公网地址或回调 URL。
开始之前
- 对话已经开始。 远程控制属于某个对话,而对话要在发出第一条消息后才存在。新建但还没发消息的对话里,面板会显示「发送第一条消息后可用」。
- 你是 Project owner。 只有 owner 能保存凭证、扫码,以及开启或关闭连接。其他成员可以打开设置、查看状态和运行测试。
- Adelie 正在运行。 连接运行在 Adelie 服务端或桌面应用里,它们停止运行时,机器人不会应答。
打开远程控制
远程控制有两个入口:侧边栏里对话的菜单,以及对话页旁边的右侧栏面板。两处的设置完全相同。
打开对话框
- 在侧边栏中右键点击对话。也可以把鼠标悬停在对话上,选择更多(「…」按钮),或者按 Shift+F10,在触屏上则长按这一行。
- 选择远程控制,打开远程控制对话框。
公司模式下,工位对话的菜单里同样有远程控制。
打开右侧栏面板
以下方式任选其一:
- 在对话页右上角选择右侧栏,再选择远程控制。
- 在右侧栏里选择添加面板(+),再选择远程控制。
- 点开悬浮的快捷方式按钮,选择纸飞机图标的远程控制。
远程控制设置
设置从上到下依次为:
| 设置 | 作用 |
|---|---|
| 渠道标签页 | 对话框顶部的飞书、Telegram、QQ 和微信。每个渠道在这个对话里单独保存自己的设置。 |
| 启用连接 | 开启或关闭连接。开启即把机器人绑定到这个对话,关闭即解除绑定。无论开关,已保存的凭证都会保留。 |
| 连接状态 | 未连接、连接中、已连接或连接错误,同时显示最近一条消息的到达时间,以及最近一次连接或投递问题。状态会自动刷新。 |
| 测试连接 | 检查已保存或刚填写的凭证能否登录,并显示响应时间。 |
| 发送测试消息 | 向聊天发送一条简短的测试消息。机器人已连接、并且至少收到过一条消息后才能使用。 |
| 渠道字段 | 所选渠道的凭证,见各渠道的小节:飞书、Telegram、QQ 或微信。 |
| 只发送最终回复 | 默认关闭,见投递选项。 |
| 每行一条消息 | 默认关闭,见投递选项。 |
| 渲染 Markdown | 默认开启,见投递选项。 |
| 保存 | 保存凭证和投递选项。保存不会开启或关闭连接。 |
表单下方有三个折叠区块,讲解所选渠道:如何创建机器人(包括设置步骤和前往教程链接)、绑定后会发生什么和常见问题。
启用连接开关置灰时,测试按钮下方会写明原因:凭证还没保存、表单有未保存的修改,或者这个对话已经启用了另一个渠道。点击置灰的开关,也会提示还差哪一步(扫码、填写凭证、保存,或先停用另一个渠道);前三种情况还会把焦点移到要操作的地方。
已保存的密钥不会再显示出来。字段留空即保留原密钥。要删除密钥,先关闭连接,再勾选字段下方的清除选项,例如 清除已存 App Secret 或 清除已存 Bot Token,然后选择保存。
连接飞书
开始之前
- 一个能在开发者后台创建企业自建应用的飞书或 Lark 账号。
- 在飞书开发者后台创建一个企业自建应用。
- 为应用开通机器人能力。
- 订阅「接收消息」事件,事件订阅方式选择「长连接」。
- 在 Adelie 中打开这个对话的远程控制,选择飞书标签页。
- 在应用的「凭证与基础信息」页取得 App ID 和 App Secret,分别填入 App ID 和 App Secret。
- 如果用的是 Lark,把 API 域名改为
https://open.larksuite.com。默认值https://open.feishu.cn对应飞书。 - 选择保存。
- 在开发者后台发布应用版本,并通过审核。
- 打开启用连接,等状态变为已连接。
- 在飞书里给机器人发一条消息。
机器人在单聊和群聊中都能用。消息开头 @ 了机器人时,这段 @ 会在消息送达 Agent 之前去掉。
要接收图片和文件,飞书应用除了接收消息的权限,还需要读取消息资源的权限。缺少这项权限时,机器人会回复需要开通的权限,并附上开发者后台的链接。
连接 Telegram
开始之前
- 一个 Telegram 账号。
- 在 Telegram 中打开 @BotFather,发送
/newbot创建机器人。 - 按提示给机器人取名,复制 @BotFather 返回的 Bot Token。
- 在 Adelie 中打开这个对话的远程控制,选择 Telegram 标签页。
- 把 Token 粘贴到 Bot Token。Bot Token 形如
<digits>:<secret>。 - 选择保存。
- 打开启用连接,等状态变为已连接。
- 在 Telegram 中找到这个机器人,给它发一条消息。
测试连接会显示这个 Token 登录的是哪个机器人。如果机器人开启了 Group Privacy,测试结果还会提醒:在它不担任管理员的群里,它收不到普通消息。解决办法见常见问题。
在开启了话题的群组里,回复会留在消息所在的话题中。Telegram 频道的贴文不受支持,机器人只处理群聊和单聊。
一个 Bot Token 同一时刻只能供一个程序使用。连接开启期间,不要在另一个 Adelie 服务端或机器人脚本里使用同一个 Token。
连接 QQ
开始之前
- 一个 QQ 开放平台上的机器人。需要先在平台注册成为开发者,才能创建机器人。
- 机器人的「开发配置」里,事件订阅方式已设为 WebSocket,回调地址留空。
- 你自己的 QQ 号或某个测试群已经加入机器人的沙箱白名单。
机器人的凭证可以扫码交给 Adelie,也可以手动填写。
扫码连接
- 在 Adelie 中打开这个对话的远程控制,选择 QQ 标签页。
- 选择扫码连接。
- 用手机 QQ 扫描二维码。
- 在打开的页面里选择要授权的机器人并确认。Adelie 会保存凭证,并显示「已保存机器人 {appId} 的凭据,可以启用连接了」。
- 打开启用连接,等状态变为已连接。
- 在 QQ 中找到这个机器人,给它发一条消息。
手动填写凭证
- 在 QQ 开放平台机器人的「开发设置」页,复制 App ID 和 App Secret。
- 在 Adelie 中打开远程控制,选择 QQ 标签页,在或手动填写下方填入 App ID 和 App Secret。
- 选择保存。
- 打开启用连接,等状态变为已连接。
- 在 QQ 中找到这个机器人,给它发一条消息。
[!WARNING] QQ 只允许机器人回复你刚发给它的消息,不允许机器人主动发消息。
这条规则决定了 QQ 渠道的表现:
- 在 Web App 里发起的对话不会同步到 QQ。
- 距离你上一条 QQ 消息过去几分钟后,回复就发不出去了。想继续,在 QQ 里再给机器人发一条消息即可。
- 一条 QQ 消息最多能收到 4 条回复,群聊里是 5 条。一次运行产生的消息超出这个数量时,余下的内容会合并到最后一条回复里。
- 开启只发送最终回复时,运行超过约五分钟就一条也发不出去。
- QQ 只支持文本。机器人不读取你发送的图片和文件,Agent 也不能向 QQ 发送文件。
连接微信
微信通过官方的机器人通道连接。不需要后台,也不用注册:扫码之后,凭证会自动保存。
- 在 Adelie 中打开这个对话的远程控制,选择微信标签页。
- 选择扫码连接,生成二维码。
- 用手机微信扫描二维码。
- 如果手机上显示了一组数字,把它填入配对码,然后选择确认。
- 在手机上确认授权。Adelie 会保存凭证,并显示「已保存机器人 {botId} 的凭据,可以启用连接了」。
- 打开启用连接,等状态变为已连接。
- 等待约 15 秒。
- 在微信里找到这个机器人,给它发一条消息。如果没有收到回复,再发一次。
[!NOTE] 状态刚变为已连接时,连接会先清掉此前积压的消息,这最初几秒里到达的消息也会一并清掉,得不到回复。每次开启连接或服务端重启后,都会再经历一次。
二维码在扫描前过期时,会自动换成新的。以后要绑定别的微信账号,先关闭连接,再选择重新扫码。
微信和其他渠道有这些不同:
- 机器人只接收单聊。在群里 @ 它不会有任何反应。
- 文本、图片和文件都能双向传输。
- 语音消息按微信自带的语音转文字结果送达;微信没能转写的语音无法读取。视频以文件形式送达。
连接之后
已连接的对话会在侧边栏的条目上显示一个纸飞机图标。鼠标指向图标,可以看到启用的是哪个渠道,例如「Telegram 连接已启用」。
发给机器人的消息
- 发给机器人的消息会在对话里启动一个 Task,和在 Web App 里输入的消息一样。Agent 不会知道这条消息来自聊天应用。
- Agent 正忙时,消息会先排队,等轮到它再运行。
- 在飞书、Telegram 和微信上,你发送的图片和文件会以附件形式随消息进入对话。每张图片最大 20 MB,同一个连接每 10 分钟最多接收 40 MB 图片。文件遵循设置里的上传限制;Telegram 另外把机器人能下载的文件限制在 20 MB。
- 不支持贴纸,飞书和 Telegram 上的语音、视频消息也不支持。遇到这些消息,机器人会回复「目前仅支持文本、图片和文件消息。」
- 在飞书、Telegram 和微信上,连接关闭期间发给机器人的消息,之后也不会补发。
机器人发出的回复
- 除非开启了只发送最终回复,否则每条助手消息一完成就发到聊天里。回复会发往最近一次给机器人发消息的聊天,所以机器人收到第一条消息之前,什么都不会发送。
- 在 Web App 里发起的对话也会同步到聊天,QQ 除外。
- 在群聊里,一次运行的第一条回复会引用触发这次运行的那条消息。
- 过长的回复会拆成多条消息,每条不超过 4000 个字符。
- 如果回复提到了本次运行在 Workspace 里创建或修改的文件,这些文件会跟着回复发到聊天里。一次运行最多发送 5 个文件,图片不超过 10 MB,其他文件不超过 30 MB。有文件没发出去时不会在聊天里说明,而是记入成本中心的异常记录。
审批
工具审批不能在聊天里完成。有工具调用等待审批时,机器人会发送「有工具调用正在等待你在网页端审批。」请到 Web App 里批准或拒绝。
工具调用要不要审批,取决于对话的审批模式。新对话默认是全部放行,什么都不询问,所以把机器人绑定到这样的对话之前,先读安全。
聊天里不支持命令。/stop 这样的文本也会当成普通消息发给 Agent。
投递选项
| 选项 | 默认 | 效果 |
|---|---|---|
| 只发送最终回复 | 关 | 运行结束时,只发送助手在这次运行中说的最后一段话。工具调用之间写下的过程记录留在 Web App 里,长时间运行期间聊天里一片安静。审批提醒仍会立即送达。 |
| 每行一条消息 | 关 | 回复的每个非空行各发一条消息,每条间隔一秒。一条回复最多拆成 20 条消息(QQ 以它的回复上限为准),余下的行合并成最后一条。 |
| 渲染 Markdown | 开 | 在聊天应用里把标题、粗体、列表、代码和表格显示为排版格式,具体取决于应用支持到什么程度。应用拒绝这种排版时,回复改以纯文本发送。 |
修改选项后,选择保存。这些选项对测试消息和审批提醒之类的通知不起作用。
各应用对 Markdown 的支持:
| 渠道 | 能显示的格式 |
|---|---|
| 飞书 | 以卡片显示标题、粗体、斜体、删除线、代码、代码块、列表、引用、分割线、链接和表格。超过五行的表格以代码块发送。 |
| Telegram | 粗体、斜体、删除线、链接、行内代码和代码块。标题变成一行粗体,列表符号保留为文本,表格以代码块发送。 |
| 标题、粗体、斜体、删除线、列表、引用、分割线和链接。代码块按普通文本行发送,表格按行发送。改以纯文本重发时,会多占用一条 QQ 允许的回复。 | |
| 微信 | 标题、粗体、删除线、列表、引用、分割线、链接、行内代码、代码块和表格。五级以下的标题、中文两侧的斜体和行内图片会失去格式,图片改为链接。 |
限制
- 一个对话只能启用一个渠道。 一个对话可以保存全部四个渠道的设置,但同一时刻只能启用其中一个。
- 一个机器人只能在一个对话里启用。 同一个机器人可以保存在多个对话里,但它的连接只能在其中一个对话里启用。要换到别的对话,先在原对话关闭连接,再到新对话开启,不必删除凭证。
- QQ 只能被动回复。 见连接 QQ。
- 微信只支持单聊。 见连接微信。
- 删除对话时,它的远程控制设置会一并删除。
安全
[!WARNING] 远程控制没有发送者白名单。任何能给机器人发消息的人都能操控这个对话:他们可以发起 Task,Agent 会按这个对话的审批模式替他们运行工具。
不要公开机器人:别把它拉进有你不信任的人的群,并选用在有风险的工具调用前先询问的审批模式。
凭证保存在服务端,不会完整地发回浏览器。扫码连接时,密钥同样只留在服务端。
常见问题
发送测试消息不可用。 机器人要先收到一条消息,才知道该发到哪个聊天。先在聊天应用里给它发一条消息,再试一次。
状态显示连接错误。 检查凭证。如果是飞书,还要检查 API 域名,并确认事件订阅方式是长连接。
同一会话只能启用一个渠道。 先在这个对话里关闭另一个渠道的连接。
该机器人的连接已在另一个会话中启用。 先到那个对话里关闭连接,再在这里启用。
Telegram:机器人不理会群里的消息。 Telegram 的 Group Privacy 默认开启。开启时,不担任群管理员的机器人只能收到明确发给它的命令,以及对它自己消息的回复。解决办法有两个:把机器人设为这个群的管理员;或者在 @BotFather 里用 /setprivacy 关闭 Group Privacy,再把机器人移出群、重新拉进来。机器人已经在的群,不做这一步就不会应用隐私设置的变更。
Telegram:提示有其他程序在轮询。 一个 Bot Token 同一时刻只能供一个程序使用。关掉正在用这个 Token 的另一个 Adelie 服务端或脚本,或者给这个对话单独建一个机器人。手动调用 getUpdates 也算另一个程序,调用之前先关闭连接。
Telegram:面板显示还没有收到过消息。 这一行只统计当前这条连接。关闭再开启连接,或者再保存一次凭证,都会开启一条新连接。先重新发一条消息。如果仍然显示没有收到,检查机器人是否还在群里,以及有没有别的程序在轮询这个 Token。
QQ:收不到回复了。 回复窗口已经关闭。在 QQ 里再给机器人发一条消息。
微信:机器人在群里没有反应。 微信渠道只接收单聊,请直接私聊机器人。
微信:第一条消息没有回复。 状态变为已连接后的最初几秒里,连接会清掉收到的消息。等约 15 秒,再重新发送。