プレゼンス

OpenClaw の「プレゼンス」は、以下を軽量かつベストエフォートで表示するビューです。

• Gateway 自体、および
• Gateway に接続しているクライアント（mac アプリ、WebChat、CLI など）

プレゼンスは主に、macOS アプリの Instances タブを表示し、 オペレーターが素早く状況を把握できるようにするために使われます。

# プレゼンスのフィールド（表示される内容）

プレゼンスエントリは、次のようなフィールドを持つ構造化オブジェクトです。

• instanceId（任意だが強く推奨）: 安定したクライアント ID（通常は connect.client.instanceId）
• host: 人間が読みやすいホスト名
• ip: ベストエフォートの IP アドレス
• version: クライアントのバージョン文字列
• deviceFamily / modelIdentifier: ハードウェアのヒント
• mode: ui, webchat, cli, backend, probe, test, node, ...
• lastInputSeconds: 「最後のユーザー入力からの秒数」（分かる場合）
• reason: self, connect, node-connected, periodic, ...
• ts: 最終更新タイムスタンプ（エポックからのミリ秒）

# 生成元（プレゼンスの由来）

プレゼンスエントリは複数のソースから生成され、マージされます。

# 1) Gateway 自身のエントリ

Gateway は起動時に常に「self」エントリを初期登録するため、クライアントが接続する前でも UI にゲートウェイホストが表示されます。

# 2) WebSocket 接続

すべての WS クライアントは connect リクエストから開始します。ハンドシェイクが成功すると、Gateway はその接続のプレゼンスエントリを upsert します。

# 単発の CLI コマンドが表示されない理由

CLI は短時間の単発コマンドのために接続することがよくあります。Instances リストが過剰に増えるのを避けるため、client.mode === "cli" はプレゼンスエントリに変換されません。

# 3) system-event ビーコン

クライアントは system-event メソッドを使って、より詳細な定期ビーコンを送信できます。mac アプリはこれを使って、ホスト名、IP、lastInputSeconds を報告します。

# 4) ノード接続（role: node）

ノードが role: node で Gateway WebSocket 経由で接続すると、Gateway はそのノードのプレゼンスエントリを upsert します（他の WS クライアントと同じ流れ）。

# マージと重複排除のルール（instanceId が重要な理由）

プレゼンスエントリは、単一のメモリ内マップに保存されます。

• エントリはプレゼンスキーでキー付けされます。
• 最適なキーは、再起動後も維持される安定した instanceId（connect.client.instanceId 由来）です。
• キーは大文字と小文字を区別しません。

クライアントが安定した instanceId なしで再接続すると、重複行として表示されることがあります。

# TTL とサイズ上限

プレゼンスは意図的に一時的なものです。

• TTL: 5 分より古いエントリは削除されます
• 最大エントリ数: 200（最も古いものから削除）

これによりリストを新鮮に保ち、メモリ使用量が無制限に増えるのを避けます。

# リモート/トンネルの注意点（ループバック IP）

クライアントが SSH トンネル / ローカルポートフォワード経由で接続すると、Gateway にはリモートアドレスが 127.0.0.1 として見えることがあります。クライアントが報告した適切な IP を上書きしないよう、ループバックのリモートアドレスは無視されます。

# 利用側

# macOS Instances タブ

macOS アプリは system-presence の出力を表示し、最終更新からの経過時間に基づいて小さなステータスインジケーター（Active/Idle/Stale）を適用します。

# デバッグのヒント

• 生のリストを見るには、Gateway に対して system-presence を呼び出します。
• 重複が表示される場合:
  • クライアントがハンドシェイクで安定した client.instanceId を送信していることを確認します
  • 定期ビーコンが同じ instanceId を使用していることを確認します
  • 接続由来のエントリに instanceId が欠けていないか確認します（この場合、重複は想定どおりです）

# 関連