OpenClaw Presence로 연결 상태 관리하기

분산 시스템이나 Gateway를 운영하다 보면 지금 누가, 어떤 장치로 연결되어 있는지 파악하기가 쉽지 않죠. 특히 여러 클라이언트가 동시에 접속하는 환경에서는 현재 활성화된 인스턴스를 한눈에 파악하는 것이 운영 효율성에 큰 차이를 만듭니다.

OpenClaw의 Presence 기능을 사용하면 Gateway 자체의 상태는 물론, macOS 앱, WebChat, CLI 등 연결된 모든 클라이언트의 가시성을 확보할 수 있어요.

필요한 것

• 실행 중인 OpenClaw Gateway
• 연결된 클라이언트 (macOS 앱, WebChat, CLI, Node 등)

빠른 시작

OpenClaw의 Presence 기능을 사용하면 Gateway와 연결된 클라이언트들의 상태를 5분 안에 확인할 수 있어요.

1. macOS 앱 확인: 앱 내의 Instances 탭을 클릭하세요. 현재 연결된 모든 인스턴스 목록과 상태(Active/Idle/Stale)가 바로 나타납니다.
2. API 호출: 원시 데이터를 직접 보고 싶다면 Gateway를 대상으로 system-presence를 호출하세요.
3. 데이터 필드 파악: 반환된 객체에서 instanceId(고유 식별자), host(호스트 이름), mode(ui, webchat, cli 등), lastInputSeconds(마지막 입력 후 경과 시간) 등을 확인합니다.
4. 상태 모니터링: ts 필드의 타임스탬프를 통해 데이터가 언제 마지막으로 업데이트되었는지 체크하세요.

문제 해결

• CLI 명령어가 목록에 보이지 않아요: CLI는 보통 일회성 명령을 위해 짧게 연결됩니다. 목록이 복잡해지는 것을 방지하기 위해 client.mode === "cli"인 경우에는 Presence 항목으로 생성되지 않아요.
• 목록에 중복된 항목이 나타나요: 클라이언트가 재연결될 때 고유한 instanceId를 보내지 않으면 중복 행이 생길 수 있어요. 핸드쉐이크 시 connect.client.instanceId가 일관되게 전송되는지 확인하세요.
• IP 주소가 127.0.0.1로 표시돼요: SSH 터널이나 로컬 포트 포워딩을 통해 연결하면 Gateway가 원격 주소를 127.0.0.1로 인식할 수 있어요. OpenClaw는 클라이언트가 보고한 유효한 IP를 덮어쓰지 않도록 루프백 주소는 무시합니다.
• 데이터가 자동으로 사라져요: Presence는 메모리에 저장되는 일시적인 데이터예요. 5분이 지나거나 전체 항목이 200개를 넘으면 오래된 순서대로 자동 삭제됩니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• System Events API 문서
• Gateway 설정 가이드