OpenClaw 集成 Matrix 教程（tuwunel + Element）

Thu, 12 Mar 2026 09:17:57 +0000

鉴于群晖chat插件在openclaw中还不成熟，现在最好的私有化chat工具就是基于matrix协议的软件，如element。

本教程目标：

使用 tuwunel 部署 Matrix Homeserver
用 Element 作为客户端
将 OpenClaw 以 Matrix 用户身份接入，实现私信/房间对话

1. 部署 tuwunel（Matrix Homeserver）

官方 docker-compose 示例：

version: "3" services: homeserver: image: jevolk/tuwunel:latest restart: unless-stopped ports: - “8448:6167” volumes: - db:/var/lib/tuwunel # - ./tuwunel.toml:/etc/tuwunel.toml environment: TUWUNEL_SERVER_NAME: your.server.name # 修改为你的域名 TUWUNEL_DATABASE_PATH: /var/lib/tuwunel TUWUNEL_PORT: 6167 TUWUNEL_MAX_REQUEST_SIZE: 20000000 TUWUNEL_ALLOW_REGISTRATION: “true” TUWUNEL_REGISTRATION_TOKEN: “YOUR_TOKEN” TUWUNEL_ALLOW_FEDERATION: “true” TUWUNEL_TRUSTED_SERVERS: ‘[“matrix.org”]’ TUWUNEL_ADDRESS: 0.0.0.0

volumes: db:

启动：

docker compose up -d

2. 使用 Element 注册/登录

下载 Element 客户端：
https://element.io/download

登录时：

Homeserver 填 https://your.server.name
使用你注册的 Matrix 用户

3. 安装 OpenClaw Matrix 插件

Matrix 是插件渠道，需要安装：

openclaw plugins install @openclaw/matrix

4. 获取 Matrix Access Token

可以用密码登录 API 获取 token：

curl --request POST \
 --url https://your.server.name/_matrix/client/v3/login \
 --header 'Content-Type: application/json' \
 --data '{
 "type": "m.login.password",
 "identifier": {
 "type": "m.id.user",
 "user": "your-user-name"
 },
 "password": "your-password"
 }'

返回 JSON 中的 access_token 即为后续配置用的 Token。

5. 配置 OpenClaw（Matrix 通道）

编辑 ~/.openclaw/openclaw.json：

{
 channels: {
 matrix: {
 enabled: true,
 homeserver: "https://your.server.name",
 accessToken: "syt_***",
 dm: { policy: "open" }
 }
 }
}

如果你希望启用端到端加密（E2EE），可加：
encryption: true

6. 重启 OpenClaw 并验证

openclaw gateway restart

在 Element 中对 OpenClaw 机器人发私信（或邀请进房间）。

7. 常见问题

✅ 机器人收不到消息？

检查 homeserver 是否可访问
检查 access token 是否正确
确认 OpenClaw gateway 正在运行

✅ E2EE 加密房间无法解密？

需要在 Element 中验证 OpenClaw 设备（Matrix 会提示）。

参考资料

[1]: tuwunel docker-compose 示例
[2]: OpenClaw Matrix 通道配置（中文）

Openclaw集成matrix on lategege 的技术博客