消息接入

支持的平台#

消息接入让你把一个外部聊天绑定到工作台的某个会话上，之后你在那个聊天里说的话会变成 Agent 的提示，Agent 的输出再渲染回同一个聊天。

如何工作#

整个过程分三步：先在设置里启用平台并填好凭据，再从聊天里发出指令把某个会话绑到这个聊天，最后就可以在聊天里驱动 Agent 了。

• 启用平台：在设置的消息页里配置对应平台，填入机器人令牌、扫码配对或应用凭据。
• 绑定会话：在外部聊天里发送 /new 新建并绑定一个会话，或用 /bind 选择已有会话，也可用 /pair 兑换配对码。
• 聊天驱动 Agent：绑定之后，你在聊天里输入的每条消息都会作为提示转给 Agent，Agent 的回复按你选择的响应模式渲染回来。

Telegram：建机器人、授权发送者并绑定#

1. 在 Telegram 打开官方 @BotFather，发送 /newbot，按提示设置名称及以 bot 结尾的用户名；保存返回的机器人令牌。官方步骤见 BotFather 教程。
2. 在 ZeroWorks 当前工作区打开设置 → 消息接入 → Telegram → 连接。输入令牌，点 Test；显示预期机器人名称后点 Save。当前适配器以长轮询接收，不需要公网 Webhook。
3. 新工作区默认 owner-only。先打开桌面上的目标会话，通过会话菜单生成 Telegram 配对码，再在与机器人的私聊中发送 /pair <配对码>。首次成功兑换会把你的 Telegram user_id 记录为首位 owner。
4. 配对成功后先发送 /status，再提出一条只读问题。已有 owner 后可用 /new 创建新会话，或用 /bind 选择近期会话。
5. 其他人请求访问后，到设置 → 消息接入的待处理请求中审查并允许。绑定可继承工作区策略、设自定义 allow-list，或显式开放；绑定拒绝产生的允许操作只扩展该绑定，不等于新增全局 owner。

• 旧工作区可能保留 open：检查访问提示，需要时执行 Lock down；不能假定升级后已经收紧。
• 默认从私聊开始。只有在 Telegram 设置中明确配对的论坛超级群才接受群话题；仅把机器人拉入普通群、频道或关闭 BotFather privacy 都不够。
• Test 返回 401：在 BotFather 核对或轮换令牌，然后重新 Test → Save。机器人不回复：查当前工作区、桌面在线状态、owner/allow-list 和 /status。
• 轮询冲突时，停止其他使用同一机器人令牌的进程，并检查是否遗留外部 Webhook；不要同时启动多个接收器。

Lark / 飞书：应用、权限、长连接与发布#

1. 按账号地区进入 Lark 开放平台 或 飞书开放平台，创建企业自建应用并启用机器人。两套平台的凭据不能互换。若看到 Built for agents 创建入口，可用其预设，但仍检查权限和事件。
2. 在权限管理启用 im:message、im:message.group_at_msg、im:message:send_as_bot。附件下载或交互能力报权限错误时，按平台返回的 scope 提示补齐对应权限并重新发布。
3. 在事件与回调中选择长连接接收事件，订阅 im.message.receive_v1；需要卡片按钮时同时检查 card.action.trigger 回调配置。长连接路径无需公网 URL，Encrypt Key 留空。
4. 创建并发布应用版本，或在允许的测试租户中启用。确认目标成员在应用可用范围内，不能只保存草稿配置。
5. 在 ZeroWorks 设置 → 消息接入 → Lark / 飞书 → 连接选择正确地区，填 App ID 与 App Secret，依次 Test → Save。Test 取得 tenant_access_token 只验证凭据；Save 后才启动长连接。
6. 在平台找到机器人并私聊；从桌面会话菜单生成 Lark 配对码，发送 /pair <配对码>，再发送 /status 和只读问题。群里先邀请机器人并 @它。

• 收不到消息：检查发布状态、长连接模式、im.message.receive_v1 和 im:message；群消息还要检查 @提及和 group_at_msg 权限。
• 卡片显示但点按无响应：检查应用发布与卡片回调；Test 成功不会验证卡片事件。
• 密钥重置或租户改变后重做 Test → Save。图片和文件支持每个 20 MB；音视频与贴纸当前不接收。

WhatsApp：扫码、自聊与重新连接#

1. 在 ZeroWorks 设置 → 消息接入 → WhatsApp → 连接打开二维码。手机进入 WhatsApp 设置 → 已关联设备 → 关联设备，扫描桌面二维码；等桌面显示已连接。
2. 新连接默认启用 self-chat。在手机打开「给自己发消息」，先发送 /new，或用桌面会话生成的 /pair <配对码> 绑定已有会话；用 /status 确认目标。
3. 发送只读问题，回复的 🤖 前缀用于区分机器人输出并避免自我回声循环。不要把带此前缀的回复删掉标记后重发成新提示。
4. 需要他人聊天驱动时，先检查工作区及绑定的访问策略，再让对方向已配对号码发命令；测试使用独立联系人与自聊是两条路径。
5. 出现权限请求、凭据输入或计划审批时，在桌面打开绑定会话完成；手机文字回复不能代替批准。

• 二维码不成功：确认扫码手机在线且 WhatsApp 已更新，等待连接状态；二维码过期时重新打开连接对话框。
• 普通掉线先保持网络并查看重连结果；若设备被撤销或登录失效，在消息设置的菜单点 Disconnect，再 Connect 重新扫码。Disconnect 会清除设备凭据，不只是隐藏窗口。
• 设备会话被撤销后重新配对不会替你重建丢失的绑定；先 /status，需要时 /bind 或 /pair 恢复目标。自聊身份变化或 LID/JID 不匹配时 /unbind 后重新绑定。
• 手机看到回复而另一设备未同步时打开那台设备的 WhatsApp 等待同步。桌面退出或被强制结束时不能承诺未发出的回复仍会送达。

命令#

聊天里以斜杠开头的消息会被当作命令处理，用来管理绑定关系与运行状态。

响应模式#

响应模式按每条绑定保存，改变的是输出时机与消息更新方式，不会要求模型把内容缩短。当前默认值为 progress。

配对码#

不想在聊天里翻会话列表时，可以从工作台会话菜单里生成一个 6 位配对码，然后在聊天里用 /pair 兑换完成绑定。

配对码是一次性的，用过即失效；它是把「你在应用里的那个会话」和「手机上的那个聊天」安全对上的凭据。

在会话菜单选择消息配对和目标平台，把命令 /pair <配对码> 发到对应机器人或自聊。配对码有效期为 5 分钟、一次性使用，并绑定当前工作区；过期后回桌面重新生成。

附件#

Telegram 与 WhatsApp 可转发图片、文档、语音、音频和视频；Lark / 飞书当前适配器接收图片与文件，不把音视频或贴纸视为已支持附件。附件下载上限为每个 20 MB。

文件会进入绑定会话，但模型是否能直接理解某种音视频格式取决于模型和工具。超出上限时拆分文件或改从已授权的来源读取。

审批通道#

审批位置与会话权限模式是两回事：消息接入不会替你提高会话权限。Telegram 与 Lark / 飞书支持按钮审批；WhatsApp 的 approvalChannel 始终强制为 app。

• Telegram / Lark：当命令审批通道为 chat 时，可在请求消息的允许或拒绝按钮上操作；选择 app 则回桌面审批。
• Telegram / Lark：提交计划可显示计划内容与接受按钮；较长计划可能作为附件发送。只有仍有效、符合发送者访问策略的按钮才能完成审批。
• WhatsApp：命令请求只发送「回桌面批准」提示；计划只发送「回桌面查看和批准」提示。聊天内没有 /accept、文字确认或按钮批准路径。凭据输入也要回桌面。
• 在桌面打开绑定会话，查看具体命令或计划，再批准或拒绝；没有有效批准时任务保持等待或按超时流程失败，不会默认放行。

安全与范围#

消息接入会让外部聊天里的输入直接驱动 Agent，因此需要明确它的边界。

• 普通提示需要有效绑定；创建、切换和驱动会话还要通过发送者访问策略。群聊中的其他成员能否读取机器人回复，由平台群成员范围决定。
• 消息在绑定工作区及会话的凭据和权限下执行；平台账号通过访问检查，并不代表获得了产品 SSO 账号的权限映射。
• 建议为消息接入单独使用权限更严格的工作区，避免外部消息触发高权限动作。
• 解除绑定后，该聊天发出的消息不再驱动任何会话。

配置位置#

消息接入的配置按工作区保存，因此每个工作区可以绑定不同的平台、不同的聊天与不同的会话，互不干扰。

平台凭据通过桌面连接对话框保存；WhatsApp 设备会话保存在 ~/.zero-works/workspaces/{工作区目录名}/messaging/whatsapp-session/。不要把该目录当普通文档分享，删除它会要求重新扫码。