xiantong 文档
消息

消息集成

从 Telegram、WhatsApp 或 Lark / Feishu 驱动 xiantong 会话

从 Telegram、WhatsApp 或 Lark / Feishu 驱动 xiantong 会话——在任意设备发送消息，并把 Agent 回复带回聊天中。

适合希望从手机与 xiantong 对话、离开桌面后继续一个会话，或从聊天工具触发 Agent 任务的用户。

消息集成可将外部聊天（Telegram 私聊、WhatsApp 联系人或 Lark/Feishu 聊天）绑定到一个 xiantong 会话。您在聊天里发送的消息会驱动 Agent；Agent 输出会渲染回同一个聊天。

支持的平台#

平台连接方式能力
TelegramBotFather 创建的 bot token长轮询或 webhook；支持内联按钮、照片、文档、语音和视频附件
WhatsAppQR 码或配对码基于 Baileys worker；支持文本、媒体附件和 self-chat 模式
Lark / FeishuApp ID + App Secret长连接模式、富文本回复、交互卡片、图片和文件附件

工作方式#

  1. 在设置中启用平台：打开 设置 → 消息，配置 Telegram、WhatsApp 或 Lark/Feishu。每个工作区都有自己的消息配置。
  2. 将聊天绑定到会话：在外部聊天中发送 /new 创建新会话，发送 /bind 选择近期会话，或发送 /pair <code> 使用应用中生成的配对码。
  3. 通过聊天驱动 Agent：绑定后，您输入的内容会转发为 Agent 提示；Agent 回复按响应模式返回聊天。

命令#

任何聊天中，以 / 开头的消息都会被网关视为命令。

命令作用
/new [name]创建新会话并绑定当前聊天，可选名称
/bind列出最多 10 个近期会话
/bind <id>通过会话 ID 或列表序号直接绑定
/pair <code>使用应用中生成的 6 位配对码
/unbind断开当前聊天与会话的绑定
/status显示绑定会话、审批通道与响应模式
/stop中止当前 Agent 运行
/help显示可用命令

绑定是工作区级别的。每个消息绑定都属于一个工作区；同一聊天可在不同工作区绑定不同会话，网关只接受当前工作区产生的命令和配对码。

响应模式#

响应模式控制 Agent 输出如何返回聊天。

模式行为适合场景
progress（默认）每次运行一个持续更新的消息。先显示“thinking…”气泡，工具运行时更新，完成后替换为最终答案大多数用户，保持聊天整洁
streaming最终回合实时编辑，并把中间文本作为独立消息发送需要接近应用内流式体验
final_only运行完成前保持安静，最后发送一条最终答案安静聊天、批处理式工作流

响应模式按绑定配置。同一工作区中，不同聊天可以使用不同模式。

配对码#

当您已在应用中打开某个会话，并希望从手机继续时，可使用配对码：

  1. 在应用中打开会话菜单，选择 配对到消息…。
  2. 复制显示的 6 位代码。
  3. 在外部聊天中发送 /pair 123456（使用真实代码）。
  4. 网关验证后完成绑定。

安全规则：

  • 配对码会在短时间后过期。
  • /pair 按发送者限流，错误尝试也会消耗额度。
  • 配对码只在签发它的工作区内有效。

附件#

Telegram 支持照片、文档、语音、视频和音频。文件会下载到临时位置，并以与应用上传相同的 FileAttachment 形式转发到会话。单个附件上限为 20 MB。

WhatsApp 与 Lark/Feishu 的附件能力类似，但具体 MIME 处理和平台限制请参考各自页面。

审批通道#

当绑定会话处于 请求编辑 权限模式时，Agent 在运行敏感命令前会请求审批。每个绑定的 approvalChannel 决定提示出现在哪里：

值行为
chat审批提示发送到聊天，可在聊天中批准或拒绝（Telegram 支持）
app审批提示仅显示在桌面应用中（WhatsApp 默认且强制）

会话自身的权限模式仍是权威设置；approvalChannel 只决定提示出现在哪里。

计划提交#

当 Agent 在 探索模式 下提交计划时：

  • Telegram 绑定可收到内联按钮用于接受计划。
  • WhatsApp 绑定会收到文字提示，提醒您打开桌面应用查看和批准。
  • Lark/Feishu 可使用交互卡片展示需要操作的按钮。

安全与范围#

  • 按工作区隔离：消息配置、绑定和配对码都属于各自工作区。
  • 计划 token 撤销：计划审批 token 按绑定隔离，重新绑定会让旧 token 失效。
  • 限流：/pair 按发送者限流，入站消息按绑定排队。
  • 聊天范围限制：不同平台对群聊支持不同；Telegram 默认仅支持私聊驱动会话。

配置位置#

消息配置按工作区持久化：

~/.xiantong/workspaces/{workspaceId}/messaging/
 ├── config.json # 平台启用标志
 ├── bindings.json # 聊天 → 会话映射
 └── whatsapp-session/ # Baileys 凭据（仅 WhatsApp）

编辑 bindings.json 后，会在下一条入站消息时生效。删除 whatsapp-session/ 会强制重新配对。

远程服务器#

消息网关也可在独立远程服务器中运行。Telegram 在服务器上使用 webhook 模式，WhatsApp 仍使用 Baileys worker 子进程。部署细节请参考 远程服务器。

上一页API 发现