| name | openclaw-troubleshooting |
| description | Use when OpenClaw is not working, the gateway is not responding, the user wants to run openclaw doctor, debug OpenClaw, view openclaw logs, a channel is not responding, messages are not being delivered, the dashboard shows errors, or cron/heartbeat jobs are failing.
|
OpenClaw Troubleshooting
Diagnose and fix common OpenClaw issues using a systematic command ladder.
Diagnostic Command Ladder
Run these in order for initial triage:
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
Healthy signals:
openclaw gateway status shows Runtime: running and RPC probe: okopenclaw doctor reports no blocking issuesopenclaw channels status --probe shows channels connected
Decision Tree
Gateway not responding?
openclaw status - is it running?openclaw gateway status - check runtime stateopenclaw logs --follow - look for errors- Common causes: port conflict (
EADDRINUSE), missing auth on non-loopback bind, gateway.mode not set to "local"
No replies from bot?
openclaw channels status --probe - channels connected?openclaw pairing list <channel> - pending pairing requests?- Check
dmPolicy and allowFrom in config
- For groups: check
requireMention and groupPolicy
Dashboard 1008 / Unauthorized?
openclaw gateway status - verify gateway is runningopenclaw config get gateway.auth.token - check token- Verify URL and auth mode match between client and gateway
- For device auth errors: update connecting client
Channel connected but silent?
- Check
dmPolicy (pairing/allowlist/open/disabled)
- Check
groupPolicy and requireMention
- Check channel-specific permissions (Telegram privacy mode, Discord Message Content Intent)
- Look for
mention required, blocked, allowlist in logs
Cron/heartbeat not firing?
openclaw cron status - scheduler enabled?openclaw cron list - jobs exist?openclaw cron runs --id <jobId> --limit 20 - run history- Check heartbeat skip reasons:
quiet-hours, dm-blocked, requests-in-flight
Node tool failing?
openclaw nodes status - node online?openclaw nodes describe --node <id> - capabilitiesopenclaw approvals get --node <id> - exec approvals- Check OS permissions (camera, location, etc.)
Browser tool failing?
openclaw browser status - browser running?openclaw browser profiles - valid profiles?- Check CDP reachability and executable path
Doctor Command
openclaw doctor
openclaw doctor --fix
openclaw doctor --yes
openclaw doctor --generate-gateway-token
Doctor checks: config syntax/schema, service metadata, port availability, file permissions, browser paths.
Log Viewing
openclaw logs --follow
openclaw logs --tail 50
OPENCLAW_LOG_LEVEL=debug openclaw status
Log levels: trace > debug > info > warn > error
Post-Upgrade Checklist
- Check auth:
openclaw config get gateway.auth.mode - non-loopback binds now require auth
- Check bind:
openclaw config get gateway.bind - verify bind/auth alignment
- Check devices:
openclaw devices list - pending approvals after identity changes
- Check pairing:
openclaw pairing list <channel> - re-approve if needed
- Reinstall service if needed:
openclaw gateway install --force && openclaw gateway restart
Common Error Signatures
| Log Message | Meaning | Fix |
|---|
Gateway start blocked: set gateway.mode=local | Local mode not enabled | Set gateway.mode: "local" |
refusing to bind ... without auth | Non-loopback without token | Add gateway.auth.token |
EADDRINUSE | Port conflict | Change port or stop other process |
device identity required | Device auth not satisfied | Update client, check device pairing |
NODE_BACKGROUND_UNAVAILABLE | Node app not in foreground | Bring app to foreground |
SYSTEM_RUN_DENIED | Exec approval pending | Check openclaw approvals |
See references/common-issues.md for detailed troubleshooting per issue type.
