홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
문제 해결

OpenClaw 자주 발생하는 오류와 해결 방법

· 9 분 소요

OpenClaw을 설치하고 사용하는 과정에서 다양한 문제에 부딪힐 수 있습니다. 이 글에서는 커뮤니티에서 가장 자주 보고되는 오류 사례와 해결 방법을 정리하여, 빠르게 문제를 찾고 수정할 수 있도록 돕겠습니다. 문제를 진단하기 전에 OpenClaw에 내장된 진단 도구를 먼저 실행하는 것을 강력히 권장합니다. 더 많은 도움은 OpenClaw을 방문하세요.

첫 번째 방법: openclaw doctor 활용하기

OpenClaw에는 강력한 자체 진단 명령이 있으며, 실행 환경, 설정 파일, 네트워크 연결 등 각종 상태를 자동으로 점검합니다:

openclaw doctor

이 명령은 다음 항목을 포함한 상세한 진단 보고서를 출력합니다:

  • Node.js 버전이 요구사항을 충족하는지
  • 설정 파일이 존재하고 형식이 올바른지
  • 게이트웨이 서비스가 실행 중인지
  • 각 AI 공급자의 연결 상태
  • 설정된 채널의 연결 상태

대부분의 문제는 openclaw doctor의 출력을 통해 원인을 빠르게 파악할 수 있습니다. 문제가 발생할 때마다 먼저 한 번 실행하는 것을 권장합니다.

Node.js 버전이 요구사항을 충족하지 않음

오류 증상:

Error: OpenClaw requires Node.js >= 22.0.0, current version: 18.x.x

또는 설치 시 구문 오류, 모듈을 찾을 수 없는 등의 이상 현상.

해결 방법:

OpenClaw은 Node.js 22 이상을 요구합니다. 현재 버전을 확인합니다:

node --version

22 미만이면 업그레이드가 필요합니다:

# NodeSource 저장소 사용 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 또는 nvm 사용
nvm install 22
nvm use 22
nvm alias default 22

업그레이드 후 OpenClaw을 다시 설치합니다:

npm install -g openclaw@latest

게이트웨이 토큰 누락 또는 유효하지 않음

오류 증상:

Error: Gateway token is missing or invalid

또는 Dashboard에서 "Unauthorized" 표시.

해결 방법:

게이트웨이 토큰은 openclaw onboard를 처음 실행할 때 자동으로 생성되어 설정 파일에 저장됩니다. 설정 파일을 확인합니다:

cat ~/.config/openclaw/openclaw.json5

gateway 섹션에 유효한 token 필드가 있는지 확인합니다. 토큰이 분실되거나 손상된 경우 재생성할 수 있습니다:

openclaw gateway reset-token

그런 다음 게이트웨이를 재시작합니다:

openclaw gateway restart

systemd로 서비스를 관리하는 경우:

sudo systemctl restart openclaw

포트 18789 사용 중

오류 증상:

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

해결 방법:

먼저 어떤 프로세스가 해당 포트를 사용하고 있는지 확인합니다:

# Linux
sudo lsof -i :18789
# 또는
sudo ss -tlnp | grep 18789

가능한 상황:

  1. 이미 OpenClaw 인스턴스가 실행 중: 기존 인스턴스를 먼저 중지합니다
openclaw gateway stop
# 또는 강제 종료
kill $(lsof -t -i:18789)
  1. 다른 프로그램이 포트를 사용 중: OpenClaw의 포트 설정을 변경합니다
nano ~/.config/openclaw/openclaw.json5

{
  gateway: {
    port: 18790,  // 다른 포트로 변경
  }
}

포트를 변경한 후, Nginx 리버스 프록시를 설정해 둔 경우에는 Nginx 설정의 upstream 주소도 함께 업데이트해야 합니다.

API 키 오류

오류 증상:

Error: 401 Unauthorized - Invalid API key

또는 AI 모델이 메시지에 응답하지 않음.

해결 방법:

API 키 설정을 하나씩 점검합니다:

nano ~/.config/openclaw/openclaw.json5

Anthropic Claude:

  • 키 형식이 sk-ant-api03-...이어야 합니다
  • console.anthropic.com에서 키가 만료되지 않았고 잔액이 있는지 확인합니다

OpenAI:

  • 키 형식이 sk-proj-... 또는 sk-...이어야 합니다
  • 계정에 사용 가능한 잔액이 있는지 확인합니다

Ollama (로컬 모델):

  • apiKey에 "ollama" 같은 아무 비어있지 않은 문자열을 입력하면 됩니다
  • Ollama 서비스가 실행 중인지 확인합니다: curl http://localhost:11434/api/tags

흔한 실수로는 키를 복사할 때 앞뒤로 공백이 포함되거나, 설정 파일에서 따옴표가 누락되는 경우가 있습니다.

채널 연결 실패

Telegram 연결 실패:

Error: Telegram Bot API: 401 Unauthorized

해결 방법:

  • Bot Token이 올바르고 폐지되지 않았는지 확인합니다
  • BotFather에서 봇 상태를 확인합니다: /mybots 전송
  • Token이 유출된 경우 /revoke로 재발급합니다

Discord 연결 실패:

Error: Discord Gateway: Authentication failed

해결 방법:

  • Bot Token이 올바른지 확인합니다
  • Discord Developer Portal에서 Bot의 Message Content Intent가 활성화되어 있는지 확인합니다
  • Bot이 대상 서버에 초대되었는지 확인합니다

WhatsApp 연결 실패:

WhatsApp은 QR 코드 인증을 사용합니다. 연결이 끊어진 경우:

openclaw channel reconnect whatsapp

안내에 따라 다시 QR 코드를 스캔합니다.

설정 파일 형식 오류

오류 증상:

Error: Failed to parse config file
SyntaxError: Unexpected token ...

해결 방법:

OpenClaw은 JSON5 형식의 설정 파일을 사용합니다. 표준 JSON보다 느슨하지만 (주석과 트레일링 쉼표 지원), 여전히 문법 규칙이 있습니다. 흔한 오류:

  • 쉼표 누락
  • 문자열 값에 따옴표 미사용
  • 중괄호 불일치

다음 방법으로 설정을 검증할 수 있습니다:

openclaw doctor

진단 도구가 설정 파일의 구체적인 오류 위치를 알려줍니다. 설정이 심하게 손상된 경우, 백업 후 다시 초기화할 수 있습니다:

cp ~/.config/openclaw/openclaw.json5 ~/.config/openclaw/openclaw.json5.bak
openclaw onboard

메모리 부족으로 인한 크래시

오류 증상: 게이트웨이가 자주 재시작되며, 로그에 JavaScript heap out of memory가 나타남.

해결 방법:

Node.js의 메모리 제한을 늘립니다:

export NODE_OPTIONS="--max-old-space-size=4096"

systemd로 서비스를 관리하는 경우, service 파일에 환경 변수를 추가합니다:

Environment=NODE_OPTIONS=--max-old-space-size=4096

그런 다음 다시 로드하고 재시작합니다:

sudo systemctl daemon-reload
sudo systemctl restart openclaw

문제가 지속되면 서버 메모리 사양 업그레이드를 고려하세요.

추가 도움 받기

위의 해결 방법으로도 문제가 해결되지 않으면, 다음 경로로 도움을 받을 수 있습니다:

  1. 공식 문서 참고: OpenClaw 공식 문서에는 가장 포괄적인 설정 참고 자료가 있습니다
  2. GitHub Issue 검색: OpenClaw GitHub 저장소에서 발생한 오류 메시지를 검색하면, 이미 같은 문제를 경험한 사람이 있을 가능성이 높습니다
  3. 새 Issue 등록: 버그가 확인되면, Issue를 등록할 때 openclaw doctor의 전체 출력과 관련 로그를 첨부하세요
  4. 로그 확인: 상세한 로그가 깊은 문제를 파악하는 데 도움이 됩니다
# 게이트웨이 실시간 로그 확인
sudo journalctl -u openclaw -f

# 최근 100줄 로그 확인
sudo journalctl -u openclaw -n 100

OpenClaw을 최신 버전으로 유지하는 것도 중요합니다. 많은 버그가 새 버전에서 이미 수정되어 있습니다:

npm update -g openclaw@latest
OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

Gateway 심층 장애 해결 가이드
Doctor 진단 도구 완전 가이드
OpenClaw WhatsApp 빈번한 연결 끊김 문제 해결