OpenClaw Debugging Guide: Reading Logs and Fixing Issues

OpenClaw debug logs are the most powerful diagnostic tool for troubleshooting agent issues. Whether your agent is giving unexpected responses, failing to execute skills, or losing connection to channels, the logs tell you exactly what happened. This guide teaches you how to read and use OpenClaw's logging system.

Log Locations

By default, OpenClaw logs to:

• Standard output: When running manually (python -m openclaw start)
• ~/.openclaw/openclaw.log: Main application log
• ~/.openclaw/audit.log: Skill call audit log (if enabled)
• journalctl -u openclaw: When running as a systemd service

Log Levels

Configure in openclaw.json:

{
  "logging": {
    "level": "info",
    "file": "~/.openclaw/openclaw.log",
    "max_size_mb": 100,
    "backup_count": 5
  }
}

Levels: debug > info > warning > error > critical

Use debug for troubleshooting, info for normal operation, error for production (minimal noise).

Reading LLM Request/Response Logs

In debug mode, every LLM API call is logged:

2026-05-07 10:23:15 DEBUG [llm.anthropic] Request: model=claude-3-5-sonnet, tokens=1247
2026-05-07 10:23:17 DEBUG [llm.anthropic] Response: tokens=342, cost=$0.0042

This helps identify:

• Which messages are expensive (high token counts)
• Slow responses (large time gaps between request/response)
• API errors (error-level log entries)

Reading Skill Call Logs

2026-05-07 10:23:17 INFO [skills.web-search] Tool called: search_web(query="OpenClaw latest news")
2026-05-07 10:23:19 INFO [skills.web-search] Tool completed: search_web -> 5 results, 2.1s

If a skill fails:

2026-05-07 10:23:17 ERROR [skills.google-calendar] Tool failed: create_event
  Exception: google.auth.exceptions.RefreshError: Token has been expired

This tells you the Google Calendar skill's OAuth token needs re-authorization.

Common Error Patterns

rate_limit_error: You're hitting your LLM provider's rate limit. Wait and retry, or upgrade your API tier.

context_length_exceeded: Your conversation context is too long for the model. Reduce max_tokens in context or enable context truncation.

connection_refused on startup: OpenClaw's web port is already in use. Check for another OpenClaw process or change the port.

SkillPermissionError: A skill tried to use a permission not in your tools.allow. Either add the permission or use a different skill.

Tail Logs in Real-Time

# Follow the log file
tail -f ~/.openclaw/openclaw.log

# Follow systemd journal
journalctl -u openclaw -f

# Filter for errors only
journalctl -u openclaw -f | grep -E "ERROR|CRITICAL"

nacre.sh Log Access

nacre.sh provides log access through the web terminal and a dedicated Logs section in the dashboard. Filter by log level, date range, and component.

Frequently Asked Questions

How do I check if a specific skill is causing problems?

Enable debug logging and reproduce the issue. Look for log entries from [skills.SKILL-NAME]. You can also temporarily disable suspect skills and test.

Can I set up alerts for error-level logs?

Yes. OpenClaw supports a webhook notification configuration that can POST error-level log events to a Slack channel, Discord webhook, or any HTTP endpoint.

What's the difference between openclaw.log and audit.log?

openclaw.log contains all application events. audit.log records specifically which tools were called with what parameters — useful for security review and debugging agent decision-making.