Matrix（外掛）

Matrix 是一個開放的去中心化通訊協定。OpenClaw 以 Matrix 使用者身分連接到任何 homeserver，因此你需要一個 Matrix 帳號給機器人。登入後，你可以直接私訊機器人或邀請它加入房間（Matrix 的「群組」）。Beeper 也是一個有效的客戶端選項，但它需要啟用 E2EE。

狀態：透過外掛支援（@vector-im/matrix-bot-sdk）。私訊、房間、討論串、媒體、表情回應、投票（發送 + poll-start 轉文字）、位置和 E2EE（含加密支援）。

需要外掛

Matrix 以外掛形式提供，不包含在核心安裝中。

透過 CLI（npm 套件庫）安裝：

openclaw plugins install @openclaw/matrix

本機 checkout（在 git repo 中開發）：

openclaw plugins install ./extensions/matrix

如果你在設定/引導設定時選擇 Matrix 且偵測到 git checkout，OpenClaw 會自動提供本機安裝路徑。

詳情：外掛

設定

  1. 安裝 Matrix 外掛：

    • 從 npm：openclaw plugins install @openclaw/matrix
    • 從本機 checkout：openclaw plugins install ./extensions/matrix

  2. 在 homeserver 上建立 Matrix 帳號：

  3. 取得機器人帳號的 access token：

    • 在你的 homeserver 使用 curl 呼叫 Matrix 登入 API：
    curl --request POST \
  --url https://matrix.example.org/_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"
}'
    • 將 matrix.example.org 替換為你的 homeserver URL。
    • 或設定 channels.matrix.userId + channels.matrix.password：OpenClaw 會呼叫相同的登入端點，將 access token 儲存在 ~/.openclaw/credentials/matrix/credentials.json，並在下次啟動時重用。

  4. 設定憑證：

    • 環境變數：MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN（或 MATRIX_USER_ID + MATRIX_PASSWORD）
    • 或設定：channels.matrix.*
    • 如果兩者都設定，設定值優先。
    • 使用 access token 時：使用者 ID 會透過 /whoami 自動取得。
    • 設定時，channels.matrix.userId 應為完整的 Matrix ID（例如：@bot:example.org）。

  5. 重啟 Gateway（或完成引導設定）。

  6. 從任何 Matrix 客戶端（Element、Beeper 等；見 https://matrix.org/ecosystem/clients/）開始與機器人私訊或邀請它加入房間。Beeper 需要 E2EE，所以請設定 channels.matrix.encryption: true 並驗證裝置。

最小設定（access token，使用者 ID 自動取得）：

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

E2EE 設定（啟用端對端加密）：

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

加密（E2EE）

端對端加密透過 Rust crypto SDK 支援。

使用 channels.matrix.encryption: true 啟用：

  • 如果加密模組載入成功，加密房間會自動解密。
  • 發送到加密房間的外送媒體會被加密。
  • 首次連接時，OpenClaw 會從你的其他工作階段請求裝置驗證。
  • 在另一個 Matrix 客戶端（Element 等）中驗證裝置以啟用金鑰共享。
  • 如果加密模組無法載入，E2EE 會被停用，加密房間將無法解密；OpenClaw 會記錄警告。
  • 如果你看到缺少加密模組的錯誤（例如 @matrix-org/matrix-sdk-crypto-nodejs-*），允許 @matrix-org/matrix-sdk-crypto-nodejs 的建置腳本並執行 pnpm rebuild @matrix-org/matrix-sdk-crypto-nodejs 或用 node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js 取得二進位檔。

加密狀態按帳號 + access token 儲存在 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/（SQLite 資料庫）。同步狀態儲存在旁邊的 bot-storage.json。如果 access token（裝置）變更，會建立新的存儲，機器人必須重新驗證以存取加密房間。

裝置驗證： 當 E2EE 啟用時，機器人會在啟動時從你的其他工作階段請求驗證。開啟 Element（或其他客戶端）並核准驗證請求以建立信任。驗證後，機器人即可解密加密房間中的訊息。

多帳號

多帳號支援：使用 channels.matrix.accounts 搭配按帳號的憑證和選用的 name。詳見 gateway/configuration 的共用模式。

每個帳號作為獨立的 Matrix 使用者在任何 homeserver 上運行。按帳號設定會繼承頂層 channels.matrix 設定，並可覆寫任何選項（私訊政策、群組、加密等）。

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

備註：

  • 帳號啟動是序列化的，以避免並行模組匯入的競爭條件。
  • 環境變數（MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN 等）僅適用於預設帳號。
  • 基本頻道設定（私訊政策、群組政策、提及管控等）適用於所有帳號，除非按帳號覆寫。
  • 使用 bindings[].match.accountId 將每個帳號路由到不同的代理。
  • 加密狀態按帳號 + access token 儲存（每個帳號有獨立的金鑰存儲）。

路由模型

  • 回覆永遠回到 Matrix。
  • 私訊共享代理的主要工作階段；房間對應到群組工作階段。

存取控制（私訊）

  • 預設：channels.matrix.dm.policy = "pairing"。未知發送者會收到配對代碼。
  • 核准方式：
    • openclaw pairing list matrix
    • openclaw pairing approve matrix <CODE>
  • 公開私訊：channels.matrix.dm.policy="open" 加上 channels.matrix.dm.allowFrom=["*"]。
  • channels.matrix.dm.allowFrom 接受完整的 Matrix 使用者 ID（例如：@user:server）。精靈會在目錄搜尋找到單一精確匹配時，將顯示名稱解析為使用者 ID。
  • 不要使用顯示名稱或裸 localpart（例如："Alice" 或 "alice"）。它們不明確，會被許可清單匹配忽略。使用完整的 @user:server ID。

房間（群組）

  • 預設：channels.matrix.groupPolicy = "allowlist"（需提及）。使用 channels.defaults.groupPolicy 覆寫未設定時的預設值。
  • 執行時備註：如果 channels.matrix 完全缺失，執行時會備援為 groupPolicy="allowlist" 用於房間檢查（即使 channels.defaults.groupPolicy 已設定）。
  • 使用 channels.matrix.groups 設定房間許可清單（房間 ID 或別名；名稱在目錄搜尋找到單一精確匹配時會被解析為 ID）：
{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}
  • requireMention: false 可在該房間啟用自動回覆。
  • groups."*" 可以設定跨房間的提及管控預設值。
  • groupAllowFrom 限制哪些發送者可以在房間中觸發機器人（完整 Matrix 使用者 ID）。
  • 按房間的 users 許可清單可以進一步限制特定房間內的發送者（使用完整的 Matrix 使用者 ID）。
  • 設定精靈會提示房間許可清單（房間 ID、別名或名稱），僅在精確、唯一匹配時解析名稱。
  • 啟動時，OpenClaw 會將許可清單中的房間/使用者名稱解析為 ID 並記錄對應關係；未解析的項目會被許可清單匹配忽略。
  • 邀請預設為自動加入；透過 channels.matrix.autoJoin 和 channels.matrix.autoJoinAllowlist 控制。
  • 若不允許任何房間，設定 channels.matrix.groupPolicy: "disabled"（或保持空白許可清單）。
  • 舊版鍵：channels.matrix.rooms（與 groups 相同結構）。

討論串

  • 支援回覆討論串。
  • channels.matrix.threadReplies 控制回覆是否留在討論串中：
    • off、inbound（預設）、always
  • channels.matrix.replyToMode 控制不在討論串中回覆時的回覆中繼資料：
    • off（預設）、first、all

功能

功能狀態
私訊✅ 支援
房間✅ 支援
討論串✅ 支援
媒體✅ 支援
E2EE✅ 支援（需要加密模組）
表情回應✅ 支援（透過工具發送/讀取）
投票✅ 發送支援；接收的 poll starts 轉換為文字（回應/結束被忽略）
位置✅ 支援（geo URI；海拔被忽略）
原生指令✅ 支援

疑難排解

首先執行此排查步驟：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

然後視需要確認私訊配對狀態：

openclaw pairing list matrix

常見失敗：

  • 已登入但房間訊息被忽略：房間被 groupPolicy 或房間許可清單封鎖。
  • 私訊被忽略：發送者在 channels.matrix.dm.policy="pairing" 時等待核准。
  • 加密房間失敗：加密支援或加密設定不匹配。

排查流程：/channels/troubleshooting。

設定參考（Matrix）

完整設定：設定

供應商選項：

  • channels.matrix.enabled：啟用/停用頻道啟動。
  • channels.matrix.homeserver：homeserver URL。
  • channels.matrix.userId：Matrix 使用者 ID（使用 access token 時選用）。
  • channels.matrix.accessToken：access token。
  • channels.matrix.password：登入密碼（token 會被儲存）。
  • channels.matrix.deviceName：裝置顯示名稱。
  • channels.matrix.encryption：啟用 E2EE（預設：false）。
  • channels.matrix.initialSyncLimit：初始同步限制。
  • channels.matrix.threadReplies：off | inbound | always（預設：inbound）。
  • channels.matrix.textChunkLimit：外送文字分段大小（字元）。
  • channels.matrix.chunkMode：length（預設）或 newline，在長度分段前先按空白行分割。
  • channels.matrix.dm.policy：pairing | allowlist | open | disabled（預設：pairing）。
  • channels.matrix.dm.allowFrom：私訊許可清單（完整 Matrix 使用者 ID）。open 需要 "*"。精靈會儘可能將名稱解析為 ID。
  • channels.matrix.groupPolicy：allowlist | open | disabled（預設：allowlist）。
  • channels.matrix.groupAllowFrom：群組訊息的許可發送者（完整 Matrix 使用者 ID）。
  • channels.matrix.allowlistOnly：強制私訊和房間的許可清單規則。
  • channels.matrix.groups：群組許可清單和按房間的設定對應。
  • channels.matrix.rooms：舊版群組許可清單/設定。
  • channels.matrix.replyToMode：討論串/標籤的回覆模式。
  • channels.matrix.mediaMaxMb：接收/外送媒體上限（MB）。
  • channels.matrix.autoJoin：邀請處理（always | allowlist | off，預設：always）。
  • channels.matrix.autoJoinAllowlist：自動加入的允許房間 ID/別名。
  • channels.matrix.accounts：多帳號設定，以帳號 ID 為鍵（每個帳號繼承頂層設定）。
  • channels.matrix.actions：按操作的工具管控（reactions/messages/pins/memberInfo/channelInfo）。
arrow_back
上一頁
Line
下一頁
Mattermost
arrow_forward