掌握 OpenClaw Presence：即時監控你的 Gateway 與客戶端狀態

當你管理多個分散的節點或客戶端時，最頭痛的就是不知道誰在線上，或者為什麼同一個裝置會重複出現在清單中。這種「盲打」的感覺往往讓開發與維運變得異常痛苦，你需要的只是一個能看清全局的儀表板。

OpenClaw 的 Presence 功能就是為了解決這個問題。它提供了一個輕量且即時的視角，讓你隨時掌握 Gateway 本身以及所有連線客戶端（如 macOS App、WebChat 或 CLI）的健康狀況。

需要準備的東西

OpenClaw Gateway
已連線的客戶端（macOS App, WebChat, CLI 或 Node）

快速開始

想在 5 分鐘內搞定狀態監控，請遵循以下路徑：

啟動 Gateway：它會自動產生一個 self 項目，確保你在 UI 中能看到 Gateway 正在運作。
連線客戶端：透過 WebSocket 發送 connect 請求，Gateway 會自動更新該連線的 Presence。
設定固定 ID：在握手時提供 connect.client.instanceId，這能確保你的裝置在重連後不會變成重複的項目。
查看結果：打開 macOS App 的 Instances 分頁，你會看到即時更新的清單。

深入了解 Presence 機制

這些數據代表什麼？

Presence 條目包含多個關鍵欄位，幫助你識別客戶端：

instanceId: 穩定的客戶端識別碼（強烈建議使用）。
host 與 ip: 裝置名稱與 IP 地址。
version: 客戶端版本。
mode: 客戶端類型（如 ui, webchat, node, backend 等）。
lastInputSeconds: 距離上次使用者操作的時間。
ts: 最後更新的時間戳記。

資料來源（Producers）

Presence 的資訊是從多個來源合併而來的：

Gateway 自我宣告：啟動時自動產生。
WebSocket 連線：每個 WS 客戶端握手成功後都會建立條目（注意：cli 模式的短暫指令不會被記錄，以免洗版）。
system-event 訊標：客戶端（如 macOS App）會定期發送更詳細的資訊，包含主機名與操作狀態。
Node 連線：當節點以 role: node 連線時，也會被納入追蹤。

存儲與清理規則

為了保持效能，Presence 採用記憶體存儲並有以下限制：

TTL：超過 5 分鐘未更新的條目會被自動刪除。
容量上限：最多保留 200 條紀錄，超過時會移除最舊的條目。
重複排除：主要透過 instanceId 進行合併。如果客戶端沒有提供穩定的 ID，重連時就會出現重複的列。

遠端隧道限制

如果你透過 SSH tunnel 或本地連接埠轉發連線，Gateway 可能會偵測到 127.0.0.1。為了避免蓋掉原本正確的 IP，Gateway 會主動忽略 Loopback 地址。

疑難排解

看到重複的實例？ 請確認你的客戶端在 handshake 時有發送穩定的 client.instanceId。同時檢查定期發送的 beacon 是否使用了相同的 ID。
想查看原始數據？ 你可以直接對 Gateway 呼叫 system-presence API 來獲取完整的 JSON 列表。
實例狀態顯示 Stale？ 這代表該條目快要超過 5 分鐘的有效期了，檢查客戶端的網路連線或 system-event 發送頻率。

如果你在設定過程遇到任何困難，可以詢問 AI Setup Assistant 獲取即時協助。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。