OpenClaw Matrix 2026｜Linux VPS、Homeserver、存取權杖與多房間路由

Matrix 提供聯邦房間、端到端加密選項，以及單一 HTTP Client-Server API，適合作為聊天基礎設施而非綁死某家 SDK。把 OpenClaw Gateway 放在Linux 雲端 VPS並與 Homeserver 鄰接是常見做法：低成本常時 CPU、對外 TLS 連線穩定，也方便依團隊或機器人拆房間。本篇是可復現檢查清單：確實啟用 Matrix 外掛、安全接上Homeserver URL 與存取權杖、用穩定房間 ID做多房間路由而不被別名漂移拖累；最後附同步或遞送看似卡住時的L0–L3簡答。暴露面請先對齊 2026 OpenClaw Linux 雲主機最小暴露面：防火牆樣板、Gateway 回環綁定與 SSH 隧道管理面存取，對比 HTTPS 公網反代的決策矩陣與分級排障 FAQ。

443

Homeserver Client API（HTTPS）

!room

設定優先使用穩定房間 ID

L0–L3

同步問題分層排查

啟用 Matrix 外掛（可復現基準）

依團隊既定方式在 VPS 安裝或升級 OpenClaw（套件、靜態二進位或容器皆可）。在 Gateway 設定開啟 Matrix 整合，並確認行程啟動時即載入外掛，而非僅互動式 shell 的 profile 才有設定。變更後請由監督程式（例如 systemd）重啟；在碰權杖之前，先從啟動日誌確認外掛已註冊。

健全性檢查（請替換成你的安裝名稱）

# 1) Gateway 版本與所讀文件一致
openclaw version   # 或套件對應指令

# 2) 對 Homeserver 出站 HTTPS（SNI + 系統 CA）
curl -sS -o /dev/null -w "%{http_code}\n" https://matrix.example.org/_matrix/client/versions

# 3) 重啟後日誌可見外掛註冊
sudo systemctl restart openclaw-gateway
journalctl -u openclaw-gateway -b --no-pager | tail -n 80

時間與 DNS

VPS 請啟用 NTP；時鐘漂移會搞砸 TLS 握手，並讓 Matrix 同步權杖「過期」訊息難以理解。若 Homeserver 僅內網或 split-horizon，請把解析覆寫寫在 Gateway 機器側並進版控，不要只存在開發筆電。

Homeserver URL、使用者 ID 與存取權杖

將基底 URL設為伺服器公告的 Client-Server API 根——通常是 https://<host>，勿拖泥帶水加尾隨路徑。機器人的MXID（@bot:domain）須與該伺服器命名空間一致。建議獨立機器人帳號：完成一次 UI/API 登入後，把長效存取權杖放進密鑰庫（systemd credentials、Vault 或雲端密封環境變數），切勿提交 Git。輪換權杖後請重啟 Gateway，讓記憶體內客戶端丟棄舊 session。

示意環境變數（實際鍵名依版本而異）

export MATRIX_HS_URL="https://matrix.example.org"
export MATRIX_USER_ID="@openclaw-bot:example.org"
export MATRIX_ACCESS_TOKEN="syt_..."   # 來自密鑰庫，勿留在 shell 歷史
export MATRIX_DEVICE_ID="OPENCLAW_VPS_01"  # 穩定裝置標籤便於稽核

E2EE 房間

若必須使用加密房，請先確認目標 Matrix 堆疊支援你預期的機器人模型（明文橋接房 vs 完整裝置金鑰）。設定錯誤常以「已加入但無訊息」呈現，而非乾脆的 403——建議先用未加密測試房驗證端到端路徑。

多房間路由：避免意外

別名字串（#team:domain）可能搬移；房間 ID（!abcdef:domain）較穩定。設定中請明示允許房間清單，並為每間房對應 Gateway 的策略設定檔（模型、工具、速率）。若還要承接其他網路的入站自動化，請把對外 HTTPS／Webhook 可達性與 Matrix 客戶端流量分開設計；細節見 2026 OpenClaw：通道 Webhook 與動態出口——Cloudflare Tunnel、Tailscale Funnel、Linux 雲端 VPS 公網反向代理（回呼可達性、TLS、閘道連接埠綁定矩陣＋可復現分層排障 FAQ）。

路由型態	適合情境	需注意風險
單一維運房	小團隊、單一助理人格	討論串嘈雜；後續可再加 thread 或 subspace
房間允許清單	一台 VPS 上多團隊隔離	更名後忘記補新房間 ID
前綴／指令路由器	同房多機器人共存	與原生斜線指令衝突

Runbook 片段

在 Gateway runbook 旁保留一頁「Matrix 切片」：HS URL、機器人 MXID、三個測試房 ID、權杖輪換負責人、以及最後一次成功的 curl 到 /_matrix/client/versions。未來的你不必猜哪個別名換過家。

分層 FAQ：同步與「靜音」類故障

延續其他 OpenClaw Linux 系列的 L0–L3 用語，方便跨通道工單對照。

L0 — 無法對 Homeserver 建立 HTTP 路徑

在 VPS 上對 HS URL 做 curl -v。此層失敗多為 DNS、TLS 信任庫、企業 CA 或出站防火牆——尚未進入 Matrix 業務邏輯。

L1 — Client API 回 401／403

權杖撤銷、MXID 不匹配，或 Homeserver 對來源 IP 設限。請重新簽發權杖、確認 Authorization: Bearer 形式與所用程式庫一致，並核對機器人是否真的已被邀請進你設定的房間 ID。

L2 — 同步迴圈或巨量追趕延遲

停機後巨大的 since 落差可能像當機。檢查行程 CPU、Homeserver 側限速，以及外掛是否過度篩時間線。優先沿用持久化在磁碟的同步權杖續傳，勿盲目重置。

L3 — 「已加入但無回覆」

可能是 power level、版主規則、E2EE 裝置信任，或第二個 Gateway 實例搶用同一 device_id。環境分離請拆不同機器人；從快照複製 VM 後務必輪換裝置 ID。