Troubleshooting
Common issues, diagnostic tools, and how to fix things when they go wrong.
Gateway Not Starting
The OpenClaw Gateway is the engine behind your agent. If it won't start:
Check if it's already running
Another instance might be using the same port. Check with:
Port conflict
The gateway defaults to port 3415. If something else is using it, change the port in your OpenClaw config or stop the conflicting service.
Node.js version
OpenClaw requires Node.js 18+. Check yours with node --version.
Channel Not Connecting
Token/credential issues
Double-check your bot token, API key, or credentials. Tokens can expire (especially OAuth tokens). Try disconnecting and reconnecting the provider.
Gateway restart needed
After changing connection settings, you usually need to restart the gateway. ClawManager shows a banner when this is needed — click it, or run:
WhatsApp QR expired
WhatsApp QR codes expire quickly. If the scan fails, restart the setup wizard to generate a fresh QR code.
Model / Provider Issues
API key not working
Check that your API key is valid and has sufficient credits/quota. You can verify by testing directly on the provider's dashboard (e.g., console.anthropic.com).
OAuth expired
OAuth tokens for Google, Anthropic, and ChatGPT can expire. The Models page shows a "needs reauth" warning — click to re-authorize.
Ollama not detected
Make sure Ollama is running (ollama serve) and listening on the default port (11434). ClawManager auto-detects it when the server is up.
Rate limiting
If you hit rate limits, the agent automatically tries fallback models (if configured). Consider setting up fallbacks in the Models page.
Viewing Logs
ClawManager includes a Logs Viewer that shows gateway logs in real-time. This is the best place to diagnose issues.
Using the Logs Viewer
- • Go to the Logs tab in ClawManager
- • Filter by date, log level, or search for keywords
- • Auto-refresh keeps you up to date in real-time
- • Click on an error to investigate it with AI assistance
CLI Logs
You can also view logs from the terminal:
Common Issues
❓ Agent responds slowly
Check your model choice — larger models are slower. Try a faster model (like Claude Haiku or GPT-4o-mini) for quicker responses. Also check your internet connection and API provider status.
❓ Agent doesn't respond at all
Verify the gateway is running (check the status indicator in ClawManager). Check that the channel is enabled and the access policy allows the user. Look at logs for errors.
❓ Skills show "needs setup"
The skill is installed but missing requirements. Click the skill card in the Skills Browser to see what's needed (usually an API key or system package).
❓ Changes not taking effect
Many config changes require a gateway restart. Look for the restart banner in ClawManager, or run: openclaw gateway restart
❓ ClawManager can't connect to gateway
Make sure the gateway is running and ClawManager is pointed at the correct URL/port. If running remotely, check firewall rules.
❓ Heartbeats not firing
Check that heartbeats are enabled and the interval is set. Verify the gateway is running. Look at logs for heartbeat-related entries.
Getting Help
If you're stuck:
- • Check the gateway logs for error messages
- • Use the Feature Request page in ClawManager to submit feedback or report issues
- • Join the community Discord for help from other users
- • Open an issue on GitHub for bugs or feature requests
Still stuck?
The best debugging tool is the Logs Viewer — most issues leave a trace there. If the log shows an error you don't understand, try the "Investigate" button, which uses your AI agent to explain the error and suggest fixes.