Debugging OpenClaw Skills with Logs: A Practical Troubleshooting Guide

When an OpenClaw skill stops working, the logs are your first and best diagnostic tool. Every API call, every skill execution, every error leaves a trace in the logs. The operators who resolve issues quickly are the ones who know how to read that trace.

This guide covers practical log analysis for skill-related problems -- how to access logs across different deployment methods, what the log levels reveal, how to filter for skill-specific issues, and what the most common error messages actually mean.

Accessing OpenClaw Logs by Deployment Method

The way you view logs depends on how you deployed OpenClaw. Here are the commands for every common setup.

Docker Compose (most common):

# Stream all logs in real time
docker compose logs -f openclaw

# Show last 200 lines then stream
docker compose logs -f --tail 200 openclaw

# Show logs from the last hour
docker compose logs --since 1h openclaw

# Show logs with timestamps
docker compose logs -f -t openclaw

# Save logs for offline analysis
docker compose logs openclaw > openclaw-logs.txt 2>&1

Systemd (bare-metal installations):

# Stream logs in real time
journalctl -u openclaw -f

# Show logs from the last hour
journalctl -u openclaw --since "1 hour ago"

# Show only error-level entries
journalctl -u openclaw -p err

Mac app: Logs are written to ~/Library/Logs/OpenClaw/openclaw.log. View them with tail -f ~/Library/Logs/OpenClaw/openclaw.log.

Understanding Log Levels for Skill Debugging

OpenClaw uses four log levels. Choosing the right level for your situation determines whether you see enough information to diagnose the problem.

Set the log level in your .env file:

OPENCLAW_LOG_LEVEL=info    # Default
OPENCLAW_LOG_LEVEL=debug   # For troubleshooting skill issues

Important: DEBUG level logs full API request and response bodies, which can include sensitive data. Never leave DEBUG enabled in production. Use it temporarily to diagnose a specific skill problem, then switch back to INFO or WARN.

After changing the log level, restart OpenClaw:

docker compose restart openclaw

Filtering Logs for Skill Problems

When you have thousands of log lines, targeted filtering saves time. Here are the most useful filter commands for skill-related troubleshooting:

# Find all skill execution logs
docker compose logs openclaw 2>&1 | grep -i "skill"

# Find all errors
docker compose logs openclaw 2>&1 | grep -i "error"

# Find API rate limit issues
docker compose logs openclaw 2>&1 | grep -i "rate.limit"

# Find memory-related operations
docker compose logs openclaw 2>&1 | grep -i "memory"

# Find errors with surrounding context (5 lines before and after)
docker compose logs openclaw 2>&1 | grep -i -B 5 -A 5 "error"

# Count errors by type to find the most frequent problem
docker compose logs openclaw 2>&1 | grep -i "error" | sort | uniq -c | sort -rn

For JSON-formatted logs (set OPENCLAW_LOG_FORMAT=json), use jq for structured analysis:

docker compose logs openclaw 2>&1 | jq -r 'select(.level == "error") | "\(.timestamp) \(.message)"'

Common Skill Errors and What They Mean

Here are the error messages most frequently encountered when running skills from the Bazaar, along with their solutions.

ERROR: Invalid API key for provider anthropic

Your API key is missing, expired, or has a formatting error. Check OPENCLAW_ANTHROPIC_KEY in your .env file for trailing spaces or newline characters. Test the key with a direct curl request to verify it works outside of OpenClaw.

ERROR: Rate limit exceeded (429) -- retrying in 30s

Your AI model provider has temporarily blocked requests because you exceeded usage limits. OpenClaw retries automatically with exponential backoff. If this happens frequently, upgrade your API tier, stagger skill schedules, or enable multi-model routing to distribute load across providers.

WARN: Skill execution timeout after 30s

A skill took longer than the allowed timeout. This usually means an external API the skill depends on is slow or unreachable. Check the target API status. Increase OPENCLAW_SKILL_TIMEOUT if the API is legitimately slow, or contact the skill author about adding error handling.

ERROR: Memory file corrupt: /memory/user_prefs.md

A memory file has invalid formatting, often from an interrupted write. Open the file manually, fix any Markdown syntax issues (the most common cause is a missing --- frontmatter delimiter), and restart OpenClaw.

ERROR: Port 3000 already in use

Another process occupies the same port. Find the conflicting process with lsof -i :3000 and stop it, or change OPENCLAW_PORT to a different value.

ERROR: Out of memory -- process killed

Your server ran out of RAM. OpenClaw typically uses 800MB to 1.5GB. If you are running on a 1GB VPS with multiple skills loaded, this is expected. Upgrade to at least 2GB RAM or reduce the number of active skills to lower memory consumption.

Configuring Log Rotation to Prevent Disk Issues

Docker does not rotate logs by default. Over weeks of running skills, log files can consume gigabytes of disk space. Add rotation to your docker-compose.yml:

services:
  openclaw:
    image: openclaw/openclaw:latest
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

This caps total log storage at about 30MB. When the current log file reaches 10MB, Docker rotates it. The oldest file is deleted when a fourth would be created.

For systemd installations, configure journald limits in /etc/systemd/journald.conf:

[Journal]
SystemMaxUse=100M
MaxRetentionSec=7d

Using the Web UI for Quick Log Checks

OpenClaw's web management UI includes a Monitoring tab showing the last 500 log entries in real time. You can filter by log level, search by keyword, and download displayed logs as a CSV file. Access it at http://your-server:3000/admin/logs.

The web UI is convenient for quick status checks, but for serious debugging sessions -- especially when tracking down intermittent skill failures -- use the command-line tools described above. They give you more control over filtering and context.

A Systematic Debugging Approach for Skill Failures

When a skill from the Bazaar misbehaves, follow this sequence:

1. Check the last 50 log lines for obvious errors: docker compose logs --tail 50 openclaw.
2. Enable DEBUG level temporarily if INFO logs lack detail. Restart, reproduce the issue, then check logs again.
3. Check resource usage. Run docker stats to see CPU and memory consumption. Run df -h to check disk space.
4. Test external dependencies. If the skill calls an external API, verify that API is reachable and responding with curl.
5. Review the .env file. Many failures trace back to environment variable typos -- a missing quote, an extra space, or a wrong variable name.
6. Restart cleanly. Use docker compose down && docker compose up -d for a full restart to clear transient issues.
7. Search the community. The Bazaar skill pages include user comments. Other operators have likely encountered and solved the same error.

When asking for help, always include: your OpenClaw version, the relevant log output (with API keys redacted), your deployment method, and the steps to reproduce the issue.

Browse the Skills Directory

Find the right skill for your workflow. The OpenClaw Bazaar skills directory has over 2,300 community-rated skills -- searchable, sortable, and free to install.

Browse Skills -->

Want a Pre-Built Setup?

If you would rather skip the browsing, OpenClaw personas come with curated skill sets already configured. Pick a persona that matches your role and start working immediately. Compare personas -->