문제 해결

이 페이지는 상세 실행 지침서입니다. 빠른 분류 흐름을 먼저 원한다면 /help/troubleshooting에서 시작하세요.

명령 사다리

먼저 다음을 이 순서대로 실행하세요.

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

예상되는 정상 신호:

• openclaw gateway status가 Runtime: running, Connectivity probe: ok, 그리고 Capability: ... 줄을 표시합니다.
• openclaw doctor가 차단되는 구성/서비스 문제가 없다고 보고합니다.
• openclaw channels status --probe가 계정별 실시간 전송 상태와, 지원되는 경우 works 또는 audit ok 같은 프로브/감사 결과를 표시합니다.

업데이트 후

업데이트가 완료되었지만 Gateway가 내려가 있거나, 채널이 비어 있거나, 모델 호출이 401로 실패하기 시작할 때 사용하세요.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

확인할 항목:

• openclaw status / openclaw status --all의 Update restart. 보류 중이거나 실패한 인계에는 다음에 실행할 명령이 포함됩니다.
• Channels 아래의 plugin load failed: dependency tree corrupted; run openclaw doctor --fix. 이는 채널 구성은 여전히 존재하지만, 채널이 로드되기 전에 Plugin 등록이 실패했다는 뜻입니다.
• 재인증 후 provider 401. openclaw doctor --fix는 오래된 agent별 OAuth 인증 섀도를 확인하고 이전 복사본을 제거하여 모든 agent가 현재 공유 프로필을 해석하도록 합니다.

분리된 설치와 더 새로운 구성 보호 장치

Gateway 서비스가 업데이트 후 예기치 않게 중지되거나, 로그에 한 openclaw 바이너리가 마지막으로 openclaw.json을 쓴 버전보다 오래되었다고 표시될 때 사용하세요.

OpenClaw는 구성 쓰기에 meta.lastTouchedVersion을 찍습니다. 읽기 전용 명령은 더 새로운 OpenClaw가 쓴 구성을 계속 검사할 수 있지만, 프로세스와 서비스 변경은 더 오래된 바이너리에서 계속 진행하지 않습니다. 차단되는 작업에는 Gateway 서비스 시작, 중지, 재시작, 제거, 강제 서비스 재설치, 서비스 모드 Gateway 시작, 그리고 gateway --force 포트 정리가 포함됩니다.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

롤백 후 프로토콜 불일치

OpenClaw를 다운그레이드하거나 롤백한 뒤 로그에 protocol mismatch가 계속 출력될 때 사용하세요. 이는 더 오래된 Gateway가 실행 중이지만, 더 새로운 로컬 클라이언트 프로세스가 여전히 더 오래된 Gateway가 처리할 수 없는 프로토콜 범위로 다시 연결하려 한다는 뜻입니다.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

확인할 항목:

• Gateway 로그의 protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>.
• openclaw gateway status --deep의 Established clients: 또는 openclaw doctor --deep의 Gateway clients. 이는 OS가 허용할 때 PID와 명령줄을 포함해 Gateway 포트에 연결된 활성 TCP 클라이언트를 나열합니다.
• 명령줄이 롤백한 더 새로운 OpenClaw 설치 또는 래퍼를 가리키는 클라이언트 프로세스.

수정:

1. gateway status --deep에 표시된 오래된 OpenClaw 클라이언트 프로세스를 중지하거나 재시작하세요.
2. 로컬 대시보드, 편집기, 앱 서버 헬퍼, 오래 실행 중인 openclaw logs --follow 셸처럼 OpenClaw를 포함하는 앱 또는 래퍼를 재시작하세요.
3. openclaw gateway status --deep 또는 openclaw doctor --deep를 다시 실행하고 오래된 클라이언트 PID가 사라졌는지 확인하세요.

더 오래된 Gateway가 더 새로운 호환되지 않는 프로토콜을 수락하게 만들지 마세요. 프로토콜 증가는 와이어 계약을 보호합니다. 롤백 복구는 프로세스/버전 정리 문제입니다.

경로 이탈로 인해 Skill 심볼릭 링크 건너뜀

로그에 다음이 포함될 때 사용하세요.

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OpenClaw는 모든 skill 루트를 포함 경계로 취급합니다. ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, 또는 ~/.openclaw/skills 아래의 심볼릭 링크는 실제 대상이 해당 루트 밖으로 해석되면 대상이 명시적으로 신뢰되지 않는 한 건너뜁니다.

링크를 검사하세요.

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

대상이 의도된 것이라면 직접 skill 루트와 허용된 심볼릭 링크 대상을 모두 구성하세요.

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

그런 다음 새 세션을 시작하거나 skills 감시자가 새로 고쳐질 때까지 기다리세요. 실행 중인 프로세스가 구성 변경보다 먼저 시작되었다면 gateway를 재시작하세요.

~, /, 또는 동기화된 프로젝트 폴더 전체 같은 광범위한 대상을 사용하지 마세요. 신뢰할 수 있는 SKILL.md 디렉터리를 포함하는 실제 skill 루트로 allowSymlinkTargets 범위를 유지하세요.

Skill Workshop 적용이 이러한 신뢰된 심볼릭 링크 workspace skill 경로에도 써야 한다면 skills.workshop.allowSymlinkTargetWrites를 활성화하세요. 읽기 전용 공유 skill 루트에는 비활성화된 상태로 두세요.

관련:

• Skills 구성
• 구성 예시

긴 컨텍스트에 Anthropic 429 추가 사용량 필요

로그/오류에 HTTP 429: rate_limit_error: Extra usage is required for long context requests가 포함될 때 사용하세요.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

확인할 항목:

• 선택된 Anthropic 모델이 GA 지원 1M Claude 4.x 모델이거나, 모델에 기존 params.context1m: true가 있습니다.
• 현재 Anthropic 자격 증명이 긴 컨텍스트 사용 자격을 갖추지 않았습니다.
• 1M 컨텍스트 경로가 필요한 긴 세션/모델 실행에서만 요청이 실패합니다.

수정 옵션:

관련:

• Anthropic
• 토큰 사용량과 비용
• Anthropic에서 HTTP 429가 표시되는 이유는 무엇인가요?

업스트림 403 차단 응답

업스트림 LLM provider가 Your request was blocked 같은 일반 403을 반환할 때 사용하세요.

이것이 항상 OpenClaw 구성 문제라고 가정하지 마세요. 응답은 CDN, WAF, 봇 관리 규칙 또는 OpenAI 호환 엔드포인트 앞단의 리버스 프록시 같은 업스트림 보안 계층에서 올 수 있습니다.

openclaw statusopenclaw gateway statusopenclaw logs --follow

확인할 항목:

• 같은 provider 아래 여러 모델이 같은 방식으로 실패함
• 정상적인 provider API 오류 대신 HTML 또는 일반 보안 텍스트
• 같은 요청 시간에 provider 측 보안 이벤트
• 작은 직접 curl 프로브는 성공하지만 일반 SDK 형태 요청은 실패함

증거가 WAF/CDN 차단을 가리키면 provider 측 필터링을 먼저 수정하세요. OpenClaw가 사용하는 API 경로에 대해 좁게 범위가 지정된 허용 또는 건너뛰기 규칙을 선호하고, 전체 사이트의 보호를 비활성화하지 마세요.

관련:

• OpenAI 호환 엔드포인트
• Provider 구성
• 로그

로컬 OpenAI 호환 백엔드는 직접 프로브를 통과하지만 agent 실행은 실패함

다음일 때 사용하세요.

• curl ... /v1/models가 작동함
• 작은 직접 /v1/chat/completions 호출이 작동함
• OpenClaw 모델 실행이 일반 agent 턴에서만 실패함

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

확인할 항목:

• 작은 직접 호출은 성공하지만 OpenClaw 실행은 더 큰 프롬프트에서만 실패함
• 같은 기본 모델 id로 직접 /v1/chat/completions가 작동하더라도 model_not_found 또는 404 오류가 발생함
• messages[].content가 문자열이어야 한다는 백엔드 오류
• OpenAI 호환 로컬 백엔드에서 간헐적인 incomplete turn detected ... stopReason=stop payloads=0 경고
• 더 큰 프롬프트 토큰 수 또는 전체 agent 런타임 프롬프트에서만 나타나는 백엔드 크래시

관련:

• 구성
• 로컬 모델
• OpenAI 호환 엔드포인트

응답 없음

채널은 올라와 있지만 아무것도 응답하지 않으면, 무언가를 다시 연결하기 전에 라우팅과 정책을 확인하세요.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

확인할 항목:

• DM 발신자에 대해 페어링이 대기 중인지.
• 그룹 멘션 게이팅(requireMention, mentionPatterns).
• 채널/그룹 허용 목록 불일치.

일반적인 징후:

• drop guild message (mention required → 멘션될 때까지 그룹 메시지가 무시됩니다.
• pairing request → 발신자 승인이 필요합니다.
• blocked / allowlist → 발신자/채널이 정책에 의해 필터링되었습니다.

관련 항목:

• 채널 문제 해결
• 그룹
• 페어링

대시보드 제어 UI 연결

대시보드/제어 UI가 연결되지 않으면 URL, 인증 모드, 보안 컨텍스트 가정을 검증하세요.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

확인할 항목:

• 올바른 프로브 URL 및 대시보드 URL.
• 클라이언트와 Gateway 간 인증 모드/토큰 불일치.
• 디바이스 ID가 필요한 곳에서 HTTP를 사용하는지.

업데이트 후 로컬 브라우저가 127.0.0.1:18789에 연결할 수 없다면, 먼저 로컬 Gateway 서비스를 복구하고 대시보드를 제공 중인지 확인하세요.

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

curl이 OpenClaw HTML을 반환하면 Gateway는 작동 중이며, 남은 문제는 브라우저 캐시, 오래된 딥 링크, 또는 오래된 탭 상태일 가능성이 큽니다. http://127.0.0.1:18789를 직접 열고 대시보드에서 이동하세요. 재시작 후에도 서비스가 계속 실행되지 않으면 openclaw gateway start를 실행하고 openclaw gateway status를 다시 확인하세요.

인증 세부 코드 빠른 매핑

실패한 connect 응답의 error.details.code를 사용해 다음 작업을 선택하세요.

디바이스 인증 v2 마이그레이션 확인:

openclaw --versionopenclaw doctoropenclaw gateway status

로그에 논스/서명 오류가 표시되면 연결 클라이언트를 업데이트하고 검증하세요.

openclaw devices rotate / revoke / remove가 예상치 못하게 거부되는 경우:

• 페어링된 디바이스 토큰 세션은 호출자에게 operator.admin도 있는 경우가 아니면 자기 자신의 디바이스만 관리할 수 있습니다.
• openclaw devices rotate --scope ...는 호출자 세션이 이미 보유한 운영자 스코프만 요청할 수 있습니다.

관련 항목:

• 구성 (Gateway 인증 모드)
• 제어 UI
• 디바이스
• 원격 접근
• 신뢰할 수 있는 프록시 인증

Gateway 서비스가 실행 중이 아님

서비스가 설치되어 있지만 프로세스가 계속 유지되지 않을 때 사용하세요.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # 시스템 수준 서비스도 스캔

확인할 항목:

• 종료 힌트가 있는 Runtime: stopped.
• 서비스 구성 불일치(Config (cli) 대 Config (service)).
• 포트/리스너 충돌.
• --deep 사용 시 추가 launchd/systemd/schtasks 설치.
• Other gateway-like services detected (best effort) 정리 힌트.

관련 항목:

• 백그라운드 실행 및 프로세스 도구
• 구성
• Doctor

macOS Gateway가 조용히 응답을 멈췄다가, 대시보드를 건드리면 다시 응답함

macOS 호스트의 채널(Telegram, WhatsApp 등)이 한 번에 몇 분에서 몇 시간 동안 조용해지고, 제어 UI를 열거나 SSH로 접속하거나 그 밖의 방식으로 호스트와 상호작용하는 순간 Gateway가 다시 돌아오는 것처럼 보일 때 사용하세요. 확인할 때쯤에는 Gateway가 다시 살아 있으므로 보통 openclaw status에는 명확한 증상이 없습니다.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

확인할 사항:

• ~/.openclaw/logs/stability/에 있는 하나 이상의 *-uncaught_exception.json 번들에서 error.code가 ENETDOWN, ENETUNREACH, EHOSTUNREACH, ECONNREFUSED 같은 일시적 네트워크 코드로 설정되어 있는지 확인합니다.
• 충돌 타임스탬프와 일치하는 Entering Sleep state due to 'Maintenance Sleep' 또는 en0 driver is slow (msg: WillChangeState to 0) 같은 pmset -g log 줄을 확인합니다. Power Nap / Maintenance Sleep은 Wi-Fi 드라이버를 잠깐 상태 0으로 전환합니다. 그 시간대에 걸린 모든 아웃바운드 connect()는 그 외에는 네트워크 연결이 정상인 호스트에서도 ENETDOWN으로 실패할 수 있습니다.
• launchctl print 출력에서 state = not running이 표시되고 최근 runs가 여러 번 있으며 종료 코드가 있는지 확인합니다. 특히 충돌과 다음 실행 사이의 간격이 몇 초가 아니라 한 시간 정도일 때 그렇습니다. macOS launchd는 충돌이 짧은 시간에 몰린 뒤 문서화되지 않은 재시작 보호 게이트를 적용하며, 대화형 로그인, 대시보드 연결, launchctl kickstart 같은 외부 트리거가 다시 활성화할 때까지 KeepAlive=true를 더 이상 따르지 않을 수 있습니다.

일반적인 징후:

• error.code가 ENETDOWN 또는 유사 코드이고 호출 스택이 Node net lookupAndConnect / Socket.connect를 가리키는 안정성 번들. OpenClaw 2026.5.26 이상은 이를 무해한 일시적 네트워크 오류로 분류하므로 더 이상 최상위 미처리 핸들러로 전파되지 않습니다. 더 오래된 릴리스를 사용 중이라면 먼저 업그레이드하세요.
• Control UI에 연결하거나 호스트에 SSH로 접속하는 즉시 끝나는 긴 무활동 기간: Gateway에 대해 대시보드가 수행한 작업이 아니라 사용자에게 보이는 활동이 launchd의 재시작 게이트를 다시 활성화합니다.
• 하루 동안 runs 횟수가 증가하지만 ~/Library/Logs/openclaw/gateway.log에 대응하는 received SIG*; shutting down 줄이 없는 경우: 정상 종료는 신호를 기록하지만, 일시적 충돌은 기록하지 않습니다.

해야 할 일:

1. 2026.5.26 이전 릴리스를 실행 중이라면 Gateway를 업그레이드합니다. 업그레이드 후에는 이후의 ENETDOWN 오류가 프로세스를 종료하는 대신 경고로 기록됩니다.

2. 항상 켜져 있는 서버로 실행해야 하는 Mac mini / 데스크톱 호스트에서는 유지 관리 절전 활동을 줄입니다.

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   이렇게 하면 근본적인 드라이버 상태 변동이 크게 줄어들지만 완전히 없어지지는 않습니다. 시스템은 이 플래그와 관계없이 TCP keepalive 및 mDNS 유지 관리를 위해 일부 유지 관리 절전을 계속 수행할 수 있습니다.

3. 향후 충돌이 짧은 시간에 몰려 launchd에 의해 정지되는 상황을 빠르게 감지하도록 활성 상태 감시기를 추가합니다.

   # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   핵심은 재시작 게이트를 외부에서 다시 활성화하는 것입니다. macOS에서는 충돌이 짧은 시간에 몰린 뒤 KeepAlive=true만으로는 충분하지 않습니다.

관련 항목:

• macOS 플랫폼 참고 사항
• 로깅
• 진단 도구

높은 메모리 사용 중 Gateway가 종료됨

Gateway가 부하 상태에서 사라지거나, 감독자가 OOM 유형의 재시작을 보고하거나, 로그에 critical memory pressure bundle written이 언급될 때 사용합니다.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

확인할 사항:

• 최신 안정성 번들의 Reason: diagnostic.memory.pressure.critical.
• critical/rss_threshold, critical/heap_threshold, critical/rss_growth가 포함된 Memory pressure:.
• 힙 한도에 가까운 V8 heap: 값.
• agents/<agent>/sessions/<session>.jsonl 또는 sessions/<session>.jsonl 같은 Largest session files: 항목.
• Gateway가 컨테이너 또는 메모리 제한 서비스 안에서 실행될 때의 Linux cgroup 메모리 카운터.

일반적인 징후:

• 재시작 직전에 critical memory pressure bundle written이 나타남 → OpenClaw가 OOM 전 안정성 번들을 캡처했습니다. openclaw gateway stability --bundle latest로 검사하세요.
• Gateway 로그에 memory pressure: level=critical ... memoryPressureSnapshot=disabled가 나타남 → OpenClaw가 심각한 메모리 압박을 감지했지만, OOM 전 안정성 스냅샷은 꺼져 있습니다.
• Largest session files:가 매우 큰 수정된 대화 기록 경로를 가리킴 → 재시작하기 전에 보존된 세션 기록을 줄이고, 세션 증가를 검사하거나, 오래된 대화 기록을 활성 저장소 밖으로 옮깁니다.
• V8 heap: 사용 바이트가 힙 한도에 가까움 → 프롬프트/세션 압박을 낮추고, 동시 작업을 줄이거나, 워크로드가 예상된 것임을 확인한 뒤에만 Node 힙 한도를 높입니다.
• Memory pressure: critical/rss_growth → 하나의 샘플링 창 안에서 메모리가 빠르게 증가했습니다. 최신 로그에서 대규모 가져오기, 폭주하는 도구 출력, 반복 재시도, 대기열에 쌓인 에이전트 작업 묶음을 확인하세요.
• 로그에는 심각한 메모리 압박이 나타나지만 번들이 없음 → 이것이 기본값입니다. 향후 심각한 메모리 압박 이벤트에서 OOM 전 안정성 번들을 캡처하려면 diagnostics.memoryPressureSnapshot: true를 설정하세요.

안정성 번들에는 페이로드가 없습니다. 여기에는 운영 메모리 증거와 수정된 상대 파일 경로가 포함되며, 메시지 텍스트, Webhook 본문, 자격 증명, 토큰, 쿠키, 원시 세션 ID는 포함되지 않습니다. 원시 로그를 복사하는 대신 버그 보고서에 진단 내보내기를 첨부하세요.

관련 항목:

• Gateway 상태
• 진단 내보내기
• 세션

Gateway가 잘못된 구성을 거부함

Gateway 시작이 Invalid config로 실패하거나 핫 리로드 로그에 잘못된 편집을 건너뛰었다고 표시될 때 사용합니다.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

확인할 사항:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• 활성 구성 옆의 타임스탬프가 있는 openclaw.json.rejected.* 파일
• doctor --fix가 손상된 직접 편집을 복구한 경우 타임스탬프가 있는 openclaw.json.clobbered.* 파일
• OpenClaw는 각 구성 경로에 대해 최신 32개의 .clobbered.* 파일을 유지하고 더 오래된 파일을 순환합니다.

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

관련 항목:

• 구성
• 구성: 핫 리로드
• 구성: 엄격한 검증
• 진단 도구

Gateway 프로브 경고

openclaw gateway probe가 무언가에 도달했지만 여전히 경고 블록을 출력할 때 사용합니다.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

확인할 사항:

• JSON 출력의 warnings[].code 및 primaryTargetId.
• 경고가 SSH 폴백, 여러 Gateway, 누락된 범위, 또는 확인되지 않은 인증 참조에 관한 것인지 여부.

일반적인 징후:

• SSH tunnel failed to start; falling back to direct probes. → SSH 설정이 실패했지만, 명령이 직접 구성된 대상 또는 loopback 대상을 계속 시도했습니다.
• multiple reachable gateway identities detected → 서로 다른 Gateway가 응답했거나, OpenClaw가 도달 가능한 대상이 같은 Gateway인지 증명할 수 없었습니다. 같은 Gateway에 대한 SSH 터널, 프록시 URL, 또는 구성된 원격 URL은 전송 포트가 다르더라도 여러 전송을 가진 하나의 Gateway로 처리됩니다.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → 연결은 되었지만 세부 RPC가 범위로 제한되어 있습니다. 장치 ID를 페어링하거나 operator.read가 있는 자격 증명을 사용하세요.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → 연결은 되었지만 전체 진단 RPC 집합이 시간 초과되었거나 실패했습니다. 이를 진단 성능이 저하된 도달 가능한 Gateway로 취급하고, --json 출력에서 connect.ok와 connect.rpcOk를 비교하세요.
• Capability: pairing-pending 또는 gateway closed (1008): pairing required → Gateway가 응답했지만, 이 클라이언트는 일반 운영자 접근 전에 여전히 페어링/승인이 필요합니다.
• 확인되지 않은 gateway.auth.* / gateway.remote.* SecretRef 경고 텍스트 → 실패한 대상에 대해 이 명령 경로에서 인증 자료를 사용할 수 없었습니다.

관련 항목:

• Gateway
• 같은 호스트의 여러 Gateway
• 원격 접근

채널은 연결되었지만 메시지가 흐르지 않음

채널 상태가 연결됨이지만 메시지 흐름이 멈춘 경우 정책, 권한, 채널별 전달 규칙에 집중하세요.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

확인할 사항:

• DM 정책(pairing, allowlist, open, disabled).
• 그룹 허용 목록 및 멘션 요구 사항.
• 누락된 채널 API 권한/범위.

일반적인 징후:

• mention required → 그룹 멘션 정책에 의해 메시지가 무시되었습니다.
• pairing / 승인 대기 추적 → 발신자가 승인되지 않았습니다.
• missing_scope, not_in_channel, Forbidden, 401/403 → 채널 인증/권한 문제입니다.

관련 항목:

• 채널 문제 해결
• Discord
• Telegram
• WhatsApp

Cron 및 Heartbeat 전달

Cron 또는 Heartbeat가 실행되지 않았거나 전달되지 않은 경우 먼저 스케줄러 상태를 확인한 다음 전달 대상을 확인하세요.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

확인할 항목:

• Cron이 활성화되어 있고 다음 깨우기 시간이 있는지.
• 작업 실행 기록 상태(ok, skipped, error).
• Heartbeat 건너뛰기 이유(quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due).

관련 항목:

• Heartbeat
• 예약된 작업
• 예약된 작업: 문제 해결

Node가 페어링되었지만 도구가 실패함

Node가 페어링되었지만 도구가 실패하면 포그라운드, 권한, 승인 상태를 분리해서 확인하세요.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

확인할 항목:

• Node가 온라인이고 예상 기능을 갖추었는지.
• 카메라/마이크/위치/화면에 대한 OS 권한 부여.
• Exec 승인 및 허용 목록 상태.

일반적인 시그니처:

• NODE_BACKGROUND_UNAVAILABLE → node 앱이 포그라운드에 있어야 합니다.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → OS 권한이 누락되었습니다.
• SYSTEM_RUN_DENIED: approval required → exec 승인이 대기 중입니다.
• SYSTEM_RUN_DENIED: allowlist miss → 명령이 허용 목록에 의해 차단되었습니다.

관련 항목:

• Exec 승인
• Node 문제 해결
• Nodes

브라우저 도구 실패

Gateway 자체는 정상인데 브라우저 도구 작업이 실패할 때 사용하세요.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

확인할 항목:

• plugins.allow가 설정되어 있고 browser를 포함하는지.
• 유효한 브라우저 실행 파일 경로.
• CDP 프로필 도달 가능성.
• existing-session / user 프로필을 위한 로컬 Chrome 사용 가능 여부.

관련 항목:

• 브라우저(OpenClaw 관리형)
• 브라우저 문제 해결

업그레이드 후 갑자기 문제가 생긴 경우

대부분의 업그레이드 후 손상은 구성 드리프트 또는 이제 적용되는 더 엄격한 기본값 때문입니다.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

확인 후에도 서비스 구성과 런타임이 여전히 일치하지 않으면 같은 프로필/상태 디렉터리에서 서비스 메타데이터를 다시 설치하세요.

openclaw gateway install --forceopenclaw gateway restart

관련 항목:

• 인증
• 백그라운드 exec 및 프로세스 도구
• Gateway 소유 페어링

관련 항목

• Doctor
• FAQ
• Gateway 런북