일반적인 오류 및 해결 방법

OpenClaw 사용 중 발생할 수 있는 일반적인 오류 20개와 그 해결 방법을 정리했습니다.

설치 관련 오류

1. "command not found: openclaw"

증상:

$ openclaw gateway start
zsh: command not found: openclaw

원인: OpenClaw가 시스템 PATH에 설치되지 않음, 또는 설치가 완료되지 않음.

방법 1 - 전역 설치 확인:

npm install -g @openclaw/cli
npm list -g @openclaw/cli

# 또는 설치 스크립트 재실행
curl -fsSL https://install.openclaw.ai | sh

방법 2 - PATH에 추가:

npm config get prefix
# 출력: /usr/local

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

방법 3 - npx 사용 (설치 없이 실행):

npx @openclaw/cli gateway start

2. "Permission denied" 오류

증상:

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openclaw'

방법 1 - 사용자 수준 설치:

npm config set prefix '~/.npm-global'
npm install -g @openclaw/cli

echo 'export PATH="~/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

방법 2 - Docker 사용 (권장):

docker pull openclaw/gateway:latest
docker run -d openclaw/gateway:latest

3. "Port 3000 is already in use"

증상:

Error: Port 3000 is already in use

방법 1 - 포트를 사용하는 프로세스 확인 및 종료:

lsof -i :3000
kill 12345

방법 2 - 다른 포트 사용:

openclaw gateway start --port 3001

방법 3 - 설정 파일에서 포트 변경:

{
  "gateway": {
    "port": 3001
  }
}

채널 연결 오류

4. Slack "Invalid Auth" 오류

증상:

[Error] Slack connection failed: invalid_auth

해결:

Slack API로 이동하여 토큰 재발급
토큰 업데이트:

openclaw config set channels.slack.botToken "xoxb-NEW_TOKEN"
openclaw config set channels.slack.appToken "xapp-NEW_TOKEN"
openclaw gateway restart

필수 Slack 권한: chat:write, channels:history, groups:history, im:history, mpim:history

5. Telegram "Unauthorized" 오류

증상:

[Error] Telegram bot failed: Unauthorized

해결:

Telegram에서 @BotFather 열기
/mybots → 해당 봇 선택 → API Token → Revoke Token
재설정:

openclaw config set channels.telegram.botToken "NEW_TOKEN"
openclaw gateway restart

6. Discord "Invalid Token" 오류

증상:

[Error] Discord connection failed: 401 Unauthorized

해결:

Discord Developer Portal → Bot → Reset Token
업데이트:

openclaw config set channels.discord.botToken "NEW_TOKEN"
openclaw gateway restart

7. Slack "bot_not_found_in_channel" 오류

증상: Slack에서 봇에게 메시지를 보냈는데 응답 없음

원인: 봇이 채널에 초대되지 않음

해결:

/invite @YourBotName

또는 채널 설정 → Add an app → 봇 선택

API/모델 관련 오류

8. Anthropic "Invalid API Key"

증상:

[Error] Anthropic API error: 401 Unauthorized

해결:

Anthropic Console → API Keys → Create Key
업데이트:

openclaw config set models.providers.anthropic.apiKey "sk-ant-NEW_KEY"
openclaw gateway restart

API 키 테스트:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'

9. "Rate limit exceeded" 오류

증상:

[Error] Rate limit exceeded. Please retry after 60 seconds.

해결:

{
  "security": {
    "rateLimiting": {
      "enabled": true,
      "maxRequests": 50,
      "windowMs": 60000
    }
  }
}

더 작은 모델 사용:

{
  "models": {
    "default": "claude-haiku-4-6"
  }
}

10. "Model not found" 오류

증상:

[Error] Model 'claude-sonnet-4-6' not found

해결:

openclaw config set models.default claude-haiku-4-6

Gateway 실행 오류

11. "Configuration file not found"

증상:

Error: Configuration file not found: ~/.openclaw/openclaw.json

해결:

openclaw config init

또는 최소 설정 파일 생성:

mkdir -p ~/.openclaw
cat > ~/.openclaw/openclaw.json << EOF
{
  "version": "1.0.0",
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  },
  "models": {
    "default": "claude-haiku-4-6",
    "providers": {
      "anthropic": {
        "apiKey": "YOUR_ANTHROPIC_API_KEY"
      }
    }
  }
}
EOF

12. "Workspace initialization failed"

증상:

[Error] Failed to initialize workspace: /Users/user/.openclaw/workspace

해결:

chmod 755 ~/.openclaw
chmod 755 ~/.openclaw/workspace

# 디스크 공간 확인
df -h

# 워크스페이스 재생성
rm -rf ~/.openclaw/workspace
mkdir -p ~/.openclaw/workspace
openclaw gateway start

13. "Failed to load skill"

증상:

[Error] Failed to load skill: web-search

해결:

# 내장 스킬인 경우
openclaw skill install web-search

# 커스텀 스킬인 경우
cd /path/to/skill
npm install

성능 및 리소스 오류

14. "Out of memory" 오류

증상:

[Error] JavaScript heap out of memory

해결:

export NODE_OPTIONS="--max-old-space-size=4096"
openclaw gateway start

설정에서 메모리 제한:

{
  "memory": {
    "maxEntries": 500,
    "retentionDays": 7
  }
}

15. Gateway가 자주 중지됨

해결 - PM2로 실행 (권장):

npm install -g pm2
pm2 start openclaw --name gateway -- gateway start
pm2 save
pm2 startup

systemd 서비스로 등록 (Linux):

sudo cat > /etc/systemd/system/openclaw.service << EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable openclaw
sudo systemctl start openclaw

16. 응답 시간이 너무 느림

해결:

{
  "models": {
    "default": "claude-haiku-4-6"
  }
}

스킬 타임아웃 설정:

{
  "skills": {
    "timeout": 10000,
    "maxConcurrent": 3
  }
}

17. "Connection timeout" 오류

증상:

[Error] Connection timeout: api.anthropic.com

해결:

# Anthropic API 연결 확인
curl https://api.anthropic.com/v1/messages

# 프록시 설정
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
openclaw gateway start

기타 오류

18. "Skill not found"

openclaw skill list
openclaw skill install clawhub://username/skill-name

19. "Failed to parse configuration"

증상:

[Error] Failed to parse openclaw.json: Unexpected token }

해결 - JSON 유효성 검사:

openclaw debug --validate-config

올바른 JSON 예시:

{
  "channels": {
    "slack": {
      "enabled": true
    }
  }
}

20. Docker 컨테이너가 즉시 종료됨

해결:

# 로그 확인
docker logs <container-id>

# 필수 환경 변수 설정
docker run -d \
  -e OPENCLAW_ANTHROPIC_API_KEY=sk-ant-... \
  -e OPENCLAW_TELEGRAM_BOT_TOKEN=123456:ABC... \
  openclaw/gateway:latest

도움 요청 가이드

도움 요청 전 체크리스트

OpenClaw 버전: openclaw --version
운영체제: macOS, Linux, Windows (버전 포함)
전체 오류 메시지: 스택 트레이스 전체
설정 파일: 민감한 정보(토큰, API 키) 제거
재현 단계: 오류가 발생하는 정확한 단계
시도한 해결 방법: 이미 시도해본 것

도움을 요청할 곳

채널	용도	응답 시간
OpenClaw Discord	일반적인 질문, 실시간 도움	보통 몇 시간 내
GitHub Issues	버그 신고, 기능 요청	1-3일
GitHub Discussions	일반적인 토론	1-2일

참고:

공식 문서: Troubleshooting

일반적인 오류 및 해결 방법

OpenClaw 사용 중 발생할 수 있는 일반적인 오류 20개와 그 해결 방법을 정리했습니다.

설치 관련 오류

1. "command not found: openclaw"

증상:

$ openclaw gateway start
zsh: command not found: openclaw

원인: OpenClaw가 시스템 PATH에 설치되지 않음, 또는 설치가 완료되지 않음.

방법 1 - 전역 설치 확인:

npm install -g @openclaw/cli
npm list -g @openclaw/cli

# 또는 설치 스크립트 재실행
curl -fsSL https://install.openclaw.ai | sh

방법 2 - PATH에 추가:

npm config get prefix
# 출력: /usr/local

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

방법 3 - npx 사용 (설치 없이 실행):

npx @openclaw/cli gateway start

2. "Permission denied" 오류

증상:

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openclaw'

방법 1 - 사용자 수준 설치:

npm config set prefix '~/.npm-global'
npm install -g @openclaw/cli

echo 'export PATH="~/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

방법 2 - Docker 사용 (권장):

docker pull openclaw/gateway:latest
docker run -d openclaw/gateway:latest

3. "Port 3000 is already in use"

증상:

Error: Port 3000 is already in use

방법 1 - 포트를 사용하는 프로세스 확인 및 종료:

lsof -i :3000
kill 12345

방법 2 - 다른 포트 사용:

openclaw gateway start --port 3001

방법 3 - 설정 파일에서 포트 변경:

{
  "gateway": {
    "port": 3001
  }
}

채널 연결 오류

4. Slack "Invalid Auth" 오류

증상:

[Error] Slack connection failed: invalid_auth

해결:

Slack API로 이동하여 토큰 재발급
토큰 업데이트:

openclaw config set channels.slack.botToken "xoxb-NEW_TOKEN"
openclaw config set channels.slack.appToken "xapp-NEW_TOKEN"
openclaw gateway restart

필수 Slack 권한: chat:write, channels:history, groups:history, im:history, mpim:history

5. Telegram "Unauthorized" 오류

증상:

[Error] Telegram bot failed: Unauthorized

해결:

Telegram에서 @BotFather 열기
/mybots → 해당 봇 선택 → API Token → Revoke Token
재설정:

openclaw config set channels.telegram.botToken "NEW_TOKEN"
openclaw gateway restart

6. Discord "Invalid Token" 오류

증상:

[Error] Discord connection failed: 401 Unauthorized

해결:

Discord Developer Portal → Bot → Reset Token
업데이트:

openclaw config set channels.discord.botToken "NEW_TOKEN"
openclaw gateway restart

7. Slack "bot_not_found_in_channel" 오류

증상: Slack에서 봇에게 메시지를 보냈는데 응답 없음

원인: 봇이 채널에 초대되지 않음

해결:

/invite @YourBotName

또는 채널 설정 → Add an app → 봇 선택

API/모델 관련 오류

8. Anthropic "Invalid API Key"

증상:

[Error] Anthropic API error: 401 Unauthorized

해결:

Anthropic Console → API Keys → Create Key
업데이트:

openclaw config set models.providers.anthropic.apiKey "sk-ant-NEW_KEY"
openclaw gateway restart

API 키 테스트:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'

9. "Rate limit exceeded" 오류

증상:

[Error] Rate limit exceeded. Please retry after 60 seconds.

해결:

{
  "security": {
    "rateLimiting": {
      "enabled": true,
      "maxRequests": 50,
      "windowMs": 60000
    }
  }
}

더 작은 모델 사용:

{
  "models": {
    "default": "claude-haiku-4-6"
  }
}

10. "Model not found" 오류

증상:

[Error] Model 'claude-sonnet-4-6' not found

해결:

openclaw config set models.default claude-haiku-4-6

Gateway 실행 오류

11. "Configuration file not found"

증상:

Error: Configuration file not found: ~/.openclaw/openclaw.json

해결:

openclaw config init

또는 최소 설정 파일 생성:

mkdir -p ~/.openclaw
cat > ~/.openclaw/openclaw.json << EOF
{
  "version": "1.0.0",
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  },
  "models": {
    "default": "claude-haiku-4-6",
    "providers": {
      "anthropic": {
        "apiKey": "YOUR_ANTHROPIC_API_KEY"
      }
    }
  }
}
EOF

12. "Workspace initialization failed"

증상:

[Error] Failed to initialize workspace: /Users/user/.openclaw/workspace

해결:

chmod 755 ~/.openclaw
chmod 755 ~/.openclaw/workspace

# 디스크 공간 확인
df -h

# 워크스페이스 재생성
rm -rf ~/.openclaw/workspace
mkdir -p ~/.openclaw/workspace
openclaw gateway start

13. "Failed to load skill"

증상:

[Error] Failed to load skill: web-search

해결:

# 내장 스킬인 경우
openclaw skill install web-search

# 커스텀 스킬인 경우
cd /path/to/skill
npm install

성능 및 리소스 오류

14. "Out of memory" 오류

증상:

[Error] JavaScript heap out of memory

해결:

export NODE_OPTIONS="--max-old-space-size=4096"
openclaw gateway start

설정에서 메모리 제한:

{
  "memory": {
    "maxEntries": 500,
    "retentionDays": 7
  }
}

15. Gateway가 자주 중지됨

해결 - PM2로 실행 (권장):

npm install -g pm2
pm2 start openclaw --name gateway -- gateway start
pm2 save
pm2 startup

systemd 서비스로 등록 (Linux):

sudo cat > /etc/systemd/system/openclaw.service << EOF
[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=your-user
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable openclaw
sudo systemctl start openclaw

16. 응답 시간이 너무 느림

해결:

{
  "models": {
    "default": "claude-haiku-4-6"
  }
}

스킬 타임아웃 설정:

{
  "skills": {
    "timeout": 10000,
    "maxConcurrent": 3
  }
}

17. "Connection timeout" 오류

증상:

[Error] Connection timeout: api.anthropic.com

해결:

# Anthropic API 연결 확인
curl https://api.anthropic.com/v1/messages

# 프록시 설정
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
openclaw gateway start

기타 오류

18. "Skill not found"

openclaw skill list
openclaw skill install clawhub://username/skill-name

19. "Failed to parse configuration"

증상:

[Error] Failed to parse openclaw.json: Unexpected token }

해결 - JSON 유효성 검사:

openclaw debug --validate-config

올바른 JSON 예시:

{
  "channels": {
    "slack": {
      "enabled": true
    }
  }
}

20. Docker 컨테이너가 즉시 종료됨

해결:

# 로그 확인
docker logs <container-id>

# 필수 환경 변수 설정
docker run -d \
  -e OPENCLAW_ANTHROPIC_API_KEY=sk-ant-... \
  -e OPENCLAW_TELEGRAM_BOT_TOKEN=123456:ABC... \
  openclaw/gateway:latest

도움 요청 가이드

도움 요청 전 체크리스트

OpenClaw 버전: openclaw --version
운영체제: macOS, Linux, Windows (버전 포함)
전체 오류 메시지: 스택 트레이스 전체
설정 파일: 민감한 정보(토큰, API 키) 제거
재현 단계: 오류가 발생하는 정확한 단계
시도한 해결 방법: 이미 시도해본 것

도움을 요청할 곳

채널	용도	응답 시간
OpenClaw Discord	일반적인 질문, 실시간 도움	보통 몇 시간 내
GitHub Issues	버그 신고, 기능 요청	1-3일
GitHub Discussions	일반적인 토론	1-2일

참고:

공식 문서: Troubleshooting

일반적인 오류 및 해결 방법

설치 관련 오류

1. "command not found: openclaw"

2. "Permission denied" 오류

3. "Port 3000 is already in use"

채널 연결 오류

4. Slack "Invalid Auth" 오류

5. Telegram "Unauthorized" 오류

6. Discord "Invalid Token" 오류

7. Slack "bot_not_found_in_channel" 오류

API/모델 관련 오류

8. Anthropic "Invalid API Key"

9. "Rate limit exceeded" 오류

10. "Model not found" 오류

Gateway 실행 오류

11. "Configuration file not found"

12. "Workspace initialization failed"

13. "Failed to load skill"

성능 및 리소스 오류

14. "Out of memory" 오류

15. Gateway가 자주 중지됨

16. 응답 시간이 너무 느림

17. "Connection timeout" 오류

기타 오류

18. "Skill not found"

19. "Failed to parse configuration"

20. Docker 컨테이너가 즉시 종료됨

도움 요청 가이드

도움 요청 전 체크리스트

도움을 요청할 곳

관련 가이드

일반적인 오류 및 해결 방법

설치 관련 오류

1. "command not found: openclaw"

2. "Permission denied" 오류

3. "Port 3000 is already in use"

채널 연결 오류

4. Slack "Invalid Auth" 오류

5. Telegram "Unauthorized" 오류

6. Discord "Invalid Token" 오류

7. Slack "bot_not_found_in_channel" 오류

API/모델 관련 오류

8. Anthropic "Invalid API Key"

9. "Rate limit exceeded" 오류

10. "Model not found" 오류

Gateway 실행 오류

11. "Configuration file not found"

12. "Workspace initialization failed"

13. "Failed to load skill"

성능 및 리소스 오류

14. "Out of memory" 오류

15. Gateway가 자주 중지됨

16. 응답 시간이 너무 느림

17. "Connection timeout" 오류

기타 오류

18. "Skill not found"

19. "Failed to parse configuration"

20. Docker 컨테이너가 즉시 종료됨

도움 요청 가이드

도움 요청 전 체크리스트

도움을 요청할 곳

관련 가이드