문제 해결 가이드

Clawdbot 사용 중 발생하는 일반적인 문제와 해결 방법

📋 목록

설치 문제

Gateway 문제

🔧 설치 문제

문제 1: Node.js 버전 호환성 오류

증상:

Error: Node.js version 20.x is not supported.
Clawdbot requires Node.js >= 22.12.0

해결책:

# Node.js 버전 확인
node --version

# 최신 LTS 버전 설치
# macOS
brew install node

# Linux
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 확인
node --version  # 22.12.0 이상이어야 함

문제 2: pnpm 설치 오류

증상:

Error: pnpm: command not found

해결책:

# npm으로 pnpm 설치
npm install -g pnpm

# 또는 Corepack 사용
corepack enable

# 확인
pnpm --version  # 10.23.0 이상이어야 함

문제 3: 포트 충돌

증상:

Error: Port 18789 is already in use

해결책:

# 충돌하는 프로세스 확인
lsof -ti:18789

# 출력 예시:
# COMMAND   PID   USER   FD   TYPE   DEVICE SIZE/OFF  NODE NAME
# clawdbot 12345 user    3u  IPv4   TCP    *:18789

# 프로세스 종료
kill 12345

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

🚀 Gateway 문제

문제 1: Gateway가 시작 안 됨

증상:

Gateway failed to start
Check logs for details

해결책:

# 1. 로그 확인
clawdbot logs gateway --tail 50

# 2. 설정 파일 확인
clawdbot config get gateway
clawdbot config get channels

# 3. 포트 확인
lsof -ti:18789

# 4. 의존성 확인
pnpm list  # 설치된 패키지 확인

# 5. 상세한 로그로 재시도
clawdbot gateway --verbose --debug

문제 2: Gateway가 즉시 종료됨

증상:

Gateway started...
Gateway stopped unexpectedly

해결책:

원인 1: 인증 오류

# 인증 설정 확인
clawdbot config get gateway.auth

# 인증 비활성화
clawdbot config set gateway.auth.mode none

# 또는 비밀번호/토큰 설정 확인
clawdbot config edit gateway

원인 2: 채널 연결 실패

# 채널 상태 확인
clawdbot channels status --probe

# 실패한 채널 재연결
clawdbot channels login <failed-channel>

원인 3: 포트 바인딩 오류

# 루프백 전용
clawdbot config set gateway.bind loopback

# 또는 0.0.0.0
clawdbot config set gateway.bind 0.0.0.0

# 포트 변경
clawdbot config set gateway.port 18790

문제 3: 클라이언트 연결 실패

증상:

Error: WebSocket connection refused
ws://127.0.0.1:18789

해결책:

# 1. Gateway 상태 확인
clawdbot status --gateway

# 2. 포트 확인
ss -ltnp | rg 18789

# 3. 방화벽 확인 (macOS)
sudo pfctl -s info | rg 18789

# 방화벽 허용
# macOS
sudo pfctl -d  # 일시적 비활성화

# 4. 바인드 주소 확인
clawdbot config get gateway.bind

# 루프백 아닌 경우
# 127.0.0.1:18789 → 0.0.0.0:18789

📱 채널 문제

문제 1: WhatsApp QR 코드가 나타나지 않음

증상:

WhatsApp login started...
Waiting for QR code...
(아무것도 일어나지 않음)

해결책:

# 1. Baileys 연결 확인
clawdbot logs gateway | rg -i "baileys\|whatsapp"

# 2. 캐시 클리어
rm -rf ~/.clawdbot/sessions/whatsapp/*

# 3. 다시 로그인
clawdbot channels login whatsapp

# 4. QR 코드 가져오기 시도
clawdbot channels login whatsapp --qr-import

문제 2: Telegram Bot 응답 없음

증상:

Telegram login started...
Bot is ready
(메시지 전송 시 응답 없음)

해결책:

# 1. Bot Token 확인
clawdbot config get channels.telegram.botToken

# 2. Bot이 그룹에 있는가 확인
# https://t.me/botfather

# 3. Bot 설정
clawdbot channels login telegram

# 4. 웹훅 설정 (필요시)
clawdbot channels telegram set-webhook

문제 3: Slack Bot API 오류

증상:

Error: Slack API rate limit exceeded

해결책:

# 1. 잠시 대기 (15분)
sleep 900

# 2. Bot 범위 확인
# https://api.slack.com/methods/auth.test

# 3. 재시도
# 요청 빈도 낮추기

문제 4: 채널 연결 끊김

증상:

Channel disconnected
Reconnecting...

해결책:

# 1. 로그 확인
clawdbot logs gateway | rg -i "disconnected\|error"

# 2. 네트워크 확인
ping -c 3 8.8.8.8

# 3. 채널 재연결
clawdbot channels status --probe

🤖 에이전트 문제

문제 1: 에이전트 응답 없음

증상:

Agent started...
(thinking...)
(아무것도 일어나지 않음)

해결책:

원인 1: API 키 문제

# 1. API 키 확인
clawdbot config get providers.anthropic.apiKey

# 2. API 키 재설정
clawdbot config set providers.anthropic.apiKey sk-ant-xxx

# 3. 컨덱셜 체크
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-xxx"

원인 2: 모델 오류

# 1. 모델 확인
clawdbot config get agent.model

# 2. 올바른 모델 확인
clawdbot config set agent.model "anthropic/claude-opus-4-5"

# 3. 지원 모델 목록
clawdbot status --agent

원인 3: 도구 권한 문제

# 1. 세션 권한 확인
clawdbot status --sessions

# 2. 권한 확인
# 메인 세션이어야 모든 도구 사용 가능

# 3. 권한 변경
clawdbot config set sandbox.allowlist '["bash","read","write"]'

문제 2: 에이전트 계속 반복됨

증상:

Hello! Hello! Hello! Hello!

해결책:

# 1. 세션 기록 확인
clawdbot logs sessions --session <session-id>

# 2. 시스템 프롬프트 확인
cat ~/clawd/SOUL.md

# 3. 페르소나 설정
clawdbot config edit

# 4. 세션 리셋
clawdbot reset --sessions <session-id>

문제 3: 도구 실행 실패

증상:

Error: Tool browser_navigate failed

해결책:

# 1. 도구 권한 확인
clawdbot config get sandbox.allowlist

# 2. 권한 추가
clawdbot config set sandbox.allowlist '["bash","browser","read","write"]'

# 3. 샌드박스 비활성화 (테스트용)
clawdbot config set sandbox.mode none

# 4. 재시도

🛠 도구 문제

문제 1: 브라우저가 시작 안 됨

증상:

Error: Browser failed to start

해결책:

# 1. Playwright 설치 확인
pnpm list | rg playwright

# 2. Chromium 설치
npx playwright install chromium

# 3. 브라우저 설정 확인
clawdbot config get browser

# 4. 브라우저 재시작
# Gateway 재시작

문제 2: 캔버스가 열리지 않음

증상:

Error: Canvas host failed to start on port 18793

해결책:

# 1. 포트 확인
lsof -ti:18793

# 2. 캔버스 설정 확인
clawdbot config get gateway.controlUi

# 3. 캔버스 비활성화 (테스트용)
clawdbot config set gateway.controlUi false

# 4. 포트 변경
clawdbot config set canvas.port 18794

문제 3: 크론 작업이 실행 안 됨

증상:

Error: Cron job failed to schedule

해결책:

# 1. 크론 문법 확인
# https://crontab.guru

# 2. 설정 확인
clawdbot config get cron

# 3. 에이전트 확인
clawdbot config get agents.bindings

# 4. 작업 재스케줄링
clawdbot config edit cron

🔒 보안 문제

문제 1: DM이 도착하지 않음

증상:

DM sent, but not received by Clawdbot

해결책:

# 1. 페어링 상태 확인
clawdbot pairing list

# 2. 페어링 승인
clawdbot pairing approve <channel> <code>

# 3. allowlist 확인
clawdbot config get channels.<channel>.allowFrom

# 4. 오픈 모드로 변경 (테스트용)
clawdbot config set channels.<channel>.dmPolicy open

문제 2: 페어링 코드가 유효하지 않음

증상:

Error: Invalid pairing code

해결책:

# 1. 새로운 코드 요청
# DM 다시 전송

# 2. 코드 유효기간 확인
# 기본 10분

# 3. 페어링 기록 확인
clawdbot pairing list

문제 3: 샌드박스 실행 오류

증상:

Error: Docker sandbox failed to start

해결책:

# 1. Docker 설치 확인
docker --version

# 2. Docker 상태 확인
docker ps -a | rg clawdbot

# 3. 샌드박스 비활성화
clawdbot config set sandbox.mode none

# 4. 샌드박스 설정 확인
clawdbot config get sandbox

⚡ 성능 문제

문제 1: 메모리 사용량 과다

증상:

Memory usage: 90%+

해결책:

# 1. 메모리 사용량 확인
ps aux | rg clawdbot

# 2. 세션 컴팩션 활성화
clawdbot config set sessions.compaction true

# 3. 세션 수 제한
clawdbot config set sessions.maxSessions 10

# 4. 재시작
clawdbot gateway restart

문제 2: 응답 속도 느림

증상:

Response time: > 30 seconds

해결책:

# 1. 모델 확인
clawdbot config get agent.model

# 2. 더 빠른 모델로 변경
clawdbot config set agent.model "anthropic/claude-sonnet-4-5"

# 3. 사고 레벨 낮추기
clawdbot config set agent.thinkingLevel low

# 4. 컨텍스트 제한
clawdbot config set agent.maxTokens 50000

문제 3: CPU 사용량 과다

증상:

CPU usage: 100%

해결책:

# 1. 실행 중인 작업 확인
ps aux | rg clawdbot

# 2. 로그 확인
clawdbot logs gateway | rg -i "error\|warn"

# 3. 불필요한 기능 비활성화
clawdbot config set features.background-sync false

# 4. 재시작
clawdbot gateway restart

🔍 디버깅 팁

1. 상세한 로그 활성화

# Gateway 상세한 로그
clawdbot gateway --verbose --debug

# 에이전트 상세한 로그
clawdbot agent --thinking high --verbose

2. 로그 파일 직접 확인

# Gateway 로그
tail -f ~/.clawdbot/logs/gateway.log

# 에이전트 로그
tail -f ~/.clawdbot/logs/agent.log

# 채널 로그
tail -f ~/.clawdbot/logs/channels.log

3. 로그 필터링

# 오류만 필터
clawdbot logs gateway | rg -i "error"

# 특정 세션만
clawdbot logs sessions --session whatsapp:+1234567890

# 시간 범위
clawdbot logs gateway --since "2026-01-26T10:00:00"

📞 추가 도움말

문제가 계속되는 경우

공식 문서 확인: 메인 문서

GitHub Issues 검색: GitHub

Discord 커뮤니티: Discord

Doctor 실행: clawdbot doctor --verbose

버그 리포트

# 버그 리포트 생성
# 1. 문제 설명 준비
# 2. 로그 수집
# 3. 설정 내보내기
# 4. GitHub Issue 생성

🔗 관련 문서

•

•

•

•