CA
文档首页

Matrix

当你希望在 Matrix 私信或房间中访问 Agent 时，可以连接 Matrix。

前提条件

  • 已有 Cloud Agents Agent。
  • 一个 Matrix bot 账号。
  • 该 bot 账号的 Matrix access token。
  • 一个未开启端到端加密的私信或房间。

当前 Matrix 渠道不支持端到端加密房间。

连接到 Cloud Agents

  1. 打开 Settings -> Channels。
  2. 创建新渠道并选择 Matrix。
  3. 选择要接收消息的 Agent。
  4. 输入 homeserver URL，例如 https://matrix.example.org。
  5. 输入 Matrix bot access token。
  6. 可以选择限制 allowed room IDs、allowed user IDs 和 free-response room IDs。
  7. 创建渠道，然后把 bot 邀请到私信或房间。
  8. 运行渠道测试。

默认情况下，bot 会自动加入允许的邀请。在私信中，它会回复每条消息。在房间中，除非房间被列入 freeResponseRoomIds，否则只会在被 mention 时回复。

推荐设置

设置建议
Allowed rooms当 bot 账号加入多个房间时，限制到已知房间。
Allowed users当 bot 只应该回复批准用户时使用。
Free-response rooms添加允许 Agent 不被 mention 也能回复的房间 ID。
Auto-join如果 bot 应接受允许房间的邀请，保持开启。
Thread isolation对 threaded 或 reply-based 对话建议开启。

验证

打开渠道详情页并运行 Test。健康的渠道会确认 bot 账号和 active 状态。

排查问题

  • Bot 不在房间中回复：mention bot，或把房间 ID 加入 free-response rooms。
  • Bot 不加入被邀请房间：检查 auto-join 和 allowed room IDs。
  • 消息被忽略：确认 homeserver URL、access token、allowed room IDs 和 allowed user IDs。
  • 加密房间被忽略：这个渠道请使用未加密房间。

另请参阅