Debug OpenClaw: Troubleshoot Logs and Fix Errors Fast

Ever had that moment where your code just stops talking to you? You send a message and wait, but nothing happens. It’s frustrating when things break and you don’t know why.

Debugging doesn’t have to be a headache. I’ll show you how to find logs and fix issues so you can get back to building.

Where does OpenClaw log?

You can find your logs under $OPENCLAW_STATE_DIR/logs. If you’re using the default setup, check ~/.openclaw/logs.

Here are the commands you’ll need to access the directory or read the logs:

# Open logs directory
openclaw logs --path

# Tail live
openclaw logs --follow

# Show last 500 lines
openclaw logs

Logs rotate every day. They also come in JSON format if you prefer structured data for parsing.

How do I read logs in real time?

Watching logs live is the best way to see what’s happening under the hood. You can follow the stream or filter for specific errors using jq.

openclaw logs --follow

# Filter JSON logs
openclaw logs --follow --json | jq 'select(.level == "error")'

A message arrived but no reply was sent. How do I debug?

If your bot goes quiet, follow these steps to find the cause.

1. Watch the live logs to see if the message is being processed:

openclaw logs --follow

2. If you need more detail, restart the gateway in debug mode:

openclaw gateway stop
OPENCLAW_DEBUG=1 openclaw gateway start

3. Verify that your channels are active:

openclaw channels status

4. Check the overall session and model status to ensure everything is online:

   openclaw status
   openclaw models status

Keep an eye out for rate limits or auth errors in the output.

Logs are too spammy or not detailed enough. How do I tune?

You can adjust the verbosity by setting gateway.logLevel. I recommend using debug when you’re fixing bugs and info for normal daily use. You can also use warn or error if you only want to see problems.

{
  gateway: { logLevel: "debug" }
}

The service is not auto-restarting after a crash. What’s wrong?

If the service stays down after a crash, check your service manager configuration. For macOS, ensure KeepAlive is set to true in your launchd config. For Linux, check that systemd is set to Restart=on-failure.

You can verify the status with these commands:

# macOS
launchctl list | grep openclaw

# macOS
launchctl list | grep openclaw

# Linux
systemctl --user status openclaw
journalctl --user -u openclaw -n 100

How do I check Gateway health programmatically?

If you need to monitor the service from another script or tool, use the health endpoint.

curl http://localhost:18789/health

# Or via CLI
openclaw health
openclaw health --json

I accidentally broke something. How do I reset?

We’ve all been there—you change one setting and everything stops working. If you need to start over, use the reset command. You can choose to wipe everything or just clear your current sessions.

# Full reset (wipes config, creds, sessions)
openclaw reset --scope full --yes

# Or just sessions
openclaw reset --scope sessions --yes

After a full reset, you’ll need to run the onboarding process again to get back up and running:

openclaw onboard --install-daemon

How do I report a bug?

If you’ve found a bug that isn’t related to your configuration, let the team know. Follow these steps to provide a helpful report:

1. Reproduce the issue with debug logging enabled.
2. Check the GitHub Issues page for known problems.
3. Gather your environment details like version numbers and OS info.
4. Open a new issue with your log snippets and reproduction steps.

OPENCLAW_DEBUG=1 openclaw gateway restart

Need more help? Try the AI Setup Assistant.

Next Steps

• GitHub Issues
• OpenClaw Status Commands