FAQ
Troubleshooting
Fix the most common issues quickly
Continue With
These are the most useful entry points for installation, troubleshooting, and deeper reading.
Use this order every time: service status -> credentials -> connectivity -> restart.
1) Bot not responding
openclaw status
openclaw health
Then verify:
- Bot token is correct
- Your user ID is in allowlist
- Gateway restarted after config changes
2) API 401
Root causes:
- Wrong key type (cloud AccessKey instead of model provider key)
- Expired or partial API key
- Missing model permission
3) API 429 / timeout
Actions:
- Reduce concurrency
- Use lighter model tier
- Keep fallback model enabled
4) Search index missing
npm run build:search
Confirm public/pagefind/ exists before deployment.
5) Minimal command set
openclaw status
openclaw health
openclaw gateway restart
npm run build:search
Need step-by-step Chinese version? Read /zh-cn/faq/troubleshooting/.