プレゼンス

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

• Gateway自体、および
• Gatewayに接続されているユーザー向けクライアント（Macアプリ、WebChat、Nodeなど）

プレゼンスでは、Control UIのDevicesページ （Settings → Devices内）と、macOSアプリのInstancesタブにライブ接続メタデータが表示されます。

このページでは、Gatewayのクライアント一覧について説明します。最後に使用したMacを検出し、 NodeのアラートをそのMacにルーティングする方法については、 アクティブなコンピューターのプレゼンスを参照してください。

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

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

• instanceId（任意ですが強く推奨）：安定したクライアントID（通常はconnect.client.instanceId）
• host：人が識別しやすいホスト名
• ip：ベストエフォートで取得したIPアドレス
• version：クライアントのバージョン文字列
• deviceFamily / modelIdentifier：ハードウェア情報のヒント
• mode：ui、webchat、cli、backend、node、probe、test
• lastInputSeconds：判明している場合、最後のユーザー入力からの経過秒数
• reason：クライアントが指定する自由形式の文字列。Gateway自体が出力するのはself、connect、disconnectのみ
• deviceId、roles、scopes：接続ハンドシェイクから得られるデバイスIDとロール／スコープのヒント
• ts：最終更新時刻（エポックからのミリ秒）

生成元（プレゼンスの取得元）

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

1) Gatewayの自己エントリ

Gatewayは、クライアントが接続する前でもUIにGatewayホストが表示されるよう、 起動時に必ず「自己」エントリを登録します。

2) WebSocket接続

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

一時的なコントロールプレーン接続が表示されない理由

CLIコマンド、バックエンドRPCクライアント、プローブは、多くの場合短時間だけ接続します。 その頻繁な変動をプレゼンスTTLの期間全体にわたって保持しないよう、 cli、backend、probeモードのクライアントは プレゼンスエントリに変換されません。テストモードのクライアントは、 テストスイートで実際のクライアントの代わりとして使用されるため、追跡されます。

3) system-eventビーコン

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

4) Node接続（ロール：Node）

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

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

プレゼンスエントリは、単一のメモリ内マップに格納されます。キーには、大文字と小文字を区別せず、 次の順序で最初に利用可能なものが使用されます。ペアリング済みデバイスID、connect.client.instanceId、 最後の手段として接続ごとのID。

一時的なコントロールプレーンクライアントは追跡対象から完全に除外されるため（前述）、 その接続IDがキーになることはありません。それ以外のすべてのクライアントでは、 接続IDへのフォールバックにより、安定したinstanceIdを持たずに再接続したクライアントは 重複した行として表示されます。

TTLと上限サイズ

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

• **TTL：**5分より古いエントリは削除
• **最大エントリ数：**200（古いものから削除）

これにより、一覧を最新の状態に保ち、メモリ使用量の無制限な増加を防ぎます。

リモート／トンネルに関する注意事項（ループバックIP）

クライアントがSSHトンネル／ローカルポートフォワーディング経由で接続すると、Gatewayには リモートアドレスが127.0.0.1として見える場合があります。そのトンネルアドレスを クライアントのIPとして記録しないよう、接続処理では、ローカル（ループバック）として検出された クライアントについて、ループバックアドレスをエントリに書き込む代わりに ip自体を省略します。

利用側

Control UIのDevicesページ

Devicesページは、system-presenceを永続的なペアリングレコードおよびNodeレコードと 結合します。Gatewayの自己ビーコンを先頭に固定し、一致するデバイスIDまたは インスタンスIDを使用して、ライブのプラットフォーム、バージョン、モデル、入力からの経過時間の メタデータを表示します。

macOSのInstancesタブ

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

デバッグのヒント

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

関連項目