문제 해결

이 문서는 심층 런북입니다. 먼저 빠른 트리아지 절차는 /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 등록에 실패했습니다.
• 재인증 후 공급자 401 오류: openclaw doctor --fix는 에이전트별로 남아 있는 오래된 OAuth 인증 섀도를 확인하고 이전 복사본을 제거하여 모든 에이전트가 현재 공유 프로필을 해석하도록 합니다.

분리된 설치와 최신 구성 보호 장치

업데이트 후 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

롤백 후 프로토콜 불일치

다운그레이드 또는 롤백 후 로그에 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: Gateway 포트에 연결된 활성 TCP 클라이언트이며, OS에서 허용하는 경우 PID와 명령줄도 표시됩니다.
• 롤백한 최신 OpenClaw 설치 또는 래퍼를 명령줄에서 가리키는 클라이언트 프로세스.

해결 방법:

1. gateway status --deep에 표시된 오래된 OpenClaw 클라이언트 프로세스를 중지하거나 다시 시작하십시오.
2. OpenClaw를 내장하는 앱 또는 래퍼를 다시 시작하십시오. 로컬 대시보드, 편집기, 앱 서버 도우미 또는 장시간 실행 중인 openclaw logs --follow 셸이 포함됩니다.
3. openclaw gateway status --deep 또는 openclaw doctor --deep을 다시 실행하여 오래된 클라이언트 PID가 사라졌는지 확인하십시오.

이전 Gateway가 호환되지 않는 최신 프로토콜을 허용하도록 만들지 마십시오. 프로토콜 버전 상향은 통신 계약을 보호합니다. 롤백 복구는 프로세스/버전 정리 문제입니다.

경로 이탈로 건너뛴 Skill 심볼릭 링크

로그에 다음 내용이 포함될 때 사용하십시오.

구성된 루트 외부로 이탈한 Skill 경로를 건너뜁니다: ... reason=symlink-escape

각 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를 다시 시작하십시오.

~, / 또는 전체 동기화 프로젝트 폴더와 같이 범위가 넓은 대상을 사용하지 마십시오. allowSymlinkTargets의 범위를 신뢰할 수 있는 SKILL.md 디렉터리가 포함된 실제 Skill 루트로 제한하십시오.

Skill Workshop 적용 작업에서도 신뢰할 수 있는 심볼릭 링크 기반 워크스페이스 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 모델이 정식 출시된 1M 지원 Claude 4.x 모델(Opus 4.6/4.7/4.8, Sonnet 4.6)이거나 모델 구성에 레거시 params.context1m: true가 여전히 포함되어 있습니다.
• 현재 Anthropic 자격 증명은 긴 컨텍스트 사용 자격이 없습니다.
• 1M 컨텍스트 경로가 필요한 긴 세션/모델 실행에서만 요청이 실패합니다.

해결 방법:

관련 항목:

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

업스트림 403 차단 응답

업스트림 LLM 공급자가 Your request was blocked와 같은 일반적인 403을 반환할 때 사용하십시오.

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

openclaw statusopenclaw gateway statusopenclaw logs --follow

확인할 사항:

• 동일한 공급자 아래의 여러 모델이 같은 방식으로 실패합니다.
• 정상적인 공급자 API 오류 대신 HTML 또는 일반적인 보안 문구가 표시됩니다.
• 동일한 요청 시간에 공급자 측 보안 이벤트가 있습니다.
• 작은 직접 curl 프로브는 성공하지만 일반적인 SDK 형태의 요청은 실패합니다.

증거가 WAF/CDN 차단을 가리키는 경우 공급자 측 필터링을 먼저 수정하십시오. OpenClaw가 사용하는 API 경로에 범위를 좁혀 허용 또는 건너뛰기 규칙을 적용하고, 전체 사이트의 보호 기능을 비활성화하지 마십시오.

관련 항목:

• OpenAI 호환 엔드포인트
• 공급자 구성
• 로그

직접 프로브는 통과하지만 에이전트 실행은 실패하는 로컬 OpenAI 호환 백엔드

다음 상황에서 사용하십시오.

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

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":"안녕하세요"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "안녕하세요" --jsonopenclaw logs --follow

확인할 사항:

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

관련 항목:

• 구성
• 로컬 모델
• 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 같은 일시적인 네트워크 코드로 설정되어 있습니다.
• 비정상 종료 타임스탬프와 일치하는 pmset -g log 줄에 Entering Sleep state due to 'Maintenance Sleep' 또는 en0 driver is slow (msg: WillChangeState to 0) 같은 내용이 있습니다. 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로 접속하는 즉시 끝나는 긴 비활성 기간입니다. launchd의 재생성 게이트를 다시 활성화하는 것은 사용자에게 보이는 활동이며, 대시보드가 Gateway에 수행하는 작업이 아닙니다.
• ~/Library/Logs/openclaw/gateway.log에 대응하는 received SIG*; shutting down 줄이 없는데도 하루 동안 runs 횟수가 증가합니다. 정상 종료 시에는 신호가 기록되지만, 일시적인 비정상 종료 시에는 기록되지 않습니다.

수행할 작업:

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에 의해 중지되더라도 빠르게 감지되도록 활성 상태 감시기를 추가하십시오.

   # 5분 간격 cron 또는 LaunchAgent에 적합한 launchd 인식 활성 상태 검사 예시state=$(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 플랫폼 참고 사항
• 로깅
• Doctor

중복 Gateway/Node LaunchAgent로 인한 macOS launchd 감독 루프

macOS 설치가 몇 초마다 계속 재시작되고, openclaw 상태 검사가 정상과 사용 불가 상태 사이를 오가며, 서비스가 실행 중인 것처럼 보여도 채널 디스패치가 멈추는 경우 사용하십시오.

이 문제는 ai.openclaw.gateway와 ai.openclaw.node LaunchAgent가 모두 활성화되어 있고 각각 OPENCLAW_LAUNCHD_LABEL을 주입하는 이전 설치에서 관찰되었습니다. 이 상태에서는 OpenClaw가 launchd 감독을 감지하고 재시작을 launchd에 다시 넘기려고 시도하다가 하나의 안정적인 Gateway 프로세스를 유지하는 대신 빠른 EADDRINUSE/재생성 루프에 빠질 수 있습니다.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

확인할 사항:

• 30초 동안의 샘플에서 하나의 안정적인 프로세스가 아니라 둘 이상의 Gateway PID가 나타납니다.
• gateway.log에 EADDRINUSE, another gateway instance is already listening 또는 반복되는 재시작/인계 줄이 있습니다.
• 하나의 관리형 Gateway 서비스만 실행해야 하는 호스트에서 ~/Library/LaunchAgents/ai.openclaw.gateway.plist와 ~/Library/LaunchAgents/ai.openclaw.node.plist가 동시에 로드되어 있습니다.

수행할 작업:

1. 이 호스트에서 Gateway 서비스만 실행해야 한다면 OpenClaw를 통해 관리형 Node 서비스를 제거하십시오. 원격 Node 기능을 위해 Node 서비스를 실제로 사용 중이라면 이 단계를 건너뛰십시오. 제거하면 이 호스트에서 해당 기능이 중지됩니다.

   openclaw node uninstall

2. OpenClaw를 시작하기 전에 상속된 launchd 마커를 제거하는 영구적인 Gateway 래퍼를 설치하십시오. 지원되는 --wrapper 옵션을 사용하십시오. 서비스 재설치, 업데이트 및 Doctor 복구 시 해당 파일이 다시 생성되므로 ~/.openclaw/service-env/ 아래의 생성된 파일을 편집하지 마십시오.

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install은 강제 재설치, 업데이트 및 Doctor 복구 후에도 래퍼 경로를 유지합니다.

3. Gateway가 단순히 수신 대기 중인 것이 아니라 안정적으로 RPC를 제공하는지 확인하십시오.

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID 샘플에는 계속 교체되는 PID 집합이 아니라 하나의 안정적인 프로세스가 표시되어야 하며, 인바운드 채널 디스패치가 재개되어야 합니다.

4. 근본적인 이중 LaunchAgent 루프가 수정된 릴리스로 업그레이드한 후에는 우회 방법을 제거하고 일반 관리형 서비스를 다시 설치하십시오.

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

관련 문서:

• macOS 플랫폼 참고 사항
• Doctor
• Gateway CLI

메모리 사용량이 많을 때 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이 있습니다.
• Memory pressure:에 critical/rss_threshold, critical/heap_threshold 또는 critical/rss_growth가 있습니다.
• V8 heap: 값이 힙 제한에 가깝습니다.
• Largest session files:에 agents/<agent>/sessions/<session>.jsonl 또는 sessions/<session>.jsonl 같은 항목이 있습니다.
• 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는 각 구성 경로마다 최신 .clobbered.* 파일 32개를 유지하고 오래된 파일을 순환 삭제합니다.

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

관련 문서:

• 구성
• 구성: 핫 리로드
• 구성: 엄격한 검증
• 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 설정에 실패했지만 명령은 구성된 직접 대상/루프백 대상에 대한 프로브를 계속 시도했습니다.
• 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 권한 부여.
• 실행 승인 및 허용 목록 상태.

일반적인 징후:

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

관련 항목:

• 실행 승인
• Node 문제 해결
• Node

브라우저 도구가 실패함

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

관련 항목:

• 인증
• 백그라운드 실행 및 프로세스 도구
• Node 페어링

관련 항목

• Doctor
• FAQ
• Gateway 실행 지침서