矩陣

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

安裝

openclaw plugins install @openclaw/matrix

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

​

設定

1. 在你的 homeserver 上建立 Matrix 帳號。
2. 使用 homeserver + accessToken，或 homeserver + userId + password 設定 channels.matrix。
3. 重新啟動 Gateway。
4. 與 bot 開始 DM，或邀請它加入房間（請參閱 自動加入 - 只有在 autoJoin 允許時，新的邀請才會加入）。

​

互動式設定

openclaw channels add
openclaw configure --section channels

​

最小設定

{
  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", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}

​

自動加入

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

​

Allowlist 目標格式

• DM（dm.allowFrom、groupAllowFrom、groups.<room>.users）：使用 @user:server。顯示名稱預設會被忽略，因為它們可變；只有在你明確需要與顯示名稱項目相容時，才設定 dangerouslyAllowNameMatching: true。
• 房間 allowlist 鍵（groups，舊版 rooms）：使用 !room:server 或 #alias:server。純房間名稱預設會被忽略；只有在你明確需要與已加入房間的名稱查詢相容時，才設定 dangerouslyAllowNameMatching: true。
• 邀請 allowlist（autoJoinAllowlist）：使用 !room:server、#alias:server 或 *。純房間名稱會被拒絕。

​

帳號 ID 正規化

​

快取憑證

• 預設帳號：credentials.json
• 命名帳號：credentials-<account>.json

​

環境變數

​

設定範例

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

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        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",
    },
  },
}

​

串流預覽

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

{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}

• 如果預覽超過 Matrix 的每事件大小限制，OpenClaw 會停止預覽串流，並 fallback 到僅最終傳送。
• 媒體回覆一律正常傳送附件。如果過期預覽已無法安全重複使用，OpenClaw 會在傳送最終媒體回覆前 redacts 它。
• 當 Matrix 預覽串流啟用時，工具進度預覽更新預設也會啟用。設定 streaming.preview.toolProgress: false 可保留回答文字的預覽編輯，但讓工具進度走一般傳送路徑。
• 預覽編輯會增加額外 Matrix API 呼叫。如果你想要最保守的 rate-limit profile，請保留 streaming: "off"。

​

核准中繼資料

​

自架 push rule，用於安靜的最終預覽

​

Bot 對 bot 房間

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

• allowBots: true 會接受允許房間與 DM 中來自其他已設定 Matrix bot 帳號的訊息。
• allowBots: "mentions" 只會在這些訊息於房間中明顯提及此 bot 時接受。DM 仍然允許。
• groups.<room>.allowBots 會覆寫單一房間的帳號層級設定。
• OpenClaw 仍會忽略來自相同 Matrix 使用者 ID 的訊息，以避免自我回覆迴圈。
• Matrix 在這裡不會公開原生 bot flag；OpenClaw 將「bot 撰寫」視為「由此 OpenClaw Gateway 上另一個已設定 Matrix 帳號傳送」。

​

加密與驗證

​

啟用加密

openclaw matrix encryption setup

• --recovery-key <key> 在啟動前套用復原金鑰（建議使用下方記載的 stdin 形式）
• --force-reset-cross-signing 捨棄目前的交叉簽署身分並建立新的身分（僅在有意如此時使用）

openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee

{
  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 --include-recovery-key --json

• Locally trusted：僅受此用戶端信任
• Cross-signing verified：SDK 回報已透過交叉簽署驗證
• Signed by owner：由你自己的自簽金鑰簽署（僅供診斷）

​

使用復原金鑰驗證此裝置

printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin

• Recovery key accepted：Matrix 已接受此金鑰，用於秘密儲存或裝置信任。
• Backup usable：可使用受信任的復原素材載入房間金鑰備份。
• Device verified by owner：此裝置具備完整的 Matrix 交叉簽署身分信任。

openclaw matrix verify self

​

啟動或修復交叉簽署

openclaw matrix verify bootstrap

• 啟動秘密儲存，並在可能時重用既有復原金鑰
• 啟動交叉簽署並上傳缺少的公開金鑰
• 標記並交叉簽署目前裝置
• 若尚不存在，建立伺服器端房間金鑰備份

• --recovery-key-stdin（搭配 printf '%s\n' "$MATRIX_RECOVERY_KEY" | …）或 --recovery-key <key>
• --force-reset-cross-signing 用於捨棄目前的交叉簽署身分（僅在有意如此時使用）

​

房間金鑰備份

openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin

openclaw matrix verify backup reset --yes

​

列出、要求與回應驗證

openclaw matrix verify list

openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF

​

多帳號注意事項

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway

openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'

openclaw matrix devices list
openclaw matrix devices prune-stale

​

個人檔案管理

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

​

執行緒

​

工作階段路由（sessionScope）

• "per-user"（預設）：與同一個已路由對等方的所有 DM 房間共用一個工作階段。
• "per-room"：每個 Matrix DM 房間都有自己的工作階段鍵，即使對等方相同也一樣。

​

回覆執行緒（threadReplies）

• "off"：回覆是頂層訊息。傳入的執行緒訊息會留在父工作階段。
• "inbound"：只有當傳入訊息已在該執行緒中時，才在執行緒內回覆。
• "always"：在以觸發訊息為根的執行緒內回覆；該對話會從第一次觸發開始，透過相符的執行緒範圍工作階段路由。

​

執行緒繼承與斜線命令

• 傳入的對話串訊息會將對話串根訊息納入為額外代理上下文。
• 訊息工具傳送在目標為同一個聊天室（或相同的 DM 使用者目標）時，會自動繼承目前的 Matrix 對話串，除非明確提供 threadId。
• 只有當目前工作階段中繼資料證明同一個 Matrix 帳號上的同一位 DM 對象時，DM 使用者目標重用才會啟用；否則 OpenClaw 會退回一般的使用者範圍路由。
• /focus、/unfocus、/agents、/session idle、/session max-age，以及繫結對話串的 /acp spawn 都可在 Matrix 聊天室和 DM 中運作。
• 當 threadBindings.spawnSessions 啟用時，頂層 /focus 會建立新的 Matrix 對話串，並將其繫結至目標工作階段。
• 在既有 Matrix 對話串內執行 /focus 或 /acp spawn --thread here，會就地繫結該對話串。

​

ACP 對話綁定

• 在你想繼續使用的 Matrix DM、聊天室或既有對話串內執行 /acp spawn codex --bind here。
• 在頂層 Matrix DM 或聊天室中，目前的 DM/聊天室會保留為聊天介面，未來訊息會路由至產生的 ACP 工作階段。
• 在既有 Matrix 對話串內，--bind here 會就地繫結目前對話串。
• /new 和 /reset 會就地重設同一個已繫結的 ACP 工作階段。
• /acp close 會關閉 ACP 工作階段並移除綁定。

• --bind here 不會建立子 Matrix 對話串。
• threadBindings.spawnSessions 會控管 /acp spawn --thread auto|here，此時 OpenClaw 需要建立或繫結子 Matrix 對話串。

​

對話串綁定設定

• threadBindings.enabled
• threadBindings.idleHours
• threadBindings.maxAgeHours
• threadBindings.spawnSessions
• threadBindings.defaultSpawnContext

• 設定 threadBindings.spawnSessions: false，可阻止頂層 /focus 和 /acp spawn --thread auto|here 建立/繫結 Matrix 對話串。
• 當原生子代理對話串產生不應分叉父層轉錄時，設定 threadBindings.defaultSpawnContext: "isolated"。

​

表情回應

• react 會為 Matrix 事件加入表情回應。
• reactions 會列出 Matrix 事件目前的表情回應摘要。
• emoji="" 會移除機器人在該事件上的自身表情回應。
• remove: true 只會移除機器人的指定 emoji 表情回應。

​

歷史上下文

• channels.matrix.historyLimit 控制當 Matrix 聊天室訊息觸發代理時，會有多少最近聊天室訊息以 InboundHistory 納入。會退回 messages.groupChat.historyLimit；如果兩者都未設定，有效預設值為 0。設定 0 可停用。
• Matrix 聊天室歷史只限聊天室。DM 會繼續使用一般工作階段歷史。
• Matrix 聊天室歷史僅限待處理：OpenClaw 會緩衝尚未觸發回覆的聊天室訊息，然後在提及或其他觸發到達時快照該視窗。
• 目前的觸發訊息不會包含在 InboundHistory 中；它會保留在該回合的主要傳入本文中。
• 同一個 Matrix 事件的重試會重用原始歷史快照，而不是向前漂移到較新的聊天室訊息。

​

上下文可見性

• contextVisibility: "all" 是預設值。補充上下文會照收到的樣子保留。
• contextVisibility: "allowlist" 會將補充上下文篩選為作用中聊天室/使用者允許清單檢查所允許的傳送者。
• contextVisibility: "allowlist_quote" 的行為類似 allowlist，但仍會保留一則明確引用的回覆。

​

DM 與聊天室政策

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

{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}

openclaw pairing list matrix
openclaw pairing approve matrix <CODE>

​

直接聊天室修復

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

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

• 優先使用已在 m.direct 中對應的嚴格 1:1 DM
• 退回任何目前已加入且包含該使用者的嚴格 1:1 DM
• 如果沒有健康的 DM，則建立新的直接聊天室並重寫 m.direct

​

Exec 核准

• enabled：透過 Matrix 原生提示傳遞核准。未設定或為 "auto" 時，只要至少可解析一位核准者，Matrix 就會自動啟用。設定 false 可明確停用。
• approvers：允許核准 exec 要求的 Matrix 使用者 ID（@owner:example.org）。選用，會退回 channels.matrix.dm.allowFrom。
• target：提示要送往的位置。"dm"（預設）會傳送至核准者 DM；"channel" 會傳送至來源 Matrix 聊天室或 DM；"both" 會同時傳送至兩者。
• agentFilter / sessionFilter：選用的允許清單，用於指定哪些代理/工作階段會觸發 Matrix 傳遞。

• Exec 核准使用 execApprovals.approvers，並退回 dm.allowFrom。
• Plugin 核准只透過 dm.allowFrom 授權。

• ✅ 允許一次
• ❌ 拒絕
• ♾️ 一律允許（當有效 exec 政策允許時）

​

斜線命令

​

多帳號

{
  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 將繼承的聊天室項目限制在特定帳號。沒有 account 的項目會在帳號之間共用；當預設帳號在頂層設定時，account: "default" 仍會運作。

• 設定 defaultAccount，以選擇隱含路由、探測和 CLI 命令偏好的具名帳號。
• 如果你有多個帳號，且其中一個實際命名為 default，即使未設定 defaultAccount，OpenClaw 也會隱含使用它。
• 如果你有多個具名帳號且未選取預設值，CLI 命令會拒絕猜測，請設定 defaultAccount 或傳入 --account <id>。
• 只有當頂層 channels.matrix.* 區塊的驗證資訊完整時（homeserver + accessToken，或 homeserver + userId + password），才會被視為隱含的 default 帳號。一旦快取憑證涵蓋驗證，具名帳號仍可從 homeserver + userId 探索。

• 當 OpenClaw 在修復或設定期間將單帳號設定提升為多帳號時，如果既有具名帳號存在，或 defaultAccount 已指向某個帳號，它會保留該帳號。只有 Matrix 驗證/啟動程序鍵會移入提升後的帳號；共用的傳遞政策鍵會保留在頂層。

​

私有/LAN homeserver

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

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

​

代理 Matrix 流量

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

​

目標解析

• 使用者：@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

• 使用者查詢會查詢該 homeserver 上的 Matrix 使用者目錄。
• 房間查詢會直接接受明確的房間 ID 和別名。已加入房間的名稱查詢是盡力而為，而且只有在設定 dangerouslyAllowNameMatching: true 時，才會套用到執行階段房間允許清單。
• 如果房間名稱無法解析為 ID 或別名，執行階段允許清單解析會忽略它。

​

設定參考

​

帳戶與連線

• enabled：啟用或停用此頻道。
• name：帳戶的可選顯示標籤。
• defaultAccount：設定多個 Matrix 帳戶時偏好的帳戶 ID。
• accounts：具名的每帳戶覆寫。頂層 channels.matrix 值會作為預設值繼承。
• homeserver：homeserver URL，例如 https://matrix.example.org。
• network.dangerouslyAllowPrivateNetwork：允許此帳戶連線到 localhost、LAN/Tailscale IP 或內部主機名稱。
• proxy：Matrix 流量的可選 HTTP(S) 代理 URL。支援每帳戶覆寫。
• userId：完整 Matrix 使用者 ID（@bot:example.org）。
• accessToken：權杖式驗證的存取權杖。支援跨 env/file/exec 提供者的純文字與 SecretRef 值（密鑰管理）。
• password：密碼式登入的密碼。支援純文字與 SecretRef 值。
• deviceId：明確的 Matrix 裝置 ID。
• deviceName：密碼登入時使用的裝置顯示名稱。
• avatarUrl：為個人資料同步與 profile set 更新儲存的自身頭像 URL。
• initialSyncLimit：啟動同步期間擷取的最大事件數。

​

加密

• encryption：啟用 E2EE。預設：false。
• startupVerification："if-unverified"（E2EE 開啟時的預設值）或 "off"。當此裝置尚未驗證時，啟動時會自動要求自我驗證。
• startupVerificationCooldownHours：下一次自動啟動要求前的冷卻時間。預設：24。

​

存取與政策

• groupPolicy："open"、"allowlist" 或 "disabled"。預設："allowlist"。
• groupAllowFrom：房間流量的使用者 ID 允許清單。
• dm.enabled：當為 false 時，忽略所有 DM。預設：true。
• dm.policy："pairing"（預設）、"allowlist"、"open" 或 "disabled"。在 bot 已加入並將房間分類為 DM 後套用；不影響邀請處理。
• dm.allowFrom：DM 流量的使用者 ID 允許清單。
• dm.sessionScope："per-user"（預設）或 "per-room"。
• dm.threadReplies：僅限 DM 的回覆串接覆寫（"off"、"inbound"、"always"）。
• allowBots：接受來自其他已設定 Matrix bot 帳戶的訊息（true 或 "mentions"）。
• allowlistOnly：當為 true 時，強制所有作用中的 DM 政策（除了 "disabled"）與 "open" 群組政策改為 "allowlist"。不變更 "disabled" 政策。
• dangerouslyAllowNameMatching：當為 true 時，允許針對使用者允許清單項目進行 Matrix 顯示名稱目錄查找，以及針對房間允許清單鍵進行已加入房間名稱查找。偏好使用完整 @user:server ID 以及房間 ID 或別名。
• autoJoin："always"、"allowlist" 或 "off"。預設："off"。套用於每個 Matrix 邀請，包括 DM 風格邀請。
• autoJoinAllowlist：當 autoJoin 為 "allowlist" 時允許的房間/別名。別名項目會依據 homeserver 解析，而不是依據受邀房間宣稱的狀態。
• contextVisibility：補充內容可見性（"all" 預設、"allowlist"、"allowlist_quote"）。

​

回覆行為

• replyToMode："off"、"first"、"all" 或 "batched"。
• threadReplies："off"、"inbound" 或 "always"。
• threadBindings：針對執行緒綁定工作階段路由與生命週期的每頻道覆寫。
• streaming："off"（預設）、"partial"、"quiet"，或物件形式 { mode, preview: { toolProgress } }。true ↔ "partial"，false ↔ "off"。
• blockStreaming：當為 true 時，完成的助理區塊會保留為獨立進度訊息。
• markdown：輸出文字的可選 Markdown 算繪設定。
• responsePrefix：附加到輸出回覆前方的可選字串。
• textChunkLimit：當 chunkMode: "length" 時，輸出分塊大小，以字元計。預設：4000。
• chunkMode："length"（預設，依字元數分割）或 "newline"（在行邊界分割）。
• historyLimit：當房間訊息觸發 agent 時，作為 InboundHistory 包含的近期房間訊息數量。會回退到 messages.groupChat.historyLimit；有效預設值為 0（停用）。
• mediaMaxMb：輸出傳送與輸入處理的媒體大小上限，以 MB 計。

​

反應設定

• ackReaction：此頻道/帳戶的確認反應覆寫。
• ackReactionScope：範圍覆寫（"group-mentions" 預設、"group-all"、"direct"、"all"、"none"、"off"）。
• reactionNotifications：輸入反應通知模式（"own" 預設、"off"）。

​

工具與每房間覆寫

• actions：每動作工具閘控（messages、reactions、pins、profile、memberInfo、channelInfo、verification）。
• groups：每房間政策對應。工作階段身分在解析後使用穩定的房間 ID。（rooms 是舊版別名。）
  • groups.<room>.account：將一個繼承的房間項目限制到特定帳戶。
  • groups.<room>.allowBots：頻道層級設定的每房間覆寫（true 或 "mentions"）。
  • groups.<room>.users：每房間傳送者允許清單。
  • groups.<room>.tools：每房間工具允許/拒絕覆寫。
  • groups.<room>.autoReply：每房間提及閘控覆寫。true 會停用該房間的提及要求；false 會強制重新開啟。
  • groups.<room>.skills：每房間技能篩選器。
  • groups.<room>.systemPrompt：每房間系統提示片段。

​

Exec 核准設定

• execApprovals.enabled：透過 Matrix 原生提示送出 exec 核准。
• execApprovals.approvers：允許核准的 Matrix 使用者 ID。會回退到 dm.allowFrom。
• execApprovals.target："dm"（預設）、"channel" 或 "both"。
• execApprovals.agentFilter / execApprovals.sessionFilter：用於傳遞的可選 agent/工作階段允許清單。

​

相關內容

• 頻道總覽 - 所有支援的頻道
• 配對 - DM 驗證與配對流程
• 群組 - 群組聊天行為與提及閘控
• 頻道路由 - 訊息的工作階段路由
• 安全性 - 存取模型與強化