將 OpenClaw 連接到 Matrix：快速設定指南

需要插件

Matrix 是一個插件，並沒有內建在 OpenClaw 核心中。

從 npm 安裝：

openclaw plugins install @openclaw/matrix

從本地路徑安裝：

openclaw plugins install ./path/to/local/matrix-plugin

關於插件的行為與安裝規則，請參考 Plugins。

設定

1. 安裝插件。
2. 在你的 homeserver 上建立一個 Matrix 帳號。
3. 設定 channels.matrix，你可以選擇：
   • homeserver + accessToken，或者
   • homeserver + userId + password。
4. 重啟 Gateway。
5. 與機器人開啟 DM（私訊）或將它邀請進房間。

互動式設定路徑：

openclaw channels add
openclaw configure --section channels

Matrix 設定精靈實際上會詢問：

• homeserver URL
• 驗證方式：access token 或 password
• 只有選擇密碼驗證時才需要輸入 user ID
• 選填的裝置名稱 (device name)
• 是否啟用 E2EE
• 是否現在就設定 Matrix 房間存取權限

設定精靈的重要行為：

• 如果所選帳號的 Matrix 驗證環境變數已經存在，且該帳號在設定檔中還沒有儲存驗證資訊，精靈會提供環境變數捷徑，並僅為該帳號寫入 enabled: true。
• 當你以互動方式新增另一個 Matrix 帳號時，輸入的帳號名稱會被正規化為設定檔與環境變數中使用的 account ID。例如，Ops Bot 會變成 ops-bot。
• DM 白名單提示可以立即接受完整的 @user:server 值。顯示名稱 (Display names) 只有在即時目錄查找剛好找到一個完全匹配的結果時才有效；否則精靈會要求你使用完整的 Matrix ID 重試。
• 房間白名單提示可以直接接受 room ID 和別名 (aliases)。它們也可以即時解析已加入的房間名稱，但未解析的名稱僅會按設定時輸入的內容保留，稍後在執行階段解析白名單時會被忽略。建議優先使用 !room:server 或 #alias:server。
• 執行階段的房間/工作階段識別會使用穩定的 Matrix room ID。房間宣告的別名僅作為查找輸入，不會作為長期工作階段金鑰或穩定的群組識別。
• 若要在儲存前解析房間名稱，請使用 openclaw channels resolve --channel matrix "Project Room"。

最簡 Token 設定：

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

密碼設定（登入後會快取 Token）：

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

Matrix 會將快取的憑證儲存在 ~/.openclaw/credentials/matrix/。 預設帳號使用 credentials.json；具名帳號則使用 credentials-<account>.json。

環境變數對應（當設定檔中未設定時使用）：

• MATRIX_HOMESERVER
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_PASSWORD
• MATRIX_DEVICE_ID
• MATRIX_DEVICE_NAME

對於非預設帳號，請使用具備帳號範圍的環境變數：

• MATRIX_<ACCOUNT_ID>_HOMESERVER
• MATRIX_<ACCOUNT_ID>_ACCESS_TOKEN
• MATRIX_<ACCOUNT_ID>_USER_ID
• MATRIX_<ACCOUNT_ID>_PASSWORD
• MATRIX_<ACCOUNT_ID>_DEVICE_ID
• MATRIX_<ACCOUNT_ID>_DEVICE_NAME

以帳號 ops 為例：

• MATRIX_OPS_HOMESERVER
• MATRIX_OPS_ACCESS_TOKEN

對於正規化後的 account ID ops-bot，請使用：

• MATRIX_OPS_BOT_HOMESERVER
• MATRIX_OPS_BOT_ACCESS_TOKEN

只有在這些驗證環境變數已經存在，且所選帳號尚未在設定檔中儲存 Matrix 驗證資訊時，互動式精靈才會提供環境變數捷徑。

設定範例

這是一個實用的基礎設定，啟用了 DM 配對、房間白名單以及 E2EE：

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: "partial",
    },
  },
}

串流預覽

Matrix 的回覆串流功能需要手動開啟。

當你希望 OpenClaw 發送單一草稿回覆，並在模型生成文字時原地編輯該草稿，最後在完成時定稿，請將 channels.matrix.streaming 設為 "partial"：

{
  channels: {
    matrix: {
      streaming: "partial",
    },
  },
}

• streaming: "off" 是預設值。OpenClaw 會等待最終回覆並一次發送。
• streaming: "partial" 會建立一個可編輯的預覽訊息，而不是發送多個片段訊息。
• 如果預覽內容不再適合放入單個 Matrix event 中，OpenClaw 會停止串流預覽並退回到正常的最終交付模式。
• 媒體回覆仍會正常發送附件。如果舊的預覽無法再安全地重複使用，OpenClaw 會在發送最終媒體回覆前將其撤回 (redact)。
• 預覽編輯會消耗額外的 Matrix API 呼叫。如果你希望使用最保守的速率限制 (rate-limit) 行為，請保持串流關閉。

加密與驗證

在加密 (E2EE) 聊天室中，發送圖片事件會使用 thumbnail_file，這樣圖片預覽就能跟完整的附件一起加密。未加密的聊天室則繼續使用一般的 thumbnail_url。你不需要做任何設定 —— 外掛會自動偵測 E2EE 狀態。

機器人對機器人聊天室 (Bot to bot rooms)

預設情況下，來自其他已設定 OpenClaw Matrix 帳號的訊息會被忽略。

如果你想要處理代理人之間的 Matrix 流量，請使用 allowBots：

{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

• allowBots: true 會在允許的聊天室和 DM 中接收來自其他已設定 Matrix 機器人帳號的訊息。
• allowBots: "mentions" 只有當這些訊息在聊天室中明顯提到 (mention) 此機器人時才會接收。DM 則不受限。
• groups.<room>.allowBots 可以針對單一聊天室覆蓋帳號層級的設定。
• OpenClaw 仍然會忽略來自同一個 Matrix user ID 的訊息，以避免陷入自我回覆的無限迴圈。
• Matrix 在這裡沒有提供原生的機器人標記；OpenClaw 將「機器人撰寫」視為「由該 OpenClaw Gateway 上另一個已設定的 Matrix 帳號所發送」。

在共享聊天室中啟用機器人對機器人流量時，請使用嚴格的聊天室允許清單 (allowlists) 和提及 (mention) 要求。

啟用加密：

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

檢查驗證狀態：

openclaw matrix verify status

詳細狀態（完整診斷）：

openclaw matrix verify status --verbose

在機器可讀的輸出中包含儲存的復原金鑰：

openclaw matrix verify status --include-recovery-key --json

初始化 (Bootstrap) 交叉簽名 (cross-signing) 與驗證狀態：

openclaw matrix verify bootstrap

多帳號支援：使用 channels.matrix.accounts 並設定各帳號的憑證與選填的 name。參考 Configuration reference 了解共用模式。

詳細的初始化診斷：

openclaw matrix verify bootstrap --verbose

在初始化前強制重設全新的交叉簽名身份：

openclaw matrix verify bootstrap --force-reset-cross-signing

使用復原金鑰驗證此裝置：

openclaw matrix verify device "<your-recovery-key>"

詳細的裝置驗證細節：

openclaw matrix verify device "<your-recovery-key>" --verbose

檢查聊天室金鑰備份健康狀況：

openclaw matrix verify backup status

詳細的備份健康診斷：

openclaw matrix verify backup status --verbose

從伺服器備份還原聊天室金鑰：

openclaw matrix verify backup restore

詳細的還原診斷：

openclaw matrix verify backup restore --verbose

刪除目前的伺服器備份並建立全新的備份基準：

openclaw matrix verify backup reset --yes

所有 verify 命令預設都很簡潔（包含安靜的內部 SDK 日誌），只有加上 --verbose 才會顯示詳細診斷。 在編寫腳本時，請使用 --json 取得完整的機器可讀輸出。

在多帳號設定中，除非你傳遞 --account <id>，否則 Matrix CLI 命令會使用隱含的 Matrix 預設帳號。 如果你設定了多個具名帳號，請先設定 channels.matrix.defaultAccount，否則這些隱含的 CLI 操作會停止並要求你明確選擇帳號。 當你希望驗證或裝置操作明確針對某個具名帳號時，請使用 --account：

openclaw matrix verify status --account assistant
openclaw matrix verify backup restore --account assistant
openclaw matrix devices list --account assistant

當具名帳號的加密功能被停用或無法使用時，Matrix 警告和驗證錯誤會指向該帳號的設定鍵，例如 channels.matrix.accounts.assistant.encryption。

什麼是「已驗證」

OpenClaw 只有在你的裝置被你自己的交叉簽名 (cross-signing) 身份驗證時，才會將其視為已驗證。 實際上，openclaw matrix verify status --verbose 會顯示三個信任訊號：

• Locally trusted：此裝置僅被目前的用戶端信任
• Cross-signing verified：SDK 回報此裝置已透過交叉簽名驗證
• Signed by owner：此裝置已由你自己的自我簽名金鑰簽署

只有當交叉簽名驗證或擁有者簽署存在時，Verified by owner 才會顯示為 yes。 單靠本地信任不足以讓 OpenClaw 將裝置視為完全驗證。

Bootstrap 的作用

openclaw matrix verify bootstrap 是加密 Matrix 帳號的修復與設定命令。 它會依序執行以下操作：

• 初始化秘密儲存空間 (secret storage)，盡可能重複使用現有的復原金鑰
• 初始化交叉簽名並上傳缺失的公開交叉簽名金鑰
• 嘗試標記並交叉簽署目前的裝置
• 如果尚不存在，則建立新的伺服器端聊天室金鑰備份

如果 homeserver 需要互動式驗證才能上傳交叉簽名金鑰，OpenClaw 會先嘗試無驗證上傳，接著嘗試 m.login.dummy，最後在設定了 channels.matrix.password 的情況下嘗試 m.login.password。

只有當你打算捨棄目前的交叉簽名身份並建立新身份時，才使用 --force-reset-cross-signing。

如果你打算捨棄目前的聊天室金鑰備份，並為未來的訊息建立新的備份基準，請使用 openclaw matrix verify backup reset --yes。 請注意，這樣做代表你接受無法復原的舊加密歷史紀錄將保持不可用狀態。

全新備份基準

如果你想讓未來的加密訊息保持運作，並接受失去無法復原的舊歷史紀錄，請依序執行這些命令：

openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status

當你想要明確針對某個具名 Matrix 帳號時，請在每個命令中加入 --account <id>。

啟動行為

當 encryption: true 時，Matrix 會將 startupVerification 預設為 "if-unverified"。 啟動時，如果此裝置仍未驗證，Matrix 會在另一個 Matrix 用戶端中請求自我驗證， 跳過已在處理中的重複請求，並在重啟後套用本地冷卻時間再重試。 預設情況下，失敗的請求嘗試會比成功建立的請求更快重試。 將 startupVerification 設為 "off" 可以停用自動啟動請求，或者調整 startupVerificationCooldownHours 來縮短或延長重試窗口。

啟動時也會自動執行保守的加密初始化 (crypto bootstrap)。 該程序會優先嘗試重複使用目前的秘密儲存空間和交叉簽名身份，除非你執行明確的 bootstrap 修復流程，否則會避免重設交叉簽名。

如果啟動時發現 bootstrap 狀態損壞且已設定 channels.matrix.password，OpenClaw 可以嘗試更嚴格的修復路徑。 如果目前裝置已經過擁有者簽署 (owner-signed)，OpenClaw 會保留該身份而不是自動重設。

從舊版公用 Matrix 外掛升級：

• OpenClaw 會盡可能自動重複使用相同的 Matrix 帳號、access token 和裝置身份。
• 在執行任何實際的 Matrix 遷移變更前，OpenClaw 會在 ~/Backups/openclaw-migrations/ 下建立或重複使用復原快照。
• 如果你使用多個 Matrix 帳號，請在從舊的扁平儲存佈局升級前設定 channels.matrix.defaultAccount，以便 OpenClaw 知道哪個帳號應該接收該共用的遺留狀態。
• 如果舊版外掛在本地儲存了 Matrix 聊天室金鑰備份的解密金鑰，啟動或執行 openclaw doctor --fix 會自動將其匯入新的復原金鑰流程。
• 如果 Matrix access token 在準備遷移後發生變更，啟動程序現在會在放棄自動備份還原前，掃描同級的 token-hash 儲存根目錄以尋找待處理的遺留還原狀態。
• 如果同一個帳號、homeserver 和使用者稍後變更了 Matrix access token，OpenClaw 現在會優先重複使用最完整的現有 token-hash 儲存根目錄，而不是從空的 Matrix 狀態目錄開始。
• 在下一次 Gateway 啟動時，備份的聊天室金鑰會自動還原到新的加密儲存中。
• 如果舊版外掛有從未備份過的僅限本地聊天室金鑰，OpenClaw 會發出明確警告。這些金鑰無法從先前的 Rust 加密儲存中自動匯出，因此某些舊的加密歷史紀錄可能在手動復原前保持不可用。
• 參考 Matrix migration 了解完整的升級流程、限制、復原命令和常見遷移訊息。

加密的執行階段狀態組織在 ~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/ 下的各帳號、各使用者 token-hash 根目錄中。 該目錄包含同步儲存 (bot-storage.json)、加密儲存 (crypto/)、 復原金鑰檔案 (recovery-key.json)、IndexedDB 快照 (crypto-idb-snapshot.json)、 討論串綁定 (thread-bindings.json) 以及啟動驗證狀態 (startup-verification.json)。 當 token 變更但帳號身份保持不變時，OpenClaw 會重複使用該帳號/homeserver/使用者組合的最佳現有根目錄，使先前的同步狀態、加密狀態、討論串綁定和啟動驗證狀態保持可見。

Node crypto 儲存模型

此外掛中的 Matrix E2EE 使用 Node 中官方的 matrix-js-sdk Rust crypto 路徑。 該路徑需要 IndexedDB 支援的持久化，才能讓加密狀態在重啟後存續。

OpenClaw 目前在 Node 中透過以下方式提供支援：

• 使用 fake-indexeddb 作為 SDK 所需的 IndexedDB API 墊片 (shim)
• 在 initRustCrypto 之前從 crypto-idb-snapshot.json 還原 Rust crypto IndexedDB 內容
• 在初始化後及執行期間將更新的 IndexedDB 內容持久化回 crypto-idb-snapshot.json

這是相容性與儲存層的處理，並非自定義的加密實作。 快照檔案是敏感的執行階段狀態，儲存時具有嚴格的文件權限。 在 OpenClaw 的安全模型下，Gateway 主機和本地 OpenClaw 狀態目錄已經在受信任的操作邊界內，因此這主要是操作可靠性的考量，而非獨立的遠端信任邊界。

計劃中的改進：

• 為持久化 Matrix 金鑰資料加入 SecretRef 支援，以便從 OpenClaw 秘密提供者 (secrets providers) 獲取復原金鑰和相關的儲存加密秘密，而不僅僅是本地檔案。

個人資料管理

使用以下命令更新所選帳號的 Matrix 個人資料：

openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png

當你想要明確針對某個具名 Matrix 帳號時，請加入 --account <id>。

Matrix 直接接受 mxc:// 頭像 URL。當你傳遞 http:// 或 https:// 頭像 URL 時，OpenClaw 會先將其上傳到 Matrix，並將解析後的 mxc:// URL 存回 channels.matrix.avatarUrl（或所選帳號的覆蓋設定）。

自動驗證通知

Matrix 現在會將驗證生命週期通知作為 m.notice 訊息直接發送到嚴格的 DM 驗證聊天室中。 這包括：

• 驗證請求通知
• 驗證就緒通知（帶有明確的「透過表情符號驗證」指引）
• 驗證開始與完成通知
• 可用時的 SAS 詳細資訊（表情符號和十進位制）

來自另一個 Matrix 用戶端的傳入驗證請求會被 OpenClaw 追蹤並自動接受。 對於自我驗證流程，當表情符號驗證可用時，OpenClaw 也會自動啟動 SAS 流程並確認自己的一方。 對於來自另一個 Matrix 使用者/裝置的驗證請求，OpenClaw 會自動接受請求，然後等待 SAS 流程正常進行。 你仍然需要在你的 Matrix 用戶端中比對表情符號或十進位制 SAS，並在那裡確認「它們匹配」以完成驗證。

OpenClaw 不會盲目地自動接受自我發起的重複流程。啟動程序在已有待處理的自我驗證請求時，會跳過建立新請求。

驗證協定/系統通知不會被轉發到代理人對話管線，因此不會產生 NO_REPLY。

裝置清理

舊的 OpenClaw 管理的 Matrix 裝置可能會在帳號上累積，使得加密聊天室的信任關係變得難以判斷。 使用以下命令列出它們：

openclaw matrix devices list

使用以下命令移除過時的 OpenClaw 管理裝置：

openclaw matrix devices prune-stale

直接聊天室修復 (Direct Room Repair)

如果直接訊息 (DM) 狀態失去同步，OpenClaw 可能會殘留過時的 m.direct 映射，指向舊的單人聊天室而非活躍的 DM。使用以下命令檢查對象的目前映射：

openclaw matrix direct inspect --user-id @alice:example.org

使用以下命令進行修復：

openclaw matrix direct repair --user-id @alice:example.org

修復過程會保留外掛內部的 Matrix 特定邏輯：

• 它會優先選擇已映射在 m.direct 中的嚴格 1:1 DM
• 否則，它會退而求其次選擇任何目前已加入且與該使用者建立的嚴格 1:1 DM
• 如果不存在健康的 DM，它會建立一個全新的直接聊天室並重寫 m.direct 指向它

修復流程不會自動刪除舊聊天室。它只會挑選健康的 DM 並更新映射，以便新的 Matrix 發送、驗證通知和其他直接訊息流程能再次針對正確的聊天室。

討論串 (Threads)

Matrix 支援原生 Matrix 討論串，可用於自動回覆和訊息工具發送。

• threadReplies: "off" 讓回覆保持在頂層，並將傳入的討論串訊息保留在父會話中。
• threadReplies: "inbound" 僅當傳入訊息已在討論串中時，才在討論串內回覆。
• threadReplies: "always" 將聊天室回覆保留在以觸發訊息為根的討論串中，並透過來自第一條觸發訊息的對應討論串範圍會話來路由該對話。
• dm.threadReplies 僅針對 DM 覆蓋頂層設定。例如，你可以保持聊天室討論串隔離，同時讓 DM 保持扁平。
• 傳入的討論串訊息會包含討論串根訊息作為額外的代理人上下文。
• 訊息工具發送現在會自動繼承目前的 Matrix 討論串（當目標是同一個聊天室或同一個 DM 使用者時），除非提供了明確的 threadId。
• Matrix 支援執行階段討論串綁定。/focus, /unfocus, /agents, /session idle, /session max-age, 以及綁定討論串的 /acp spawn 現在都能在 Matrix 聊天室和 DM 中運作。
• 當 threadBindings.spawnSubagentSessions=true 時，頂層 Matrix 聊天室/DM 的 /focus 會建立一個新的 Matrix 討論串並將其綁定到目標會話。
• 在現有的 Matrix 討論串中執行 /focus 或 /acp spawn --thread here 則會改為綁定該目前的討論串。

ACP 對話綁定

Matrix 房間、私訊 (DM) 和現有的 Matrix 討論串 (thread) 都可以變成持久的 ACP 工作空間，而且不需要改變聊天介面。

快速操作流程：

• 在你想繼續使用的 Matrix 私訊、房間或現有討論串中執行 /acp spawn codex --bind here。
• 在頂層 Matrix 私訊或房間中，目前的私訊/房間會維持聊天介面，未來的訊息會路由到生成的 ACP 工作階段。
• 在現有的 Matrix 討論串中，--bind here 會就地綁定該討論串。
• /new 和 /reset 會就地重設同一個綁定的 ACP 工作階段。
• /acp close 會關閉 ACP 工作階段並移除綁定。

注意：

• --bind here 不會建立子 Matrix 討論串。
• 只有在使用 /acp spawn --thread auto|here 且 OpenClaw 需要建立或綁定子 Matrix 討論串時，才需要設定 threadBindings.spawnAcpSessions。

討論串綁定配置

Matrix 會繼承 session.threadBindings 的全域預設值，也支援每個頻道的覆寫：

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSubagentSessions
• threadBindings.spawnAcpSessions

Matrix 討論串綁定的生成 flag 是手動開啟的：

• 設定 threadBindings.spawnSubagentSessions: true 來允許頂層 /focus 建立並綁定新的 Matrix 討論串。
• 設定 threadBindings.spawnAcpSessions: true 來允許 /acp spawn --thread auto|here 綁定 ACP 工作階段到 Matrix 討論串。

表情符號回應

Matrix 支援傳出回應動作、傳入回應通知以及傳入的 ack 回應。

• 傳出回應工具受到 channels["matrix"].actions.reactions 的限制。
• react 會在特定的 Matrix 事件上新增回應。
• reactions 會列出特定 Matrix 事件目前的回應摘要。
• emoji="" 會移除機器人帳號在該事件上的所有回應。
• remove: true 只會從機器人帳號中移除指定的 emoji 回應。

Ack 回應使用標準的 OpenClaw 解析順序：

• channels["matrix"].accounts.<accountId>.ackReaction
• channels["matrix"].ackReaction
• messages.ackReaction
• 代理人身分 emoji 備案

Ack 回應範圍的解析順序如下：

• channels["matrix"].accounts.<accountId>.ackReactionScope
• channels["matrix"].ackReactionScope
• messages.ackReactionScope

回應通知模式的解析順序如下：

• channels["matrix"].accounts.<accountId>.reactionNotifications
• channels["matrix"].reactionNotifications
• 預設值：own

目前的行為：

• reactionNotifications: "own" 會在 m.reaction 事件針對機器人發布的 Matrix 訊息時轉發該事件。
• reactionNotifications: "off" 會停用回應系統事件。
• 回應移除目前仍不會合成為系統事件，因為 Matrix 將其呈現為撤回 (redactions)，而不是獨立的 m.reaction 移除。

歷史紀錄上下文

• channels.matrix.historyLimit 控制當 Matrix 房間訊息觸發代理人時，有多少最近的房間訊息會被包含在 InboundHistory 中。
• 它會退而求其次使用 messages.groupChat.historyLimit。設定為 0 即可停用。
• Matrix 房間歷史紀錄僅限房間。私訊則繼續使用正常的工作階段歷史紀錄。
• Matrix 房間歷史紀錄僅限待處理 (pending-only)：OpenClaw 會緩衝尚未觸發回覆的房間訊息，然後在提到 (mention) 或其他觸發條件到達時擷取該視窗的快照。
• 目前的觸發訊息不會包含在 InboundHistory 中；它會保留在該輪的主要傳入內容中。
• 重試同一個 Matrix 事件時會重複使用原始的歷史紀錄快照，而不是向後漂移到較新的房間訊息。
• 抓取的房間上下文（包括回覆和討論串上下文查找）會受到發送者允許清單 (groupAllowFrom) 的過濾，因此非允許清單中的訊息會被排除在代理人上下文之外。

私訊與房間政策範例

{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}

參考 Groups 了解標記限制和允許清單行為。

Matrix 私訊的配對範例：

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

如果未經核准的 Matrix 使用者在核准前不斷傳訊息給你，OpenClaw 會重複使用同一個待處理的配對代碼，並可能在短暫的冷卻時間後再次發送提醒回覆，而不是產生新的代碼。

參考 Pairing 了解共享的私訊配對流程和儲存佈局。

多帳號範例

{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}

channels.matrix 的頂層數值會作為具名帳號的預設值，除非該帳號有另外覆寫。

你可以用 groups.<room>.account（或舊版的 rooms.<room>.account）將繼承的房間項目限制在特定的 Matrix 帳號。沒有設定 account 的項目會由所有 Matrix 帳號共享，而當預設帳號直接設定在頂層 channels.matrix.* 時，標記為 account: "default" 的項目依然有效。

部分共享的驗證預設值本身不會建立獨立的隱含預設帳號。只有當頂層 default 帳號擁有完整的驗證資訊（homeserver 加上 accessToken，或 homeserver 加上 userId 與 password）時，OpenClaw 才會合成該帳號；當快取的憑證稍後滿足驗證需求時，具名帳號仍可透過 homeserver 加上 userId 被找到。

當你希望 OpenClaw 在隱含路由、探測和 CLI 操作中優先使用某個具名 Matrix 帳號時，請設定 defaultAccount。如果你設定了多個具名帳號，請設定 defaultAccount，或在依賴隱含帳號選擇的 CLI 命令中傳入 --account <id>。

當你想在特定命令中覆寫隱含選擇時，請將 --account <id> 傳給 openclaw matrix verify ... 或 openclaw matrix devices ...。

私有/區域網路 homeservers

為了防止 SSRF 攻擊，OpenClaw 預設會封鎖私有或內部的 Matrix homeservers，除非你針對個別帳號明確啟用。

如果你的 homeserver 執行在 localhost、區域網路/Tailscale IP 或內部主機名稱上，請為該 Matrix 帳號啟用 allowPrivateNetwork：

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

CLI 設定範例：

openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx

此選項僅允許受信任的私有/內部目標。像 http://matrix.example.org:8008 這樣的公開明文 homeservers 仍會被封鎖。請盡可能優先使用 https://。

代理 Matrix 流量

如果你的 Matrix 部署需要明確的 HTTP(S) 出站 Proxy，請設定 channels.matrix.proxy：

{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}

具名帳號可以用 channels.matrix.accounts.<id>.proxy 來覆蓋頂層的預設值。OpenClaw 會在運行時的 Matrix 流量和帳號狀態探測中使用相同的 Proxy 設定。

目標解析

在 OpenClaw 要求你提供房間或使用者目標的任何地方，Matrix 都接受以下這些目標格式：

• 使用者：@user:server、user:@user:server 或 matrix:user:@user:server
• 房間：!room:server、room:!room:server 或 matrix:room:!room:server
• 別名：#alias:server、channel:#alias:server 或 matrix:channel:#alias:server

即時目錄查詢會使用已登入的 Matrix 帳號：

• 使用者查詢會請求該 Homeserver 上的 Matrix 使用者目錄。
• 房間查詢會直接接受明確的 Room ID 和別名，如果找不到，則會退而搜尋該帳號已加入的房間名稱。
• 已加入房間的名稱查詢是盡力而為的。如果房間名稱無法解析為 ID 或別名，運行時的 Allowlist 解析就會忽略它。

配置參考

• enabled: 啟用或停用此頻道。
• name: 帳號的選填標籤。
• defaultAccount: 設定多個 Matrix 帳號時的首選帳號 ID。
• homeserver: homeserver URL，例如 https://matrix.example.org。
• allowPrivateNetwork: 允許此 Matrix 帳號連線到私有/內部 homeserver。當 homeserver 解析為 localhost、區域網路/Tailscale IP 或內部主機（如 matrix-synapse）時請啟用此項。
• proxy: Matrix 流量的選填 HTTP(S) 代理 URL。具名帳號可以用自己的 proxy 覆蓋頂層的預設值。
• userId: 完整的 Matrix 使用者 ID，例如 @bot:example.org。
• accessToken: 基於 token 認證的存取權杖。在 env/file/exec 供應商中，channels.matrix.accessToken 和 channels.matrix.accounts.<id>.accessToken 都支援純文字和 SecretRef 值。請參考 Secrets Management。
• password: 密碼登入使用的密碼。支援純文字和 SecretRef 值。
• deviceId: 明確的 Matrix 裝置 ID。
• deviceName: 密碼登入時顯示的裝置名稱。
• avatarUrl: 儲存的個人頭像 URL，用於個人資料同步和 set-profile 更新。
• initialSyncLimit: 啟動時的同步事件限制。
• encryption: 啟用 E2EE。
• allowlistOnly: 強制對 DM 和房間執行僅限白名單的行為。
• groupPolicy: open、allowlist 或 disabled。
• groupAllowFrom: 房間流量的使用者 ID 白名單。
• groupAllowFrom 的項目應為完整的 Matrix 使用者 ID。未解析的名稱在執行時會被忽略。
• historyLimit: 作為群組歷史上下文包含的房間訊息上限。若未設定則回退到 messages.groupChat.historyLimit。設為 0 則停用。
• replyToMode: off、first 或 all。
• streaming: off（預設）或 partial。partial 支援單條訊息的草稿預覽與原地編輯更新。
• threadReplies: off、inbound 或 always。
• threadBindings: 針對執行緒綁定（thread-bound）的 session 路由與生命週期的各頻道覆蓋設定。
• startupVerification: 啟動時的自動自我驗證請求模式（if-unverified、off）。
• startupVerificationCooldownHours: 重試自動啟動驗證請求前的冷卻時間。
• textChunkLimit: 外發訊息的區塊大小。
• chunkMode: length 或 newline。
• responsePrefix: 外發回覆的選填訊息前綴。
• ackReaction: 此頻道/帳號的選填 ack 反應（reaction）覆蓋。
• ackReactionScope: 選填的 ack 反應範圍覆蓋（group-mentions、group-all、direct、all、none、off）。
• reactionNotifications: 入站反應通知模式（own、off）。
• mediaMaxMb: Matrix 媒體處理的媒體大小上限（MB）。適用於外發傳送和入站媒體處理。
• autoJoin: 邀請自動加入策略（always、allowlist、off）。預設值：off。
• autoJoinAllowlist: 當 autoJoin 為 allowlist 時允許的房間/別名。別名項目在處理邀請時會解析為房間 ID；OpenClaw 不會信任受邀房間所聲稱的別名狀態。
• dm: DM 策略區塊（enabled、policy、allowFrom、threadReplies）。
• dm.allowFrom 項目應為完整的 Matrix 使用者 ID，除非你已經透過即時目錄查詢解析過它們。
• dm.threadReplies: DM-only 執行緒策略覆蓋（off、inbound、always）。它會覆蓋 DM 中回覆位置和 session 隔離的頂層 threadReplies 設定。
• accounts: 具名的個別帳號覆蓋。頂層 channels.matrix 的值會作為這些項目的預設值。
• groups: 個別房間的策略對照表。建議使用房間 ID 或別名；未解析的房間名稱在執行時會被忽略。Session/群組識別在解析後會使用穩定的房間 ID，而易於閱讀的標籤仍來自房間名稱。
• rooms: groups 的舊版別名。
• actions: 個別動作的工具門控（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。

相關文件

• 頻道概覽 — 所有支援的頻道
• 配對 — DM 認證與配對流程
• 群組 — 群組聊天行為與提及門控
• 頻道路由 — 訊息的 session 路由
• 安全性 — 存取模型與加固