OpenClaw 로그 분석 및 디버깅 가이드: 문제 해결 5분 완성

코드를 짜다 보면 분명히 잘 돌아가야 하는데 왜인지 모르게 동작하지 않는 순간이 있죠. 이럴 때 가장 먼저 확인해야 할 것은 역시 로그입니다. OpenClaw에서 문제를 빠르게 파악하고 해결할 수 있는 디버깅 팁을 정리해 드릴게요.

문제가 생겼을 때 당황하지 않고 원인을 찾아낼 수 있도록, 로그 확인법부터 서비스 복구 방법까지 차근차근 설명해 드릴게요.

OpenClaw 로그는 어디에 저장되나요?

로그 파일은 $OPENCLAW_STATE_DIR/logs (기본 경로: ~/.openclaw/logs)에서 확인할 수 있어요.

빠르게 접근하려면 다음 명령어를 사용해 보세요:

# Open logs directory
openclaw logs --path

# Tail live
openclaw logs --follow

# Show last 500 lines
openclaw logs

로그는 매일 로테이션되며, 구조화된 파싱을 위해 JSON 형식으로도 제공됩니다.

실시간으로 로그를 확인하려면 어떻게 하나요?

실시간 로그 확인은 다음 명령어로 가능해요:

openclaw logs --follow

# Filter JSON logs
openclaw logs --follow --json | jq 'select(.level == "error")'

메시지는 도착했는데 답장이 없어요. 어떻게 디버깅하나요?

1. 먼저 로그를 확인하세요:

   openclaw logs --follow

2. 임시로 디버그 모드를 실행해 보세요:

   openclaw gateway stop
   OPENCLAW_DEBUG=1 openclaw gateway start

3. 채널이 정상적으로 연결되었는지, 메시지가 무시되지는 않았는지 확인하세요:

   openclaw channels status

4. 세션과 모델의 상태를 확인하세요:

   openclaw status
   openclaw models status

5. 로그에서 rate-limit, auth 또는 모델 관련 에러가 있는지 찾아보세요.

로그가 너무 많거나 부족해요. 어떻게 조절하나요?

gateway.logLevel 설정을 통해 조절할 수 있어요 (기본값: info):

• debug = 아주 상세함
• info = 일반적임
• warn = 경고와 에러만 표시
• error = 에러만 표시

{
  gateway: { logLevel: "debug" }
}

크래시 이후 서비스가 자동으로 재시작되지 않아요. 무엇이 문제일까요?

사용 중인 서비스 매니저(launchd/systemd) 설정을 확인해 보세요:

• launchd: KeepAlive 값이 true여야 합니다.
• systemd: Restart=on-failure와 WantedBy=multi-user.target 설정이 필요합니다.

서비스 상태는 다음 명령어로 확인할 수 있어요:

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw
journalctl --user -u openclaw -n 100

프로그래밍 방식으로 Gateway 상태를 확인하려면 어떻게 하나요?

curl http://localhost:18789/health

# Or via CLI
openclaw health
openclaw health --json

실수로 설정을 망가뜨렸어요. 어떻게 초기화하나요?

# Full reset (wipes config, creds, sessions)
openclaw reset --scope full --yes

# Or just sessions
openclaw reset --scope sessions --yes

초기화 후에는 온보딩 과정을 다시 진행해 주세요:

openclaw onboard --install-daemon

버그는 어떻게 제보하나요?

1. 디버그 로그를 활성화해서 문제를 재현해 보세요:

   OPENCLAW_DEBUG=1 openclaw gateway restart

2. GitHub Issues에 이미 알려진 문제인지 확인합니다.
3. 새로운 이슈를 등록할 때는 다음 정보를 포함해 주세요:
   • OpenClaw 버전 (openclaw --version)
   • OS 및 Node 버전
   • 관련 로그 스니펫 (API 키나 토큰은 반드시 가려주세요)
   • 재현 단계

도움이 필요하신가요? AI Setup Assistant에게 물어보세요.

다음 단계

• CLI Reference
• Configuration Guide