# 문제 해결 가이드

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

---

## 📋 목록

1. [설치 문제](https://#%EC%84%A4%EC%B9%98-%EB%AC%B8%EC%A0%9C)

2. [Gateway 문제](https://#gateway-%EB%AC%B8%EC%A0%9C)

3. [채널 문제](https://#%EC%B1%84%EB%84%90-%EB%AC%B8%EC%A0%9C)

4. [에이전트 문제](https://#%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EB%AC%B8%EC%A0%9C)

5. [도구 문제](https://#%EB%8F%84%EA%B5%AC-%EB%AC%B8%EC%A0%9C)

6. [보안 문제](https://#%EB%B3%B4%EC%95%88-%EB%AC%B8%EC%A0%9C)

7. [성능 문제](https://#%EC%84%B1%EB%8A%A5-%EB%AC%B8%EC%A0%9C)

---

## 🔧 설치 문제

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

**증상:**

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

**해결책:**

```javascript
# 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 설치 오류

**증상:**

```javascript
Error: pnpm: command not found
```

**해결책:**

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

# 또는 Corepack 사용
corepack enable

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

### 문제 3: 포트 충돌

**증상:**

```javascript
Error: Port 18789 is already in use
```

**해결책:**

```javascript
# 충돌하는 프로세스 확인
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가 시작 안 됨

**증상:**

```javascript
Gateway failed to start
Check logs for details
```

**해결책:**

```javascript
# 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가 즉시 종료됨

**증상:**

```javascript
Gateway started...
Gateway stopped unexpectedly
```

**해결책:**

**원인 1: 인증 오류**

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

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

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

**원인 2: 채널 연결 실패**

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

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

**원인 3: 포트 바인딩 오류**

```javascript
# 루프백 전용
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: 클라이언트 연결 실패

**증상:**

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

**해결책:**

```javascript
# 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 코드가 나타나지 않음

**증상:**

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

**해결책:**

```javascript
# 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 응답 없음

**증상:**

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

**해결책:**

```javascript
# 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 오류

**증상:**

```javascript
Error: Slack API rate limit exceeded
```

**해결책:**

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

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

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

### 문제 4: 채널 연결 끊김

**증상:**

```javascript
Channel disconnected
Reconnecting...
```

**해결책:**

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

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

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

---

## 🤖 에이전트 문제

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

**증상:**

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

**해결책:**

**원인 1: API 키 문제**

```javascript
# 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: 모델 오류**

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

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

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

**원인 3: 도구 권한 문제**

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

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

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

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

**증상:**

```javascript
Hello! Hello! Hello! Hello!
```

**해결책:**

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

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

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

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

### 문제 3: 도구 실행 실패

**증상:**

```javascript
Error: Tool browser_navigate failed
```

**해결책:**

```javascript
# 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: 브라우저가 시작 안 됨

**증상:**

```javascript
Error: Browser failed to start
```

**해결책:**

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

# 2. Chromium 설치
npx playwright install chromium

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

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

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

**증상:**

```javascript
Error: Canvas host failed to start on port 18793
```

**해결책:**

```javascript
# 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: 크론 작업이 실행 안 됨

**증상:**

```javascript
Error: Cron job failed to schedule
```

**해결책:**

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

# 2. 설정 확인
clawdbot config get cron

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

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

---

## 🔒 보안 문제

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

**증상:**

```javascript
DM sent, but not received by Clawdbot
```

**해결책:**

```javascript
# 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: 페어링 코드가 유효하지 않음

**증상:**

```javascript
Error: Invalid pairing code
```

**해결책:**

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

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

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

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

**증상:**

```javascript
Error: Docker sandbox failed to start
```

**해결책:**

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

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

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

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

---

## ⚡ 성능 문제

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

**증상:**

```javascript
Memory usage: 90%+
```

**해결책:**

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

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

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

# 4. 재시작
clawdbot gateway restart
```

### 문제 2: 응답 속도 느림

**증상:**

```javascript
Response time: > 30 seconds
```

**해결책:**

```javascript
# 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 사용량 과다

**증상:**

```javascript
CPU usage: 100%
```

**해결책:**

```javascript
# 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. 상세한 로그 활성화

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

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

### 2. 로그 파일 직접 확인

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

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

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

### 3. 로그 필터링

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

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

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

---

## 📞 추가 도움말

### 문제가 계속되는 경우

1. **공식 문서 확인**: [메인 문서](https://docs.clawd.bot)

2. **GitHub Issues 검색**: [GitHub](https://github.com/clawdbot/clawdbot/issues)

3. **Discord 커뮤니티**: [Discord](https://discord.gg/clawd)

4. **Doctor 실행**: `clawdbot doctor --verbose`

### 버그 리포트

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

---

## 🔗 관련 문서

- [설치 가이드](https://../deployment/installation.md)

- [상태 확인](https://../cli-config/commands.md#status-%EB%AA%85%EB%A0%B9%EC%96%B4)

- [보안](https://../security/README.md)

- [개발 환경](https://../development/README.md)

For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).