Help Hub: Troubleshooting, Diagnostics, and FAQ for OpenClaw
Find quick fixes for stuck states, debugging tips, install sanity checks, and gateway troubleshooting. Also covers FAQs, diagnostics flags, environment variables, and testing guides.
Read this when
- You are new and want a "what do I click/run" guide
- Something broke and you want the fastest path to a fix
Quickest way to resolve a stuck state, organized by symptom:
- Troubleshooting - a decision tree guided by symptoms
- Debugging - watch mode, raw streams, and the dev profile
- Install sanity - verifying Node, npm, and PATH settings
- Gateway troubleshooting - problems specific to the gateway
- Doctor -
openclaw doctor: health checks, config migration, and repair steps
FAQ
- FAQ - everyday concepts and operational queries
- First-run FAQ - installation, onboarding, authentication, subscriptions, and early failures
- Models FAQ - choosing models, failover behavior, and authentication profiles
Diagnostics
- Environment variables - where OpenClaw reads environment variables and how precedence works
- Diagnostics flags - verbose modes and runtime diagnostics
- Node + tsx crash - specific crash scenarios in Node and tsx runtimes
Testing
- Testing - test suites and Docker-based runners
- Update and plugin tests - validating package updates, migrations, and plugin installations
- Live tests - network-dependent provider and CLI smoke tests
Community and meta
- OpenClaw lore - the backstory
- Docs hubs - how this documentation is structured
- Docs directory - the complete file map