OpenClaw Troubleshooting Guide

When OpenClaw doesn’t start, drops connections, or shows errors, this hub points you to the right fix. Start with the Quick Diagnostic below (run openclaw doctor first), then use the topic links or the common-issues table to find step-by-step solutions.

Run openclaw doctor first. The doctor command checks gateway health, config, paths, and common issues. Many problems are reported there with hints. See Quick diagnostics for the full flow.

Quick Diagnostic

Use these commands in order to narrow down the issue:

# 1. Full health check (do this first)
openclaw doctor

# 2. Apply automatic fixes where safe (dev/test; use with care in production)
openclaw doctor --fix

# 3. Check gateway and service status
openclaw status
openclaw status --all

# 4. Test gateway connectivity (RPC probe)
openclaw gateway probe

# 5. View logs (recent or live)
openclaw logs --tail 50
openclaw logs --follow

# 6. Validate configuration
openclaw config validate

Emergency restart: If the gateway is stuck, run openclaw stop, wait a few seconds, then openclaw start. Do not kill the process by hand unless necessary-prefer a clean stop so the PID file is cleared.

Log file locations: Logs are typically under your OpenClaw data directory (e.g. ~/.openclaw or the path shown by openclaw doctor). Use openclaw logs --tail 50 or openclaw logs --follow to view them without hunting for files.

Troubleshooting Topics

Jump to the guide that matches your issue:

  • Quick diagnostics - Run openclaw doctor and basic checks in under 2 minutes
  • Installation errors - "openclaw command not found", Node version, PATH, permissions, npm install failures
  • Gateway issues - Gateway won't start, PID lock, unauthorized, RPC probe failures, token mismatch
  • Channel errors - Telegram, WhatsApp, Discord, Slack connection and permission problems
  • Configuration problems - Config validation failed, session path violations, schema errors, agent config moved
  • Model & API errors - Rate limits, billing, API key invalid, timeouts, provider unreachable
  • Skills issues - Skill install/load failures, credential leaks, security audit
  • Performance problems - High memory, slow response, gateway crashes, log bloat
  • Error code reference - Look up error messages and codes with solutions

Common Issues & Solutions

Quick reference. For full steps, follow the linked topic pages.

Symptom Likely Cause Solution
Gateway won't start Port in use, bad config, or bind address lsof -i :3000 (or your port). Bind to 127.0.0.1 only. See Gateway issues and Security best practices.
"openclaw command not found" PATH or install path Ensure OpenClaw install dir is on PATH, or use full path. See Installation errors and Installation guide.
Agent not responding API key invalid, gateway down, or channel misconfigured Run openclaw doctor and openclaw status. Verify API key and channel config. See Model & API errors and Channel errors.
Config validation failed Wrong key, typo, or schema Run openclaw config validate and openclaw doctor. Fix reported key or syntax. See Configuration problems and Config file structure.
Channel connection failures Token, permissions, or gateway Check channel block and credentials; openclaw config validate and openclaw doctor. See Channel errors and Channel setup.
Rate limit / billing errors API quota or billing Check provider dashboard and spending limits. See Model & API errors.
High memory / crashes Insufficient RAM or leak Ensure 4GB+ RAM for typical setups. Check openclaw logs for OOM. See Performance problems.
Skill won't load Path, version, or dependency Check skill path in config; openclaw logs --tail 50 for load errors. See Skills issues and Installing skills.

Using Diagnostic Commands

  • openclaw doctor - Run first. It checks configuration, gateway, paths, and common issues. Many errors are reported here with hints.
  • openclaw doctor --fix - Use when doctor reports fixable items (e.g. permissions, missing dirs). Prefer in dev/test; in production, review suggested fixes before applying.
  • openclaw status / openclaw status --all - See whether the gateway is running and which config path is in use.
  • openclaw logs --follow - Stream logs while you reproduce the issue to capture the exact error.
  • openclaw gateway probe - Test that the CLI can reach the gateway (URL/port and token).

For a full walkthrough, see Quick diagnostics.

Step-by-Step Debugging

  1. Run openclaw doctor - Review output for gateway, config, and path issues.
  2. Check status: openclaw status and openclaw status --all.
  3. Probe gateway: openclaw gateway probe.
  4. Review logs: openclaw logs --follow while reproducing the issue.
  5. Validate config: openclaw config validate.
  6. Clean restart: openclaw stop, then openclaw start.

Getting Help

If you're still stuck after using this guide:

  • Quick diagnostics - Run through the checklist and capture output.
  • Discord community - Ask for help; include OpenClaw version, openclaw doctor output (redact paths if sensitive), and relevant log lines.
  • GitHub issues - Search existing issues or open a new one with the same details.
  • Official documentation - Install, config, and channel docs for your version.

When reporting: Always include OpenClaw version, output of openclaw doctor, relevant log lines, and config (with API keys and tokens removed). Safe report generation tools may be available in your setup.