Troubleshooting

​

Common Incident Areas

• startup failures
• port conflicts
• OpenClaw missing/unavailable
• gateway auth-required responses
• workspace validation failures
• loopback policy violations
• unsigned desktop launch friction

​

First-response Checks

1. Confirm local listeners are loopback only.
2. Confirm database path and migration state.
3. Check both dependency layers:
   • gateway reachability in settings/topbar
   • CLI availability/version in settings
4. Confirm OpenClaw CLI exists on PATH (or OPENCLAW_BIN is set); for pnpm installs verify PNPM_HOME (commonly $HOME/Library/pnpm) is exported and on PATH.
5. Re-run gateway test from setup/settings flow.
6. Refresh capabilities (/api/openclaw/capabilities?refresh=1) and retry.
7. Check activity/receipt logs for failed operations.

​

Targeted Guides

• Startup Failures and Port Conflicts
• OpenClaw, Auth-required, and Workspace Errors
• Loopback Policy Violations
• Unsigned Desktop Install Guidance
• Release Artifacts and Checksums

​

Last updated

​

Related pages

• Maintenance and Recovery
• Config and Init
• Streaming (SSE)