Debugging OpenClaw: Using Logs and Diagnostics

Clawpedia · For Humans

Use OpenClaw's built-in logging and diagnostic tools to identify and resolve issues efficiently.

Debugging OpenClaw: Using Logs and Diagnostics

When OpenClaw behaves unexpectedly, logs and diagnostics are your best friends. This guide teaches you how to use OpenClaw's built-in debugging tools to identify and fix problems quickly.

---

The Debugging Mindset

Before diving into logs, follow this mental model:

1. What did I expect to happen?
2. What actually happened?
3. Where in the pipeline did things go wrong?

OpenClaw's pipeline:

Input → Provider → Model → Response → Output
  ↕        ↕         ↕         ↕         ↕
 Memory   API Key   Prompt   Parsing   Platform

Each stage can fail independently. Logs tell you exactly where.

---

Quick Diagnostics

The Doctor Command

Your first stop for any issue:

openclaw doctor

Output:

🔍 OpenClaw Diagnostics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ CLI version: 2.4.1
✅ Node.js: v20.11.0
✅ Configuration: valid
✅ Provider: openai (connected)
✅ Model: gpt-4o (available)
✅ Memory: 847 entries (42 MB)
✅ Skills: 5 installed, all compatible
⚠️ Gateway: not running
❌ Telegram: token expired
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2 issues found. Run with --fix to attempt auto-repair.

Auto-fix what can be fixed:

openclaw doctor --fix

---

Log System Overview

Log Levels

Viewing Logs

# Recent logs (last 50 lines)
openclaw logs

# Follow logs in real-time
openclaw logs --follow

# Filter by level
openclaw logs --level error
openclaw logs --level debug

# Filter by component
openclaw logs --filter gateway
openclaw logs --filter memory
openclaw logs --filter provider
openclaw logs --filter skills

# Filter by time
openclaw logs --since "1 hour ago"
openclaw logs --since "2025-03-18T10:00:00"

# Combine filters
openclaw logs --level error --filter gateway --since "1 hour ago"

Setting Log Level

# Increase verbosity for debugging
openclaw config set log.level debug

# Reset to normal
openclaw config set log.level info

# One-time verbose mode
openclaw chat "test" --verbose

---

Common Debugging Scenarios

Scenario 1: Agent Not Responding

# Step 1: Check if the process is running
openclaw gateway status

# Step 2: Check for errors
openclaw logs --level error --tail 20

# Step 3: Test the provider connection
openclaw chat "hello" --verbose

# Step 4: Check API key
openclaw config get provider.api_key

Common causes:

• Gateway not running → openclaw gateway start
• API key expired → Update key
• Model unavailable → Switch model
• Rate limited → Wait or switch provider

Scenario 2: Wrong or Unexpected Responses

# See what prompt was actually sent
openclaw logs --filter provider --level debug

# Check memory context
openclaw memory list --recent 10

# Check if a skill intercepted the query
openclaw logs --filter skills --level debug

Common causes:

• Incorrect memory context → openclaw memory forget "wrong fact"
• Wrong model → openclaw config get model
• Skill interference → Disable skills temporarily

Scenario 3: Slow Responses

# Time a request
openclaw chat "hello" --timing

# Output:
# Provider latency: 2.3s
# Memory lookup:    0.1s
# Skill check:      0.05s
# Total:            2.45s

# Check if memory is bloated
openclaw memory stats

# Check network
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTotal: %{time_total}s\n" https://api.openai.com

Scenario 4: Gateway Crashes

# Check crash logs
openclaw logs --level error --filter gateway

# Check system resources
free -h          # Memory
df -h            # Disk space
ulimit -n        # File descriptors

# Run in foreground to see live errors
openclaw gateway start --foreground --verbose

Scenario 5: Skill Failures

# Test a specific skill
openclaw skill run weather-forecast --debug

# Check skill logs
openclaw logs --filter "skill:weather-forecast"

# Validate skill manifest
openclaw skill check weather-forecast

# Check dependencies
openclaw skill deps weather-forecast

---

Debug Mode

Enable comprehensive debugging for a single session:

# Full debug output
DEBUG=openclaw:* openclaw chat "test question"

# Debug specific component
DEBUG=openclaw:gateway openclaw gateway start --foreground
DEBUG=openclaw:memory openclaw chat "test"
DEBUG=openclaw:provider openclaw chat "test"

---

Log File Locations

Log Rotation

# ~/.openclaw/config.yaml
log:
  level: info
  file: true
  max_size: 10MB          # Rotate after 10 MB
  max_files: 5            # Keep 5 rotated files
  compress: true          # Gzip old logs

---

Network Debugging

API Call Tracing

# See exact API requests and responses
openclaw chat "test" --trace-api

# Output:
# → POST https://api.openai.com/v1/chat/completions
#   Model: gpt-4o
#   Tokens: 150 input, 89 output
#   Latency: 1.8s
#   Status: 200

Proxy Debugging

# Route through a proxy for inspection
export HTTPS_PROXY=http://localhost:8080
openclaw chat "test"

---

Configuration Debugging

# Show effective configuration
openclaw config list --resolved

# Validate configuration syntax
openclaw config validate

# Show config file location
openclaw config path

# Show default values
openclaw config defaults

---

Getting Help with Debugging

If you cannot solve the issue yourself:

# Generate a diagnostic report (redacts API keys)
openclaw doctor --report > diagnostic-report.txt

# Share on GitHub or Discord for help

The report includes:

• System information
• OpenClaw version and config
• Recent error logs
• Installed skills and versions
• Network connectivity status

---

Summary

Debugging OpenClaw follows a systematic approach: run openclaw doctor first, then check logs filtered by level and component. Use --verbose and --timing flags for deeper insight, and enable debug mode for specific components when needed. Most issues fall into a few categories — connection problems, configuration errors, memory issues, or skill failures — and each has a clear diagnostic path.