프레전스
OpenClaw "프레전스"는 다음의 가볍고 최선형 뷰입니다:
- 게이트웨이 자체, 그리고
- 게이트웨이에 연결된 클라이언트 (Mac 앱, 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) 게이트웨이 자체 항목
게이트웨이는 시작 시 항상 "self" 항목을 시드합니다. 따라서 클라이언트가 연결되기 전에도 UI는 게이트웨이 호스트를 표시합니다.
2) WebSocket 연결
모든 WS 클라이언트는 connect 요청으로 시작합니다. 성공적인 핸드셰이크 시 게이트웨이는 해당 연결에 대한 프레전스 항목을 업서트합니다.
일회성 CLI 커맨드가 표시되지 않는 이유
CLI는 종종 짧은 일회성 커맨드를 위해 연결합니다. Instances 목록을 스팸으로 채우지 않기 위해 client.mode === "cli"는 프레전스 항목으로 변환되지 않습니다.
3) system-event 비콘
클라이언트는 system-event 메서드를 통해 더 풍부한 주기적 비콘을 보낼 수 있습니다. Mac 앱은 이를 사용하여 호스트 이름, IP, lastInputSeconds를 보고합니다.
4) 노드 연결 (역할: node)
노드가 role: node로 게이트웨이 WebSocket을 통해 연결되면, 게이트웨이는 해당 노드에 대한 프레전스 항목을 업서트합니다 (다른 WS 클라이언트와 동일한 흐름).
병합 + 중복 제거 규칙 (instanceId가 중요한 이유)
프레전스 항목은 단일 인메모리 맵에 저장됩니다:
- 항목은 프레전스 키로 키가 지정됩니다.
- 최상의 키는 재시작 후에도 살아남는 안정적인
instanceId(connect.client.instanceId에서)입니다. - 키는 대소문자를 구분하지 않습니다.
클라이언트가 안정적인 instanceId 없이 재연결하면 중복 행으로 표시될 수 있습니다.
TTL 및 제한된 크기
프레전스는 의도적으로 일시적입니다:
- TTL: 5분보다 오래된 항목은 정리됩니다
- 최대 항목: 200개 (가장 오래된 것 먼저 삭제)
이는 목록을 신선하게 유지하고 무제한 메모리 증가를 방지합니다.
원격/터널 주의사항 (루프백 IP)
클라이언트가 SSH 터널 / 로컬 포트 포워드를 통해 연결하면 게이트웨이는 원격 주소를 127.0.0.1로 볼 수 있습니다. 좋은 클라이언트 보고 IP를 덮어쓰지 않기 위해 루프백 원격 주소는 무시됩니다.
소비자
macOS Instances 탭
macOS 앱은 system-presence 출력을 렌더링하고 마지막 업데이트 나이에 따라 작은 상태 표시기 (Active/Idle/Stale)를 적용합니다.
디버깅 팁
- 원시 목록을 보려면 게이트웨이에 대해
system-presence를 호출하십시오. - 중복이 보이는 경우:
- 클라이언트가 핸드셰이크에서 안정적인
client.instanceId를 보내는지 확인하십시오 - 주기적 비콘이 동일한
instanceId를 사용하는지 확인하십시오 - 연결 유래 항목에
instanceId가 누락되어 있는지 확인하십시오 (중복은 예상됨)
- 클라이언트가 핸드셰이크에서 안정적인