OpenClaw Manual OpenClaw
문제 해결 15 분 소요

OpenClaw 일반적인 오류와 해결 방법

설치 문제, API 오류, 채널 문제, 성능 문제를 포함한 일반적인 OpenClaw 오류를 진단하고 해결하는 종합 가이드입니다.

O

OpenClaw Manuals

Tutorial Authors

빠른 진단

특정 오류를 살펴보기 전에 다음 진단을 실행하세요:

bash 
# 전체 상태 확인
openclaw status

# 구성 검증
openclaw config validate

# 최근 오류 로그 확인
openclaw logs --tail 50 --level error

# 상태 점검 실행
openclaw doctor

설치 오류

오류: "Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

해결:

bash 
# nvm 사용 (권장)
nvm install 22
nvm use 22
nvm alias default 22

# 또는 Homebrew 사용 (macOS)
brew install node@22

# 확인
node --version  # v22.x.x가 표시되어야 함

오류: "EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

해결: sudo를 사용하지 마세요. 대신 npm 권한을 수정하세요:

bash 
# 옵션 1: nvm 사용 (권장)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 옵션 2: npm 기본 디렉토리 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 그런 다음 재설치
npm install -g openclaw@latest

오류: "Cannot find module"

Error: Cannot find module '@openclaw/core'

해결:

bash 
# npm 캐시 정리 및 재설치
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# 또는 설치 스크립트 사용
curl -fsSL https://openclaw.ai/install.sh | bash

오류: "gyp ERR! build error" (네이티브 모듈)

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

해결: 빌드 도구 설치:

bash 
# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API 및 인증 오류

오류: "401 Unauthorized"

Error: API request failed with status 401: Invalid API key

해결:

bash 
# API 키가 설정되었는지 확인
openclaw config get api-key

# 비어 있거나 잘못된 경우 다시 설정
openclaw config set api-key

# 키 형식 확인 (Anthropic 키는 sk-ant-로 시작)
# 추가 공백이나 따옴표가 없는지 확인

오류: "429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

해결:

json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

지속적인 속도 제한의 경우 API 티어를 업그레이드하거나 다른 모델을 사용하는 것을 고려하세요:

bash 
openclaw config set default-model claude-3-5-haiku

오류: "402 Payment Required"

Error: API request failed: Insufficient credits

해결:

  1. API 제공업체 잔액 확인
  2. 계정에 크레딧 추가
  3. 또는 사용량 제한 설정:
json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

오류: "Connection Refused" to API

Error: connect ECONNREFUSED api.anthropic.com:443

해결:

bash 
# 인터넷 연결 확인
ping api.anthropic.com

# 프록시 뒤에 있는지 확인
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 필요한 경우 프록시 구성
openclaw config set proxy http://your-proxy:8080

# 또는 방화벽/VPN 설정 확인

게이트웨이 오류

오류: "EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

해결:

bash 
# 포트를 사용 중인 프로세스 찾기
lsof -i :18789

# 프로세스 종료
kill -9 

# 또는 다른 포트 사용
openclaw gateway start --port 18790

# 새 포트를 사용하도록 구성 업데이트
openclaw config set gateway-port 18790

오류: "Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

해결:

bash 
# 구성 파일 구문 검증
openclaw config validate

# 손상된 경우 기본값으로 재설정
openclaw config reset --confirm

# 그런 다음 재구성
openclaw onboard

오류: "Gateway not responding"

bash 
# 게이트웨이가 실행 중인지 확인
openclaw status

# 중지된 경우 이유 확인
openclaw logs --tail 100

# 재시작 시도
openclaw gateway restart

# 여전히 실패하면 시스템 리소스 확인
free -h  # 메모리
df -h    # 디스크 공간

채널별 오류

WhatsApp: "Session expired"

Error: WhatsApp session invalid or expired

해결:

bash 
# 재인증
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# 새 QR 코드 스캔

WhatsApp: "QR code not generating"

bash 
# 다른 세션이 활성 상태인지 확인
pkill -f "openclaw.*whatsapp"

# 이전 세션 데이터 삭제
rm -rf ~/.openclaw/whatsapp-session

# 다시 시도
openclaw channel connect whatsapp

Telegram: "Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

다른 인스턴스가 동일한 봇 토큰을 사용하고 있습니다.

해결:

bash 
# 모든 OpenClaw 인스턴스 중지
pkill -f openclaw

# 다른 실행 중인 인스턴스 확인
ps aux | grep openclaw

# 새로 시작
openclaw gateway start

Discord: "Invalid token"

Error: An invalid token was provided

해결:

bash 
# Discord Developer Portal에서 토큰 재생성
# Bot → Reset Token

# OpenClaw 업데이트
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord: "Missing intents"

Error: Disallowed intents specified

해결:

  1. Discord Developer Portal로 이동
  2. 애플리케이션 선택 → Bot
  3. "Privileged Gateway Intents"에서 필요한 인텐트 활성화
  4. 저장 및 OpenClaw 재시작

메모리 및 성능 오류

오류: "JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

해결:

bash 
# Node.js 메모리 제한 증가
export NODE_OPTIONS="--max-old-space-size=4096"

# 지속성을 위해 셸 프로필에 추가
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# OpenClaw 재시작
openclaw gateway restart

오류: "Too many open files"

Error: EMFILE: too many open files

해결:

bash 
# 현재 제한 확인
ulimit -n

# 제한 증가 (임시)
ulimit -n 65535

# 제한 증가 (영구 - Linux)
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

느린 응답 시간

진단:

bash 
# 모델 지연 시간 확인
openclaw benchmark

# 시스템 리소스 확인
openclaw stats

해결:

json 
// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

구성 오류

오류: "Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

해결:

bash 
# YAML 검증
openclaw config validate

# 일반적인 문제:
# - 공백 대신 탭 (2개의 공백 사용)
# - 키 뒤에 콜론 누락
# - 따옴표 없는 특수 문자

# 수정 또는 재설정
openclaw config edit
# 또는
openclaw config reset --confirm

오류: "Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

해결:

bash 
# 사용 가능한 옵션 확인
openclaw config list

# 알 수 없는 키 제거
openclaw config edit

오류: "Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

해결:

bash 
# .env 파일에 추가
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# 또는 셸에서 export
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 지속성을 위해 셸 프로필에 추가
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

데이터베이스 및 스토리지 오류

오류: "Database locked"

Error: SQLITE_BUSY: database is locked

해결:

bash 
# OpenClaw 중지
openclaw gateway stop

# 잠금 파일 확인
ls -la ~/.openclaw/*.lock

# 오래된 잠금 제거
rm ~/.openclaw/*.lock

# 재시작
openclaw gateway start

오류: "Disk quota exceeded"

Error: ENOSPC: no space left on device

해결:

bash 
# 디스크 사용량 확인
df -h

# OpenClaw 로그 및 캐시 정리
openclaw cache clear
openclaw logs clear --older-than 7d

# 이전 세션 정리
rm -rf ~/.openclaw/sessions/*.old

추가 도움 받기

디버그 로깅 활성화

bash 
# 디버그 모드 설정
export OPENCLAW_DEBUG=true
openclaw gateway start

# 또는 구성에서
openclaw config set logLevel debug

진단 보고서 생성

bash 
openclaw doctor --report > diagnostic-report.txt

커뮤니티 지원

버그 리포트 제출

문제 보고 시 포함할 내용:

bash 
# 시스템 정보
openclaw --version
node --version
uname -a

# 구성 (민감한 데이터 삭제)
openclaw config show --redact

# 최근 로그
openclaw logs --tail 100

다음 단계