Presence

기준일: 2026-07-26
공식 기준: Presence

Presence 문서는 OpenClaw 공식 문서(concepts/presence)를 한국어로 정리한 가이드입니다. How OpenClaw presence entries are produced, merged, and displayed 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw presence entries are produced, merged, and displayed

한국어 가이드 범위: concepts/presence 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Presence fields (what shows up)
• Producers (where presence comes from)
• 1) Gateway self entry
• 2) WebSocket connect
• 3) system-event beacons
• 4) Node connects (role: node)
• Merge + dedupe rules (why instanceId matters)
• TTL and bounded size
• Remote/tunnel caveat (loopback IPs)
• Consumers
• Control UI Devices page
• macOS Instances tab
• Debugging tips
• 관련 문서

상세 내용

본문

OpenClaw "presence" is a lightweight, best-effort view of:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• the Gateway itself, and
• user-visible clients connected to the Gateway (mac app, WebChat, nodes, etc.)

Presence fields (what shows up)

Presence entries are structured objects with fields like:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• instanceId (optional but strongly recommended): stable client identity (usually connect.client.instanceId)
• host: human-friendly host name
• ip: best-effort IP address
• version: client version string
• deviceFamily / modelIdentifier: hardware hints
• mode: ui, webchat, cli, backend, node, probe, test
• lastInputSeconds: seconds since last user input, if known
• reason: free-form client-supplied string; the Gateway itself only emits self, connect, and disconnect
• deviceId, roles, scopes: device identity and role/scope hints from the connect handshake
• ts: last update timestamp (ms since epoch)

Producers (where presence comes from)

Presence entries are produced by multiple sources and merged.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

1) Gateway self entry

The Gateway always seeds a "self" entry at startup so UIs show the gateway host even before any clients connect.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

2) WebSocket connect

Every WS client begins with a connect request. On successful handshake the Gateway upserts a presence entry for that connection.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

3) system-event beacons

Clients can send richer periodic beacons via the system-event method. The mac app uses this to report host name, IP, version, and liveness metadata. Physical input activity is not part of this generic beacon; the purpose-specific native node event described in Active computer presence owns it. The Mac tags these beacons with system-presence-clear-last-input; current Gateways use that backward-compatible marker to remove any input recency retained from an older app. The beacon also carries a fixed 30-day value so older Gateways that ignore the tag overwrite exact recency instead of retaining it. No new activity is sampled for this compatibility value.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

4) Node connects (role: node)

When a node connects over the Gateway WebSocket with role: node, the Gateway upserts a presence entry for that node (same flow as other WS clients).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Merge + dedupe rules (why instanceId matters)

Presence entries are stored in a single in-memory map, keyed case-insensitively by the first available of, in order: a paired device id, connect.client.instanceId, or the per-connection id as a last resort.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

TTL and bounded size

This keeps the list fresh and avoids unbounded memory growth.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• TTL: entries older than 5 minutes are pruned
• Max entries: 200 (oldest dropped first)

Remote/tunnel caveat (loopback IPs)

When a client connects over an SSH tunnel / local port forward, the Gateway may see the remote address as 127.0.0.1. To avoid recording that tunnel address as the client's IP, connect handling omits ip entirely for detected-local (loopback) clients rather than writing the loopback address into the entry.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Consumers

이 섹션의 세부 항목은 공식 문서 Consumers를 참고하세요.

Control UI Devices page

The Devices page joins system-presence with durable pairing and node records. It pins the Gateway self beacon first and uses matching device or instance ids for live platform, version, model, and input-recency metadata.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

macOS Instances tab

The macOS app renders the output of system-presence and applies a small status indicator (Active/Idle/Stale) based on the age of the last update.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Debugging tips

주요 항목:

• To see the raw list, call system-presence against the Gateway.
• If you see duplicates:
• confirm clients send a stable client.instanceId in the handshake
• confirm periodic beacons use the same instanceId
• check whether the connection-derived entry is missing instanceId (duplicates are expected)

관련 문서

How physical Mac input selects an active node and routes connection alerts.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/presence
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

관련 링크

• 공식 원문: concepts/presence
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.