OpenClawSkills
GitHub
Gateway & Ops • TutorialHeader.readTime

Troubleshooting

Quick troubleshooting guide for common OpenClaw failures

When OpenClaw misbehaves, use this checklist to quickly isolate and fix the issue.

If you only want the shortest triage flow, see the FAQ’s first 60 seconds. This page goes deeper: runtime failures, diagnostics, and common pitfalls.

Channel-specific shortcuts: /channels/troubleshooting

Tutorial.step

Status & Diagnostics

Quick triage checkpoints:

  • Gateway file logs (structured): /tmp/openclaw/openclaw-YYYY-MM-DD.log (or logging.file).
  • Gateway service logs (supervisor):

    macOS: $OPENCLAW_STATE_DIR/logs/gateway.log + gateway.err.log (default ~/.openclaw/logs/...; profiles use ~/.openclaw-<profile>/logs/...).

    Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager

    Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

  • Session files: $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/
  • Media cache: $OPENCLAW_STATE_DIR/media/
  • Credentials: $OPENCLAW_STATE_DIR/credentials/
Tutorial.step

Health Check

Bash
openclaw gateway status

openclaw gateway status --deep


openclaw health --json

openclaw health --verbose


lsof -nP -iTCP:18789 -sTCP:LISTEN


openclaw logs --follow

tail -20 /tmp/openclaw/openclaw-*.log
Tutorial.step

Full Reset

Nuclear option:

Bash
openclaw gateway stop



trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # Re-pair WhatsApp
openclaw gateway restart           # Or: openclaw gateway

Warning: This deletes all sessions and you will need to re-pair WhatsApp.

Tutorial.step

Getting Help

  1. Check logs first: by default in /tmp/openclaw/ (openclaw-YYYY-MM-DD.log or your configured logging.file).
  2. Search existing GitHub issues.
  3. When opening a new issue, include:
    • OpenClaw version
    • Relevant log snippets
    • Steps to reproduce
    • Your configuration (redact secrets!)

"Have you tried turning it off and on again?" — every IT person

Tutorial.step

Browser won't start (Linux)

If you see "Failed to start Chrome CDP on port 18800":

Most likely cause: On Ubuntu, you are using the Snap-packaged Chromium.

Quick fix: install Google Chrome:

Bash
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

And set in config:

Json
{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

Full guide: see /reference/tools/browser-linux-troubleshooting