プレゼンス

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

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

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

​

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

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

• instanceId（任意だが強く推奨）: 安定したクライアント識別子（通常は 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: 接続ハンドシェイクから得られるデバイス識別子とロール/スコープのヒント
• ts: 最終更新タイムスタンプ（エポックからのミリ秒）

​

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

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

​

1) Gateway 自身のエントリ

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

​

2) WebSocket 接続

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

​

1 回限りの CLI コマンドが表示されない理由

CLI は短時間の 1 回限りのコマンドのために接続することがよくあります。Instances リストを大量の項目で埋めないようにするため、client.mode === "cli" はプレゼンスエントリに変換されません。

​

3) system-event ビーコン

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

​

4) Node 接続（role: node）

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

​

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

プレゼンスエントリは単一のインメモリマップに保存され、大文字小文字を区別せずに、次のうち最初に利用可能なものをキーにします。ペアリング済みデバイス ID、connect.client.instanceId、最後の手段として接続ごとの ID。 CLI クライアントは追跡対象から完全に除外されるため（上記参照）、その接続 ID がキーになることはありません。それ以外のすべてのクライアントでは、接続 ID へのフォールバックにより、安定した instanceId なしで再接続するクライアントは重複行として表示されます。

​

TTL と上限サイズ

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

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

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

​

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

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

​

利用側

​

macOS Instances タブ

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

​

デバッグのヒント

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

​

関連