OpenClaw Troubleshooting: Fix Every Common Error in Minutes

The difference between spending five minutes and five hours on an OpenClaw issue is knowing which three commands to run first. I've debugged over 40 production OpenClaw deployments. The same error patterns come up repeatedly. Here's the complete playbook — organized by error category so you can go straight to what's breaking.

Diagnostic First Steps: Run These Before Anything Else

Before you dig into any specific error, run this sequence. These three commands give you 80% of the information you need to diagnose any OpenClaw problem.

# Step 1: Check overall system health
openclaw doctor

# Step 2: Check process status
openclaw status

# Step 3: Read recent logs
openclaw logs --tail 200 --level error

openclaw doctor validates your Node.js version, checks environment variables, tests connectivity to your model provider, and verifies MCP servers are reachable. Each check produces a clear pass/fail result. Start here every time.

openclaw status shows you the live state of every agent, gateway, and channel. If something shows as offline or errored, you've found your problem layer.

openclaw logs gives you the raw error messages. The --level error flag filters out noise so you see only the actual errors. Read the most recent ones first — they're usually causally related.

Gateway Errors

Gateway errors are the most common category. The gateway is the central process that routes messages between channels and agents — if it's broken, nothing works.

Gateway shows as offline

Check if the gateway process is actually running:

ps aux | grep openclaw-gateway

If it's not in the output, the process crashed or was never started. Check the gateway log for the crash reason:

cat ~/.openclaw/logs/gateway.log | tail -50

Common crash causes: missing required environment variables, port already in use, or Node.js version incompatibility.

Gateway running but not reachable

The process is alive but connections are failing. Test local connectivity first:

curl -s http://localhost:8080/health

If this returns a health response, the gateway is running fine locally. The issue is network routing — a firewall, reverse proxy misconfiguration, or the wrong port in your config. If it returns nothing, the port binding failed even though the process started.

Gateway pairing required error

This specific error means a new device or agent is trying to connect to the gateway but hasn't been authorized. Run:

openclaw devices approve

This lists pending device connection requests and lets you approve them. See the dedicated gateway pairing guide for the full flow.

Installation and Startup Errors

Command not found

Running openclaw returns "command not found". The binary isn't in your PATH. Check:

which openclaw
npm list -g openclaw

If npm shows it installed but which can't find it, your npm global bin directory isn't in PATH. Fix it:

export PATH="$(npm bin -g):$PATH"

Add that line to your shell profile for a permanent fix.

npm install errors

Installation fails with permission errors, EACCES, or package dependency conflicts. The most common fix is correcting npm's global directory permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Then reinstall without sudo. Using sudo for npm global installs creates permission issues that cascade through the entire tool chain.

Authentication and API Key Errors

Auth errors are almost always environment variable issues. The pattern is consistent: the variable isn't set, it's set with the wrong name, or there's invisible whitespace in the value.

Verify your key is actually in the environment:

echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

If nothing prints, the variable isn't exported. If it prints but looks wrong (extra characters, wrong prefix), the key is malformed.

Agents Not Responding to Messages

The gateway is healthy, channels are connected, but agents don't reply. This is a different failure layer.

Check what's happening when a message arrives:

openclaw logs --follow --level debug

Send a test message and watch the log output in real time. You'll see exactly where the processing chain breaks — whether the message was received, whether the agent started processing, whether the LLM call was made, and whether it returned an error.

Common causes for silent agent failures:

• LLM rate limit — the model provider is returning 429 errors. Check your usage dashboard on the provider's site.
• Skill error halting execution — a skill threw an exception during processing. The error appears in logs but not in the channel response.
• Context overflow — the conversation history exceeded the model's context window. The agent returns an empty response instead of an error message.
• Invalid soul.md or identity.md — a syntax error in a system prompt file causes agent initialization to fail silently.

Common Troubleshooting Mistakes

Restarting without reading logs first. A restart masks the error message. Always read the logs before restarting so you capture the actual failure reason.

Changing multiple config values at once. When you change three things and one works, you don't know which one fixed it — or which of the others might cause problems later. Change one thing, test, then change the next.

Ignoring doctor output. The doctor command explicitly tells you what's wrong. Most people run it, see a failure they don't immediately recognize, and start guessing instead of addressing the specific check that failed.

Testing in production before local. Always reproduce an issue locally first. Production environments have additional variables — firewalls, proxies, different Node versions — that make root cause harder to isolate.

Sound familiar? The pattern is consistent: slow down, read the output, address the specific error message you're seeing.

Frequently Asked Questions

What command shows OpenClaw error logs?

Run openclaw logs --tail 100 to see the last 100 log lines. Add --level error to filter for errors only. For the gateway process specifically, check ~/.openclaw/logs/gateway.log directly for gateway-level crash information.

Why does OpenClaw say my gateway is offline?

Gateway offline errors occur when the heartbeat misses consecutive beats. Check that the gateway process is running with ps aux | grep openclaw-gateway, verify the gateway URL is reachable, and confirm no firewall is blocking the heartbeat endpoint.

How do I reset OpenClaw to factory defaults?

Delete or rename ~/.openclaw/config to remove your configuration, then run openclaw onboard to go through setup again. Your installed skills and channel pairings will need to be re-added — there is no single reset command.

Why are my agents not responding to messages?

Start with openclaw status to verify everything is online. Then check openclaw logs for error patterns. Common causes: missing or expired API key, model provider rate limit hit, or a skill returning errors that halt processing without a visible failure message.

Why does openclaw doctor show a failed check?

Each failed check has a specific message. Common failures: Node.js version below minimum (upgrade Node), missing environment variable (set it and restart), MCP server not found (check npm global install path), or gateway unreachable (verify the gateway URL and network connectivity).

What does 'connection refused' mean in OpenClaw logs?

Connection refused means the process OpenClaw is trying to reach isn't listening on that port. Check if the target service is running, verify the port in your config matches what the service is using, and check firewall rules. For gateway connections, ensure the gateway process started before the agent tried to connect.