트러블슈팅 (Troubleshooting)
OpenClaw 사용 중 발생하는 문제를 해결하는 방법을 안내합니다.
섹션 개요
| 문서 | 내용 |
|---|---|
| 일반적인 에러 | 자주 발생하는 20가지 에러 |
| 디버깅 | 디버그 모드와 진단 도구 |
| 엣지 케이스 | 희귀한 문제 상황 |
빠른 문제 해결
1단계: 진단
# 시스템 상태 확인
openclaw doctor
# 게이트웨이 상태 확인
openclaw gateway status
# 로그 확인
openclaw logs --level error --follow
2단계: 일반적인 해결책
| 문제 | 해결책 |
|---|---|
| 설치 실패 | Node.js 22+ 확인 후 재설치 |
| 토큰 오류 | 토큰 재발급 및 설정 확인 |
| 포트 충돌 | 다른 포트 사용 또는 프로세스 종료 |
| 메모리 부족 | 세션 제한 늘리기 |
| 연결 실패 | 방화벽 및 프록시 설정 확인 |
3단계: 상세 가이드 참조
각 문제의 상세 가이드를 참조하세요.
문제 해결 흐름
문제 발생
↓
openclaw doctor (진단)
↓
로그 확인 (openclaw logs --follow)
↓
문제 유형 식별
↓
해결책 적용
↓
검증
↓
해결됨? ──→ 예: 완료
│
아니오
↓
상세 가이드 참조
↓
공식 문서 확인
↓
커뮤니티 질문
진단 도구
openclaw doctor
시스템 상태를 전체 진단합니다:
$ openclaw doctor
Node.js: v22.0.0
npm: 10.0.0
OpenClaw: v1.2.0
Config: Valid
Gateway: Running
Port 3000: Already in use (경고)
로그 분석
# 실시간 로그
openclaw logs --follow
# 에러만 표시
openclaw logs --level error
# 특정 채널 필터링
openclaw logs --filter telegram
# 지난 1시간
openclaw logs --since 1h
문제 유형별 해결책
설치 문제
| 증상 | 해결책 |
|---|---|
command not found |
PATH에 추가 또는 재설치 |
EACCES |
권한 문제, sudo 없이 npm fix |
| 버전 충돌 | npm ls openclaw로 확인 |
연결 문제
| 증상 | 해결책 |
|---|---|
ECONNREFUSED |
방화벽/포트 확인 |
ETIMEDOUT |
프록시 설정 확인 |
| 토큰 오류 | 토큰 재발급 |
성능 문제
| 증상 | 해결책 |
|---|---|
| 느린 응답 | historyLimit 줄이기 |
| 높은 CPU | 세션 제한 늘리기 |
| 메모리 부족 | maxMessages 줄이기 |
자주 묻는 질문
Q: 문제를 보고하려면 어떤 정보가 필요한가요?
다음 정보를 포함하세요:
- OpenClaw 버전 (
openclaw --version) - 운영체제 및 Node.js 버전
- 에러 메시지 전체
- 재현 단계
- 로그 파일 (
openclaw logs > logs.txt)
Q: 버그를 신고하는 방법은?
GitHub Issues에 버그 리포트를 생성하세요.
Q: 긴급 지원이 필요합니다.
Discord 커뮤니티에 가입하거나 유료 지원을 확인하세요.
추가 리소스
참고: