OpenClaw

OpenClaw Matrix 渠道

去中心化
中等

将 OpenClaw 连接到 Matrix——一个开放的联邦通信协议。此集成让您的 AI 助手可以参与任何 Homeserver（matrix.org、Element 或自托管）上的 Matrix 房间和私聊。OpenClaw 通过 Matrix Client-Server API 连接,并通过 Rust crypto SDK 提供可选的端到端加密(E2EE)支持。Matrix 渠道作为插件发布,支持联邦、线程、表情回应和富媒体。

快速信息
难度中等
分类去中心化
支持功能数5 / 6

Matrix 支持的功能

文本消息

支持

媒体与文件

支持

消息反应

支持

消息线程

支持

语音消息

不支持

群聊

支持

Matrix 前置条件

  • 在任何 Homeserver（matrix.org、Element 或自托管）上拥有活跃的 Matrix 账户
  • 已安装 Matrix 插件:openclaw plugins install @openclaw/matrix
  • OpenClaw Gateway 正在运行并已配置
  • 服务器上已安装 Node.js 18+

Matrix 快速设置

1

安装 Matrix 插件

Matrix 渠道作为独立插件发布。通过 'openclaw plugins install @openclaw/matrix' 安装。插件将从 npm 仓库下载并自动启用。

2

获取 Matrix 凭证

您需要访问令牌或用户名/密码。对于访问令牌:使用 curl 调用 Homeserver 的登录端点并复制令牌。对于用户名/密码:Gateway 将自动登录并将令牌存储在 ~/.openclaw/credentials/matrix/credentials.json 中。

3

添加 Matrix 渠道配置

将 Matrix 渠道配置添加到 ~/.openclaw/openclaw.json,包含您的 Homeserver URL 和凭证。您也可以使用环境变量 MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN、MATRIX_USER_ID 和 MATRIX_PASSWORD。

4

启动 Gateway 并测试

运行 'openclaw gateway' 启动服务。从另一个账户向您的 Matrix 机器人用户发送私聊消息。如果使用默认的配对策略,通过终端中的 'openclaw pairing approve matrix <code>' 批准发送者。

Matrix 配置示例

config.json
{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "accessToken": "your_access_token_here",
      "dmPolicy": "pairing"
    }
  }
}

Matrix 深入了解

架构概览

OpenClaw 通过 Client-Server API 连接到 Matrix,作为标准 Matrix 客户端。架构是事件驱动的:您的机器人通过长轮询同步请求接收事件(消息、表情回应、成员变更),用 AI 处理它们,然后通过 API 发送响应。 Matrix 是联邦式的,这意味着您的机器人可以与全球 Matrix 网络上任何 Homeserver 的用户通信——不仅仅是您的机器人账户注册的 Homeserver。这与 WhatsApp 或 Telegram 等中心化平台有本质区别。 流程是:用户在 Matrix 中发送消息 → Homeserver 通过同步路由到您的 Gateway → OpenClaw 用 AI 处理 → 通过发送事件 API 回复 → 消息通过联邦传递。
联邦意味着您在 matrix.org 上的机器人可以与任何 Matrix Homeserver(如 element.io、Mozilla 的 Homeserver 或自托管实例)上的用户聊天。
Matrix 插件默认使用长轮询。不需要 Webhook 或公共 URL——Gateway 向您的 Homeserver 建立出站连接。

认证方法

OpenClaw 支持两种 Matrix 认证方式: 1. **访问令牌(推荐)** — 通过 curl 或 Matrix 客户端调用 Homeserver 的登录 API 获取令牌。在配置中设置 channels.matrix.accessToken。系统自动通过 /whoami 端点获取您的用户 ID。 2. **用户名/密码** — 设置 channels.matrix.userId 和 channels.matrix.password。OpenClaw 自动调用登录端点并将访问令牌存储在 ~/.openclaw/credentials/matrix/credentials.json 中。 环境变量优先于配置文件:MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN、MATRIX_USER_ID、MATRIX_PASSWORD。
openclaw.json
# 访问令牌方法
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "accessToken": "syt_xxx..."
    }
  }
}

# 用户名/密码方法
{
  "channels": {
    "matrix": {
      "homeserver": "https://matrix.example.org",
      "userId": "@bot:example.org",
      "password": "your_password"
    }
  }
}
切勿将访问令牌或密码提交到版本控制。在生产部署中使用环境变量。如果您的令牌被泄露,通过 Matrix 客户端注销所有设备以使所有令牌失效,然后生成新令牌。

私聊策略

私聊策略控制谁可以与您的 AI 助手互动。OpenClaw 支持四种策略: • pairing(默认) — 未知用户在首次联系时收到配对码。通过 'openclaw pairing approve matrix <CODE>' 批准以授予访问权限。一旦批准,用户可以自由聊天。 • allowlist — 只有明确列在 channels.matrix.dm.allowFrom 中的 Matrix 用户 ID 可以向机器人发消息。其他人被静默忽略。 • open — 任何向机器人发消息的人都会收到响应。需要 allowFrom: ["*"]。请谨慎使用。 • disabled — 完全关闭私聊处理。 白名单接受 @user:server 格式的完整 Matrix 用户 ID(如 @alice:matrix.org)。
openclaw.json
{
  "channels": {
    "matrix": {
      "dmPolicy": "allowlist",
      "dm": {
        "allowFrom": ["@alice:matrix.org", "@bob:example.org"]
      }
    }
  }
}

群聊(房间)支持

Matrix 群组对话称为"房间"。默认情况下,OpenClaw 对房间使用白名单策略,需要提及激活。您可以配置机器人参与的房间以及响应方式。 房间通过房间 ID(!roomId:server)或房间别名(#alias:server)标识。您可以配置特定房间的设置,如自动加入行为、提及要求和每个房间的用户白名单。
openclaw.json
{
  "channels": {
    "matrix": {
      "groupPolicy": "allowlist",
      "groups": {
        "!abc123:matrix.org": {
          "allow": true,
          "requireMention": false,
          "users": ["@alice:matrix.org"]
        },
        "#team-chat:example.org": {
          "allow": true
        }
      },
      "autoJoin": "allowlist"
    }
  }
}
将 autoJoin 设为 'always' 以自动接受所有房间邀请,'allowlist' 只加入已配置的房间,或 'off' 忽略邀请。
使用 requireMention: false 启用无需提及机器人的自动回复。在高流量房间中请谨慎使用。

端到端加密(E2EE)

Matrix 通过 Olm 和 Megolm 协议支持端到端加密(E2EE)。当您通过 Rust crypto SDK 启用加密时,OpenClaw 可以参与加密房间。 启用后,系统自动解密加密消息,在受保护房间中加密出站媒体,并将加密状态存储在 ~/.openclaw/matrix/accounts/(SQLite)中。首次连接时需要设备验证——在 Element 或其他 Matrix 客户端中批准验证请求以启用密钥共享。 如果加密模块加载失败,E2EE 被禁用,加密房间将无法访问。
openclaw.json
{
  "channels": {
    "matrix": {
      "encryption": true
    }
  }
}
更改访问令牌需要重新验证设备。保留加密状态目录(~/.openclaw/matrix/accounts/)的备份,以防止失去访问加密消息历史的能力。

联邦与 Homeserver 选择

Matrix 是联邦协议——没有单一的中心服务器。您可以选择在任何 Homeserver 上注册您的机器人: • **matrix.org** — Matrix 基金会运营的旗舰 Homeserver。开放注册,高可靠性,但由于高流量可能较慢。 • **Element Matrix Services** — 在 element.io 专业托管的 Homeserver,具有高级功能和支持。 • **自托管** — 运行您自己的 Homeserver,实现最大控制和隐私。Synapse 是最成熟且仍在活跃开发的选项。Dendrite (Go) 和 Conduit (Rust) 是更轻量的替代方案,适合小型部署,但目前均已进入维护或有限开发模式。 无论您的机器人在哪里注册,它都可以与任何 Homeserver 上的用户通信,这要归功于联邦。
对于生产部署,考虑使用自托管 Homeserver 或 Element Matrix Services 以获得更好的控制和性能。
联邦透明工作——用户无需知道您的机器人在哪个 Homeserver 上。

线程与回复模式

Matrix 通过 m.thread 关系类型支持线程对话。OpenClaw 可以参与线程并控制如何处理回复。 threadReplies 设置控制线程行为:'off' 禁用线程支持,'inbound' 只读取线程上下文,'always' 既读取又创建线程回复。replyToMode 设置控制回复关系的元数据附加。
openclaw.json
{
  "channels": {
    "matrix": {
      "threadReplies": "always",
      "replyToMode": "reference"
    }
  }
}

媒体处理与文件上传

Matrix 支持丰富媒体,包括图片、视频、音频和文档。OpenClaw 自动处理媒体上传——文件上传到您的 Homeserver 的媒体存储库并在消息事件中引用。 您可以通过 mediaMaxMb 设置配置最大文件大小。默认入站媒体为 50 MB,出站发送时对超大图片自动进行 JPEG 优化和调整大小。
openclaw.json
{
  "channels": {
    "matrix": {
      "mediaMaxMb": 50
    }
  }
}
媒体上传存储在您的 Homeserver 上。如果您使用 matrix.org 等公共 Homeserver,请注意存储限制和服务条款。

表情回应与丰富功能

OpenClaw 支持 Matrix 表情回应(对消息的表情响应)、投票、位置分享(geo URI 格式)和其他丰富功能。如果启用,可以通过工具发送和读取表情回应。 您可以通过 actions 配置限制特定操作,限制您的 AI 代理可以做什么(表情回应、消息、置顶、成员/频道信息)。
openclaw.json
{
  "channels": {
    "matrix": {
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": false
      }
    }
  }
}

为什么选择 Matrix 作为自托管 AI?

Matrix 是自托管 AI 助手的绝佳选择,因为: • **真正开放** — 开放规范,无供应商锁定,多个客户端和服务器实现。 • **联邦式** — 无单点控制或故障。您的机器人可以在全球 Matrix 网络中通信。 • **注重隐私** — E2EE 支持,自托管选项,无中心化数据收集。 • **功能丰富** — 线程、表情回应、媒体、投票和可扩展的事件类型。 • **无需手机号** — 与 WhatsApp 或 Signal 不同,Matrix 注册不需要手机号。 代价是复杂性:Matrix 的联邦模型和 E2EE 设置可能比中心化平台更复杂。对于注重隐私的用户和团队来说,这种代价是值得的。

Matrix 配置参考

enabled
Type: booleanDefault: true

启用或禁用 Matrix 渠道

homeserver
Type: stringDefault: "https://matrix.org"

Matrix Homeserver URL(如 https://matrix.org、https://element.io)

accessToken
Type: stringDefault: ""

用于认证的 Matrix 访问令牌(推荐方法)

userId
Type: stringDefault: ""

Matrix 用户 ID(如 @bot:matrix.org)—— 与密码认证一起使用

password
Type: stringDefault: ""

Matrix 账户密码——与 userId 一起用于登录

encryption
Type: booleanDefault: false

通过 Rust crypto SDK 启用端到端加密

dmPolicy
Type: stringDefault: "pairing"

私聊访问策略:pairing、allowlist、open 或 disabled

dm.allowFrom
Type: arrayDefault: []

允许私聊的 Matrix 用户 ID(如 [@alice:matrix.org])

groupPolicy
Type: stringDefault: "allowlist"

房间策略:allowlist 或 disabled

groups
Type: objectDefault: {}

特定房间配置(房间 ID 或别名作为键)

groups.<roomId>.allow
Type: booleanDefault: false

允许机器人参与此房间

groups.<roomId>.requireMention
Type: booleanDefault: true

在此房间中需要提及机器人才能触发响应

groups.<roomId>.users
Type: arrayDefault: []

每个房间的用户白名单(Matrix 用户 ID)

autoJoin
Type: stringDefault: "allowlist"

自动加入房间邀请:always、allowlist 或 off

textChunkLimit
Type: numberDefault: 4096

每条出站消息的最大字符数

chunkMode
Type: stringDefault: "length"

如何分割长响应:length(硬限制)或 newline(段落边界)

threadReplies
Type: stringDefault: "inbound"

线程行为:off、inbound(只读)或 always(读取+创建)

replyToMode
Type: stringDefault: "reference"

回复元数据附加模式

mediaMaxMb
Type: numberDefault: 50

最大媒体文件大小(兆字节)

actions.reactions
Type: booleanDefault: true

允许代理发送/读取表情回应

actions.messages
Type: booleanDefault: true

允许代理读取/发送/编辑/删除消息

actions.pins
Type: booleanDefault: true

允许代理置顶/取消置顶消息

actions.memberInfo
Type: booleanDefault: true

允许代理查找房间成员信息

actions.channelInfo
Type: booleanDefault: true

允许代理检索房间/频道信息

Matrix 常见问题

Matrix 故障排查

机器人无法接收消息

私聊策略阻止消息,或机器人不在房间中

检查 channels.matrix.dmPolicy 和 dm.allowFrom 设置。对于房间,确保房间在您的 groups 白名单中,并且机器人已被邀请并加入。
E2EE 加密房间不显示消息

设备未验证或加密模块加载失败

在 Element 或其他 Matrix 客户端中验证您的机器人设备。检查日志中的加密模块加载错误。确保 channels.matrix.encryption 设为 true。
访问令牌无效或已过期

令牌在 Homeserver 上被撤销或失效

通过重新登录生成新的访问令牌。如果使用用户名/密码,删除 ~/.openclaw/credentials/matrix/credentials.json 并重启 Gateway。
机器人加入房间但不响应

房间不在白名单中或 requireMention 已启用

将房间添加到 channels.matrix.groups,设置 allow: true。如果 requireMention 为 true,用户必须提及机器人才能获得响应。
与其他 Homeserver 的联邦错误

Homeserver 连接或联邦问题

在 federationtester.matrix.org 检查您的 Homeserver 联邦状态。如果是自托管,验证 DNS SRV 记录和 SSL 证书。
插件安装失败

npm 仓库访问或 Node.js 版本不兼容

确保已安装 Node.js 18+。尝试 'openclaw plugins install @openclaw/matrix --verbose' 获取详细错误日志。检查到 npm 仓库的网络连接。
查看完整文档返回所有渠道

相关渠道

Nostr

Advanced

OpenClaw 去中心化 NIP-04 DM 集成

配置指南

Tlon

Advanced

OpenClaw Urbit 消息应用集成

配置指南