線上狀態

OpenClaw「presence」是對以下項目的輕量級、盡力而為檢視：

• 閘道本身，以及
• 連線到閘道的用戶端（mac 應用程式、WebChat、命令列介面等）

Presence 主要用於呈現 macOS 應用程式的執行個體分頁，並提供操作人員快速可見性。

​

Presence 欄位（會顯示什麼）

Presence 項目是結構化物件，包含如下欄位：

• instanceId（選用但強烈建議）：穩定的用戶端身分（通常是 connect.client.instanceId）
• host：便於人類閱讀的主機名稱
• ip：盡力而為的 IP 位址
• version：用戶端版本字串
• deviceFamily / modelIdentifier：硬體提示
• mode：ui、webchat、cli、backend、node、probe、test
• lastInputSeconds：距離上次使用者輸入的秒數，如已知
• reason：用戶端提供的自由格式字串；閘道本身只會發出 self、connect 和 disconnect
• deviceId、roles、scopes：來自連線交握的裝置身分與角色/範圍提示
• ts：上次更新時間戳記（自 epoch 起算的毫秒數）

​

產生者（presence 從何而來）

Presence 項目由多個來源產生，並會被合併。

​

1) 閘道自身項目

閘道啟動時一律會植入一個「self」項目，讓 UI 即使在任何用戶端連線前，也能顯示閘道主機。

​

2) WebSocket 連線

每個 WS 用戶端都會以 connect 請求開始。交握成功後，閘道會為該連線 upsert 一個 presence 項目。

​

為什麼一次性的命令列介面命令不會顯示

命令列介面經常為短暫的一次性命令建立連線。為避免讓執行個體清單充滿雜訊，client.mode === "cli" 不會被轉成 presence 項目。

​

3) system-event 信標

用戶端可以透過 system-event 方法傳送更豐富的週期性信標。mac 應用程式會使用這點回報主機名稱、IP 和 lastInputSeconds。

​

4) 節點連線（角色：節點）

當節點透過閘道 WebSocket 以 role: node 連線時，閘道會為該節點 upsert 一個 presence 項目（流程與其他 WS 用戶端相同）。

​

合併 + 去重規則（為什麼 instanceId 很重要）

Presence 項目會儲存在單一記憶體內 map 中，鍵值不分大小寫，並依序使用第一個可用值：配對裝置 ID、connect.client.instanceId，或最後才使用每個連線的 ID 作為備援。 命令列介面用戶端會完全排除在追蹤之外（見上文），因此其連線 ID 永遠不會成為鍵值。對其他所有用戶端而言，連線 ID 備援表示沒有穩定 instanceId 就重新連線的用戶端，會顯示為重複列。

​

TTL 與有界大小

Presence 刻意設計為暫時性：

• TTL： 會修剪超過 5 分鐘的項目
• 最大項目數： 200（最舊的先丟棄）

這能讓清單保持新鮮，並避免記憶體無限制成長。

​

遠端/通道注意事項（loopback IP）

當用戶端透過 SSH 通道 / 本機連接埠轉送連線時，閘道可能會看到遠端位址是 127.0.0.1。為避免把該通道位址記錄為用戶端的 IP，連線處理會對偵測為本機（loopback）的用戶端完全省略 ip，而不是把 loopback 位址寫入項目。

​

消費者

​

macOS 執行個體分頁

macOS 應用程式會呈現 system-presence 的輸出，並根據上次更新的時間套用小型狀態指示器（作用中/閒置/過時）。

​

偵錯提示

• 若要查看原始清單，請對閘道呼叫 system-presence。
• 如果你看到重複項目：
  • 確認用戶端在交握中傳送穩定的 client.instanceId
  • 確認週期性信標使用相同的 instanceId
  • 檢查由連線衍生的項目是否缺少 instanceId（重複是預期情況）

​

相關