OpenClaw 시작이 안 될 때 완전 해결 2026: 초보자가 자주 만나는 설치·연결 에러 5가지와 해결법
이 글에서 다루는 내용: OpenClaw를 처음 설치하는 초보자가 가장 자주 겪는 5가지 오류 상황과 단계별 해결 방법을 정리했습니다. X.com 커뮤니티에서 수집한 실제 오류 사례를 바탕으로 작성했습니다. "새벽 2시인데 아직도 CLI와 씨름 중"이신가요? 이 글이 도움이 될 것입니다.
오류 전 먼저 시도할 빠른 진단
OpenClaw가 시작되지 않을 때, 복잡한 디버깅 전에 간단한 진단 명령어로 문제를 빠르게 파악할 수 있습니다:
# 빠른 진단 명령어 (이 순서대로 실행)
node --version # Node.js 버전 확인 (18+ 필요)
npm --version # npm 버전 확인
openclaw --version # OpenClaw 설치 확인
openclaw status # 실행 상태 확인
openclaw logs --lines 20 # 최근 오류 로그 확인
📋 오류별 빠른 이동
오류 1 Node.js 버전 오류
# 오류 메시지
Error: Requires Node.js 18 or higher. Current: 14.17.0
SyntaxError: Cannot use import statement outside a module
npm WARN engine: [email protected]: wanted: {"node":">=18"}
원인: OpenClaw는 Node.js 18 이상을 요구합니다. 오래된 버전이 설치되어 있으면 ES Module 문법을 인식하지 못해 오류가 발생합니다.
✅ 해결 방법
# macOS (Homebrew)
brew install node@20
brew link node@20
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
# Windows: nodejs.org에서 20.x LTS 다운로드 및 설치
# 설치 후 확인
node --version # v20.x.x 출력 확인
💡 여러 Node.js 버전 관리 팁
다른 프로젝트와 충돌이 걱정된다면 nvm(Node Version Manager)을 사용하세요. nvm install 20 && nvm use 20 으로 OpenClaw용 버전을 별도 관리할 수 있습니다.
오류 2 포트 충돌 오류 (EADDRINUSE)
# 오류 메시지
Error: listen EADDRINUSE: address already in use :::3000
Error: Port 3000 is already in use. Please free the port or configure a different one.
UnhandledPromiseRejectionWarning: Error: EADDRINUSE :::3000
원인: OpenClaw가 사용하려는 포트(기본 3000번)가 다른 프로그램에 의해 이미 사용되고 있습니다. 또는 이전에 비정상 종료된 OpenClaw 프로세스가 포트를 점유하고 있는 경우입니다.
✅ 해결법 A: 포트 점유 프로세스 종료
# macOS/Linux: 포트 3000 사용 프로세스 확인
lsof -i :3000
kill -9 [PID]
# Windows PowerShell
netstat -ano | findstr :3000
taskkill /PID [PID] /F
✅ 해결법 B: 다른 포트 사용
# 설정 파일에서 포트 변경
nano ~/.openclaw/config.json
# "port": 3001 로 변경
# 또는 환경 변수
export OPENCLAW_PORT=3001
openclaw start
💡 예방 방법
OpenClaw를 종료할 때 항상 openclaw stop을 사용하세요. Ctrl+C로 강제 종료하면 포트가 해제되지 않아 다음 실행 시 이 오류가 발생합니다.
오류 3 권한 오류 (EACCES/Permission denied)
# 오류 메시지
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'
Error: EACCES: permission denied, open '/usr/local/lib/node_modules'
Error: Cannot write to /root/.openclaw/config.json: Permission denied
원인: npm 글로벌 패키지 설치 디렉토리에 쓰기 권한이 없거나, OpenClaw 설정 파일 경로에 접근이 제한되어 있습니다. macOS에서 Homebrew 없이 Node.js를 설치하거나, Linux에서 sudo로 npm을 사용했을 때 자주 발생합니다.
✅ 권장 해결법: npm 디렉토리 권한 수정
# npm 글로벌 디렉토리를 사용자 홈으로 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
# 이후 재설치
npm i -g openclaw
✅ macOS: Homebrew Node.js 사용
# 기존 Node.js 제거 후 Homebrew로 재설치
brew install node
# Homebrew Node.js는 권한 문제 없음
npm i -g openclaw
⚠️ sudo npm i -g openclaw는 사용하지 마세요
sudo를 사용하면 설치는 되지만 이후 실행 시 다른 권한 오류가 연쇄적으로 발생합니다. 반드시 위의 방법으로 권한을 올바르게 설정하세요.
오류 4 텔레그램 봇 연결 실패
# 오류 메시지
Error: Telegram bot connection failed: 401 Unauthorized
TelegramError: Error: 401: Unauthorized (Bot token invalid)
Error: Connection to Telegram API timed out after 10s
Error: bot is not started (invalid bot token or network issue)
원인: 텔레그램 봇 토큰이 잘못 입력되었거나, 봇이 비활성화되었거나, 네트워크가 텔레그램 서버에 연결되지 않는 경우입니다. 이 오류는 초보자에게 가장 흔한 오류 중 하나입니다.
봇 토큰 재확인
텔레그램에서 @BotFather를 열고 /mybots를 입력하면 내 봇 목록이 나옵니다. 봇을 선택하고 "API Token"을 클릭해 토큰을 다시 확인하세요.
⚠️ 토큰 형식: 숫자:영문+숫자+특수문자 (예: 1234567890:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
봇 토큰 재입력 방법
openclaw onboard
# → "텔레그램 봇 토큰 입력" 단계에서 새 토큰 입력
# 또는 설정 파일 직접 수정
nano ~/.openclaw/config.json
# "telegram_bot_token": "새_토큰" 으로 변경
네트워크 연결 문제 확인
텔레그램 API 서버(api.telegram.org)가 접근 가능한지 확인하세요:
curl -s https://api.telegram.org/bot<토큰>/getMe
# {"ok":true,"result":{...}} 가 나오면 토큰 정상
# 응답 없으면 → VPN07로 연결 후 재시도
봇 재생성 (최후 수단)
위 방법이 모두 실패하면 @BotFather에서 /newbot으로 새 봇을 생성하고 새 토큰을 사용하세요.
오류 5 API 연결 타임아웃 오류
# 오류 메시지
Error: Request timeout after 30000ms
Error: connect ETIMEDOUT 3.130.130.130:443
FetchError: network timeout at: https://api.anthropic.com/v1/messages
Error: getaddrinfo ENOTFOUND api.anthropic.com
원인: OpenClaw가 Claude(Anthropic), GPT(OpenAI) 등 해외 AI API 서버에 연결할 수 없습니다. 이 오류는 대부분 네트워크 연결 문제이며, 지역 제한이나 방화벽이 원인인 경우가 많습니다.
🚫 타임아웃 오류가 발생하는 주요 원인
일부 국가/지역에서 Anthropic·OpenAI API 서버에 대한 직접 접속이 차단됩니다.
회사 네트워크나 학교 Wi-Fi에서 외부 API 서버 접속이 차단되는 경우가 많습니다.
패킷 손실이 높은 네트워크에서 장시간 API 스트리밍 응답이 타임아웃됩니다.
api.anthropic.com DNS 해석 실패 (ENOTFOUND). ISP DNS 서버 문제입니다.
✅ 해결법 1: VPN으로 안정적인 해외 연결
가장 확실한 해결책입니다. VPN07 같은 고속 VPN을 연결하면 Anthropic·OpenAI API 서버에 안정적으로 접속할 수 있습니다.
# VPN 연결 후 API 접속 확인
curl -s --max-time 5 https://api.anthropic.com/v1/models \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01"
# 정상: {"models":[...]} 응답
✅ 해결법 2: DNS 서버 변경
# /etc/resolv.conf 수정 (Linux)
nameserver 8.8.8.8 # Google DNS
nameserver 1.1.1.1 # Cloudflare DNS
# 확인
nslookup api.anthropic.com
✅ 해결법 3: 타임아웃 값 늘리기
느린 네트워크를 사용 중이라면 타임아웃을 늘려서 일시적으로 해결할 수 있습니다:
/config set api_timeout 60000 # 60초로 늘리기
/config set retry_count 3 # 실패 시 3회 재시도
보너스: 오류는 없는데 작동이 이상할 때
📩 텔레그램에 메시지를 보내도 응답이 없어요
openclaw status로 데몬이 실행 중인지 확인- 텔레그램 봇에서 /start를 먼저 입력했는지 확인
- 봇 프라이버시 설정: @BotFather → /mybots → Group Privacy → Disable
openclaw logs로 오류 메시지 확인
🔄 응답이 너무 느려요 (30초 이상)
Claude Opus는 응답이 느릴 수 있습니다. 빠른 응답이 필요하다면 /model use claude-haiku-3.5나 /model use gpt-4o-mini로 경량 모델을 사용하세요. VPN07로 API 서버와 최적 경로로 연결하면 응답 속도를 크게 개선할 수 있습니다.
🌏 한국어로 답변하지 않아요
기본 언어가 영어로 설정되어 있을 수 있습니다. 온보딩 또는 설정에서 언어를 변경하세요:
/config set language ko
# 또는 AI에게 직접: "앞으로 한국어로만 답해줘"
💾 컴퓨터를 껐다 켜면 OpenClaw가 꺼져요
부팅 시 자동 시작을 설정하세요:
# macOS: launchd 서비스 등록
openclaw service install
openclaw service start
# Linux: systemd 서비스
openclaw service install --system
sudo systemctl enable openclaw
아무것도 안 될 때: 완전 초기화 방법
위의 모든 방법을 시도했는데도 해결이 안 된다면 OpenClaw를 완전히 초기화하고 처음부터 다시 설치하는 것이 가장 빠릅니다. 주의: 모든 기억(memory)과 설정이 삭제됩니다.
⚠️ 완전 초기화 명령어 (되돌릴 수 없음)
# 1. 실행 중인 프로세스 종료
openclaw stop
# 2. 설정 파일 삭제
rm -rf ~/.openclaw
# 3. 패키지 재설치
npm uninstall -g openclaw
npm i -g openclaw
# 4. 처음부터 다시 설정
openclaw onboard
Windows 전용 추가 문제 해결
Windows 환경에서는 macOS·Linux와 다른 추가적인 문제가 발생할 수 있습니다. 아래는 Windows 사용자에게 특히 자주 발생하는 오류들입니다:
⊞ PowerShell 실행 정책 오류
PSSecurityException: .ps1 is not digitally signed
PowerShell 기본 실행 정책이 스크립트 실행을 막습니다.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
⊞ 경로에 한국어·공백 포함 오류
Error: Cannot find path 'C:\Users\사용자\Documents\openclaw'
Windows에서 한국어가 포함된 경로나 공백이 있는 경로에 설치하면 오류가 납니다. C:\openclaw 처럼 영문 경로에 설치하세요:
mkdir C:\openclaw
cd C:\openclaw
npm i -g openclaw
⊞ Windows Defender 차단
Windows Defender가 OpenClaw 실행 파일을 차단하는 경우가 있습니다. 이때는 Windows 보안 → 바이러스 및 위협 방지 → 제외 추가에서 OpenClaw 경로를 예외로 추가하세요. OpenClaw는 오픈소스이므로 소스 코드를 직접 확인할 수 있습니다.
macOS 전용 추가 문제 해결
Gatekeeper 차단 오류
Error: "openclaw" cannot be opened because it is from an unidentified developer
macOS Gatekeeper가 OpenClaw 실행을 막을 수 있습니다.
# 시스템 설정 → 개인 정보 보호 및 보안 → '무관계' 클릭
# 또는 터미널에서:
xattr -dr com.apple.quarantine $(which openclaw)
iMessage 통합 오류
iMessage 통합은 macOS 전용 기능입니다. 시스템 환경설정 → 개인 정보 보호 → 자동화에서 OpenClaw가 Messages에 접근할 수 있도록 권한을 부여해야 합니다. 권한이 없으면 iMessage를 통한 명령이 작동하지 않습니다.
Homebrew 충돌
Homebrew로 설치한 Node.js와 다른 방법으로 설치한 Node.js가 충돌할 수 있습니다. which node로 현재 사용 중인 Node.js 경로를 확인하고, Homebrew 버전만 사용하도록 PATH를 정리하세요.
which node # 현재 Node.js 경로
brew doctor # Homebrew 문제 진단
brew link --overwrite node # Homebrew Node.js 우선
설치 성공 최종 확인 방법
모든 설치가 완료되었다면 다음 명령어로 최종 확인을 해보세요. 모든 항목이 정상이면 OpenClaw를 본격적으로 사용할 준비가 된 것입니다:
# 최종 확인 스크립트
node --version # v20.x.x 이상
openclaw --version # 최신 버전 확인
openclaw status # 🟢 Running 상태
# 텔레그램 봇에서 확인
/start # AI 비서 환영 메시지
/help # 명령어 목록
/status # 모든 연결 정상 확인
설치 전 체크리스트 (다시는 이 오류를 만나지 않으려면)
설치 막혔을 때 도움받을 수 있는 곳
공식 문서
docs.openclaw.ai에서 공식 설치 가이드와 FAQ를 확인하세요. 영어로 작성되어 있지만 Chrome 번역 기능으로 한국어로 볼 수 있습니다.
GitHub Issues
github.com/openclaw/openclaw/issues에서 다른 사용자들의 오류 보고와 해결책을 검색할 수 있습니다. 새 이슈를 등록하면 커뮤니티가 도움을 줍니다.
X.com 커뮤니티
@openclaw를 태그하거나 #OpenClaw 해시태그로 질문하면 전 세계 사용자와 개발자들이 빠르게 답변해줍니다. 가장 활발한 채널입니다.
💡 전문가 팁: 설치 전 이것만 준비하면 오류 제로
설치 스크립트가 해외 서버에서 패키지를 다운로드합니다. 연결이 불안정하면 중간에 끊겨 절반만 설치된 상태가 됩니다. VPN07 연결 후 설치하면 한 번에 완료됩니다.
온보딩 중 API 키 입력 단계에서 막히는 경우가 많습니다. console.anthropic.com에서 키를 미리 발급받아 클립보드에 복사해두세요.
커뮤니티 도움: 같은 오류로 막힌 사용자가 많습니다.
X.com에서 #OpenClaw 또는
GitHub Issues에서 검색하면 대부분의 오류에 대한 해결책을 빠르게 찾을 수 있습니다.
OpenClaw Discord 채널에서도 실시간 도움을 받을 수 있습니다.
VPN07 - OpenClaw 오류의 99%는 연결 문제
1000Mbps 기가급으로 해외 API 완벽 연결, 타임아웃 오류 완전 해소
OpenClaw 오류의 상당수는 불안정한 해외 API 연결에서 비롯됩니다. VPN07의 10년 이상 안정 운영 IEPL 전용선으로 Anthropic·OpenAI·텔레그램 서버에 완벽하게 연결하면 타임아웃·연결 끊김 오류가 사라집니다.