OpenClaw 설치가 안 되나요? 직접 겪은 7가지 문제와 해결법

2026-06-08 업데이트: 예제 설정의 모델명을 현재 사용 가능한 버전으로 변경했습니다(Anthropic은 claude-sonnet-4-6, OpenAI는 gpt-5). Node 버전 요구 사항(v22.14 이상, v24 권장), 리소스 설정, 진단 명령도 2026년 6월 기준으로 다시 확인했습니다. 구체적인 최신 요구 사항은 docs.openclaw.ai/install을 기준으로 확인하세요.

터미널에 벌써 몇 번째인지 모를 빨간 오류 메시지가 또 나타납니다. OpenClaw라는 새 도구를 한번 써보려 했을 뿐인데 저녁부터 지금까지 npm 권한 오류, 계속 재시작되는 Docker 컨테이너, 아무리 해도 적용되지 않는 API key와 씨름하게 됩니다. 하나를 해결하면 세 가지 문제가 새로 생깁니다. GitHub Issues에도 같은 질문이 가득한 것을 보면 이 도구의 설치 진입 장벽은 생각보다 훨씬 높습니다.

공식 문서를 한 단계씩 그대로 따라 했는데도 실행되지 않습니다. 명령줄에 쏟아지는 오류를 보면 어디서부터 손대야 할지 막막합니다.

다행히 주말 내내 시행착오를 겪은 끝에 웬만한 함정은 모두 확인했습니다. 아래 문제 해결 가이드는 OpenClaw 설치에서 가장 자주 발생하는 7가지 문제를 다룹니다. 문제마다 명확한 진단 단계와 해결 방법을 담았고, 어떻게 고치는지만이 아니라 왜 오류가 발생하는지도 설명합니다. 다음에 비슷한 문제가 생겨도 점검할 방향을 잡을 수 있습니다.

적은 비용으로 ‘새우 키우기’: ArkClaw로 AI Agent를 더 쉽게 사용하기

최근 인기를 얻은 OpenClaw(바닷가재)는 유용하지만 설정 과정이 지나치게 복잡합니다. ByteDance Volcano Engine의 ArkClaw는 이 진입 장벽을 크게 낮춥니다. 서버와 Token 설정을 직접 만질 필요 없이 클릭 한 번으로 24시간 온라인 상태에서 브라우저를 제어하고, 스크립트를 실행하며, 캘린더를 관리하는 AI 작업 도우미를 사용할 수 있습니다.

특히 가격이 저렴합니다. 월 이용료는 9.9위안이며, 제 초대 코드 ZLKUK54M(여기에서 가입)을 사용하면 8.9위안입니다. 프로그래머라면 Coding Plan Pro를 선택해 무료로 이용할 수도 있습니다.

Node.js 버전 문제(가장 흔함)

OpenClaw를 설치할 때 가장 먼저 확인해야 할 것은 Node.js 버전입니다. 처음에는 시스템에 기본으로 설치된 Node 16을 사용했다가 원인을 알기 어려운 문법 오류가 잇따라 발생했습니다.

먼저 버전을 확인합니다.

node -v

버전이 눈에 띄게 오래됐다면 우선 이 부분을 의심하세요. docs.openclaw.ai/install을 기준으로 최소 Node.js v22.14 이상이 필요하며 Node.js v24를 권장합니다. 버전이 너무 낮으면 문법이나 런타임 API가 호환되지 않을 수 있습니다.

대표적인 버전 비호환 오류는 다음과 같습니다.

SyntaxError: Unexpected token '?'
TypeError: fetch is not a function

첫 번째 오류는 오래된 런타임이 optional chaining 같은 문법을 지원하지 않을 때 자주 나타납니다. 두 번째 오류는 공식 최소 Node 버전(v22.14 이상)에 미달하거나, 현재 환경과 shell에서 실제로 사용하는 node가 달라 내장 fetch 같은 API가 일치하지 않을 때 발생할 수 있습니다. 이런 오류가 보인다면 버전이나 PATH/nvm 전환부터 확인하는 것이 좋습니다.

해결 방법은 nvm으로 버전을 관리하는 것입니다.

개인적으로는 nvm(Node Version Manager)으로 Node.js 버전을 관리하는 방법을 적극 권장합니다. 다른 프로젝트에 영향을 주지 않고 여러 버전을 자유롭게 바꿀 수 있습니다.

🪟 Windows 사용자:

nvm-windows에서 설치 프로그램을 다운로드합니다. 설치하기 전에 시스템에 있던 Node.js를 완전히 제거해야 PATH 충돌을 피할 수 있습니다.

🐧 Linux/macOS 사용자:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

nvm을 설치한 다음 공식 권장 버전이자 최소 v22.14 요구 사항을 충족하는 Node.js 24를 설치합니다.

nvm install 24
nvm use 24
nvm alias default 24

마지막 명령은 24를 기본 버전으로 지정하므로 새 터미널에서도 자동으로 이 버전을 사용합니다.

npm 권한 오류(WSL2/Linux에서 자주 발생)

npm 권한 오류는 특히 까다로웠습니다. WSL2 환경에서 npm install을 실행할 때마다 EACCES 오류가 나타나면 작업 흐름이 계속 끊깁니다.

먼저 오류 형태를 살펴봅니다.

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/openclaw'
EACCES: permission denied, open 'package.json'

첫 번째 오류는 전역 설치 과정에서 발생하고, 두 번째 오류는 보통 WSL2의 /mnt/c 디렉터리에서 나타납니다.

❌ 다음 방법부터 시도하지 마세요.

• sudo npm install을 사용하지 마세요. 파일 소유권이 뒤엉켜 나중에 더 복잡해집니다.
• chmod 777을 사용하지 마세요. 심각한 보안 위험을 만듭니다.
• npm config set unsafe-perm true를 사용하지 마세요. 근본 원인을 해결하지 못합니다.

✅ 상황에 따라 다음 세 가지 해결 방법 중 하나를 선택합니다.

방법 A: npm 전역 디렉터리 변경(권장, 모든 Linux 사용자에게 적합)

핵심은 npm의 전역 설치 디렉터리를 자신의 home 디렉터리 아래로 옮기는 것입니다. 그러면 권한 문제가 발생하지 않습니다.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

터미널을 다시 열고 npm 설치를 시도하면 권한 오류가 사라질 것입니다.

방법 B: WSL2 파일 시스템 권한 수정(WSL2 전용)

Alibaba Cloud - 개발자 클라우드 1순위, Lighthouse 서버 15% 할인

15% 할인 받기 →광고

🔧 WSL2에는 주의할 점이 있습니다. 마운트된 Windows 파일 시스템(/mnt/c)의 권한 모델이 Linux와 달라 npm이 자주 실패합니다.

해결하려면 /etc/wsl.conf를 설정합니다.

sudo nano /etc/wsl.conf

다음 내용을 추가합니다.

[automount]
options = "metadata,umask=22,fmask=11"

저장한 뒤 Windows PowerShell에서 다음 명령을 실행합니다.

wsl.exe --shutdown

WSL2를 다시 열면 대부분의 권한 문제가 해결됩니다.

방법 C: WSL home 디렉터리에서 작업(가장 간단함)

가장 간단한 방법은 /mnt/c 아래에서 개발하지 않는 것입니다. ~/projects 같은 WSL 네이티브 디렉터리를 사용하면 npm 설치 속도가 훨씬 빠르고 이상한 권한 문제도 생기지 않습니다.

mkdir ~/projects
cd ~/projects
# 여기에서 OpenClaw 설치

Docker 관련 문제

Docker는 다소 복잡합니다. 컨테이너 시작이 실패하는 원인이 다양하므로 한 단계씩 확인해야 합니다.

문제를 진단하는 방법부터 확인합니다.

# 1단계: 컨테이너 상태 확인
docker compose ps

# 2단계: 로그 확인
docker compose logs openclaw-gateway

# 3단계: 오류 정보 필터링
docker compose logs openclaw-gateway | grep -i "error"

이 세 단계로 문제의 위치를 빠르게 파악할 수 있습니다.

문제 A: 상태 확인 실패로 컨테이너가 반복해서 재시작됨

이 문제는 여러 번 겪었습니다. 컨테이너가 시작된 지 몇 초 만에 자동으로 멈춘 뒤 다시 시작하는 동작이 반복됩니다.

로그에는 다음과 비슷한 내용이 표시됩니다.

Health check failed: container unhealthy
Container openclaw-gateway exited with code 137

대부분 리소스 부족이 원인입니다. OpenClaw의 공식 권장 사항은 최소 2 vCPU / 4 GB RAM, 권장 4 vCPU / 8 GB RAM입니다.

Docker 리소스를 조정하는 방법

🪟 Windows/Mac 사용자: Docker Desktop → Settings → Resources를 열고 CPU와 메모리를 늘립니다.

🐧 Linux 사용자: 일반적으로 별도 설정이 필요하지 않으며 Docker가 호스트의 전체 리소스를 사용합니다.

컴퓨터 사양이 부족하다면 상태 확인을 잠시 비활성화할 수 있습니다. 권장하는 방법은 아니지만 긴급한 경우 사용할 수 있습니다.

# docker-compose.yml 편집
healthcheck:
  disable: true

문제 B: Docker 권한 오류(Linux 전용)

Linux에서는 다음 오류가 발생할 수 있습니다.

permission denied while trying to connect to the Docker daemon socket

사용자가 docker 그룹에 속하지 않아서 생기는 오류입니다. 다음과 같이 해결합니다.

sudo usermod -aG docker $USER
newgrp docker

⚠️ 보안 알림: 사용자를 docker 그룹에 추가하면 사실상 root 수준의 권한을 부여하게 됩니다. 운영 환경이나 여러 사람이 공유하는 서버에서는 rootless Docker를 권장합니다.

문제 C: 포트 18789가 이미 사용 중임

이전에 실행한 OpenClaw 프로세스가 제대로 종료되지 않아 포트를 계속 점유하고 있을 수 있습니다.

🐧 Linux/Mac 진단 방법:

lsof -i :18789

🪟 Windows 진단 방법:

netstat -ano | findstr 18789

포트를 점유한 프로세스 ID를 찾은 뒤 정상적으로 종료합니다.

openclaw gateway stop

필요하다면 강제로 종료할 수 있습니다. PID는 조회한 값으로 바꾸세요.

kill -9 <PID>

문제 D: ARM64 아키텍처 문제(Apple Silicon 사용자 주의)

M1/M2 칩을 사용하는 Mac에서는 Chromium 경로 불일치 문제가 발생할 수 있습니다. 자주 발생하지는 않지만 해결하기 까다롭습니다.

ARM64용 Chromium 경로를 지정하도록 Dockerfile을 직접 구성해야 합니다. 구체적인 설정은 OpenClaw의 GitHub Issues에서 정리된 내용을 찾을 수 있습니다.

API 키 설정 문제

API 키 설정도 골치 아픈 부분이었습니다. 설정 파일에 key를 입력했는데도 OpenClaw가 찾지 못하는 경우가 있습니다.

자주 발생하는 오류는 다음과 같습니다.

No API key found for anthropic
Invalid API key format
API key validation failed

이런 오류가 나타나면 당황하지 말고 아래 체크리스트를 순서대로 확인합니다.

확인 1: 환경 변수가 올바르게 설정됐나요?

먼저 환경 변수가 실제로 적용되었는지 확인합니다.

echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

출력이 비어 있다면 환경 변수가 제대로 설정되지 않은 것입니다.

Railway - 현대적인 배포 플랫폼, 번거로운 운영 없이 몇 분 만에 라이브

지금 시작 →광고

올바른 설정 방법은 다음과 같습니다.

# 임시 설정(현재 터미널에서만 유효)
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 영구 설정(설정 파일에 기록)
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.bashrc
source ~/.bashrc

🔧 WSL2 사용자 주의: WSL2에서 설정한 환경 변수는 Windows와 공유되지 않습니다. Windows 환경 변수에만 설정하면 WSL2에서는 찾을 수 없습니다.

확인 2: 설정 파일 형식이 올바른가요?

설정 파일 방식(~/.openclaw/openclaw.json)을 사용한다면 형식이 JSON 규격을 엄격히 따라야 합니다. 현재 기본 설정과 상태 디렉터리는 ~/.openclaw/입니다. 이전 버전의 ~/.clawdbot/을 아직 사용한다면 먼저 시리즈의 ‘OpenClaw 이름 변경 이야기’를 읽고 마이그레이션하세요.

자주 본 오류는 다음과 같습니다.

• 불필요한 공백이나 따옴표가 들어감
• 쉼표를 빠뜨림
• 마지막 항목 뒤에 쉼표를 붙임

다음 명령으로 JSON 형식이 유효한지 확인합니다.

cat ~/.openclaw/openclaw.json | jq .

jq에서 오류가 발생하면 JSON 형식에 문제가 있는 것입니다. jq가 없다면 먼저 설치합니다.

# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq

확인 3: API key 자체에 문제가 있나요?

설정 문제가 아니라 key가 만료되었거나 폐기된 경우도 있습니다.

• Anthropic Claude: https://console.anthropic.com/settings/keys 에서 확인
• OpenAI GPT: https://platform.openai.com/api-keys 에서 확인

key 상태가 Active인지, 사용량 제한에 걸리지 않았는지 확인합니다.

팁: API 제공자별 설정 차이

기본으로 사용할 모델을 바꾸려면 설정 파일에서 다음과 같이 지정합니다.

{
  "defaultProvider": "anthropic",
  "anthropic": {
    "apiKey": "sk-ant-xxxxx",
    "model": "claude-sonnet-4-6"
  },
  "openai": {
    "apiKey": "sk-xxxxx",
    "model": "gpt-5"
  }
}

WSL2 환경 전용 설정

Windows에서 WSL2를 사용한다면 많은 Linux 안내가 WSL2에서는 그대로 적용되지 않는다는 점을 알게 됩니다. WSL2와 네이티브 Linux 사이에는 분명한 차이가 있습니다.

핵심 차이는 세 가지입니다.

1. 파일 시스템 권한 모델이 다름 - 앞의 npm 권한 부분에서 설명했습니다.
2. 네트워크 스택이 독립적임 - localhost가 서로 연결되지 않을 때가 있습니다.
3. Docker Desktop 연동 문제 - Windows와 WSL2에서 Docker를 함께 사용할 때 문제가 발생할 수 있습니다.

WSL2 전용 설정: 전체 /etc/wsl.conf

다음과 같이 설정 파일 전체를 구성하면 여러 문제를 피할 수 있습니다.

sudo nano /etc/wsl.conf

아래 내용을 입력합니다.

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
enabled = true
appendWindowsPath = true

[network]
generateResolvConf = true

설정을 마치면 WSL2를 다시 시작합니다.

# Windows PowerShell에서 실행
wsl.exe --shutdown

Docker Desktop for Windows 연동 설정

Docker Desktop을 사용한다면 설정에서 WSL2 연동을 켭니다.

1. Docker Desktop을 엽니다.
2. Settings → Resources → WSL Integration으로 이동합니다.
3. 사용 중인 WSL2 배포판(예: Ubuntu)을 선택합니다.
4. Apply & Restart를 누릅니다.

성능 최적화: 파일 시스템을 넘나드는 작업 피하기

이 문제에서 가장 오래 헤맸습니다. 처음에는 코드를 Windows D 드라이브(WSL2에서는 /mnt/d)에 두었는데 npm install 속도가 지나치게 느렸습니다.

WSL2에서 Windows 파일에 접근하는 것처럼 파일 시스템을 넘나들면 성능이 50~90% 저하될 수 있습니다. 과장이 아니라 실제로 체감되는 차이입니다.

올바른 방법은 다음과 같습니다.

# WSL2의 home 디렉터리에서 작업
cd ~
mkdir projects
cd projects
git clone https://github.com/openclaw/openclaw.git

모든 작업을 WSL2 네이티브 파일 시스템(/home/username)에서 수행하면 훨씬 빠릅니다.

리소스 제한 설정(선택 사항)

컴퓨터의 메모리가 부족하다면 Windows 사용자 디렉터리에 .wslconfig를 만들어 WSL2의 리소스 사용량을 제한할 수 있습니다.

# C:\Users\사용자명\.wslconfig
[wsl2]
memory=4GB
processors=2
swap=2GB

다만 OpenClaw 자체가 많은 리소스를 사용하므로 지나치게 제한하면 실행되지 않을 수 있습니다.

스킬 설치 시간 초과와 의존성 문제

스킬 설치도 몇 차례 시간 초과를 겪었습니다. 특히 일부 스킬을 처음 설치할 때 오랫동안 반응이 없으면 멈춘 것처럼 보입니다.

먼저 문제의 원인을 진단합니다.

openclaw skill check <skill-name>

이 명령은 스킬 상태와 자세한 오류 정보를 보여 줍니다.

Gateway 로그에서도 더 많은 단서를 찾을 수 있습니다.

docker compose logs openclaw-gateway | grep -i "skill"

자주 발생하는 의존성 문제는 다음과 같습니다.

문제 A: 바이너리 의존성이 설치되지 않음

Vultr - 고성능 NVMe 클라우드 서버, 전 세계 32개 노드, Docker 원클릭 배포

요금 보기 →광고

일부 스킬에는 Go 환경 같은 특정 시스템 의존성이 필요합니다. 설치되지 않았다면 스킬을 불러올 수 없습니다.

로그에서 특정 의존성이 없다고 나오면 안내에 따라 설치합니다.

# 예: Go가 없을 때
sudo apt install golang-go

# Python 관련 의존성
sudo apt install python3-dev

문제 B: 네트워크 시간 초과

가장 흔한 문제입니다. 스킬을 처음 설치할 때 OpenClaw가 많은 의존성을 다운로드하므로 네트워크가 불안정하면 쉽게 시간 초과가 발생합니다.

설치 진행률이 움직이지 않고 로그에 timeout 또는 connection refused가 나타나는 것이 대표적인 증상입니다.

해결 방법은 간단합니다. 다시 시도하세요.

openclaw skill install <skill-name>

중국에서 사용한다면 npm 미러를 설정해 속도를 높일 수 있습니다.

npm config set registry https://registry.npmmirror.com

Docker 미러도 중국 내 소스로 바꿀 수 있지만 관련 안내가 많으므로 여기서는 자세히 다루지 않습니다.

문제 C: 운영체제 설정이 맞지 않음

일부 스킬은 특정 시스템에 최적화되어 있습니다. 예를 들어 Ubuntu 22.04에서만 테스트한 스킬을 다른 배포판에서 사용하면 문제가 생길 수 있습니다.

이 경우 OpenClaw의 GitHub Issues에서 비슷한 사례를 찾아보세요. 보통 workaround가 제시되어 있습니다.

팁:

Go 의존성이 있는 스킬은 처음 설치할 때 5~10분이 걸릴 수 있습니다. 로그가 계속 출력된다면 정상적으로 실행 중이므로 서둘러 Ctrl+C를 누르지 마세요.

체계적인 문제 해결 절차(종합 진단)

앞에서 구체적인 문제를 살펴봤으므로 이제 체계적인 진단 절차를 정리합니다. 어디서부터 확인해야 할지 모르겠다면 다음 순서대로 진행하세요.

OpenClaw 내장 진단 명령:

# 서비스 상태 확인
openclaw status

# 상태 확인
openclaw health

# 전체 진단(권장)
openclaw doctor

openclaw doctor는 특히 유용합니다. Node.js 버전, Docker 상태, API 키 설정, 포트 사용 여부 등 자주 발생하는 문제를 자동으로 점검하고 진단 보고서를 제공합니다.

로그 분석 팁:

많은 로그 출력에 압도될 필요는 없습니다. 다음 정보에 집중하세요.

• ERROR 수준 정보 - grep -i "error"로 필터링합니다.
• 첫 번째 오류 - 뒤에 나오는 오류는 대개 연쇄 반응입니다.
• 스택 추적(stack trace) - 문제가 발생한 정확한 코드 줄을 찾는 데 도움이 됩니다.

GitHub Issue는 언제 제출해야 하나요?

위 절차대로 확인해도 해결되지 않는다면 실제 Bug일 수 있습니다.

Issue를 제출하기 전에 다음 정보를 준비합니다.

• 운영체제와 버전(Windows 11 + WSL2 Ubuntu 22.04 / macOS 14 / Ubuntu 22.04)
• Node.js 버전(node -v)
• OpenClaw 버전(openclaw --version)
• 전체 오류 로그(코드 블록으로 서식 지정)
• 재현 단계

정보가 자세할수록 관리자가 문제를 더 쉽게 파악할 수 있습니다.

결론

앞에서 다룬 7가지 문제의 핵심 해결 방법을 빠르게 정리하면 다음과 같습니다.

1. Node.js 버전 - nvm으로 Node 24(또는 최소 v22.14 이상)를 설치해 공식 요구 사항에 맞춥니다.
2. npm 권한 - 전역 디렉터리를 home으로 옮기거나 WSL 네이티브 디렉터리에서 작업합니다.
3. Docker 문제 - 먼저 로그로 원인을 찾습니다. 대부분 리소스 부족이나 포트 충돌입니다.
4. API 키 - 환경 변수, JSON 형식, key 유효성을 확인합니다.
5. WSL2 설정 - wsl.conf를 구성하고 파일 시스템을 넘나드는 작업을 피합니다.
6. 스킬 설치 - 네트워크 시간 초과는 재시도하고, 의존성이 없으면 설치합니다.
7. 체계적인 진단 - openclaw doctor로 전체를 진단하고 순서대로 점검합니다.

OpenClaw 설치가 번거로운 것은 사실이지만 한 번 해결한 문제는 다시 겪지 않게 됩니다. 가장 중요한 것은 체계적인 문제 해결 방식을 갖추는 것입니다. 오류를 보고 당황하기보다 어느 단계에서 문제가 생겼는지 차분히 분석한 다음 원인에 맞는 해결책을 적용하세요.

이 체크리스트를 저장해 두면 다음에 문제가 생겼을 때 빠르게 대조할 수 있습니다. 이 목록으로 시간을 아꼈다면 OpenClaw를 설치하느라 고생하는 다른 사람에게도 공유해 주세요.

글에서 다루지 않은 문제가 있나요? 댓글에서 함께 이야기해 주세요. 이 문제 해결 가이드는 계속 업데이트하겠습니다.