16. 外部 IM 工具
完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。
本章内容：本章面向负责企业消息集成的管理员、智能体编辑者和通过 IM 使用智能体的成员。IM 工具把钉钉、飞书、企业微信等企业消息渠道连接到智能体，成员在原消息渠道中发消息，智能体在同一渠道回复。读完本章，你可以开放可用的频道、创建并测试 IM 工具连接、把它绑定到智能体、绑定自己的 IM 身份，并处理常见故障。
16.1 入口与职责
适用场景：确定一项 IM 相关操作应该在哪里完成、由谁完成。
你会看到
| 入口 | 用途 | 操作人 |
|---|---|---|
| :-- | :-- | :-- |
| 「管理后台 › 智能体 › 频道管理」 | 决定哪些频道可用，并分发给部门、成员或职能组 | 管理员 |
| 「个人设置 › IM 工具」 | 创建并维护 IM 工具连接（机器人应用的凭据） | 集成负责人、智能体编辑者 |
| 智能体详情「智能体」页签的 IM 工具区域 | 把 IM 工具连接绑定到智能体，设置该智能体的 IM 行为 | 智能体编辑者 |
| 「个人设置 › 渠道绑定」 | 把自己的 IM 账号身份绑定到平台账号 | 每位成员 |
| 智能体列表的「IM 工具」列 | 查看每个智能体已接入的 IM 工具 | 所有可见成员 |
注意：向成员开放前，先完成连接测试和真实消息收发。
16.2 支持的渠道
适用场景：确认业务需要的消息渠道是否可以接入。
你会看到
页面中可选的渠道包括「钉钉」「飞书 — 长连接 (Feishu/Lark)」「企业微信」「微信（个人）」「Slack」「Discord」「Telegram」「WhatsApp」「Microsoft Teams」「LINE」「Signal」「Matrix」。企业微信在同一张卡片中区分自建应用和「企业微信（智能机器人）」两种接入方式。
注意：实际可选的渠道以页面显示为准，取决于部署版本和管理员在频道管理中的开放情况。飞书只支持长连接方式，只需要 App ID 和应用密钥，不需要公网回调地址。使用前分别验证业务需要的文本、图片、文件、卡片、群聊和回复效果。
16.3 管理员开放频道
适用场景：管理员控制企业内可以使用哪些 IM 频道、谁可以使用。
前提：具备管理后台访问权限。
操作步骤
- 进入「管理后台 › 智能体 › 频道管理」。
- 用「搜索」查找频道，或按状态筛选。列表列为「频道」「客户端应用」「群聊」「启用与分发」「可用性」。
- 打开某个频道的「可用性」开关。
- 在「启用与分发」中选择「添加分发目标」，选择分发范围（「所有用户」「组织部门」「职能组」「成员」或「工作空间」）和生效方式（「打开频道」或「关闭频道」），按需设置有效期，选择「保存分发」。
你会看到
- 「客户端应用」列显示「需要」时，表示接入该频道需要先在渠道侧创建客户端应用（如钉钉 AppKey）。
- 「群聊」列显示「支持」时，表示该频道可在群聊中使用。
- 标注「默认启用」的频道无需分发，默认对全体成员可用；其余频道须先开启可用性，再分发给部门或成员。
- 保存后提示「频道治理已更新」。
注意：分发到部门时，页面会预估影响人数，影响较大时需要再次确认。分发规则的通用说明见第 7 章。
16.4 创建 IM 工具连接
适用场景：为企业的钉钉、飞书或其他机器人应用在平台上建立连接。
前提：已在渠道侧创建机器人应用并拿到凭据；该频道已对你开放。
操作步骤
- 在工作台进入「个人设置 › IM 工具」（页面说明为「创建并维护 IM 工具连接」）。
- 新建连接并选择渠道类型。钉钉和飞书可以选择「扫码创建」，用对应 App 扫码后自动创建机器人连接；其他渠道按页面要求填写字段，例如钉钉的「Client ID (AppKey)」「Client Secret (AppSecret)」，飞书的「App ID」「应用密钥」，企业微信智能机器人的「BotID」「BotSecret」，Slack 的「机器人令牌 (xoxb-...)」等。
- 保存后选择「测试连通性」，确认提示「IM 工具连通正常。」
- 不再使用时删除连接。删除前确认提示：凭据一并删除，绑定它的智能体将无法再通过它收发消息。
你会看到
- 扫码创建成功后提示「钉钉机器人连接已创建。」或「飞书机器人连接已创建。」
- 更新连接后提示「IM 工具已更新」。
注意：令牌和密钥只填写在对应的敏感字段中，不要写进名称或描述。一个连接可以被多个智能体复用。
16.5 把 IM 工具绑定到智能体
适用场景：让某个智能体通过指定的 IM 渠道接收和回复消息。
前提：对智能体具有编辑权限。
操作步骤
- 展开「自定义此智能体的 IM 工具行为」，按需设置运行参数（见第 16.6 节）。
- 选择「测试连通性」，再「确认」。
- 用测试账号在 IM 中给机器人发消息，确认能收到回复。
你会看到
- 保存时页面提示「正在应用 IM 工具配置并验证就绪状态…」，结果为「IM 工具已就绪。」「IM 工具配置已保存，但就绪检查失败：原因」或「IM 工具配置已保存，待智能体启动后会再次执行就绪检查。」
- IM 工具卡片显示「状态」，以及「最近一次消息」「令牌过期时间」「24h 失败」等健康数据。
- 不再需要时选择「解绑」，确认「确定要将该 IM 工具从智能体解绑吗？」
注意：没有编辑权限的成员看到的 IM 工具卡片为「仅查看」。智能体接入面向外部用户的 IM 工具后，对话访问权限切换到「完全访问」需要再次确认（见第 14.6 节）。
16.6 常用运行参数
适用场景：调整智能体在 IM 中的回复方式，例如只在被 @ 时回复群消息。
你会看到
| 参数 | 说明 |
|---|---|
| :-- | :-- |
| 「私聊策略」 | 「开放（任何人可私聊）」「配对模式（首次联系需确认）」或「白名单」 |
| 「群聊策略」 | 「开放（open）」「白名单（allowlist）」或「关闭（off）」 |
| 「回复所有群消息」 | 关闭时仅在群中被 @ 才回复，开启则回复所有群消息 |
| 「群会话范围」 | 「按群」共享一个会话，或「按群 + 发送者」区分每个人 |
| 「消息类型」 | 「Markdown（默认）」「纯文本」「Markdown 卡片」或「AI 卡片」；钉钉 AI 卡片需要填写「卡片模板 ID」 |
| 「卡片流式模式」 | 「关闭（off）」最稳定、调用最少；「仅答案流式（answer）」「全量流式（all）」更实时但调用更多 |
| 「处理中反馈」 | 处理开始时对用户原消息添加表情反馈，处理结束后自动撤回 |
| 「异步模式（群聊推荐开启）」 | 先回复「异步回复文案」，处理完成后再发送结果 |
| 「显示名解析」 | 开启后可能有误投与权限扩散风险，敏感场景保持关闭 |
注意：可用参数随渠道不同，以绑定对话框中显示的字段为准。「调试日志」「发送链路绕过代理」只在排障时开启。
16.7 绑定个人微信
适用场景：用个人微信与智能体对话，适合低频的客服或通知场景。
操作步骤
- 在 IM 工具区域选择「配置个人微信」，阅读「个人微信绑定合规告知」，逐项勾选确认后选择「继续绑定」。
- 页面显示二维码和倒计时，用微信扫码登录；二维码失效时选择「刷新二维码」。
- 显示「登录成功」后选择「完成」。
你会看到
- 微信会话过期时，卡片显示「微信会话已过期，请重新绑定以继续接收消息。」，选择「重新绑定」或「换绑微信」。
注意：个人微信处于实验性阶段。合规告知中说明：使用频率与封号风险由微信平台决定；不得用于群发、营销、骚扰等高风险用途；所有进出消息内容会保留 90 天用于运维与审计。
16.8 绑定我的 IM 身份
适用场景：让平台识别你在 IM 中的身份，以便按你的权限回复、把定时任务结果私聊发给你。
操作步骤
- 在 IM 中给机器人发消息，按提示获取绑定短码。
- 在工作台进入「个人设置 › 渠道绑定」，选择「绑定」。
- 输入「短码」（例如 A8K-3X9P），选择「预览」，核对身份信息后选择「确认绑定」。
- 在「我的 IM 身份」列表中查看已绑定的身份（列为「IM 工具」「身份标识」），不再需要时选择「解绑」。
你会看到
- 绑定成功提示「IM 身份已绑定」。
- 短码无效时提示「短码不存在或不可用于当前工作空间」「短码已过期」或「短码已被使用」。
注意：机器人提示短码的方式以实际界面为准。解绑后，这个 IM 身份不再映射到当前账号。
16.9 定时任务结果推送到 IM
适用场景：让智能体按计划把结果发到钉钉私聊或群。
操作步骤
注意：发送目标失效时，任务卡片提示「发送目标需要确认 — 请打开编辑器选择目标。」
16.10 常见故障
| 问题 | 处理方式 |
|---|---|
| :-- | :-- |
| 收不到消息 | 在 IM 工具卡片查看「最近一次消息」和「24h 失败」；用「测试连通性」检查凭据；确认频道已开放、智能体处于运行中 |
| 能收到但不回复 | 检查智能体状态和所选模型；检查私聊策略、群聊策略和「回复所有群消息」设置 |
| 群里没有响应 | 默认只在被 @ 时回复；确认群聊策略不是「关闭」 |
| 就绪检查失败 | 按提示中的原因修正凭据；智能体未运行时，启动后会再次检查 |
| 令牌即将过期 | 查看「令牌过期时间」，在渠道侧更新后到「个人设置 › IM 工具」更新连接 |
| 微信不再收消息 | 微信会话过期，选择「重新绑定」 |
| 消息格式显示异常 | 调整「消息类型」，钉钉 AI 卡片需正确的卡片模板 ID |
| 工具确认无法在 IM 中处理 | 回到网页对话处理确认卡（第 14.7 节） |
能力说明
| 不提供的能力 | 替代做法 |
|---|---|
| :-- | :-- |
| 由外部系统通过 HTTP Webhook 直接触发智能体任务 | 用定时任务按计划执行（第 15.7 节），或把智能体发布为 A2A 服务供外部系统调用（第 17 章） |
| 飞书事件订阅（回调）模式 | 使用「飞书 — 长连接」方式接入，无需公网回调地址 |
| 在管理后台为成员代建 IM 工具连接 | 由集成负责人在「个人设置 › IM 工具」创建，智能体编辑者绑定时选择「选择已有」或「复用绑定」 |
---