主题

频道（IM） ​

频道配置让您可以将 Sage Agent 连接到第三方即时通讯平台，实现跨平台的智能对话。目前支持飞书、钉钉和 iMessage（macOS 专属）三种渠道。

访问频道配置 ​

点击左侧导航栏的「个人中心」，在展开的菜单中选择「频道」，即可进入 IM 频道配置页面。

支持的频道 ​

Sage 目前支持以下 IM 平台：

  • 飞书（Lark）- 通过飞书机器人与用户对话
  • 钉钉（DingTalk）- 通过钉钉机器人与用户对话
  • iMessage - 通过 macOS 信息应用与用户对话（仅限 macOS）

通用配置说明 ​

所有频道都包含以下通用配置项：

配置项说明
启用是否激活该频道
机器人前缀机器人回复消息的前缀标识，如 [BOT]
过滤工具消息是否隐藏工具调用和输出详情

飞书配置 ​

飞书配置

飞书频道通过 WebSocket 长连接接收消息，无需公网 IP 或 Webhook；发送消息走飞书开放平台 Open API。支持文本、图片、文件收发。

配置参数 ​

参数说明
App ID飞书应用的 App ID
App Secret飞书应用的 App Secret

获取凭证步骤 ​

1. 创建企业自建应用 ​

打开 飞书开放平台，点击「创建企业自建应用」。

创建企业自建应用

填写应用名称和描述，点击「创建」完成应用创建。

填写应用信息

2. 获取凭证信息 ​

在「凭证与基础信息」页面获取 App ID 和 App Secret。

凭证与基础信息

安全提示

App Secret 只会显示一次，请妥善保存。如果遗失，需要重新生成。

3. 启用机器人能力 ​

在「能力」页面中，点击「添加应用能力」，选择「机器人」。

添加应用能力

启用后，机器人就可以接收和发送消息了。

4. 配置权限 ​

在「权限管理」中，点击「批量导入/导出权限」，添加以下机器人相关权限：

json
{
  "scopes": {
    "tenant": [
      "im:chat",
      "im:message",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:resource",
      "contact:user.base:readonly"
    ],
    "user": []
  }
}

权限管理

权限说明：

  • im:chat - 获取与更新群组信息
  • im:message - 获取与发送单聊、群组消息
  • im:message.group_msg - 获取群组中所有消息
  • im:message.p2p_msg:readonly - 读取用户发给机器人的单聊消息
  • im:resource - 获取与上传图片或文件资源
  • contact:user.base:readonly - 以应用身份读取通讯录（用于显示用户昵称）

5. 配置事件订阅 ​

在「事件与回调」页面：

  1. 选择订阅方式为「长连接（WebSocket）」模式
  2. 点击「添加事件」
  3. 搜索并订阅「接收消息 v2.0」

操作顺序

必须先配置 App ID/Secret → 保存 Sage 配置 → 再在开放平台配置长连接。如果显示错误，尝试重启 Sage 服务。

6. 发布应用 ​

在「应用发布」的「版本管理与发布」中：

  1. 点击「创建版本」
  2. 填写版本号和更新说明
  3. 点击「保存并发布」

7. 填写 Sage 配置 ​

将获取的 App ID 和 App Secret 填入 Sage 的飞书配置页面，启用频道并保存。

飞书配置

使用说明 ​

  • 在飞书中搜索创建的机器人名称
  • 与机器人单聊或将其添加到群聊中
  • 群聊场景下会将 chat_id、message_id 放入请求消息的 metadata，便于上下文识别

钉钉配置 ​

钉钉配置

钉钉频道通过 Stream 模式（流式接收）接收消息，支持文本、图片、文件收发。

配置参数 ​

参数说明
Client ID钉钉应用的 Client ID（即 AppKey）
Client Secret钉钉应用的 Client Secret（即 AppSecret）

获取凭证步骤 ​

  1. 创建钉钉应用

    • 打开 钉钉开发者后台
    • 进入「应用开发 → 企业内部应用 → 钉钉应用 → 创建应用」

  2. 添加机器人能力

    • 在「应用能力 → 添加应用能力」中添加「机器人」
    • 配置机器人基础信息
    • 设置消息接收模式为 Stream 模式（流式接收）
    • 点击发布

  3. 获取凭证信息

    • 在「基础信息 → 凭证与基础信息」中获取：
      • Client ID（即 AppKey）
      • Client Secret（即 AppSecret）

  4. 配置服务器 IP 白名单（可选）

    • 如需下载用户发送的图片和文件，需将服务器 IP 加入白名单
    • 在「安全设置 → 服务器出口 IP」中添加运行 Sage 的机器的公网 IP
    • 可在终端执行 curl ifconfig.me 查看公网 IP

  5. 发布应用

    • 在「应用发布 → 版本管理与发布」中创建新版本
    • 填写基础信息后保存

  6. 填写配置

    • 将获取的 Client ID 和 Client Secret 填入 Sage 的钉钉配置页面
    • 启用频道并保存

使用说明 ​

  • 在钉钉消息栏搜索机器人名称
  • 与机器人单聊或将其添加到群聊
  • 注意：从与机器人的单聊界面中创建群聊，会无法触发机器人的回复

iMessage 配置（macOS 专属） ​

iMessage 配置

系统限制

iMessage 频道仅支持 macOS，依赖本地「信息」应用与 iMessage 数据库，无法在 Linux / Windows 上使用。

iMessage 频道通过本地 iMessage 数据库轮询新消息并代为回复，让您的 Agent 可以通过 macOS 信息应用与用户对话。

前置准备 ​

在配置 iMessage 频道前，请确保完成以下准备工作：

  1. 登录 Apple ID

    • 确保本地「信息」(Messages) 已登录 Apple ID
    • 在系统设置里打开「信息」并登录

  2. 授予完全磁盘访问权限

    • 应用需要「完全磁盘访问权限」才能读取 Messages 数据库
    • 前往「系统设置 → 隐私与安全性 → 完全磁盘访问权限」
    • 添加运行 Sage 的终端或应用

隐私说明

iMessage 数据仅限本地使用，不会离开您的电脑。Sage 仅在本地读取数据库，不会上传任何消息内容到云端。

配置参数 ​

参数说明
启用是否启用 iMessage 频道
监听模式数据库轮询（通过轮询 Messages 数据库获取新消息）
监听发送者每行输入一个手机号或邮箱地址，只有这些发送者的消息会被处理（必填）

配置步骤 ​

1. 启用 iMessage 频道 ​

在 Sage 的 iMessage 配置页面，打开「启用」开关。

2. 配置监听发送者 ​

输入允许与 Agent 对话的手机号或邮箱地址：

  • 每行一个地址
  • 支持格式：
    +86138xxxxxxxx
18910982928
user@example.com
  • 必须配置至少一个发送者，只有这些发送者的消息会被处理

安全提示

建议仅配置您信任的发送者，避免未经授权的访问。

3. 授予权限 ​

首次启用时，系统会提示授予 Sage 访问 Messages 数据库的权限：

  1. 前往「系统设置 → 隐私与安全性 → 完全磁盘访问权限」
  2. 点击「+」添加应用
  3. 选择运行 Sage 的终端或应用
  4. 重启 Sage 使权限生效

4. 保存配置 ​

点击「保存」使配置生效。

使用说明 ​

  1. 在 macOS 的「信息」应用中，向配置的号码或邮箱发送消息
  2. Agent 会检测新消息并通过 iMessage 回复
  3. 对话会显示在 macOS 的「信息」应用中

功能限制 ​

功能支持情况
接收文本✓ 支持
发送文本✓ 支持
接收图片✗ 不支持
发送图片✗ 不支持
接收文件✗ 不支持
发送文件✗ 不支持

限制说明

由于 iMessage 平台/实现限制，无法支持附件收发。如需传输图片或文件，请使用飞书或钉钉频道。

故障排查 ​

无法接收消息 ​

  1. 检查权限

    • 确认已授予「完全磁盘访问权限」
    • 尝试移除权限后重新添加

  2. 检查发送者配置

    • 确认发送者号码/邮箱格式正确
    • 确认发送者已添加到监听列表

  3. 重启服务

    • 重启 Sage 应用
    • 重启「信息」应用

消息发送失败 ​

  1. 检查 macOS 是否已登录 Apple ID
  2. 检查「信息」应用是否正常运行
  3. 检查网络连接状态

延迟过高 ​

  1. 检查系统负载，关闭不必要的应用
  2. 检查「信息」应用的消息同步状态
  3. 尝试重启「信息」应用

多频道管理 ​

您可以同时启用多个 IM 频道，让 Agent 在不同平台上为用户提供服务：

  1. 独立配置：每个频道的配置相互独立
  2. 统一回复：Agent 使用相同的知识和能力回复所有频道的消息
  3. 上下文隔离：不同频道的对话上下文相互隔离

故障排查 ​

飞书连接失败 ​

  1. 检查 App ID 和 App Secret 是否正确
  2. 确认应用已发布且状态正常
  3. 检查权限配置是否完整
  4. 查看飞书开放平台的应用日志

钉钉连接失败 ​

  1. 检查 Client ID 和 Client Secret 是否正确
  2. 确认机器人已启用 Stream 模式
  3. 检查应用是否已发布
  4. 确认服务器 IP 白名单配置（如涉及文件下载）

iMessage 无法接收消息 ​

  1. 检查是否已授予完全磁盘访问权限
  2. 确认监听发送者号码/邮箱格式正确
  3. 检查 Messages 应用是否正常运行
  4. 尝试重启 Sage 应用

消息发送失败 ​

  1. 检查网络连接状态
  2. 确认凭证信息未过期
  3. 查看平台方的 API 调用限制
  4. 检查机器人是否被禁言或移除

安全建议 ​

  1. 保护凭证信息

    • 不要将 App ID、App Secret 等敏感信息泄露给他人
    • 定期更换凭证，特别是在怀疑泄露时

  2. 限制监听范围

    • iMessage 建议仅配置信任的发送者
    • 钉钉和飞书建议在可控的群聊中使用

  3. 监控异常行为

    • 定期检查各频道的消息记录
    • 发现异常及时处理

基于 MIT 许可发布

Copyright © 2025 Sage AI