Quick Diagnostics

When something goes wrong with OpenClaw, run through this flow first. It takes about two minutes and often pinpoints the issue or tells you which topic page to open next.

Run openclaw doctor first. The doctor command checks gateway health, config, paths, and common issues. Many problems are reported there with hints. If the command is not found, fix your installation and PATH before continuing.

Quick diagnostic commands

Run these in order. Copy and paste into your terminal (macOS/Linux or WSL on Windows):

# 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

Common command reference

Quick reference for what each command does:

Command	Purpose
`openclaw doctor`	Run first. Checks configuration, gateway, paths, and common issues; reports hints for many errors.
`openclaw doctor --fix`	Apply fixable items (e.g. permissions, missing dirs). Prefer in dev/test; in production, review suggested fixes before applying.
`openclaw status`	Shows whether the gateway is running and which config path is in use.
`openclaw status --all`	Extended status (channels, agents, etc.).
`openclaw gateway probe`	Tests that the CLI can reach the gateway (URL/port and token).
`openclaw logs --tail 50`	Print the last 50 log lines.
`openclaw logs --follow`	Stream logs live while you reproduce the issue.
`openclaw config validate`	Validates your config file and reports schema/key errors.

Emergency restart

If the gateway is stuck or unresponsive:

Run openclaw stop and wait a few seconds.
Run openclaw start.

Prefer this over killing the process by hand so the PID file is cleared correctly. If you must kill the process, remove the PID file in the path shown by openclaw doctor before starting again. See Gateway issues for more.

Log file locations

Logs are typically under your OpenClaw data directory (e.g. ~/.openclaw on macOS/Linux, or the path shown by openclaw doctor). You don't need to hunt for files: use openclaw logs --tail 50 or openclaw logs --follow to view logs from the CLI.

Common issues & where to look

Use this table to match what you see to the right guide. After running openclaw doctor and the commands above, follow the linked page for step-by-step fixes.

Symptom	Likely cause	What to do
Gateway won't start	Port in use, bad config, or bind address	Check port with `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. 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; run `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 / gateway 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.

Step-by-step debugging flow

Run openclaw doctor - Review output for gateway, config, and path issues.
Check status: openclaw status and openclaw status --all.
Probe gateway: openclaw gateway probe.
Review logs: openclaw logs --follow while you reproduce the issue.
Validate config: openclaw config validate.
Clean restart: openclaw stop, then openclaw start.

Troubleshooting topics

If the quick flow above doesn't fix it, jump to the guide that matches your issue:

Troubleshooting guide - Hub with full command list and common-issues table
Installation errors - "openclaw command not found", Node version, PATH, permissions
Gateway issues - Gateway won't start, PID lock, unauthorized, RPC probe failures
Channel errors - Telegram, WhatsApp, Discord, Slack connection and permission problems
Configuration problems - Config validation failed, session path violations, schema errors
Model & API errors - Rate limits, billing, API key invalid, timeouts
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

Getting help

If you're still stuck after running the diagnostics and checking the topic pages:

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.