> ## Documentation Index
> Fetch the complete documentation index at: https://openclawdoc.org/llms.txt
> Use this file to discover all available pages before exploring further.

# プレゼンス (稼働状況)

> プレゼンス情報は、主に macOS アプリの Instances（インスタンス） タブでの表示や、管理者が現在の接続状況を把握するために使用されます。プレゼンスフィールド (表示される項目)、情報のソース (どこから来るか)、1) ゲートウェイ自身のセルフエントリを確認できます。

OpenClaw の「プレゼンス」は、以下の要素の稼働状況をベストエフォートで可視化したものです:

* **ゲートウェイ** 自体
* **ゲートウェイに接続されているクライアント** (macOS アプリ、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) ゲートウェイ自身のセルフエントリ

ゲートウェイは起動時に自身の情報を登録します。これにより、クライアントが 1 つも接続されていない状態でも UI にゲートウェイホストが表示されます。

### 2) WebSocket の接続時

すべての WebSocket クライアントは `connect` リクエストから始まります。ハンドシェイク（接続確立）が成功すると、ゲートウェイはその接続に対するプレゼンスエントリを作成または更新（upsert）します。

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

CLI は短時間の単発コマンドのために頻繁に接続します。インスタンス一覧が CLI で埋め尽くされるのを避けるため、`client.mode === "cli"` の接続はプレゼンスエントリとして**登録されません**。

### 3) `system-event` による定期通知

クライアントは `system-event` メソッドを使用して、より詳細な情報を定期的に通知できます。macOS アプリはこの仕組みを利用して、ホスト名、IP、および `lastInputSeconds` を報告しています。

### 4) ノードの接続 (role: node)

ノードが `role: node` としてゲートウェイの WebSocket に接続すると、他のクライアントと同様のフローでプレゼンスエントリが作成されます。

## マージと重複排除のルール (`instanceId` の重要性)

すべてのプレゼンスエントリは、メモリ上の 1 つのマップに保存されます:

* 各エントリは **プレゼンスキー** によって管理されます。
* 最も適切なキーは、再起動後も変わらない安定した `instanceId` (`connect.client.instanceId` 由来) です。
* キーの大文字・小文字は区別されません。

クライアントが固定の `instanceId` を持たずに再接続を繰り返すと、一覧に **重複した行** が表示される原因となります。

## 有効期限 (TTL) と最大件数

プレゼンス情報は意図的に一時的なものとして扱われます:

* **TTL**: 最終更新から 5 分以上経過したエントリは自動的に削除されます。
* **最大件数**: 200 件（上限を超えた場合は古いものから削除されます）。

これにより、常に最新の稼働状況が保たれ、メモリの無制限な増加を防いでいます。

## リモート/トンネル利用時の注意 (ループバック IP)

SSH トンネルやローカルポート転送を介してクライアントが接続している場合、ゲートウェイから見たリモートアドレスが `127.0.0.1` になることがあります。クライアントが報告した正しい IP アドレスを上書きしてしまわないよう、ループバックアドレスからの通知は IP 情報の更新対象から除外されます。

## 情報の利用者

### macOS アプリの Instances タブ

macOS アプリは `system-presence` の出力を表示し、最終更新からの経過時間に基づいて「Active（アクティブ）」「Idle（アイドル）」「Stale（古い）」のステータスインジケーターを付与します。

## デバッグのヒント

* 生のリストを確認するには、ゲートウェイに対して `system-presence` メソッドを呼び出してください。
* 重複が発生している場合:
  * クライアントが接続時のハンドシェイクで固定の `client.instanceId` を送信しているか確認してください。
  * 定期的な `system-event` 通知でも同じ `instanceId` が使われているか確認してください。
  * 接続由来のエントリに `instanceId` が欠落していないか確認してください（欠落していると重複が発生しやすくなります）。