OpenClaw Logs: How to View, Debug, and Troubleshoot [2026]

How to View OpenClaw Logs

The method for viewing logs depends on how you deployed OpenClaw. Most operators use Docker, but there are other methods too.

Docker Compose (most common):

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

# Show last 200 lines and 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 to a file for 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 logs from today only
journalctl -u openclaw --since today

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

Mac app: If you are using the OpenClaw Mac application, logs are written to ~/Library/Logs/OpenClaw/openclaw.log. You can view them with tail -f ~/Library/Logs/OpenClaw/openclaw.log or open them in Console.app.

Understanding Log Levels

OpenClaw uses four log levels, from least verbose to most verbose:

Set the log level in your .env file:

# In your .env file
OPENCLAW_LOG_LEVEL=info    # Default
OPENCLAW_LOG_LEVEL=debug   # For troubleshooting

Warning: The DEBUG level logs full API request and response bodies, which can include sensitive data like message content and API keys in headers. Never leave DEBUG enabled in production. Use it temporarily for troubleshooting, then switch back to INFO or WARN.

After changing the log level, restart OpenClaw for the change to take effect:

docker compose restart openclaw

Filtering and Searching Logs

When you have thousands of log lines, filtering is essential. Here are the most useful filtering commands:

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

# Find all warnings and errors
docker compose logs openclaw 2>&1 | grep -iE "(error|warn)"

# Find WhatsApp-related entries
docker compose logs openclaw 2>&1 | grep -i "whatsapp"

# 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 skill execution logs
docker compose logs openclaw 2>&1 | grep -i "skill"

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

# Count errors by type
docker compose logs openclaw 2>&1 | grep -i "error" | sort | uniq -c | sort -rn

For more advanced analysis, pipe logs to jq if your OpenClaw is configured to output JSON-formatted logs (set OPENCLAW_LOG_FORMAT=json):

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

Common Errors and What They Mean

Here are the most frequently encountered OpenClaw log errors and how to fix them:

1. ERROR: Invalid API key for provider anthropic

Your Anthropic API key is either missing, expired, or formatted incorrectly. Check OPENCLAW_ANTHROPIC_KEY in your .env file. Ensure there are no trailing spaces or newline characters. Test the key with a direct curl request to verify it works.

2. ERROR: Rate limit exceeded (429) — retrying in 30s

You are hitting the AI model provider's rate limit. This is usually temporary. OpenClaw has built-in retry logic with exponential backoff. If this happens frequently, consider upgrading your API tier, switching to a model with higher rate limits, or enabling multi-model routing to distribute load.

3. WARN: WhatsApp connection lost — reconnecting

The WhatsApp Web bridge connection dropped. This happens occasionally and OpenClaw auto-reconnects. If it happens repeatedly, check your network stability, verify the WhatsApp session is still valid, and ensure no other process is using the same WhatsApp session.

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

A memory file has invalid formatting. This can happen if a write was interrupted. Open the file manually, fix any Markdown syntax issues, and restart OpenClaw. The most common cause is a missing frontmatter delimiter (the --- at the top of the file).

5. ERROR: Port 3000 already in use

Another process is using the same port. Either stop the conflicting process (lsof -i :3000 to find it) or change OPENCLAW_PORT to a different value.

6. WARN: Skill execution timeout after 30s

A skill took longer than the allowed timeout. This usually means an external API the skill calls is slow or down. Check the skill's target API, increase OPENCLAW_SKILL_TIMEOUT if the API is legitimately slow, or add error handling to the skill.

7. ERROR: Out of memory — process killed

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

Configuring Log Rotation

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

services:
  openclaw:
    image: openclaw/openclaw:latest
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"
    # ... rest of your config

This configuration keeps a maximum of 3 log files, each up to 10MB, for a total maximum of 30MB. When the current log file reaches 10MB, Docker rotates it and starts a new one. The oldest file is deleted when a fourth would be created.

For systemd installations, log rotation is handled by journald. You can configure maximum disk usage in /etc/systemd/journald.conf:

[Journal]
SystemMaxUse=100M
MaxRetentionSec=7d

Logs in the Web UI

OpenClaw's web-based management UI includes a Monitoring tab that shows recent log entries. This is useful for quick checks without SSH access. The web UI shows the last 500 log entries by default and updates in real time.

You can filter by log level, search by keyword, and download the displayed logs as a CSV file. The web UI is accessible at http://your-server:3000/admin/logs (or whatever port you configured).

Keep in mind that the web UI log viewer is not a replacement for command-line log analysis. For serious debugging sessions, use the Docker or systemd commands described above. The web UI is best for quick status checks and sharing log snippets with others.

Debugging Tips

When something goes wrong with your OpenClaw deployment, follow this systematic approach:

1. Check the logs first. 90% of issues are visible in the logs. Start with docker compose logs --tail 50 openclaw to see recent entries.
2. Enable DEBUG level temporarily. If the INFO logs do not show enough detail, set OPENCLAW_LOG_LEVEL=debug, restart, reproduce the issue, then check logs again.
3. Check resource usage. Run docker stats to see if OpenClaw is running out of CPU or memory. Run df -h to check disk space.
4. Test external connections. If the issue involves an integration, test the external service directly. Can you reach the WhatsApp API? Is the Anthropic API responding? Use curl to test endpoints.
5. Check the .env file. Many issues trace back to environment variable typos. A missing quote, an extra space, or a wrong variable name can cause silent failures.
6. Restart cleanly. Sometimes a clean restart resolves transient issues. Use docker compose down && docker compose up -d for a full restart.
7. Search the community. The OpenClaw Skool community and GitHub Issues are searchable. Someone has likely encountered your error before.

For persistent issues that you cannot resolve from logs alone, the community is your best resource. When posting for help, always include: your OpenClaw version (openclaw --version), the relevant log output (with any API keys redacted), your deployment method (Docker, systemd, Mac app), and the steps to reproduce the issue.