Matrix

Documentation Index

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

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

​

隨附 Plugin

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，或邀請它加入房間（請參閱 auto-join — 只有在 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",
    },
  },
}

​

Auto-join

{
  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。只有在 homeserver 目錄剛好回傳一個相符項目時，才會解析顯示名稱。
• 房間（groups、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 會停止預覽串流，並退回只傳遞最終內容。
• 媒體回覆一律正常傳送附件。如果過期預覽無法再安全重用，OpenClaw 會在傳送最終媒體回覆前將其 redact。
• Matrix 預覽串流啟用時，預設會啟用工具進度預覽更新。設定 streaming.preview.toolProgress: false 可保留答案文字的預覽編輯，但讓工具進度走一般傳遞路徑。
• 預覽編輯會耗費額外的 Matrix API 呼叫。如果你想要最保守的 rate-limit profile，請保留 streaming: "off"。

​

核准 metadata

​

自行託管的 quiet 最終預覽 push rule

​

Bot 對 bot 房間

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

• allowBots: true 會接受來自其他已設定 Matrix bot 帳號、且位於允許房間與 DM 中的訊息。
• allowBots: "mentions" 只會在那些訊息於房間中明顯提及此 bot 時接受。DM 仍然允許。
• groups.<room>.allowBots 會覆寫單一房間的帳號層級設定。
• OpenClaw 仍會忽略來自相同 Matrix 使用者 ID 的訊息，以避免自我回覆迴圈。
• Matrix 在此不公開原生 bot 旗標；OpenClaw 將「bot-authored」視為「由此 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"：在以觸發訊息為根的執行緒內回覆；該對話會從第一次觸發起，透過相符的執行緒範圍工作階段路由。

​

執行緒繼承與斜線命令

• 傳入的對話串訊息會包含對話串根訊息，作為額外的 agent 脈絡。
• 訊息工具傳送在目標為同一個房間（或同一個 DM 使用者目標）時，會自動繼承目前的 Matrix 對話串，除非明確提供 threadId。
• DM 使用者目標重用只有在目前工作階段中繼資料證明是同一個 Matrix 帳號上的同一個 DM 對象時才會啟用；否則 OpenClaw 會退回一般的使用者範圍路由。
• /focus、/unfocus、/agents、/session idle、/session max-age，以及繫結對話串的 /acp spawn 都可在 Matrix 房間和 DM 中使用。
• 當 threadBindings.spawnSubagentSessions: true 時，頂層 /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.spawnAcpSessions 只有在 /acp spawn --thread auto|here 時才需要，此時 OpenClaw 需要建立或繫結子 Matrix 對話串。

​

對話串繫結設定

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

• 設定 threadBindings.spawnSubagentSessions: true，允許頂層 /focus 建立並繫結新的 Matrix 對話串。
• 設定 threadBindings.spawnAcpSessions: true，允許 /acp spawn --thread auto|here 將 ACP 工作階段繫結到 Matrix 對話串。

​

回應

• react 會將回應新增到 Matrix 事件。
• reactions 會列出 Matrix 事件目前的回應摘要。
• emoji="" 會移除該事件上 bot 自己的回應。
• remove: true 只會從 bot 移除指定的 emoji 回應。

​

歷史脈絡

• channels.matrix.historyLimit 控制當 Matrix 房間訊息觸發 agent 時，會有多少最近的房間訊息作為 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：選用允許清單，指定哪些 agent/工作階段會觸發 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 與別名，然後退回搜尋該帳號已加入的房間名稱。
• 已加入房間的名稱查詢是盡力而為。如果房間名稱無法解析為 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) Proxy URL。支援逐帳號覆寫。
• userId：完整的 Matrix 使用者 ID（@bot:example.org）。
• accessToken：Token 型驗證的存取 Token。支援跨 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" 政策。
• 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：此頻道/帳號的 ack 回應覆寫。
• 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：逐房間 skill 篩選器。
  • 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 驗證與配對流程
• 群組 — 群組聊天行為與提及控管
• 頻道路由 — 訊息的工作階段路由
• 安全性 — 存取模型與強化