OpenClaw 상태 체크: 어떤 채널이나 세션이 실제로 고장 났는지 파악하기

대부분의 에이전트 장애는 잘못된 질문에서 시작됩니다. 누군가는 “Slack이 고장 났어”라고 말하지만, Gateway는 정상이며 채널이 단순히 방을 무시하고 있는 상태일 수 있습니다. 누군가는 “세션이 사라졌어”라고 말하지만, 프로바이더 (provider)는 연결되어 있고 아직 새로운 대화 행 (conversation row)이 생성되지 않았을 뿐일 수도 있습니다. 진짜 문제는 만료된 토큰 (token), 오래된 허용 목록 (allowlist), 또는 설정된 대로 정확히 작동하고 있는 멘션 정책 (mention policy)인데, 사람들은 모든 것을 재시작해 버리곤 합니다. 이러한 이유로 OpenClaw는 운영자에게 여러 가지 상태 확인 인터페이스 (health surfaces)를 제공합니다. openclaw status는 로컬 채널 및 세션 상태를 요약합니다. openclaw health는 실행 중인 Gateway에 상태 스냅샷 (health snapshot)을 요청합니다. openclaw doctor는 구성 (configuration), 상태 (state), 플러그인 (plugins), 모델 준비 상태 (model readiness), 그리고 복구 가능한 문제들을 점검합니다. 채널 프로브 (Channel probes)는 프로바이더 전송 (provider transport)이 실제로 사용 가능한지 알려줍니다. 유용한 습관은 “마법 같은 명령어 하나를 실행하는 것”이 아닙니다. 파괴적인 조치를 취하기 전에 Gateway 상태, 채널 상태, 세션 상태, 그리고 응답 정책 (reply policy)을 분리하여 확인하는 것입니다.

가장 짧고 안전한 단계부터 시작하세요
채널 트러블슈팅 (troubleshooting) 문서는 실질적인 명령어 단계를 제공합니다. 느낌(vibes)만으로 진단하기 전에 다음을 실행하십시오: openclaw status, openclaw gateway status, openclaw logs --follow, openclaw doctor, openclaw channels status --probe. 이 단계는 의도적으로 보수적입니다. openclaw status는 빠르고 읽기 전용인 개요를 제공합니다. openclaw gateway status는 서비스 경계 (service boundary)가 실행 중인지 알려줍니다. openclaw logs --follow는 인바운드 메시지 (inbound messages), 재연결 (reconnects), 그리고 전송 (sends)과 관련된 실시간 이벤트를 보여줍니다. openclaw doctor는 더 넓은 시스템 상태를 점검합니다. openclaw channels status --probe는 구성된 채널들이 단순히 “설정 행이 존재함” 이상의 것을 증명하도록 요청합니다. 문서는 건강한 기준선 (baseline)을 실행 중인 런타임 (runtime), 정상적인 연결성 또는 RPC 프로브 (RPC probe), 그리고 프로바이더 및 OpenClaw 버전에 따라 전송이 연결되어 준비되었거나(ready), 작동 중이거나(working), 또는 감사 통과(audit-ok) 상태임을 보여주는 채널 프로브로 설명합니다. 만약 이 계층 중 하나가 빨간색(red)이라면, 해당 계층을 먼저 수정하십시오.

“Slack에서 응답이 없다”는 사실로부터 곧바로 에이전트 전체를 재구축하는 단계로 건너뛰지 마십시오. 운영자 개요를 위해 status를 사용하십시오. openclaw status는 제가 가장 먼저 시작하는 단계인데, 그 이유는 이 명령어가 다음과 같은 광범위한 질문에 답하기 때문입니다: "이 설치 환경은 현재 무엇이 살아있다고 판단하고 있는가?"

openclaw status
openclaw status --all
openclaw status --deep
openclaw status --usage

상태(status) 문서는 이를 채널(channels)과 세션(sessions)에 대한 진단(diagnostics)으로 정의합니다. 일반적인 명령어는 빠른 읽기 전용(read-only) 경로를 유지합니다. --all은 로컬 진단을 확장하여 비밀 정보(secrets) 개요와 사용 가능한 경우 SecretRef 문제에 대한 진단 섹션을 포함합니다. --deep은 지원되는 채널에 대해 실행 중인 게이트웨이(Gateway)를 통해 라이브 프로브(live probes)를 실행합니다. --usage는 정규화된 제공자 사용량(provider usage) 창을 남은 할당량(remaining quota)으로 출력합니다.

이러한 차이점은 중요합니다. 빠른 상태 스냅샷(status snapshot)은 분류(triage)에 유용합니다. 라이브 채널 증거가 필요한 경우에는 심층 상태 프로브(deep status probe)가 더 낫습니다. 사용량(usage)은 에이전트가 "작동"은 하지만 모델 호출(model calls)이 실패하거나 제한(throttled)될 때 유용합니다. 만약 고객 대상 자동화 기능을 디버깅하고 있다면, 채팅 앱의 스크린샷 10장보다는 status --all 한 번과 특정 채널 프로브(channel probe) 한 번을 보는 것이 훨씬 낫습니다.

상태(status)에는 채널 이름 이상의 정보가 포함됩니다. 문서에 따르면 여러 에이전트가 구성된 경우 에이전트별 세션 저장소(session stores)를 보여줄 수 있으며, 가능한 경우 게이트웨이(Gateway) 및 노드 호스트 서비스(node host service)의 설치/런타임 상태, 소스 체크아웃을 위한 업데이트 채널 및 git SHA, 그리고 해당 명령 경로에서 지원되는 비밀 정보(secret)를 사용할 수 없는 경우에도 충돌 없이 작동하는 SecretRef 진단 정보를 보여줄 수 있습니다. 이 점 덕분에 개인적인 정보가 포함되어 있는지 검토한 후라면, 내부 디버깅 스레드에 붙여넣기에 안전한 도구가 됩니다.

세션(sessions)과 소켓(sockets)을 혼동하지 마십시오. 이것이 가장 많은 시간을 낭비하게 만드는 함정입니다. 세션 행(Session rows)은 대화 상태(conversation state)입니다. 이는 제공자 소켓(provider socket)이 활성화되어 있다는 증거가 아닙니다. 게이트웨이 상태(Gateway health) 문서는 이를 직접적으로 지적합니다: Discord 및 기타 채팅 제공자의 경우, 세션 행은 저장된 대화 상태를 읽습니다. 제공자는 재연결될 수 있으며, 새로운 세션 행이 나타나기 전에 건강한 채널 상태(healthy channel status)를 보여줄 수 있습니다.

따라서 세션이 누락된 것처럼 보인다면, 두 가지 질문을 별도로 던져보아야 합니다. 첫째: 채널 전송(channel transport)이 연결되어 있으며 수신 또는 송신이 가능한 상태인가? openclaw health, openclaw status --deep, 또는 openclaw channels status --probe를 사용하십시오. 둘째: 새로운 인바운드 메시지(inbound message)가 실제로 게이트웨이(Gateway)에 도달하여 채널의 정책 게이트(policy gates)를 통과했는가? 로그(logs), 페어링 확인(pairing checks), 허용 목록(allowlists)을 사용하고 정책(policy)을 언급하십시오. 세션 행이 누락되었다는 사실 자체만으로는 채널 장애(channel outage)라고 할 수 없습니다. 더 심층적인 세션 동작을 파악하려면 이 내용을 OpenClaw 세션 관리 가이드와 함께 확인하십시오. 여기서 운영상의 핵심 요점은 더 간단합니다: 트랜스크립트 저장소(transcript store)를 탓하기 전에 전송(transport) 상태를 먼저 진단하십시오.

게이트웨이가 스스로의 상태를 증명해야 할 때는 health를 사용하십시오. openclaw health는 실행 중인 게이트웨이에 건강 상태 스냅샷(health snapshot)을 요청합니다. 문서에는 이것이 WS(WebSocket) 전용으로 설명되어 있지만, CLI가 직접 프로바이더 소켓(provider sockets)을 여는 것은 아닙니다. 이는 "현재 실행 중인 게이트웨이가 무엇을 알고 있는가?"라는 질문에 답하고자 할 때 정확히 원하는 방식입니다.

openclaw health
openclaw health --verbose
openclaw health --json
openclaw health --json --timeout 20000

openclaw health --json은 기계가 읽을 수 있는 출력(machine-readable output)을 제공합니다. --timeout <ms>는 기본 10초인 프로브(probe) 타임아웃을 변경합니다. 현재 문서에는 실시간 프로브를 강제하고 게이트웨이 연결 세부 정보를 출력하는 --verbose에 대해서도 설명되어 있습니다. 건강 상태 스냅샷에는 ok 불리언(boolean), 타임스탬프(timestamp), 프로브 지속 시간(probe duration), 채널별 상태(per-channel status), 에이전트 가용성(agent availability), 세션 저장소 요약(session-store summary)이 포함될 수 있습니다. 게이트웨이에 도달할 수 없거나 프로브가 실패 또는 타임아웃되면 0이 아닌 종료 코드(non-zero exit)로 종료됩니다. 이러한 종료 동작 덕분에 스크립트에서 유용하게 사용할 수 있습니다. 만약 예약된 작업(scheduled job)이 게이트웨이에 의존한다면, 건강 상태 체크를 통해 다운스트림 자동화(downstream automation)가 정상인 것처럼 가장하는 대신 작업을 차단(fail closed)할 수 있습니다. 만약 건강 상태 스냅샷이 게이트웨이에 도달할 수 없다고 한다면, 다음 단계는 Slack 범위 감사(Slack scope audit)가 아니라 게이트웨이 경계(Gateway boundary)를 확인하는 것입니다.

메모리, 모델 라우팅(model routing), 크론 잡(cron jobs), 브라우저 세션, 그리고 프로덕션 안전성에 대해서도 이러한 운영자 체크리스트가 필요하다면, 여기서 ClawKit을 확인하십시오. 어떤 의사가 변경을 허용받는지 확인하십시오. openclaw doctor는 더 넓은 범위의 건강 상태(health surface)를 다룹니다.

이는 게이트웨이(gateway) 및 채널(channel) 상태, 설정(configuration), 로컬 상태(local state), 플러그인 준비 상태(plugin readiness), 모델 라우팅(model routing), 메모리 준비 상태(memory readiness), 그리고 복구 가능한 설정 문제(repairable setup problems)를 점검합니다. openclaw doctor, openclaw doctor --lint, openclaw doctor --json, openclaw doctor --deep, openclaw doctor --fix --non-interactive를 사용할 수 있습니다. 이 포스처(posture)를 의도에 맞게 사용하십시오. 일반적인 명령어는 사람 중심의 점검과 안내 프롬프트(guided prompts)를 위한 것입니다. doctor --lint는 읽기 전용(read-only)이며 자동화 또는 검토 게이트(review gates)에 더 적합합니다. --json 옵션을 사용하면 구조화된 결과(structured findings)를 출력합니다. doctor --deep은 추가적인 서비스 상태를 스캔합니다. doctor --fix 또는 --repair는 지원되는 복구 작업을 적용할 수 있습니다. 복구 경로(repair path)는 단순히 무해한 잔업이 아닙니다. 문서에 따르면 --fix는 ~/.openclaw/openclaw.json.bak에 백업을 작성하고 알 수 없는 설정 키(config keys)를 삭제하며, 삭제된 항목을 목록으로 표시합니다. 대화형 프롬프트(Interactive prompts)는 stdin이 TTY이고 --non-interactive가 설정되지 않은 경우에만 실행되므로, 헤드리스 크론(headless cron) 실행 시 프롬프트가 필요한 수정 작업은 건너뛰게 됩니다. 상태 무결성 점검(State integrity checks)을 통해 고립된 트랜스크립트 파일(orphan transcript files)을 감지할 수 있지만, 이를 아카이브하려면 대화형 확인이 필요합니다. 즉, 증거가 필요할 때는 --lint를 사용하고, 통제된 변이(controlled mutation)를 수행할 준비가 되었을 때만 복구를 사용하십시오.

인증 실패(auth failures)와 정책 실패(policy failures)를 구분하십시오. 연결된 채널이라도 응답을 거부할 수 있습니다. 문제 해결(troubleshooting) 문서에는 제공자(provider)별 일반적인 징후들이 나열되어 있습니다. Slack의 경우, 앱 토큰(app token), 봇 토큰(bot token) 또는 스코프(scopes)가 잘못되어 소켓 모드(socket mode)가 연결되어 있음에도 응답이 실패할 수 있습니다. DM은 페어링(pairing)에 의해 차단될 수 있으며, 채널 메시지는 그룹 정책(group policy) 또는 채널 허용 목록(channel allowlists)에 의해 무시될 수 있습니다. Telegram의 경우, 봇이 온라인 상태임에도 멘션 요구 사항(mention requirements)이나 봇 개인정보 보호 모드(bot privacy mode)에 의해 그룹 가시성이 차단될 수 있습니다. Discord의 경우, 봇이 온라인 상태임에도 허용 목록(allowlists), 채널 규칙(channel rules) 또는 메시지 콘텐츠 의도(message content intent) 누락으로 인해 길드(guild) 답장이 차단될 수 있습니다. 가장 빠른 해결 방법은 실패 유형(failure class)에 따라 다릅니다. 제공자가 로그아웃되었거나 WhatsApp이 409-515 범위의 상태 코드(status codes)를 표시하는 경우, 상태(health) 문서에서는 재연결(relinking)을 권장합니다.

인바운드 메시지 (inbound messages)가 전혀 나타나지 않는다면, 모델 프롬프트 (model prompts)를 수정하기 전에 발신자 허용 목록 (sender allowlist), 그룹 허용 목록 (group allowlist), 그리고 멘션 정책 (mention policy)을 확인하십시오. 전송 실패 (send failures)가 네트워크 오류 (network errors)를 나타내는 경우, 에이전트 지침 (agent instructions)을 변경하는 대신 제공업체 API 라우팅 (provider API routing)과 로그 (logs)를 조사하십시오.

openclaw channels status --probe
openclaw channels logout
openclaw channels login --verbose

재연결 (Relinking)은 실제 동작이므로, 프로브 (probes)와 로그 (logs)가 이를 가리킬 때만 수행하십시오. WhatsApp의 경우, 해당 상태 코드 (status codes)나 loggedOut이 나타나면 로그아웃 (logout) 후 로그인 (login)할 것을 문서에서 권장합니다. 다른 제공업체의 경우, 채널 문제 해결 인덱스 (channel troubleshooting index)에 링크된 특정 문제 해결 페이지를 사용하십시오.

로그를 사용하여 메시지 경로를 증명하십시오
UI에서 “아무 일도 일어나지 않음 (nothing happened)”이라고 표시될 때, 로그는 메시지가 아예 도착하지 않았는지, 도착했으나 정책에 의해 드롭 (dropped)되었는지, 도착하여 작업 (work)을 생성했는지, 아니면 전송 단계에서 실패한 응답을 생성했는지를 알려줄 수 있습니다. 상태 (health) 문서에서는 OpenClaw 로그를 테일링 (tailing)하고 웹 하트비트 (web heartbeat), 재연결 (reconnect), 자동 응답 (auto-reply), 인바운드 이벤트 (inbound events)를 필터링할 것을 제안합니다.

tail -f /tmp/openclaw/openclaw- * .log | grep -E 'web-heartbeat|web-reconnect|web-auto-reply|web-inbound'

저는 로그를 채널 상태 (channel health)와 세션 상태 (session health) 사이의 가교로 취급합니다. 채널 프로브 (channel probe)는 전송 계층 (transport)이 연결되어 있다고 말할 수 있습니다. 세션 저장소 (session store)는 이전 대화 내용을 보여줄 수 있습니다. 로그는 이 특정 메시지가 라이브 경로 (live path)를 통해 전달되었는지 여부를 보여줍니다. 로그에 인바운드 이벤트 (inbound events)는 나타나지만 응답이 없다면, 멘션 게이팅 (mention gating), 허용 목록 (allowlists), 그룹 정책 (group policy), 도구/액션 요구 사항 (tool/action requirements), 모델/런타임 문제 (model/runtime issues), 그리고 전송 오류 (send errors)를 살펴보십시오. 로그에 인바운드 이벤트가 나타나지 않는다면, 에이전트 (agent)를 탓하지 마십시오. 메시지가 응답할 수 있는 시스템 부분에 도달조차 하지 못한 것입니다.

모니터를 조정하되, 장애를 숨기지 마십시오
OpenClaw에는 현재 노출되어 있는 내장 모니터 (built-in monitors)를 위한 채널 상태 모니터 (channel health monitor) 설정이 있으며, 여기에는 Discord, Google Chat, iMessage, Microsoft Teams, Signal, Slack, Telegram, WhatsApp이 포함됩니다.

문서화된 Gateway 설정에는 기본값이 5분인 gateway.channelHealthCheckMinutes, 기본값이 30분인 gateway.channelStaleEventThresholdMinutes, 그리고 기본값이 10회인 gateway.channelMaxRestartsPerHour가 있습니다. gateway.channelHealthCheckMinutes를 0으로 설정하면 전역적으로 상태 모니터링 재시작(health-monitor restarts)을 비활성화할 수 있습니다. 또한 channels.<provider>.healthMonitor.enabled를 통해 채널별로 재시작을 비활성화하거나, channels.<provider>.accounts.<accountId>.healthMonitor.enabled를 통해 계정별로 비활성화할 수 있습니다. 계정 수준의 재정의(override)가 채널 수준의 설정보다 우선합니다. 이는 제공자(provider)가 불안정하게 끊겼다 연결되기를 반복(flapping)할 때, 조사하는 동안 재시작으로 인한 혼란(restart churn)을 멈춰야 하는 경우에 유용합니다. 하지만 이것은 해결책이 아닙니다. 모니터링을 낮추거나 끄는 경우, 그 이유를 기록하고 대체 확인 절차를 검증한 뒤, 제공자가 안정되면 정상적인 모니터링을 다시 켜야 합니다.

제가 사용하는 의사결정 트리(decision tree)는 다음과 같습니다. openclaw status를 실행합니다. 만약 Gateway 또는 런타임(runtime)이 명확하게 다운된 상태라면, 서비스 계층(service layer) 단계에 머무르십시오. 실시간 Gateway/채널 증거가 필요한 경우에는 openclaw health --json 또는 openclaw status --deep을 실행합니다. 제공자별 증거가 필요한 경우에는 openclaw channels status --probe를 실행합니다. 세션 저장소(session store)를 탓하기 전에 실제 인바운드 메시지(inbound message)에 대한 로그를 확인하십시오. 프롬프트(prompts)를 변경하기 전에 페어링(pairing), 허용 목록(allowlists), 그룹 정책(group policy), 그리고 멘션 요구 사항(mention requirements)을 확인하십시오. 읽기 전용의 구조화된 결과가 필요하다면 openclaw doctor --lint --json을 실행한 다음, 수리가 적절한지 선택하십시오. 실패한 계층이 식별된 후에만 다시 연결(relink), 재시작(restart), 또는 수리(repair)를 수행하십시오.

상태 체크는 안심시켜 주는 초록색 배지를 수집하는 것이 아닙니다. 그것은 다음의 네 가지 서로 다른 문제를 혼동하지 않기 위한 것입니다: Gateway를 사용할 수 없음, 채널이 연결 해제됨, 메시지가 정책에 의해 차단됨, 또는 세션 상태(session state)가 예상과 다름. 이 문제들을 분리하고 나면, 해결책은 대개 간단합니다. 관련 운영 습관에 대해서는 상태 체크 가이드(health checks guide)와 재시도 정책 가이드(retry policy guide)를 읽어보십시오. 최고의 운영자는 이 부분에서 지루할 정도로 원칙을 지킵니다: 먼저 조사(probe)하고, 그다음에 수리(repair)하며, 검증된 내용만 보고하십시오. 전체 가이드를 원하시나요?

Get ClawKit — $9.99 Originally published at https://www.openclawplaybook.ai/blog/openclaw-status-checks-channel-session-health/ Get The OpenClaw Playbook → https://www.openclawplaybook.ai?utm_source=devto&utm_medium=article&utm_campaign=parasite-seo