Channel - Matrix

Matrix 是 OpenClaw 的可下载 channel 插件，使用官方 matrix-js-sdk，支持 DM、房间、线程、媒体、reaction、投票、位置和 E2EE。

安装

openclaw plugins install @openclaw/matrix

快速配置

Token 认证（推荐）

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}

密码认证

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me",
      deviceName: "OpenClaw Gateway",
    },
  },
}

自动加入（autoJoin）

默认 off，bot 不会自动加入新房间。

{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
    },
  },
}

allowlist 只接受稳定目标：!roomId:server、#alias:server 或 *，不接受普通房间名。

E2EE 加密

# 启用加密
openclaw matrix encryption setup
 
# 查看验证状态
openclaw matrix verify status
 
# 用恢复密钥验证设备
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
 
# 自我验证
openclaw matrix verify self

启动时若设备未验证，startupVerification 默认为 "if-unverified"，会自动请求自我验证（24 小时冷却）。

流式回复（Streaming）

{
  channels: {
    matrix: {
      streaming: "partial",  // "off" | "partial" | "quiet"
    },
  },
}

"off"（默认）：等待完整回复后一次性发送
"partial"：实时编辑消息预览
"quiet"：非通知预览，仅在最终完成时通知（需配置 push rules，见 channel-matrix-push-rules）

线程（Threads）

dm.sessionScope："per-user"（默认）或 "per-room"
threadReplies："off" | "inbound" | "always"

多账号

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
        },
      },
    },
  },
}

私有/LAN homeserver

{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: { dangerouslyAllowPrivateNetwork: true },
      accessToken: "syt_internal_xxx",
    },
  },
}

环境变量

默认账号	命名账号（`<ID>` 为规范化账号 ID）
`MATRIX_HOMESERVER`	`MATRIX_<ID>_HOMESERVER`
`MATRIX_ACCESS_TOKEN`	`MATRIX_<ID>_ACCESS_TOKEN`
`MATRIX_USER_ID`	`MATRIX_<ID>_USER_ID`
`MATRIX_RECOVERY_KEY`	`MATRIX_<ID>_RECOVERY_KEY`

目标格式

用户：@user:server
房间：!room:server
别名：#alias:server

Wiki AI

目录