OpenClaw连接Matrix和Element教程

前言

Matrix 是一个开放的、去中心化的即时通讯协议，Element 则是其最流行的客户端。将 OpenClaw 接入 Matrix 网络后，你可以在任何 Matrix 客户端中与 AI 助手对话，同时享受 Matrix 协议提供的隐私保护和去中心化优势。

本教程将从零开始，带你完成 OpenClaw 与 Matrix 的对接。

环境准备

在开始之前，请确保以下条件已满足：

依赖项	最低版本	说明
Node.js	22+	OpenClaw 运行环境
OpenClaw	最新版	`npm install -g openclaw@latest`
Matrix Homeserver	任意	可以是 matrix.org 或自建 Synapse
Element 客户端	任意	用于测试和日常使用

如果你还没有安装 OpenClaw，请先执行：

npm install -g openclaw@latest
openclaw onboard

第一步：创建 Matrix Bot 账号

你需要为 OpenClaw 创建一个专用的 Matrix 账号。推荐使用 Element 客户端进行注册。

在 matrix.org 注册

访问 Element Web，点击"Create Account"
选择 matrix.org 作为 Homeserver（或者使用你自建的 Homeserver 地址）
填写用户名，建议使用类似 openclaw-bot 的名称
设置强密码并完成注册

在自建 Synapse 上注册

如果你运行了自己的 Synapse 服务器，可以通过命令行注册：

# 在 Synapse 服务器上执行
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008
# 按提示输入用户名、密码，admin 选择 no

第二步：获取 Access Token

OpenClaw 需要通过 Access Token 来认证 Matrix 账号。有两种获取方式。

方式一：通过 Element 客户端获取

用 Bot 账号登录 Element
点击左上角头像 → "All settings"
进入 "Help & About" 标签页
展开底部的 "Advanced" 区域
找到 "Access token" 字段，点击复制

方式二：通过 API 获取

curl -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@openclaw-bot:matrix.org",
    "password": "your-password-here"
  }'

返回结果中会包含 access_token 字段：

{
  "user_id": "@openclaw-bot:matrix.org",
  "access_token": "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
  "device_id": "ABCDEFGHIJ"
}

请妥善保管此 Token，不要泄露给他人。

第三步：配置 OpenClaw

编辑 OpenClaw 的配置文件 ~/.config/openclaw/openclaw.json5：

{
  // 其他配置...
  channels: {
    matrix: {
      enabled: true,
      // Matrix Homeserver 地址
      homeserverUrl: "https://matrix.org",
      // Bot 的完整 Matrix ID
      userId: "@openclaw-bot:matrix.org",
      // 上一步获取的 Access Token
      accessToken: "syt_b3BlbmNsYXctYm90_xxxxxxxxxxxxx_xxxxxx",
      // 自动加入被邀请的房间
      autoJoin: true,
      // 响应模式：all 响应所有消息，mention 仅在被@时响应
      responseMode: "mention",
      // 允许的房间列表（留空则允许所有房间）
      allowedRooms: [],
      // 显示名称
      displayName: "OpenClaw AI",
      // 头像 URL（可选）
      avatarUrl: ""
    }
  }
}

配置项详解

配置项	类型	默认值	说明
`homeserverUrl`	string	必填	Homeserver 的完整 URL
`userId`	string	必填	Bot 的 Matrix 用户 ID
`accessToken`	string	必填	认证令牌
`autoJoin`	boolean	`true`	是否自动接受房间邀请
`responseMode`	string	`"mention"`	`all` 或 `mention`
`allowedRooms`	array	`[]`	允许响应的房间 ID 列表
`displayName`	string	用户名	Bot 的显示名称

第四步：启动并验证

保存配置后，重启 OpenClaw：

openclaw restart

查看日志确认 Matrix 频道已连接：

openclaw logs

你应该能看到类似以下的输出：

[INFO] Matrix channel initializing...
[INFO] Connected to homeserver: https://matrix.org
[INFO] Logged in as @openclaw-bot:matrix.org
[INFO] Matrix channel ready, listening for messages

第五步：创建房间并邀请 Bot

创建专用房间

在 Element 中点击 "+" 创建新房间
房间名称填写如 "AI 助手"
根据需要选择是否加密（见下文加密章节）
创建房间后，邀请 Bot 账号加入

邀请 Bot

在房间中输入命令邀请 Bot：

/invite @openclaw-bot:matrix.org

如果你配置了 autoJoin: true，Bot 会自动接受邀请并加入房间。

测试对话

在房间中发送消息测试：

@openclaw-bot 你好，请介绍一下你自己

如果 responseMode 设为 all，则无需 @ 也能触发响应。

端到端加密注意事项

Matrix 的端到端加密（E2EE）是一个强大的隐私保护功能，但在与 Bot 集成时需要额外注意。

当前限制

OpenClaw 的 Matrix 集成支持 E2EE，但存在以下考虑：

设备验证：首次启动时，Bot 需要完成设备验证。建议在 Element 中手动验证 Bot 的设备
密钥备份：建议启用密钥备份，否则 OpenClaw 重启后可能无法读取旧的加密消息
性能开销：E2EE 会增加消息处理的延迟

启用加密房间支持

在配置中添加 E2EE 相关设置：

{
  channels: {
    matrix: {
      // ...基础配置...
      encryption: {
        enabled: true,
        // 存储加密密钥的路径
        storePath: "~/.openclaw/matrix-crypto-store",
        // 是否自动验证新设备
        autoVerify: false
      }
    }
  }
}

验证 Bot 设备

在 Element 中完成设备验证：

打开与 Bot 的私聊
点击 Bot 头像 → "Security"
选择 "Manually verify by text" 或使用 emoji 验证
按提示完成验证流程

限制房间访问

出于安全考虑，建议限制 Bot 只在特定房间中响应：

{
  channels: {
    matrix: {
      // 只在这些房间中响应消息
      allowedRooms: [
        "!abcdefg:matrix.org",    // AI 助手房间
        "!hijklmn:matrix.org"     // 团队讨论房间
      ]
    }
  }
}

获取房间 ID 的方法：在 Element 中进入房间设置 → "Advanced" → 复制 "Internal room ID"。

使用 Bridge 连接其他平台

Matrix 的一个强大特性是可以通过 Bridge 连接其他平台。配合 OpenClaw 使用时，你可以实现一个 Bot 账号同时服务于多个平台。

常见的 Bridge 包括：

Bridge	连接平台	项目地址
mautrix-telegram	Telegram	github.com/mautrix/telegram
mautrix-whatsapp	WhatsApp	github.com/mautrix/whatsapp
mautrix-discord	Discord	github.com/mautrix/discord
mautrix-signal	Signal	github.com/mautrix/signal

通过 Bridge，消息会自动在 Matrix 和目标平台之间同步，OpenClaw 只需连接 Matrix 即可。

常见问题

Bot 无法连接到 Homeserver

# 检查 Homeserver 是否可达
curl -s https://matrix.org/_matrix/client/versions

# 检查 Access Token 是否有效
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  "https://matrix.org/_matrix/client/v3/account/whoami"

Bot 不响应消息

确认 responseMode 设置正确
检查 allowedRooms 是否包含当前房间
查看 OpenClaw 日志中是否有错误信息：openclaw logs

加密房间消息无法解密

确认 encryption.enabled 设为 true
检查 crypto-store 路径是否正确且有写权限
重新完成设备验证流程

小结

通过本教程，你已经成功将 OpenClaw 连接到了 Matrix 网络。Matrix 的去中心化特性和端到端加密能力，使其成为注重隐私的用户的理想选择。结合 OpenClaw 的 AI 能力，你可以在 Element 或任何兼容 Matrix 的客户端中享受智能助手服务。

下一步建议：

参考"OpenClaw同时连接多个聊天频道教程"实现多平台接入
探索 ClawHub 技能市场为你的 Bot 添加更多能力