디버깅 (Debugging)

OpenClaw의 디버그 모드와 진단 도구를 사용하여 문제를 해결하는 방법을 알아봅니다.

개요

디버깅 도구

디버그 모드

활성화 방법

# 1. 명령행 플래그
openclaw --debug gateway start

# 2. 환경 변수
export OPENCLAW_DEBUG=1
openclaw gateway start

# 3. 설정 파일
# openclaw.json
{
  "debug": true,
  "logLevel": "debug"
}

디버그 출력 예시

[DEBUG] 2026-02-23T10:00:00.000Z Loading configuration from ~/.openclaw/openclaw.json
[DEBUG] 2026-02-23T10:00:00.100Z Configuration loaded successfully
[DEBUG] 2026-02-23T10:00:00.200Z Initializing Slack client
[DEBUG] 2026-02-23T10:00:00.300Z Connecting to Slack RTM
[DEBUG] 2026-02-23T10:00:01.000Z Slack connection established
[DEBUG] 2026-02-23T10:00:01.100Z Gateway started successfully
[INFO] 2026-02-23T10:00:01.200Z Ready to receive messages

로그 확인

로그 레벨

# 모든 로그 (DEBUG 레벨부터)
openclaw logs --level debug

# INFO 레벨부터 (기본)
openclaw logs

# WARNING만
openclaw logs --level warning

# ERROR만
openclaw logs --level error

로그 필터링

# 특정 텍스트 검색
openclaw logs | grep "Slack"

# 최근 50줄
openclaw logs | tail -50

# 실시간 로그
openclaw logs --follow

# 실시간 + ERROR만
openclaw logs --follow --level error

로그 파일 위치

# 로그 파일 경로 확인
openclaw logs --path
# 출력: ~/.openclaw/logs/gateway.log

# 직접 확인
tail -f ~/.openclaw/logs/gateway.log

진단 명령어

상태 확인

openclaw gateway status

# 출력 예시:
# Status: Running
# PID: 12345
# Uptime: 2 hours 30 minutes
# Channels: 3 active (Slack, Telegram, Discord)

설정 검증

# 전체 설정 검증
openclaw config validate

# 특정 섹션만
openclaw config validate --section channels
openclaw config validate --section agents
openclaw config validate --section skills

채널 테스트

openclaw channel test --type slack
openclaw channel test --type telegram
openclaw channel test --type discord

Dry-run 모드

Gateway 테스트

openclaw gateway start --dry-run

# 출력:
# Configuration valid
# Slack connection OK
# Telegram connection OK
# Discord connection failed (check token) - 경고

명령어 테스트

# 에이전트 응답 테스트 (메시지 전송 없음)
openclaw agent test "날씨 알려줘"

# 스킬 실행 테스트
openclaw skill test weather --city "Seoul"

문제 진단 워크플로우

1단계: 로그 확인

openclaw logs --level error | tail -20
openclaw logs --follow

2단계: 상태 확인

openclaw gateway status
openclaw channel list

3단계: 설정 검증

openclaw config validate
openclaw config get channels.slack.enabled

4단계: 디버그 모드 재시작

openclaw --debug gateway restart
openclaw logs --follow --level debug

일반적인 문제 패턴

패턴 1: API 연결 실패

# 1. API 키 확인
echo $OPENCLAW_API_KEY

# 2. 네트워크 연결 확인
ping api.anthropic.com

# 3. 디버그 모드로 테스트
openclaw --debug agent test "안녕"

# 4. 로그에서 에러 확인
openclaw logs --level error

패턴 2: 채널 연결 실패

# 1. 채널 테스트
openclaw channel test --type slack

# 2. 토큰 확인
openclaw config get channels.slack.botToken

# 3. 재연결
openclaw gateway restart

패턴 3: 스킬 실행 실패

# 1. 스킬 목록 확인
openclaw skill list

# 2. 스킬 테스트
openclaw skill test my-skill

# 3. 스킬 로그 확인
openclaw logs | grep "my-skill"

# 4. 스킬 재설치
openclaw skill remove my-skill
openclaw skill install my-skill

고급 진단

프로세스 모니터링

ps aux | grep openclaw
top | grep openclaw
lsof -i -P | grep openclaw

진단 정보 수집

문제 보고용 정보 수집 스크립트:

#!/bin/bash
echo "=== OpenClaw Debug Info ==="

echo "Version:"
openclaw --version

echo "Gateway Status:"
openclaw gateway status

echo "Recent Errors:"
openclaw logs --level error | tail -10

echo "Config Validation:"
openclaw config validate

echo "System Info:"
uname -a

echo "Node Version:"
node --version

echo "Environment:"
env | grep OPENCLAW

디버깅 팁

효과적인 디버깅

이분법 검색으로 문제 범위를 좁힙니다:

# 설정이 문제인가?
openclaw config validate

# 연결이 문제인가?
openclaw channel test --type slack

# 에이전트가 문제인가?
openclaw agent test "안녕"

최소한의 재현:

export default {
  async execute(context) {
    console.log('Context:', JSON.stringify(context, null, 2));
    return { success: true };
  }
};

로그에 타임스탬프 포함:

console.log(`[${new Date().toISOString()}] Step 1 complete`);
console.log(`[${new Date().toISOString()}] Step 2 complete`);

주의사항

프로덕션에서 디버그 출력을 제한합니다:

// 조건부 출력
if (process.env.OPENCLAW_DEBUG) {
  console.log('Debug:', data);
}

과도한 로그를 피합니다:

for (let i = 0; i < 1000000; i++) {
  if (i % 10000 === 0) {
    console.log('Progress:', i);
  }
}

참고:

• 공식 문서: Debugging