OpenClaw Presence：接続状況をリアルタイムに把握する

分散されたシステムを運用していると、どのインスタンスが生きているのか、どのバージョンが動いているのかを特定するのに時間がかかることがあります。ログを追いかける前に、パッと一覧で状態を確認できる場所が欲しいと感じることは多いはずです。

OpenClaw の Presence は、Gateway 本体とそこに接続されているクライアント（macOS アプリ、WebChat、CLI など）の状態を軽量に把握するための仕組みです。これを利用することで、現在どのデバイスがアクティブなのかを即座に確認できます。

必要なもの

• OpenClaw Gateway
• 接続クライアント（macOS app, WebChat, Node.js など）
• 固定された instanceId（重複防止のために推奨）
• WebSocket による通信環境

クイックスタート

Presence 情報を反映させ、確認するための最短ステップは以下の通りです。

1. Gateway を起動する Gateway は起動時に自動で self エントリを作成します。これにより、クライアントが接続される前でも Gateway 自体のホスト名などがリストに表示されます。

2. クライアントを接続する WebSocket のハンドシェイクが成功すると、Gateway はその接続用の Presence エントリを自動で作成（アップサート）します。

3. 詳細情報を送信する クライアントから system-event メソッドを使用して、定期的にビーコンを送信します。macOS アプリなどでは、これを利用して lastInputSeconds（最終入力からの経過時間）や IP アドレスを報告します。

4. 接続状況を確認する 現在の Presence 一覧を取得するには、Gateway に対して system-presence を実行します。macOS アプリの「Instances」タブでもこの結果がレンダリングされます。

Presence の仕組みとルール

Presence エントリはメモリ上のマップに保存されます。効率的に管理するために、いくつかのルールがあります。

• 重複の排除: エントリは instanceId をキーとして管理されます。再起動しても変わらない固定の instanceId を使用するのがベストな方法です。
• 自動削除 (TTL): 5 分以上更新がないエントリは自動的に削除されます。
• 最大容量: 最大 200 エントリまで保持され、上限を超えると古いものから削除されます。
• ループバック IP の除外: SSH トンネルなどを経由した接続で IP が 127.0.0.1 となる場合、クライアントから報告された正しい IP を上書きしないよう、ループバックアドレスは無視されます。

トラブルシューティング

リストに同じクライアントが重複して表示される ハンドシェイク時と定期ビーコンの両方で、同じ固定の instanceId を送信しているか確認してください。instanceId が欠落していると、新しい接続として扱われてしまいます。

CLI を実行してもリストに表示されない これは意図された挙動です。CLI による単発のコマンド実行でリストが埋め尽くされるのを防ぐため、client.mode === "cli" の場合は Presence エントリが作成されません。

---

困ったときは AI Setup Assistant に相談してください。

次のステップ

• Gateway Configuration
• System Events API