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

よくある原因：

シナリオ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 がトリガーされ、ツールも呼び出されたが、出力フォーマットまたは内容が正しくない。

デバッグ方法：

1. SKILL.md の Output Format の記述が十分に明確か確認する
2. AI モデルが受け取った完全なプロンプトを確認する（verbose ログで確認可能）
3. Output Format にさらに多くの例を追加してみる
4. より安定した出力を得るために temperature を下げることを検討する

パフォーマンス指標の監視

主要パフォーマンス指標

Dashboard または API を通じて以下の指標を監視できます：

# Dashboard を開く
openclaw dashboard

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

ユーザーが天気を問い合わせた際には、天気データを美しく情報豊富な方法で
提示する必要があります。まず都市名を表示し、次に現在の天気状況の説明を
表示し、その後に気温情報（現在の気温と体感温度を含む）を表示し、
さらに湿度と風速の情報を表示し、最後にデータに日の出日没時刻がある場合は
それも表示します。適切な絵文字を使用して情報をより生き生きとさせてください...

最適化後：

## Output Format

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

不要なコンテキストの削減

{
  context: {
    // コンテキストウィンドウを縮小
    maxMessages: 20,   // デフォルトの50から20に変更
    // スキル起動時に完全なコンテキストを含めるかどうか
    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 を構築できます。