OpenClaw 接入 Matrix 信道步骤

OpenClaw 接入 Matrix 信道完整步骤

1. 概述

本文介绍如何将 OpenClaw AI 智能体接入自建的 Matrix Homeserver (Tuwunel)，实现通过 Element Web / Cinny 等 Matrix 客户端与 OpenClaw agent 进行私聊对话。

2. 环境要求

组件 版本 说明
OS CentOS 7+ / Ubuntu 20+ / macOS -
Docker >= 20.10 部署 Tuwunel 和 Cinny
Docker Compose >= 1.18 或 v2 -
Rust >= 1.70 编译 Tuwunel (可选)
OpenClaw >= 2026.6.5 matrix 插件最低要求
Node.js >= 18 OpenClaw 运行环境
Matrix Server Tuwunel 1.7+ Matrix homeserver

3. 架构图

┌─────────────────┐
│  Element Web /  │  Matrix 客户端
│     Cinny       │
└────────┬────────┘
         │ Matrix Protocol (HTTP/WebSocket)
         ↓
┌─────────────────┐
│    Tuwunel      │  Matrix Homeserver
│   192.168.2.124  │  监听 6167
│   :6167         │
└────────┬────────┘
         │ Matrix Client-Server API
         ↓
┌─────────────────┐
│    OpenClaw     │  AI Gateway
│  (其他机器)      │  监听 18789
│                 │  插件: @openclaw/matrix
└────────┬────────┘
         │ HTTP API
         ↓
┌─────────────────┐
│  LLM Provider   │  大模型服务
│   (minimax,     │
│   OpenAI 等)    │
└─────────────────┘

4. 部署 Matrix Homeserver (Tuwunel)

4.1 创建项目目录

mkdir -p ~/tuwunel
cd ~/tuwunel

4.2 创建 docker-compose.yml

version: '3'

services:
  tuwunel:
    image: jevolk/tuwunel:latest
    container_name: tuwunel-server
    restart: unless-stopped
    ports:
      - "6167:6167"
    volumes:
      - tuwunel_data:/var/lib/tuwunel
    environment:
      - TUWUNEL_SERVER_NAME=matrix.boss
      - TUWUNEL_PORT=6167
      - TUWUNEL_ADDRESS=0.0.0.0
      - TUWUNEL_ALLOW_REGISTRATION=true
      - TUWUNEL_YES_I_AM_VERY_VERY_SURE_I_WANT_AN_OPEN_REGISTRATION_SERVER_PRONE_TO_ABUSE=true
      - TUWUNEL_MAX_REQUEST_SIZE=50000000
      - TUWUNEL_LOG=info

  cinny:
    image: ajbura/cinny:latest
    container_name: cinny
    restart: unless-stopped
    depends_on:
      - tuwunel
    ports:
      - "8077:8080"
    volumes:
      - ./cinny-config.json:/app/config.json

volumes:
  tuwunel_data:

4.3 创建 cinny-config.json

{
  "defaultHomeserver": "192.168.2.124:6167"
}

4.4 启动 Tuwunel

cd ~/tuwunel
docker-compose up -d

# 查看状态
docker-compose ps
# 验证可访问性
curl http://localhost:6167/_matrix/client/versions

4.5 创建管理员账号

# 停止 Tuwunel (释放数据库锁)
cd ~/tuwunel
docker-compose stop tuwunel

# 进入 console
docker run --rm -it \
  -v tuwunel_tuwunel_data:/var/lib/tuwunel \
  -e TUWUNEL_SERVER_NAME=matrix.boss \
  jevolk/tuwunel:latest \
  --console

在 uwu> 提示符下执行：

admin users create-user admin <你的管理员密码>
admin users make-user-admin @admin:matrix.boss

按 Ctrl+\ 退出 console，然后重启 Tuwunel：

cd ~/tuwunel
docker-compose start tuwunel

4.6 创建其他用户

按需创建 Matrix 用户（例如为每个 agent 创建一个用户）：

cd ~/tuwunel
docker-compose stop tuwunel

docker run --rm -it \
  -v tuwunel_tuwunel_data:/var/lib/tuwunel \
  -e TUWUNEL_SERVER_NAME=matrix.boss \
  jevolk/tuwunel:latest \
  --console

在 uwu> 下：

admin users create-user page_config OpenClawPass123
admin users create-user weekly_report OpenClawPass123
admin users create-user doc_review OpenClawPass123
admin users create-user release_check OpenClawPass123

Ctrl+\ 退出，然后：

cd ~/tuwunel
docker-compose start tuwunel

4.7 验证账号

curl -X POST http://localhost:6167/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "admin",
    "password": "<你的管理员密码>"
  }'

返回的 access_token 用于后续 API 调用。

5. 部署 OpenClaw

5.1 升级 OpenClaw

OpenClaw matrix 插件要求 OpenClaw >= 2026.6.5，升级：

# 备份配置
cp -r ~/.openclaw/ ~/.openclaw.bak.$(date +%s)

# 升级
npm install -g openclaw@latest

# 验证版本
openclaw --version
# 确认 >= 2026.6.5

5.2 安装 matrix 插件

openclaw plugins install clawhub:@openclaw/matrix

# 验证
openclaw plugins list | grep matrix

5.3 准备账号的 access_token

在 Tuwunel 服务器上获取 bot 用户的 access_token：

# 以 page_config 为例
curl -X POST http://192.168.2.124:6167/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "page_config",
    "password": "OpenClawPass123"
  }'

返回的 JSON 中 access_token 字段是后续步骤要用的凭证。

为每个需要接入的 OpenClaw 实例获取对应 token。

5.4 修改 OpenClaw 配置

OpenClaw 配置文件位置：

  • npm 全局安装：~/.openclaw/config.json
  • 自定义安装：根据实际情况

使用 Python 脚本修改配置（推荐，避免 JSON 格式错误）：

import json
import os

CONFIG = os.path.expanduser("~/.openclaw/config.json")

with open(CONFIG, 'r') as f:
    cfg = json.load(f)

# 1. 启用 matrix 插件
cfg.setdefault('plugins', {}).setdefault('entries', {})['matrix'] = {"enabled": True}

# 2. 配置 channels.matrix
cfg.setdefault('channels', {})
cfg['channels']['matrix'] = {
    "enabled": True,
    "defaultAccount": "page_config",
    "dm": {
        "policy": "allowlist",
        "allowFrom": ["@admin:matrix.boss"]
    },
    "accounts": {
        "page_config": {
            "homeserver": "http://192.168.2.124:6167",
            "network": {"dangerouslyAllowPrivateNetwork": True},
            "accessToken": "<page_config 的 access_token>",
            "userId": "@page_config:matrix.boss",
            "deviceName": "OpenClaw Page Config",
            "agentId": "pageconfig"
        }
    }
}

with open(CONFIG, 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)

print("✓ OpenClaw 配置已更新")
print(f"  agents: {[a['id'] for a in cfg.get('agents', {}).get('list', [])]}")
print(f"  accounts: {list(cfg['channels']['matrix']['accounts'].keys())}")

5.5 重启 OpenClaw

根据 OpenClaw 部署方式选择：

# 方式 1: systemd
systemctl restart openclaw

# 方式 2: Docker
docker restart openclaw

# 方式 3: 直接运行的进程
ps -ef | grep openclaw | grep -v grep
kill <PID> && nohup openclaw > openclaw.log 2>&1 &

5.6 验证 matrix 频道启动

# systemd
journalctl -u openclaw --no-pager | tail -50

# Docker
docker logs --tail=50 openclaw

# 进程日志
tail -50 openclaw.log

预期输出：

[matrix] [page_config] starting provider (http://192.168.2.124:6167)
[matrix] [page_config] ready

5.7 绑定 agent 到 matrix 账号

# 把 pageconfig agent 绑定到 matrix 的 page_config 账号
openclaw agents bind --agent pageconfig --bind matrix:page_config

# 验证绑定
openclaw agents list
openclaw agents bindings

6. 客户端配置

6.1 Cinny (推荐)

已经在 docker-compose.yml 中部署，直接访问：

http://<服务器IP>:8077

Cinny 默认会显示登录页，homeserver 地址自动填好。

6.2 Element Web (备选)

Element Web 对自建 homeserver 兼容性较差，容易触发 OIDC 相关问题。推荐用 Cinny。

如需使用 Element Web，必须用 user: "0"（root 模式）启动，并提供 hostname 命名的 config 文件。

7. 端到端测试

7.1 登录 Cinny

  1. 浏览器打开 http://192.168.2.124:8077
  2. 使用 admin 账号登录
  3. Cinny 默认会通过 defaultHomeserver 找到 Tuwunel

7.2 私聊 bot

  1. 在 Cinny 中点击 "+" 添加新对话
  2. 输入 bot 的 Matrix ID：@page_config:matrix.boss
  3. 发送测试消息：hello

7.3 验证消息处理

# 查看 OpenClaw 日志
docker logs -f openclaw
# 或
tail -f openclaw.log

预期看到：

[matrix] [page_config] received message: hello
[matrix] [page_config] routing to agent: pageconfig
[agent] calling model: minimax/MiniMax-M2.7
[matrix] [page_config] sent response: ...

8. 多 OpenClaw 实例部署

为不同的 agent 部署多个 OpenClaw 实例，每个实例对应一个 Matrix 用户：

机器 OpenClaw 实例 关联 Matrix 用户 agentId
机器 1 OpenClaw-1 @page_config:matrix.boss pageconfig
机器 2 OpenClaw-2 @weekly_report:matrix.boss weekly_report
机器 3 OpenClaw-3 @doc_review:matrix.boss doc_review
机器 4 OpenClaw-4 @release_check:matrix.boss release_check

每台机器的 OpenClaw 配置中 channels.matrix.accounts 只需保留对应的一个账号，并指定对应的 agentId。

9. 完整命令清单

# === Matrix 服务器端 ===
mkdir -p ~/tuwunel
cd ~/tuwunel
# 创建 docker-compose.yml 和 cinny-config.json (见上文)
docker-compose up -d

# 创建账号
cd ~/tuwunel
docker-compose stop tuwunel
docker run --rm -it -v tuwunel_tuwunel_data:/var/lib/tuwunel \
  -e TUWUNEL_SERVER_NAME=matrix.boss jevolk/tuwunel:latest --console
# 在 uwu> 提示符下执行 admin users create-user ...
# Ctrl+\ 退出
cd ~/tuwunel
docker-compose start tuwunel

# 验证
curl -X POST http://localhost:6167/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"admin","password":"<密码>"}'

# === OpenClaw 端（每台机器） ===
# 备份
cp -r ~/.openclaw/ ~/.openclaw.bak.$(date +%s)

# 升级
npm install -g openclaw@latest
openclaw --version

# 装插件
openclaw plugins install clawhub:@openclaw/matrix

# 拿 access_token（在 Tuwunel 机器上）
curl -X POST http://192.168.2.124:6167/_matrix/client/r0/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"page_config","password":"OpenClawPass123"}'

# 改配置（用 Python 脚本，见 5.4）

# 重启
systemctl restart openclaw
# 或 docker restart openclaw

# 验证
tail -50 openclaw.log
# 看到 [matrix] [page_config] ready

# 绑定 agent
openclaw agents bind --agent pageconfig --bind matrix:page_config

# 验证绑定
openclaw agents bindings

10. 常见问题

10.1 插件版本不兼容

Plugin "@openclaw/matrix" requires plugin API >=2026.6.5, 
but this OpenClaw runtime exposes 2026.5.22.

解决：npm install -g openclaw@latest

10.2 ENOTFOUND tuwunel

OpenClaw 容器找不到 tuwunel 主机名（Docker DNS 解析失败）。

解决：使用宿主 IP 替代容器名，例如 http://192.168.2.124:6167，并配置 network.dangerouslyAllowPrivateNetwork: true。

10.3 OIDC server not configured

Element Web 现代版本会请求 /_matrix/client/v1/auth_metadata 等 OIDC 发现端点，Tuwunel 默认不实现 OIDC，导致页面卡在加载状态。

解决：使用 Cinny 替代 Element Web，配置 defaultHomeserver 即可。

10.4 React error #185

Element Web 前端组件在特定场景下会进入无限循环 setState。

解决：使用 Cinny 替代 Element Web。

10.5 数据库锁冲突

While lock file: /var/lib/tuwunel/LOCK: Resource temporarily unavailable

Tuwunel 主服务和 console 容器争抢同一个数据库。

解决：先 docker-compose stop tuwunel，再运行 console。

10.6 dm policy 不生效

OpenClaw 配置 dm.policy: "open" 可能被忽略，实际仍走 pairing 模式。

解决：使用 allowlist + allowFrom 显式指定允许的用户。

11. 防火墙配置

确保 OpenClaw 所在机器能够访问 Tuwunel：

# CentOS / RHEL
sudo firewall-cmd --permanent --add-port=6167/tcp
sudo firewall-cmd --reload

# 验证
sudo firewall-cmd --list-ports

12. 总结

通过本文的步骤，可以完成：

  1. 部署 Tuwunel Matrix Homeserver
  2. 创建管理员和 bot 用户
  3. 部署 Cinny Web 客户端
  4. 升级并配置 OpenClaw 接入 matrix 频道
  5. 绑定 OpenClaw agent 到 matrix 账号
  6. 通过 Cinny 客户端与 OpenClaw agent 私聊对话

整套流程涉及的关键点：

  • OpenClaw 版本必须 >= 2026.6.5
  • OpenClaw 与 Tuwunel 之间使用 HTTP 协议（homeserver 端口）
  • 必须启用 network.dangerouslyAllowPrivateNetwork 以允许内网访问
  • 推荐使用 Cinny 客户端，Element Web 对自建服务器兼容性较差
posted @ 2026-06-15 17:19  雪山上的蒲公英  阅读(10)  评论(0)    收藏  举报
/* 返回顶部代码 */