These come directly from Reddit threads, Discord support channels, and people who helped 50+ others debug their setups. If your OpenClaw install is not working right, check this list first.
1. Wrong API key or provider mismatch
Symptom: Gateway is running but shows "0 tokens used." Agent responds with errors or not at all.
Cause: You configured the provider as Anthropic but pasted an OpenAI key, or vice versa. The key format is different for each provider and easy to mix up during setup.
Fix: Open your .env file. Check that LLM_PROVIDER matches the key you actually have. Verify the key is valid by testing it with a simple curl request to the provider's API.
2. Node.js version too old
Symptom: Obscure syntax errors during install or startup. Commands fail with messages about missing features.
Cause: OpenClaw requires Node.js v20 or newer. Many system default repositories install older versions.
Fix: Run node --version. If below v20, install a current LTS version using nvm (Node Version Manager).
3. Missing build tools on Linux
Symptom: npm install fails with compilation errors for native modules.
Cause: Many npm packages need to compile C code during installation. Fresh Linux servers often lack the build toolchain.
Fix: On Ubuntu/Debian: sudo apt install build-essential git python3. On Fedora/RHEL: sudo dnf install gcc gcc-c++ make.
4. Gateway port conflict
Symptom: Gateway fails to start. Error about port already in use.
Cause: Another service is using port 18789 (OpenClaw's default gateway port).
Fix: Either stop the conflicting service or change OpenClaw's bind port in openclaw.json.
5. Running directly on your main machine
Symptom: No immediate symptom. This one bites you later when a skill misbehaves or a prompt injection trick gets through.
Cause: OpenClaw has deep system access. Running it without isolation means it (or a compromised skill) can access everything on your machine.
Fix: Use Docker. It is not optional for production setups. The Docker image is maintained and tested. Your laptop is not a hardened server.
6. DM policy left on 'open'
Symptom: Random people can message your agent. Unexpected conversations appear in your logs.
Cause: The default DM (direct message) policy is sometimes set to open, which means anyone who finds your bot can start talking to it.
Fix: Set the DM policy to restrict to known users or require pairing. This is especially important on Telegram where bots are publicly discoverable.
7. Skipping openclaw doctor
Symptom: Subtle config issues that cause confusing errors later. Channel connections that fail silently.
Cause: openclaw doctor checks your entire setup for common problems. Skipping it means missing easy fixes.
Fix: Run openclaw doctor after every initial setup, after upgrades, and after major config changes. It takes 30 seconds and catches things you will spend hours debugging otherwise.
8. Docker volumes not configured
Symptom: All your data, memory, and configuration disappear after a container restart.
Cause: Docker containers are ephemeral by default. If you do not mount persistent volumes, everything inside the container is lost when it restarts.
Fix: Configure named volumes or bind mounts in your docker-compose.yml for the data, config, and memory directories. The setup script handles this if you use it.
9. Gateway exposed without authentication
Symptom: Your OpenClaw gateway is reachable from the public internet without a password.
Cause: Gateway bound to 0.0.0.0 with no firewall rules. Port 18789 is open to the world.
Fix: Bind to 127.0.0.1 in openclaw.json. Set a strong gateway token in .env. Use UFW to firewall port 18789 on your VPS. Access remotely via SSH tunnel.
10. Never starting fresh sessions
Symptom: Token costs keep climbing. Agent performance degrades over time. Responses become less relevant.
Cause: OpenClaw sends conversation history with every API call. Longer sessions mean larger context windows and higher costs. Memory files also accumulate and get loaded into every call.
Fix: Use /new to start a fresh session before heavy tasks. Keep your memory files concise. Summarize active conversations periodically instead of letting them grow unchecked.
Still stuck?
These 10 cover the most common issues, but OpenClaw has a lot of moving parts. If your problem is not on this list, the fastest path to an answer is usually:
- Run
openclaw doctor - Check
openclaw logs --followfor error details - Search the official troubleshooting docs
- Ask in the community (someone has probably hit the same issue)
Need help from people who already use this stuff?
Debugging OpenClaw alone is slow
Join My AI Agent Profit Lab to get help from people who have already solved the same problems. Most setup issues get answered in minutes, not days.
FAQ
Why does my OpenClaw gateway show 0 tokens used?
Usually means your API key does not match the configured provider. If you set LLM_PROVIDER=anthropic but pasted an OpenAI key, the gateway cannot connect. Fix the key or the provider setting.
Why does OpenClaw keep losing context?
Long sessions accumulate context that gets compressed or truncated. Start fresh sessions with /new before heavy tasks. Also check that your memory files are not too large, as they load into every context window.
Why are my Telegram messages not reaching OpenClaw?
Check that your bot token is correct, the webhook URL is publicly reachable, and privacy mode is disabled (via BotFather). Also verify your DM pairing policy is not set to restrict unknown users.
Why does OpenClaw consume tokens without finishing tasks?
Common causes: the agent loops on a failed step, the model is too ambitious and tries to do too much at once, or context has grown too large. Use /new to reset, check your skill configurations, and consider using a cheaper model for routine tasks.