프레즌스

OpenClaw의 "프레즌스"는 다음 항목을 간단하게 최선의 방식으로 보여주는 뷰입니다.

• Gateway 자체
• Gateway에 연결된 사용자 표시 클라이언트(Mac 앱, WebChat, Node 등)

프레즌스는 Control UI의 장치 페이지와 macOS 앱의 인스턴스 탭에 실시간 연결 메타데이터를 표시합니다.

이 페이지에서는 Gateway 클라이언트 목록을 다룹니다. 가장 최근에 사용한 Mac을 감지하고 해당 Mac으로 Node 알림을 라우팅하는 방법은 활성 컴퓨터 프레즌스를 참조하십시오.

프레즌스 필드(표시되는 정보)

프레즌스 항목은 다음과 같은 필드를 포함하는 구조화된 객체입니다.

• 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가 해당 연결의 프레즌스 항목을 업서트합니다.

일시적인 제어 영역 연결이 표시되지 않는 이유

CLI 명령, 백엔드 RPC 클라이언트, 프로브는 대개 잠깐만 연결됩니다. 이러한 변동을 프레즌스 TTL 전체 기간 동안 유지하지 않도록 cli, backend, probe 모드의 클라이언트는 프레즌스 항목으로 변환되지 않습니다. 테스트 스위트에서는 테스트 모드 클라이언트를 실제 클라이언트의 대용으로 사용하므로 계속 추적합니다.

3) system-event 비콘

클라이언트는 system-event 메서드를 통해 더 상세한 주기적 비콘을 전송할 수 있습니다. Mac 앱은 이를 사용하여 호스트 이름, IP, lastInputSeconds를 보고합니다.

4) Node 연결(역할: Node)

Node가 role: node를 사용하여 Gateway WebSocket을 통해 연결되면 Gateway는 다른 WS 클라이언트와 동일한 흐름으로 해당 Node의 프레즌스 항목을 업서트합니다.

병합 및 중복 제거 규칙(instanceId가 중요한 이유)

프레즌스 항목은 단일 인메모리 맵에 저장되며, 다음 중 처음 사용할 수 있는 값을 순서대로 선택하여 대소문자를 구분하지 않는 키로 사용합니다. 페어링된 장치 ID, connect.client.instanceId, 최후 수단으로 연결별 ID입니다.

일시적인 제어 영역 클라이언트는 추적에서 완전히 제외되므로(위 참조) 해당 연결 ID가 키로 사용되지 않습니다. 그 외 모든 클라이언트에는 연결 ID 폴백이 적용되므로, 안정적인 instanceId 없이 다시 연결하는 클라이언트는 중복 행으로 표시됩니다.

TTL 및 크기 제한

프레즌스는 의도적으로 일시적으로 유지됩니다.

• TTL: 5분보다 오래된 항목은 제거됩니다.
• 최대 항목 수: 200개(가장 오래된 항목부터 제거)

이를 통해 목록을 최신 상태로 유지하고 메모리가 무제한으로 증가하는 것을 방지합니다.

원격/터널 주의 사항(루프백 IP)

클라이언트가 SSH 터널/로컬 포트 전달을 통해 연결되면 Gateway에서 원격 주소가 127.0.0.1로 보일 수 있습니다. 해당 터널 주소가 클라이언트의 IP로 기록되지 않도록, 연결 처리에서는 로컬로 감지된(루프백) 클라이언트의 항목에 루프백 주소를 기록하는 대신 ip를 완전히 생략합니다.

사용 주체

Control UI 장치 페이지

장치 페이지는 system-presence를 영구 페어링 및 Node 레코드와 조인합니다. Gateway 자체 비콘을 첫 번째로 고정하고, 일치하는 장치 또는 인스턴스 ID를 사용하여 실시간 플랫폼, 버전, 모델 및 입력 최신성 메타데이터를 표시합니다.

macOS 인스턴스 탭

macOS 앱은 system-presence의 출력을 렌더링하고 마지막 업데이트 이후 경과 시간에 따라 간단한 상태 표시기(활성/유휴/오래됨)를 적용합니다.

디버깅 팁

• 원시 목록을 보려면 Gateway를 대상으로 system-presence를 호출하십시오.
• 중복 항목이 표시되는 경우:
  • 클라이언트가 핸드셰이크에서 안정적인 client.instanceId를 전송하는지 확인하십시오.
  • 주기적 비콘에서 동일한 instanceId를 사용하는지 확인하십시오.
  • 연결에서 파생된 항목에 instanceId가 누락되었는지 확인하십시오(이 경우 중복은 예상된 동작입니다).

관련 문서