OpenClaw CLI: 헬스 체크 및 연결 상태 진단 가이드

개발을 하다 보면 서비스가 제대로 돌아가고 있는지, 연결은 끊기지 않았는지 답답할 때가 많죠. 특히 여러 채널의 연결 상태를 일일이 확인하는 건 꽤 번거로운 일이에요. 이제 추측은 그만하고, CLI를 통해 확실하게 상태를 점검해 보세요.

Health Checks (CLI)

추측에 의존하지 않고 채널 연결 상태를 확인할 수 있는 간단한 가이드입니다.

빠른 확인 방법 (Quick checks)

• openclaw status — 로컬 요약: Gateway 도달 가능 여부 및 모드, 업데이트 힌트, 연결된 채널의 인증 기간, 세션 및 최근 활동을 보여줍니다.
• openclaw status --all — 전체 로컬 진단 (읽기 전용이며 컬러로 출력되어 디버깅용으로 복사하기 좋습니다).
• openclaw status --deep — 실행 중인 Gateway까지 조사합니다 (지원되는 경우 채널별 프로브를 수행합니다).
• openclaw health --json — 실행 중인 Gateway에 전체 헬스 스냅샷을 요청합니다 (WS 전용이며, Baileys 소켓에 직접 연결하지 않습니다).
• WhatsApp이나 WebChat에서 /status 메시지를 단독으로 보내면 에이전트를 호출하지 않고도 상태 응답을 받을 수 있습니다.
• 로그 확인: /tmp/openclaw/openclaw-*.log 파일을 tail로 확인하며 web-heartbeat, web-reconnect, web-auto-reply, web-inbound 항목을 필터링해 보세요.

심층 진단 (Deep diagnostics)

• 디스크의 자격 증명(Creds): ls -l ~/.openclaw/credentials/whatsapp/<accountId>/creds.json (mtime이 최근이어야 합니다).
• 세션 저장소: ls -l ~/.openclaw/agents/<agentId>/sessions/sessions.json (경로는 설정에서 변경할 수 있습니다). 세션 수와 최근 수신자는 status 명령어를 통해 확인할 수 있습니다.
• 재연결 흐름: 로그에 상태 코드 409–515 또는 loggedOut이 나타나면 openclaw channels logout && openclaw channels login --verbose를 실행하세요. (참고: QR 로그인 흐름은 페어링 후 상태 코드 515가 발생하면 자동으로 한 번 재시작됩니다.)

헬스 모니터 설정 (Health monitor config)

• gateway.channelHealthCheckMinutes: Gateway가 채널 상태를 체크하는 주기입니다. 기본값은 5입니다. 0으로 설정하면 전역적으로 헬스 모니터 재시작 기능을 비활성화합니다.
• gateway.channelStaleEventThresholdMinutes: 연결된 채널이 유휴 상태로 유지될 때, 헬스 모니터가 이를 ‘stale(오래됨)‘로 간주하고 재시작하기까지의 시간입니다. 기본값은 30입니다. 이 값은 gateway.channelHealthCheckMinutes보다 크거나 같게 유지하세요.
• gateway.channelMaxRestartsPerHour: 채널/계정당 헬스 모니터 재시작 횟수를 1시간 단위로 제한합니다. 기본값은 10입니다.
• channels.<provider>.healthMonitor.enabled: 전역 모니터링은 유지하면서 특정 채널의 헬스 모니터 재시작만 비활성화할 수 있습니다.
• channels.<provider>.accounts.<accountId>.healthMonitor.enabled: 채널 수준 설정보다 우선순위가 높은 다중 계정용 개별 설정입니다.
• 이러한 채널별 설정은 현재 Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, WhatsApp 등 내장 채널 모니터에서 지원됩니다.

문제가 발생했을 때 (When something fails)

• logged out 또는 상태 코드 409–515 발생 → openclaw channels logout 실행 후 openclaw channels login으로 다시 연결하세요.
• Gateway에 접속할 수 없음 → openclaw gateway --port 18789 명령어로 시작하세요 (포트가 이미 사용 중이라면 --force를 사용하세요).
• 인바운드 메시지가 오지 않음 → 연결된 폰이 온라인 상태인지, 발신자가 허용되었는지(channels.whatsapp.allowFrom) 확인하세요. 그룹 채팅의 경우 허용 리스트와 멘션 규칙(channels.whatsapp.groups, agents.list[].groupChat.mentionPatterns)이 일치하는지 확인해야 합니다.

전용 “health” 명령어 (Dedicated “health” command)

openclaw health --json 명령어는 실행 중인 Gateway에 헬스 스냅샷을 요청합니다 (CLI에서 채널 소켓에 직접 연결하지 않습니다). 사용 가능한 경우 연결된 인증 정보 및 인증 기간, 채널별 프로브 요약, 세션 저장소 요약, 프로브 소요 시간을 보고합니다. Gateway에 연결할 수 없거나 프로브가 실패 또는 타임아웃되면 0이 아닌 종료 코드를 반환합니다.

옵션:

• --json: 기계가 읽을 수 있는 JSON 형식으로 출력합니다.
• --timeout <ms>: 기본 10초인 프로브 타임아웃 시간을 변경합니다.
• --probe: 캐시된 헬스 스냅샷을 반환하는 대신 모든 채널에 대해 실시간 프로브를 강제로 실행합니다.

헬스 스냅샷에는 ok (불리언), ts (타임스탬프), durationMs (프로브 시간), 채널별 상태, 에이전트 가용성, 세션 저장소 요약 정보가 포함됩니다.

AI Setup Assistant

다음 단계

• CLI Reference
• Gateway Configuration