Managing OpenClaw Logs and Debugging Output
Clawpedia · For Humans
Learn to read, filter, and analyze OpenClaw logs to diagnose issues and optimize agent performance.
Overview
Effective logging and debugging are essential for diagnosing issues with your OpenClaw agent quickly. This article covers log configuration, the different log levels, output formats, log rotation, and practical debugging techniques that will save you hours of troubleshooting.
Log Levels
OpenClaw uses five standard log levels, ordered from most to least verbose:
| Level | Description | When to Use |
|---|
debug | Detailed internal state, API payloads, memory lookups | Deep troubleshooting |
|---|
info | Normal operations: startup, shutdown, skill loading | Default for production |
|---|
warn | Non-critical issues: slow responses, retry attempts | Monitoring |
|---|
error | Failures: API errors, skill crashes, connection drops | Always enabled |
|---|
fatal | Unrecoverable errors that cause the agent to stop | Always enabled |
|---|
Tip: Use
debugonly during active troubleshooting. It generates significantly more output and can impact performance.
Log Output Destinations
Logs can be directed to multiple destinations simultaneously:
logging:
level: info
outputs:
console:
enabled: true
format: pretty # pretty | json | compact
colors: true
file:
enabled: true
path: ~/.openclaw/logs/agent.log
format: json
max_size: 50MB
max_files: 10
syslog:
enabled: false
address: localhost:514
| Destination | Best For |
|---|
| Console | Development and interactive debugging |
|---|
| File | Production logging and post-mortem analysis |
|---|
| Syslog | Integration with centralized log management |
|---|
A typical log entry in pretty format:
2024-01-15 09:32:14 [INFO] agent.core Agent started successfully (PID: 48291)
2024-01-15 09:32:14 [INFO] skills.loader Loaded 12 skills in 340ms
2024-01-15 09:32:15 [INFO] platform.tg Connected to Telegram (bot: @my_claw_bot)
2024-01-15 09:32:45 [DEBUG] model.openai Request: {model: gpt-4o, tokens: 2340, temp: 0.7}
2024-01-15 09:32:47 [DEBUG] model.openai Response: 1205 tokens in 1.8s ($0.0042)
2024-01-15 09:33:01 [WARN] memory.store Memory near capacity (89% used, 445/500 MB)
2024-01-15 09:35:22 [ERROR] skill.calendar Failed to sync: 401 Unauthorized
Log Entry Components
| Component | Example | Description |
|---|
| Timestamp | 2024-01-15 09:32:14 | When the event occurred |
|---|
| Level | [INFO] | Severity level |
|---|
| Source | agent.core | Module that generated the log |
|---|
| Message | Agent started successfully | Human-readable description |
|---|
| Context | (PID: 48291) | Additional structured data |
|---|
Prevent logs from filling up your disk:
logging:
file:
path: ~/.openclaw/logs/agent.log
max_size: 50MB # Rotate when file exceeds this size
max_files: 10 # Keep up to 10 rotated files
max_age: 30d # Delete files older than 30 days
compress: true # Gzip rotated files
Rotated files are named agent.log.1, agent.log.2, etc. With compress: true, they become agent.log.1.gz.
Module-Specific Logging
Enable debug logging for specific modules without flooding the log:
logging:
level: info # Default level
modules:
model: debug # Debug AI model interactions
skills: debug # Debug skill execution
memory: warn # Only warnings for memory
platform: info # Normal platform logging
# CLI shorthand
openclaw config set logging.modules.model debug
openclaw config set logging.modules.skills debug
This is extremely useful when you know which subsystem is causing problems.
Debugging Techniques
1. The Doctor Command
Always start here. It checks all components automatically:
openclaw doctor --all
Output:
✅ Configuration: Valid
✅ API Keys: OpenAI (valid), Anthropic (valid)
✅ Model: gpt-4o responding (latency: 230ms)
✅ Memory: Healthy (445/500 MB)
✅ Skills: 12/12 loaded
⚠️ Platform: Telegram connected, Slack disconnected
❌ Disk: Log directory >1 GB — consider rotation
2. Dry-Run Mode
Test configuration changes without affecting the live agent:
openclaw start --dry-run
This validates the config, checks connections, and reports what would happen — without actually starting.
3. Request Tracing
Trace a single request through the entire pipeline:
openclaw ask "What's the weather?" --trace
Trace output shows every step:
[TRACE] Input received: "What's the weather?"
[TRACE] Memory lookup: 3 relevant entries found (12ms)
[TRACE] Skill match: weather-forecast (confidence: 0.94)
[TRACE] Skill execution: weather-forecast (started)
[TRACE] API call: wttr.in/Berlin (200 OK, 89ms)
[TRACE] Skill execution: weather-forecast (completed, 102ms)
[TRACE] Model request: gpt-4o (2140 tokens)
[TRACE] Model response: 380 tokens (1.2s, $0.0031)
[TRACE] Total pipeline: 1.4s
4. Skill Debugging
Run a specific skill in isolation:
# Test a skill directly
openclaw skills test weather-forecast --input "Weather in Berlin"
# Run with debug output
openclaw skills test weather-forecast --input "Weather in Berlin" --debug
5. Memory Inspection
# Search what the agent remembers
openclaw memory search "user preferences"
# View recent memory entries
openclaw memory recent --last 20
# Check memory statistics
openclaw memory stats
Common Log Patterns and Solutions
| Log Pattern | Likely Cause | Solution |
|---|
429 Too Many Requests | Rate limit hit | Add fallback model or reduce request frequency |
|---|
Connection refused | Platform bot offline | Check bot token and platform status |
|---|
Skill timeout after 30s | Slow external API | Increase skill timeout or add caching |
|---|
Memory full | Storage limit reached | Run openclaw memory prune |
|---|
Invalid model | Typo in model name | Check with openclaw models list |
|---|
ECONNRESET | Network instability | Check firewall, proxy, or VPN settings |
|---|
For production environments, use JSON logging for easy parsing:
logging:
file:
format: json
JSON log entries can be ingested by tools like Elasticsearch, Datadog, or Grafana Loki:
{
"timestamp": "2024-01-15T09:32:47Z",
"level": "info",
"module": "model.openai",
"message": "Request completed",
"model": "gpt-4o",
"tokens_in": 2340,
"tokens_out": 1205,
"latency_ms": 1800,
"cost_usd": 0.0042
}
Troubleshooting
Logs Are Empty
- Check that the agent is running:
openclaw status. - Verify the log file path:
openclaw config get logging.file.path. - Ensure write permissions on the log directory.
Logs Are Too Verbose
Raise the log level: openclaw config set logging.level warn.
Log File Is Growing Too Fast
Enable rotation and set max_size and max_files as shown above. Also ensure debug level is not active in production.
Next Steps
- Learn more CLI commands in OpenClaw CLI: Essential Commands and Options.
- Explore skill debugging in Testing and Debugging OpenClaw Skills.
- Set up monitoring with OpenClaw for DevOps: Managing Servers and Services.
Source: Clawpedia — https://clawpedia.io/article/managing-openclaw-logs-and-debugging-output. If you reuse or quote this article, please credit Clawpedia with a link.
Related Articles
- Debugging OpenClaw: Using Logs and Diagnostics — Use OpenClaw's built-in logging and diagnostic tools to identify and resolve issues efficiently.
- Managing Long-Term Memory in Your OpenClaw Assistant — Configure and optimize long-term memory to make your OpenClaw agent smarter over time.
- Debugging Unwanted Behavior: When Prompts Go Wrong — Diagnose and fix unexpected agent behavior caused by ambiguous, conflicting, or poorly structured prompts.
- Testing and Debugging OpenClaw Skills — Write tests and debug your OpenClaw skills systematically to ensure reliable agent behavior.
- AI Agent Monitoring and Observability: A Production Guide — Master AI agent monitoring and observability in production. Learn best practices and tools for 2026 to ensure reliability and performance.