Troubleshooting

Use this order every time: service status -> credentials -> connectivity -> restart.

1) Bot not responding

openclaw status
openclaw health

Then verify:

1. Bot token is correct
2. Your user ID is in allowlist
3. 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:

1. Reduce concurrency
2. Use lighter model tier
3. 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/.