線上狀態

OpenClaw 的「上線狀態」是以下項目的輕量、盡力而為檢視：

• 閘道本身，以及
• 連線至閘道且使用者可見的用戶端（Mac 應用程式、WebChat、節點等）

上線狀態會在控制介面的 Devices 頁面 （位於 Settings → Devices）以及 macOS 應用程式的 Instances 分頁中顯示即時連線中繼資料。

本頁說明閘道用戶端清單。若要偵測你最近使用的 Mac，並將節點警示路由至該處，請參閱 使用中電腦的上線狀態。

上線狀態欄位（顯示的內容）

上線狀態項目是結構化物件，包含以下欄位：

• 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 起算的毫秒數）

產生來源（上線狀態來自何處）

上線狀態項目由多個來源產生，並會進行合併。

1) 閘道自身項目

閘道啟動時一律會建立一筆「自身」項目，讓介面即使在任何用戶端連線前，也能顯示閘道主機。

2) WebSocket 連線

每個 WS 用戶端都會先送出 connect 要求。交握成功後，閘道會為該連線新增或更新一筆上線狀態項目。

為何暫時性的控制平面連線不會顯示

命令列介面命令、後端 RPC 用戶端和探測器通常只會短暫連線。為避免在完整的上線狀態 TTL 期間保留這類頻繁變動，處於 cli、backend 或 probe 模式的用戶端不會轉換為上線狀態項目。測試模式用戶端仍會持續追蹤，因為測試套件會使用它們代替真實用戶端。

3) system-event 信標

用戶端可透過 system-event 方法定期傳送包含更多資訊的信標。Mac 應用程式會使用此方式回報主機名稱、IP 和 lastInputSeconds。

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

當節點透過閘道 WebSocket 使用 role: node 連線時，閘道會為該節點新增或更新一筆上線狀態項目（流程與其他 WS 用戶端相同）。

合併與去重規則（instanceId 為何重要）

上線狀態項目儲存在單一記憶體內映射中，鍵值不區分大小寫，並依序採用第一個可用的值：已配對的裝置 ID、connect.client.instanceId， 最後才使用每個連線的 ID。

暫時性的控制平面用戶端會完全排除在追蹤範圍之外（見上文），因此其連線 ID 絕不會成為鍵值。對其他所有用戶端而言，連線 ID 的備援機制表示，若用戶端重新連線時未提供穩定的 instanceId，就會顯示為重複資料列。

TTL 與大小上限

上線狀態刻意設計為暫時性資料：

• **TTL：**超過 5 分鐘的項目會遭到清除
• **項目上限：**200（優先移除最舊的項目）

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

遠端／通道注意事項（迴路 IP）

當用戶端透過 SSH 通道／本機連接埠轉送進行連線時，閘道可能會將遠端位址識別為 127.0.0.1。為避免將該通道位址記錄為用戶端的 IP，連線處理程序針對偵測為本機（迴路）的用戶端，會完全省略 ip，而不會將迴路位址寫入項目。

使用端

控制介面的 Devices 頁面

Devices 頁面會將 system-presence 與永久保存的配對及節點記錄結合。它會將閘道自身信標固定在最前方，並使用相符的裝置或執行個體 ID，取得即時平台、版本、型號及輸入時間近況等中繼資料。

macOS 的 Instances 分頁

macOS 應用程式會呈現 system-presence 的輸出，並根據上次更新距今的時間顯示簡短狀態指示器（Active/Idle/Stale）。

偵錯提示

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

相關內容