The first 60 seconds
Run these in order. Stop at the first one that looks wrong. That's where your problem is.
openclaw statusChannels are listed, with no auth errorsopenclaw gateway statusRuntime: runningandConnectivity probe: okopenclaw gateway probeReachable: yesopenclaw doctorNo blocking config or service errorsopenclaw channels status --probeEach account showsworksoraudit okopenclaw logs --followSteady activity, with no repeating fatal errors. Now reproduce the problem.
openclaw status
openclaw gateway status
openclaw gateway probe
openclaw doctor
openclaw channels status --probe
openclaw logs --followFind your problem
Pick what's going wrong to see the commands to run, what "good" looks like, and the usual fixes.
Error message lookup
Paste part of an error or log line to find what it means.
| Message | What it means | What to do |
|---|
Using openclaw doctor
openclaw doctor checks the gateway, channels, plugins, skills, model routing, local state and config migrations, then explains what's wrong. Run it whenever something misbehaves, and always after an update.
| Command | What it does |
|---|---|
openclaw doctor | Guided checks, with prompts before changes |
openclaw doctor --fix | Applies supported repairs, asking first unless it's safe not to |
openclaw doctor --fix --non-interactive | Applies only the repairs that are safe without prompts |
openclaw doctor --deep | Adds deeper checks |
openclaw doctor --json | A read-only report for scripts |
openclaw doctor --lint | Read-only findings that exit with an error code, for CI |
Run openclaw doctor --fix. It migrates old config such as legacy model names and auth profiles. If it's still broken, see update and back up for rolling back.
AI-assisted triage
openclaw triage collects sanitized diagnostics: version, platform, Node.js, doctor findings and a support archive. It then opens a coding agent already on your machine, such as Codex or Claude Code, to diagnose, repair and verify your install.
openclaw triage # start the first coding agent found
openclaw triage --agent codex # choose one
openclaw triage --non-interactive # just collect the diagnosticsA repair agent can edit your config and run commands. Some, such as Kimi Code's prompt mode, run with automatic permissions, and triage prints that policy first. Review its changes, and back up ~/.openclaw before you start.
Getting help safely
- Make a shareable report:
openclaw status --allredacts secrets, so it's safe to paste. Don't paste raw config files or logs. - Note your setup: the OpenClaw version (
openclaw --version), your OS, how you installed it, and which channel and model you use. - Search first: the official troubleshooting docs and GitHub issues.
- Never share your gateway token, API keys, WhatsApp credentials or
~/.openclawfolder. Real maintainers won't ask for them.
Think something was compromised? Follow the incident steps first.
Fixes by platform and app
OpenClaw troubleshooting questions
Why isn't OpenClaw replying to my messages?
Usually the sender hasn't been approved through pairing, a group message didn't mention the bot, or the gateway isn't running. Run openclaw gateway status, then openclaw pairing list --channel followed by the channel name, and watch openclaw logs --follow while you send a test message.
How do I fix "openclaw: command not found"?
It's almost always a PATH issue: npm's global bin directory isn't on your shell's PATH. Add it to PATH or reinstall with the official installer script, then open a new terminal. Also check that Node.js is 24.16 or newer, or 26.1 or newer.
What does openclaw doctor --fix do?
It runs OpenClaw's health checks and applies the supported repairs, such as config migrations, service and token repairs and legacy model reference fixes. It asks before changes unless they're safe to apply automatically.
Why does the gateway say the port is already in use?
Another gateway instance or another program is already using port 18789, shown as EADDRINUSE. Stop the other instance, or check openclaw gateway status for a service that's already running.
Why does OpenClaw suddenly ask me to approve commands?
A host-level or per-session policy has made exec stricter than the defaults, or a sandbox setting changed. Check tools.exec.security and tools.exec.ask with openclaw config get. Approvals are the safer setting, so consider keeping them.
How do I share my OpenClaw logs safely?
Use openclaw status --all, which produces a shareable report with secrets redacted. Don't post raw config files, tokens or API keys.