OpenClaw Troubleshooting: Fix Duplicate Agents, High Costs, and Common Errors
Something's broken. Duplicate messages, a silent bot, a $200 API bill, or an agent spinning in circles. This guide covers the most common OpenClaw problems with step-by-step fixes.
Quick Diagnosis First
Before diving into specific issues, run these three commands. They'll reveal 80% of problems immediately:
# 1. Check gateway status openclaw gateway status # 2. Watch recent logs openclaw logs --tail 50 # 3. List active sessions openclaw sessions list
When in doubt: restart
openclaw gateway restart fixes 60% of weird issues instantly. It kills all sessions, clears stuck state, and starts fresh. Use this first if you're in a hurry.
👥 Duplicate Responses
This almost always happens when you have two gateway instances running simultaneously. Both receive the incoming message and both respond.
Common triggers: running openclaw gateway start when one was already running, or OpenClaw auto-restarting after a crash while the old process was still alive.
# Step 1: Check how many gateway processes are running ps aux | grep openclaw # Step 2: Kill all of them openclaw gateway stop pkill -f openclaw # Step 3: Verify clean state ps aux | grep openclaw # Should show nothing # Step 4: Start fresh openclaw gateway start
If duplicates recur after restarting, check if you have OpenClaw configured as a system service (launchd on Mac, systemd on Linux) AND also running manually.
💸 High Token Usage / Unexpected Costs
Usually one of: using Opus when Sonnet/Haiku would do, context window not being pruned, heartbeat running on a heavy model, or a cron job firing more often than intended.
The most common cost culprit: maxContextTokens has never been set. If you've had OpenClaw running for months, your conversation history could be sending 100K+ tokens with every single message.
# Check which model is set as default
cat ~/.openclaw/config/openclaw.json | grep -A5 '"model"'
# Check context size being sent
openclaw logs --tail 20 | grep tokens
# Fix: Cap context immediately in openclaw.json
{
"context": {
"maxTokens": 80000
},
"model": {
"default": "anthropic/claude-sonnet-4-6",
"heartbeat": "google/gemini-flash-lite"
}
}After saving, restart the gateway. Your next API calls should be dramatically cheaper. See the full cost optimization guide for comprehensive strategies.
🔇 Bot Not Responding
Multiple possible causes in order of likelihood: gateway is down, the sending user isn't on the allowlist, the bot token is invalid/expired, or the channel plugin crashed.
# Step 1: Is the gateway running? openclaw gateway status # Step 2: Check for token errors openclaw logs --tail 30 | grep -i "token|auth|invalid" # Step 3: Verify your user ID is in allowedUserIds cat ~/.openclaw/config/openclaw.json | grep allowedUserIds # Step 4: Test the bot token directly curl "https://api.telegram.org/bot<TOKEN>/getMe" # Step 5: Nuclear option openclaw gateway restart
🔄 Model Fallback Loops
OpenClaw has model fallback logic — if the primary model fails, it tries the next model in the chain. If that also fails, it loops. This can happen when hitting rate limits or the primary model's API is having issues.
# Check logs for fallback messages
openclaw logs --tail 50 | grep -i "fallback|rate.limit|429"
# Fix: Explicit fallback chain in openclaw.json
{
"model": {
"default": "anthropic/claude-sonnet-4-6",
"fallback": [
"anthropic/claude-haiku-4",
"google/gemini-flash-2.5",
"openai/gpt-4o-mini"
],
"fallbackOnError": true,
"fallbackOnRateLimit": true
}
}💓 Heartbeat Spam
The heartbeat is misconfigured — it's either using the wrong model (causing actual AI responses instead of silent pings), or heartbeatResponse: true is set.
# Fix heartbeat config in openclaw.json
{
"heartbeat": {
"intervalMs": 60000,
"model": "google/gemini-flash-lite",
"silent": true,
"heartbeatResponse": false
}
}🔐 Fixing Allowlist Issues
The allowlist limits who can talk to your agent. If your own Telegram user ID isn't on it, your messages will be silently ignored.
{
"plugins": {
"telegram": {
"token": "YOUR_TOKEN",
"allowedUserIds": [123456789],
"adminUserIds": [123456789]
}
}
}To find your Telegram user ID: message @userinfobot on Telegram. It replies with your user ID instantly.
An empty allowlist means everyone who finds your bot can talk to your AI agent. Always explicitly list your user ID.
Diagnostic Command Reference
# Gateway health openclaw gateway status openclaw gateway restart openclaw gateway stop && openclaw gateway start # Logs openclaw logs --tail 50 openclaw logs --follow openclaw logs --channel telegram # Sessions openclaw sessions list openclaw sessions kill <session-id> # Config openclaw config show openclaw config validate # Processes ps aux | grep openclaw pkill -f openclaw # LCM / context openclaw lcm stats openclaw lcm prune --older-than 30d # Cost tracking openclaw usage --today openclaw usage --month
Prevent Issues With Proper Config
Most problems come from misconfigured settings. Read the cost optimization guide to set up smart defaults from the start.
Cost Optimization Guide