OpenClaw Matrix 頻道
去中心化
中等
將 OpenClaw 連接到 Matrix——一個開放的聯邦通訊協定。此整合讓您的 AI 助理可以參與任何 Homeserver（matrix.org、Element 或自架）上的 Matrix 房間和私訊。OpenClaw 透過 Matrix Client-Server API 連接,並透過 Rust crypto SDK 提供可選的端對端加密(E2EE)支援。Matrix 頻道作為外掛發布,支援聯邦、執行緒、表情回應和豐富媒體。
快速資訊
難度中等
分類去中心化
支援功能數5 / 6
Matrix 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
支援
討論串
支援
語音訊息
不支援
群組聊天
支援
Matrix 前置條件
- 在任何 Homeserver（matrix.org、Element 或自架）上擁有活躍的 Matrix 帳戶
- 已安裝 Matrix 外掛:openclaw plugins install @openclaw/matrix
- OpenClaw Gateway 正在執行並已設定
- 伺服器上已安裝 Node.js 18+
Matrix 快速設定
1
安裝 Matrix 外掛
Matrix 頻道作為獨立外掛發布。透過 'openclaw plugins install @openclaw/matrix' 安裝。外掛將從 npm 倉庫下載並自動啟用。
2
取得 Matrix 憑證
您需要存取權杖或使用者名稱/密碼。對於存取權杖:使用 curl 呼叫 Homeserver 的登入端點並複製權杖。對於使用者名稱/密碼:Gateway 將自動登入並將權杖儲存在 ~/.openclaw/credentials/matrix/credentials.json 中。
3
新增 Matrix 頻道設定
將 Matrix 頻道設定新增到 ~/.openclaw/openclaw.json,包含您的 Homeserver URL 和憑證。您也可以使用環境變數 MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN、MATRIX_USER_ID 和 MATRIX_PASSWORD。
4
啟動 Gateway 並測試
執行 'openclaw gateway' 啟動服務。從另一個帳戶向您的 Matrix 機器人使用者傳送私訊。如果使用預設的配對策略,透過終端機中的 'openclaw pairing approve matrix <code>' 批准傳送者。
Matrix 設定範例
config.json
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.org",
"accessToken": "your_access_token_here",
"dmPolicy": "pairing"
}
}
}Matrix 深入了解
架構概覽
OpenClaw 透過 Client-Server API 連接到 Matrix,作為標準 Matrix 用戶端。架構是事件驅動的:您的機器人透過長輪詢同步請求接收事件(訊息、表情回應、成員變更),用 AI 處理它們,然後透過 API 傳送回應。
Matrix 是聯邦式的,這意味著您的機器人可以與全球 Matrix 網路上任何 Homeserver 的使用者通訊——不僅僅是您的機器人帳戶註冊的 Homeserver。這與 WhatsApp 或 Telegram 等中心化平台有本質區別。
流程是:使用者在 Matrix 中傳送訊息 → Homeserver 透過同步路由到您的 Gateway → OpenClaw 用 AI 處理 → 透過傳送事件 API 回覆 → 訊息透過聯邦傳遞。
聯邦意味著您在 matrix.org 上的機器人可以與任何 Matrix Homeserver(如 element.io、Mozilla 的 Homeserver 或自架實例)上的使用者聊天。
Matrix 外掛預設使用長輪詢。不需要 Webhook 或公開 URL——Gateway 向您的 Homeserver 建立出站連接。
驗證方法
OpenClaw 支援兩種 Matrix 驗證方式:
1. **存取權杖(推薦)** — 透過 curl 或 Matrix 用戶端呼叫 Homeserver 的登入 API 取得權杖。在設定中設定 channels.matrix.accessToken。系統自動透過 /whoami 端點取得您的使用者 ID。
2. **使用者名稱/密碼** — 設定 channels.matrix.userId 和 channels.matrix.password。OpenClaw 自動呼叫登入端點並將存取權杖儲存在 ~/.openclaw/credentials/matrix/credentials.json 中。
環境變數優先於設定檔:MATRIX_HOMESERVER、MATRIX_ACCESS_TOKEN、MATRIX_USER_ID、MATRIX_PASSWORD。
openclaw.json
# 存取權杖方法
{
"channels": {
"matrix": {
"homeserver": "https://matrix.example.org",
"accessToken": "syt_xxx..."
}
}
}
# 使用者名稱/密碼方法
{
"channels": {
"matrix": {
"homeserver": "https://matrix.example.org",
"userId": "@bot:example.org",
"password": "your_password"
}
}
}切勿將存取權杖或密碼提交到版本控制。在正式部署中使用環境變數。如果您的權杖被洩露,透過 Matrix 用戶端登出所有裝置以使所有權杖失效,然後產生新權杖。
私訊策略
私訊策略控制誰可以與您的 AI 助理互動。OpenClaw 支援四種策略:
• pairing(預設) — 未知使用者在首次聯絡時收到配對碼。透過 'openclaw pairing approve matrix <CODE>' 批准以授予存取權限。一旦批准,使用者可以自由聊天。
• allowlist — 只有明確列在 channels.matrix.dm.allowFrom 中的 Matrix 使用者 ID 可以向機器人傳訊息。其他人被靜默忽略。
• open — 任何向機器人傳訊息的人都會收到回應。需要 allowFrom: ["*"]。請謹慎使用。
• disabled — 完全關閉私訊處理。
白名單接受 @user:server 格式的完整 Matrix 使用者 ID(如 @alice:matrix.org)。
openclaw.json
{
"channels": {
"matrix": {
"dmPolicy": "allowlist",
"dm": {
"allowFrom": ["@alice:matrix.org", "@bob:example.org"]
}
}
}
}群組聊天(房間)支援
Matrix 群組對話稱為"房間"。預設情況下,OpenClaw 對房間使用白名單策略,需要提及啟動。您可以設定機器人參與的房間以及回應方式。
房間透過房間 ID(!roomId:server)或房間別名(#alias:server)識別。您可以設定特定房間的設定,如自動加入行為、提及要求和每個房間的使用者白名單。
openclaw.json
{
"channels": {
"matrix": {
"groupPolicy": "allowlist",
"groups": {
"!abc123:matrix.org": {
"allow": true,
"requireMention": false,
"users": ["@alice:matrix.org"]
},
"#team-chat:example.org": {
"allow": true
}
},
"autoJoin": "allowlist"
}
}
}將 autoJoin 設為 'always' 以自動接受所有房間邀請,'allowlist' 只加入已設定的房間,或 'off' 忽略邀請。
使用 requireMention: false 啟用無需提及機器人的自動回覆。在高流量房間中請謹慎使用。
端對端加密(E2EE)
Matrix 透過 Olm 和 Megolm 協定支援端對端加密(E2EE)。當您透過 Rust crypto SDK 啟用加密時,OpenClaw 可以參與加密房間。
啟用後,系統自動解密加密訊息,在受保護房間中加密出站媒體,並將加密狀態儲存在 ~/.openclaw/matrix/accounts/(SQLite)中。首次連接時需要裝置驗證——在 Element 或其他 Matrix 用戶端中批准驗證請求以啟用金鑰共享。
如果加密模組載入失敗,E2EE 被停用,加密房間將無法存取。
openclaw.json
{
"channels": {
"matrix": {
"encryption": true
}
}
}變更存取權杖需要重新驗證裝置。保留加密狀態目錄(~/.openclaw/matrix/accounts/)的備份,以防止失去存取加密訊息歷史的能力。
聯邦與 Homeserver 選擇
Matrix 是聯邦協定——沒有單一的中心伺服器。您可以選擇在任何 Homeserver 上註冊您的機器人:
• **matrix.org** — Matrix 基金會營運的旗艦 Homeserver。開放註冊,高可靠性,但由於高流量可能較慢。
• **Element Matrix Services** — 在 element.io 專業託管的 Homeserver,具有進階功能和支援。
• **自架** — 執行您自己的 Homeserver,實現最大控制和隱私。Synapse 是最成熟且仍在活躍開發的選項。Dendrite (Go) 和 Conduit (Rust) 是更輕量的替代方案,適合小型部署,但目前均已進入維護或有限開發模式。
無論您的機器人在哪裡註冊,它都可以與任何 Homeserver 上的使用者通訊,這要歸功於聯邦。
對於正式部署,考慮使用自架 Homeserver 或 Element Matrix Services 以獲得更好的控制和效能。
聯邦透明運作——使用者無需知道您的機器人在哪個 Homeserver 上。
執行緒與回覆模式
Matrix 透過 m.thread 關係類型支援執行緒對話。OpenClaw 可以參與執行緒並控制如何處理回覆。
threadReplies 設定控制執行緒行為:'off' 停用執行緒支援,'inbound' 只讀取執行緒脈絡,'always' 既讀取又建立執行緒回覆。replyToMode 設定控制回覆關係的中繼資料附加。
openclaw.json
{
"channels": {
"matrix": {
"threadReplies": "always",
"replyToMode": "reference"
}
}
}媒體處理與檔案上傳
Matrix 支援豐富媒體,包括圖片、影片、音訊和文件。OpenClaw 自動處理媒體上傳——檔案上傳到您的 Homeserver 的媒體儲存庫並在訊息事件中參照。
您可以透過 mediaMaxMb 設定設定最大檔案大小。預設入站媒體為 50 MB,出站傳送時對超大圖片自動進行 JPEG 最佳化和調整大小。
openclaw.json
{
"channels": {
"matrix": {
"mediaMaxMb": 50
}
}
}媒體上傳儲存在您的 Homeserver 上。如果您使用 matrix.org 等公開 Homeserver,請注意儲存限制和服務條款。
表情回應與豐富功能
OpenClaw 支援 Matrix 表情回應(對訊息的表情響應)、投票、位置分享(geo URI 格式)和其他豐富功能。如果啟用,可以透過工具傳送和讀取表情回應。
您可以透過 actions 設定限制特定操作,限制您的 AI 代理可以做什麼(表情回應、訊息、釘選、成員/頻道資訊)。
openclaw.json
{
"channels": {
"matrix": {
"actions": {
"reactions": true,
"messages": true,
"pins": false
}
}
}
}為什麼選擇 Matrix 作為自架 AI?
Matrix 是自架 AI 助理的絕佳選擇,因為:
• **真正開放** — 開放規範,無供應商鎖定,多個用戶端和伺服器實作。
• **聯邦式** — 無單點控制或故障。您的機器人可以在全球 Matrix 網路中通訊。
• **注重隱私** — E2EE 支援,自架選項,無中心化資料收集。
• **功能豐富** — 執行緒、表情回應、媒體、投票和可擴充的事件類型。
• **無需手機號碼** — 與 WhatsApp 或 Signal 不同,Matrix 註冊不需要手機號碼。
代價是複雜性:Matrix 的聯邦模型和 E2EE 設定可能比中心化平台更複雜。對於注重隱私的使用者和團隊來說,這種代價是值得的。
Matrix 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 啟用或停用 Matrix 頻道 |
| homeserver | string | "https://matrix.org" | Matrix Homeserver URL(如 https://matrix.org、https://element.io) |
| accessToken | string | "" | 用於驗證的 Matrix 存取權杖(推薦方法) |
| userId | string | "" | Matrix 使用者 ID(如 @bot:matrix.org)—— 與密碼驗證一起使用 |
| password | string | "" | Matrix 帳戶密碼——與 userId 一起用於登入 |
| encryption | boolean | false | 透過 Rust crypto SDK 啟用端對端加密 |
| dmPolicy | string | "pairing" | 私訊存取策略:pairing、allowlist、open 或 disabled |
| dm.allowFrom | array | [] | 允許私訊的 Matrix 使用者 ID(如 [@alice:matrix.org]) |
| groupPolicy | string | "allowlist" | 房間策略:allowlist 或 disabled |
| groups | object | {} | 特定房間設定(房間 ID 或別名作為鍵) |
| groups.<roomId>.allow | boolean | false | 允許機器人參與此房間 |
| groups.<roomId>.requireMention | boolean | true | 在此房間中需要提及機器人才能觸發回應 |
| groups.<roomId>.users | array | [] | 每個房間的使用者白名單(Matrix 使用者 ID) |
| autoJoin | string | "allowlist" | 自動加入房間邀請:always、allowlist 或 off |
| textChunkLimit | number | 4096 | 每條出站訊息的最大字元數 |
| chunkMode | string | "length" | 如何分割長回應:length(硬限制)或 newline(段落邊界) |
| threadReplies | string | "inbound" | 執行緒行為:off、inbound(唯讀)或 always(讀取+建立) |
| replyToMode | string | "reference" | 回覆中繼資料附加模式 |
| mediaMaxMb | number | 50 | 最大媒體檔案大小(MB) |
| actions.reactions | boolean | true | 允許代理傳送/讀取表情回應 |
| actions.messages | boolean | true | 允許代理讀取/傳送/編輯/刪除訊息 |
| actions.pins | boolean | true | 允許代理釘選/取消釘選訊息 |
| actions.memberInfo | boolean | true | 允許代理查詢房間成員資訊 |
| actions.channelInfo | boolean | true | 允許代理檢索房間/頻道資訊 |
enabled
Type: booleanDefault: true
啟用或停用 Matrix 頻道
homeserver
Type: stringDefault: "https://matrix.org"
Matrix Homeserver URL(如 https://matrix.org、https://element.io)
accessToken
Type: stringDefault: ""
用於驗證的 Matrix 存取權杖(推薦方法)
userId
Type: stringDefault: ""
Matrix 使用者 ID(如 @bot:matrix.org)—— 與密碼驗證一起使用
password
Type: stringDefault: ""
Matrix 帳戶密碼——與 userId 一起用於登入
encryption
Type: booleanDefault: false
透過 Rust crypto SDK 啟用端對端加密
dmPolicy
Type: stringDefault: "pairing"
私訊存取策略:pairing、allowlist、open 或 disabled
dm.allowFrom
Type: arrayDefault: []
允許私訊的 Matrix 使用者 ID(如 [@alice:matrix.org])
groupPolicy
Type: stringDefault: "allowlist"
房間策略:allowlist 或 disabled
groups
Type: objectDefault: {}
特定房間設定(房間 ID 或別名作為鍵)
groups.<roomId>.allow
Type: booleanDefault: false
允許機器人參與此房間
groups.<roomId>.requireMention
Type: booleanDefault: true
在此房間中需要提及機器人才能觸發回應
groups.<roomId>.users
Type: arrayDefault: []
每個房間的使用者白名單(Matrix 使用者 ID)
autoJoin
Type: stringDefault: "allowlist"
自動加入房間邀請:always、allowlist 或 off
textChunkLimit
Type: numberDefault: 4096
每條出站訊息的最大字元數
chunkMode
Type: stringDefault: "length"
如何分割長回應:length(硬限制)或 newline(段落邊界)
threadReplies
Type: stringDefault: "inbound"
執行緒行為:off、inbound(唯讀)或 always(讀取+建立)
replyToMode
Type: stringDefault: "reference"
回覆中繼資料附加模式
mediaMaxMb
Type: numberDefault: 50
最大媒體檔案大小(MB)
actions.reactions
Type: booleanDefault: true
允許代理傳送/讀取表情回應
actions.messages
Type: booleanDefault: true
允許代理讀取/傳送/編輯/刪除訊息
actions.pins
Type: booleanDefault: true
允許代理釘選/取消釘選訊息
actions.memberInfo
Type: booleanDefault: true
允許代理查詢房間成員資訊
actions.channelInfo
Type: booleanDefault: true
允許代理檢索房間/頻道資訊
Matrix 常見問題
Matrix 故障排除
機器人無法接收訊息
私訊策略阻止訊息,或機器人不在房間中
檢查 channels.matrix.dmPolicy 和 dm.allowFrom 設定。對於房間,確保房間在您的 groups 白名單中,並且機器人已被邀請並加入。
E2EE 加密房間不顯示訊息
裝置未驗證或加密模組載入失敗
在 Element 或其他 Matrix 用戶端中驗證您的機器人裝置。檢查記錄檔中的加密模組載入錯誤。確保 channels.matrix.encryption 設為 true。
存取權杖無效或已過期
權杖在 Homeserver 上被撤銷或失效
透過重新登入產生新的存取權杖。如果使用使用者名稱/密碼,刪除 ~/.openclaw/credentials/matrix/credentials.json 並重啟 Gateway。
機器人加入房間但不回應
房間不在白名單中或 requireMention 已啟用
將房間新增到 channels.matrix.groups,設定 allow: true。如果 requireMention 為 true,使用者必須提及機器人才能獲得回應。
與其他 Homeserver 的聯邦錯誤
Homeserver 連接或聯邦問題
在 federationtester.matrix.org 檢查您的 Homeserver 聯邦狀態。如果是自架,驗證 DNS SRV 記錄和 SSL 憑證。
外掛安裝失敗
npm 倉庫存取或 Node.js 版本不相容
確保已安裝 Node.js 18+。嘗試 'openclaw plugins install @openclaw/matrix --verbose' 取得詳細錯誤記錄檔。檢查到 npm 倉庫的網路連接。