OpenClaw Skill 디버깅 및 성능 최적화 팁

소개

Skill 개발 과정에서 디버깅과 최적화는 피할 수 없는 과정입니다. 동작이 비정상적인 Skill은 부정확한 응답을 초래할 수 있고, 비효율적인 Skill은 대량의 Token을 낭비할 수 있습니다. 이 튜토리얼에서는 OpenClaw Skill의 디버깅 도구와 성능 최적화 전략을 체계적으로 소개합니다.

디버그 모드

전역 디버그 활성화

OpenClaw는 여러 단계의 로그 출력을 제공합니다:

# 기본 로그 레벨 (info)
openclaw logs

# 디버그 레벨 (Skill 매칭 및 실행 상세 정보 표시)
openclaw logs --level debug

# 상세 레벨 (MCP 통신 데이터 포함)
openclaw logs --level verbose

설정에서 로그 레벨 지정

~/.config/openclaw/openclaw.json5에서 영구적으로 설정할 수도 있습니다:

{
  logging: {
    level: "debug",        // info, debug, verbose
    // 로그 출력 위치
    file: "~/.openclaw/logs/openclaw.log",
    // 로그 파일 최대 크기
    maxSize: "10MB",
    // 보관할 로그 파일 수
    maxFiles: 5,
    // 콘솔 출력 여부
    console: true
  }
}

디버그 로그 해석

debug 레벨을 활성화하면 다음과 같은 주요 로그를 확인할 수 있습니다:

[DEBUG] === Message Processing Start ===
[DEBUG] Input: "北京天气怎么样"
[DEBUG] Channel: telegram, User: user_12345

[DEBUG] --- Skill Matching Phase ---
[DEBUG] Checking skill: weather (triggers: 天气,weather,气温)
[DEBUG]   ✓ Trigger matched: "天气" found in message
[DEBUG] Checking skill: reminder (triggers: 提醒,remind,闹钟)
[DEBUG]   ✗ No trigger match
[DEBUG] Checking skill: translator (triggers: 翻译,translate)
[DEBUG]   ✗ No trigger match

[DEBUG] --- Skill Execution Phase ---
[DEBUG] Active skill: weather
[DEBUG] MCP tools available: [http_fetch]
[DEBUG] Sending to model with skill context...

[DEBUG] --- MCP Tool Calls ---
[DEBUG] Tool call: http_fetch.http_get({url: "https://api.openweathermap.org/..."})
[DEBUG] Tool result: 200 OK, 1.2KB response
[DEBUG] Total tool calls: 1

[DEBUG] --- Response Generation ---
[DEBUG] Model response tokens: 245
[DEBUG] Total latency: 2340ms
[DEBUG] === Message Processing End ===

Skill 격리 테스트

Gateway API를 사용한 테스트

채팅 채널을 거치지 않고 Gateway API로 직접 테스트 메시지를 전송합니다:

# 특정 Skill 테스트
curl -X POST http://localhost:18789/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "北京天气怎么样",
    "options": {
      "skill": "weather",
      "debug": true
    }
  }'

debug: true 매개변수를 추가하면 응답에 디버그 정보가 포함됩니다:

{
  "response": "🌤️ 北京天气...",
  "debug": {
    "skillMatched": "weather",
    "triggerWord": "天气",
    "mcpCalls": [
      {
        "server": "http-fetch",
        "tool": "http_get",
        "latency": 890,
        "status": "success"
      }
    ],
    "modelTokens": {
      "input": 1250,
      "output": 245
    },
    "totalLatency": 2340
  }
}

다른 Skill을 비활성화하여 격리 테스트

특정 Skill을 테스트할 때 간섭을 배제하기 위해 다른 Skill을 임시로 비활성화합니다:

{
  skills: {
    // 테스트할 Skill만 활성화
    enabled: ["weather"],
    // 또는 다른 모든 Skill 비활성화
    // disabled: ["reminder", "translator", "rss-reader"]
  }
}

수정 후 재시작합니다:

openclaw restart

테스트 완료 후 설정을 복원하는 것을 잊지 마십시오.

테스트 메시지를 사용한 일괄 검증

Skill 동작을 일괄 검증하기 위한 테스트 스크립트를 생성합니다:

#!/bin/bash
# test-weather-skill.sh

GATEWAY="http://localhost:18789/api/chat"

test_cases=(
  "北京天气怎么样"
  "上海明天会下雨吗"
  "weather in Tokyo"
  "深圳这周气温多少"
  "要不要带伞"
)

for msg in "${test_cases[@]}"; do
  echo "=== Testing: $msg ==="
  curl -s -X POST "$GATEWAY" \
    -H "Content-Type: application/json" \
    -d "{\"message\": \"$msg\", \"options\": {\"debug\": true}}" \
    | python3 -m json.tool
  echo ""
done

주요 디버깅 시나리오

시나리오 1: Skill이 트리거되지 않음

증상: 트리거 키워드가 포함된 메시지를 보냈지만 Skill이 활성화되지 않습니다.

문제 해결 단계:

# 1. Skill이 로드되었는지 확인
openclaw skill list

# 2. 매칭 로그 확인
openclaw logs --level debug

일반적인 원인:

원인	해결 방법
Skill 파일명이 올바르지 않음	`.SKILL.md`로 끝나야 합니다
SKILL.md 문법 오류	YAML frontmatter 형식을 확인합니다
트리거 키워드 불일치	더 많은 트리거 키워드 변형을 추가합니다
Skill이 비활성화됨	설정의 disabled 목록을 확인합니다
다른 Skill이 우선 매칭됨	Skill 우선순위를 조정합니다

시나리오 2: MCP 도구 호출 실패

증상: Skill이 트리거되었지만 MCP 도구가 오류를 반환합니다.

# 상세 MCP 통신 로그 확인
openclaw logs --level verbose

일반적인 오류 및 해결 방법:

[ERROR] MCP tool error: ECONNREFUSED
→ MCP Server가 시작되지 않았거나 포트가 잘못됨

[ERROR] MCP tool error: TIMEOUT
→ 도구 호출 타임아웃, timeout 설정을 늘리십시오

[ERROR] MCP tool error: PERMISSION_DENIED
→ 파일 시스템 MCP에 읽기/쓰기 권한이 없음

[ERROR] MCP tool error: INVALID_PARAMS
→ AI가 잘못된 매개변수 형식을 전달함

시나리오 3: 응답 내용이 기대와 다름

증상: Skill이 트리거되고 도구도 호출되었지만 출력 형식이나 내용이 올바르지 않습니다.

디버깅 방법:

SKILL.md의 Output Format 설명이 충분히 명확한지 확인합니다
AI 모델이 받은 전체 프롬프트를 확인합니다 (verbose 로그에서 확인 가능)
Output Format에 더 많은 예시를 추가해 봅니다
더 안정적인 출력을 위해 temperature를 낮추는 것을 고려합니다

성능 지표 모니터링

주요 성능 지표

Dashboard 또는 API를 통해 다음 지표를 모니터링할 수 있습니다:

# Dashboard 열기
openclaw dashboard

지표	설명	정상 범위
응답 지연	메시지 수신부터 응답 전송까지의 시간	< 5초
MCP 호출 지연	단일 MCP 도구 호출 소요 시간	< 2초
Token 입력량	요청당 입력 Token 수	시나리오에 따라 다름
Token 출력량	응답당 출력 Token 수	< 500
Skill 매칭 시간	트리거 키워드 매칭 소요 시간	< 10ms

API를 통한 성능 데이터 조회

curl http://localhost:18789/api/stats

{
  "uptime": "3d 14h 22m",
  "totalMessages": 1250,
  "avgLatency": 2100,
  "skillStats": {
    "weather": {
      "invocations": 89,
      "avgLatency": 2340,
      "avgInputTokens": 1250,
      "avgOutputTokens": 245,
      "errorRate": 0.02
    },
    "reminder": {
      "invocations": 156,
      "avgLatency": 1100,
      "avgInputTokens": 890,
      "avgOutputTokens": 120,
      "errorRate": 0.0
    }
  }
}

Token 사용량 최적화

Token 소비는 API 비용에 직접적으로 영향을 미칩니다. 다음은 Token 사용량을 줄이는 실용적인 팁입니다.

SKILL.md 간소화

SKILL.md의 내용은 시스템 프롬프트로 모델에 전송되므로, 파일이 클수록 요청당 Token 비용이 높아집니다.

최적화 전:

## Output Format

当用户查询天气时，你需要以一种美观且信息丰富的方式来呈现天气数据。
首先显示城市名称，然后显示当前的天气状况描述，接着显示温度信息
（包括当前温度和体感温度），再显示湿度和风速信息，
最后如果数据中有日出日落时间的话也一并显示出来。
请确保使用适当的emoji来让信息更加生动...

최적화 후:

## Output Format

🌤️ {城市} | {天气} 🌡️ {温度}°C（体感{体感}°C）| 💧{湿度}% | 💨{风速}m/s

불필요한 컨텍스트 줄이기

{
  context: {
    // 컨텍스트 윈도우 축소
    maxMessages: 20,   // 기본 50에서 20으로 변경
    // Skill 활성화 시 전체 컨텍스트를 포함할지 여부
    skillContext: "minimal"  // minimal은 최근 3개만 유지
  }
}

적합한 모델 선택

모든 시나리오에 가장 강력한 모델이 필요한 것은 아닙니다:

{
  channels: {
    telegram: {
      // 간단한 시나리오에는 소형 모델 사용
      model: {
        provider: "claude",
        name: "claude-haiku-4-20250514"   // 더 빠르고 저렴
      }
    }
  }
}

Skill 로드 순서

여러 Skill의 트리거 키워드가 겹칠 때 로드 순서가 우선순위를 결정합니다.

현재 로드 순서 확인

openclaw skill list --verbose

Skills (loaded in order):
  1. weather        (priority: 10, triggers: 天气,weather,气温)
  2. reminder       (priority: 10, triggers: 提醒,remind,闹钟)
  3. translator     (priority: 5,  triggers: 翻译,translate)
  4. rss-reader     (priority: 5,  triggers: 订阅,新闻,rss)

우선순위 설정

SKILL.md의 frontmatter에서 설정합니다:

---
name: weather
priority: 20    # 숫자가 클수록 우선순위가 높음
triggers:
  - 天气
---

또는 전역 설정에서 재정의합니다:

{
  skills: {
    priority: {
      "weather": 20,
      "reminder": 15,
      "translator": 10
    }
  }
}

성능 최적화 체크리스트

Skill을 배포하기 전에 다음 체크리스트로 최적화합니다:

[ ] SKILL.md 파일 크기가 적절한가 (3KB 미만 권장)
[ ] 트리거 키워드가 정확한가 (오탐 방지)
[ ] MCP 도구 호출 횟수가 최소화되었는가 (불필요한 호출 방지)
[ ] 컨텍스트 윈도우 크기가 적절한가
[ ] 출력 형식이 간결한가
[ ] 시나리오에 적합한 모델을 선택했는가
[ ] 오류 처리가 완벽한가 (재시도 폭주 방지)
[ ] 우선순위 설정이 합리적인가

실용 디버그 명령어 빠른 참조

# 모든 스킬 상태 확인
openclaw skill list

# 실시간 로그 확인
openclaw logs --level debug

# 시스템 상태 점검
openclaw doctor

# 모니터링 대시보드 열기
openclaw dashboard

# 재시작 (새 수정 사항 로드)
openclaw restart

# Gateway API 테스트
curl http://localhost:18789/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "test", "options": {"debug": true}}'

# Gateway 상태 확인
curl http://localhost:18789/health

마무리

효과적인 디버깅과 성능 최적화는 Skill 개발 품질의 보증입니다. 로그 분석, 격리 테스트, Token 최적화, 로드 순서 관리 등의 기법을 습득하면 효율적으로 문제를 진단하고 비용을 최적화하여 고품질의 OpenClaw Skill을 만들 수 있습니다.