OpenClaw Troubleshooting: Fix the 6 Most Common Failures

When OpenClaw troubleshooting is needed, the failure is almost always one of six things: a dropped messaging channel, a process that won’t start, memory exhaustion on a small VPS, a bad update, an unreachable dashboard, or corrupted state. This guide walks each symptom from diagnosis to fix, starting with the command that answers most questions:

pm2 logs openclaw --lines 200

Find your symptom below and work through it.

Why does my OpenClaw channel keep disconnecting?

Channel disconnects are the most common OpenClaw complaint, and the diagnosis differs by channel.

WhatsApp keeps dropping

WhatsApp is the most failure-prone channel because it has the most moving parts: Meta’s API, tokens, webhooks, and TLS. Three causes account for nearly all drops.

1. Expired temporary token. The developer token from Meta’s Getting Started page expires in 24 hours and breaks your integration silently. If WhatsApp worked for a day and then went quiet, this is almost certainly it. The fix: generate a permanent access token via a system user in Meta Business Settings with the whatsapp_business_messaging and whatsapp_business_management permissions, put it in config/openclaw.yaml, and restart:

pm2 restart openclaw

Our WhatsApp setup guide covers the token generation steps in detail.

2. TLS handshake failure. If your logs show certificate verify failed, unable to get local issuer certificate, SSL handshake failed, or UNABLE_TO_VERIFY_LEAF_SIGNATURE, your trust store can’t validate Meta’s certificates. The big one here was Meta’s April 2026 migration from DigiCert to its own meta-outbound-api-ca, which broke self-hosted instances overnight with no code change on the operator’s side. Confirm it with:

openssl s_client -connect graph.facebook.com:443 -showcerts

A Verify return code: 20 or 21 confirms the missing root. The fix involves installing the new CA into your system trust store and setting NODE_EXTRA_CA_CERTS - the full walkthrough is in our dedicated Meta CA migration fix guide. Don’t skip the NODE_EXTRA_CA_CERTS step: OpenClaw runs on Node 24, which bundles its own CA list and ignores the system store.

3. Webhook proxy breakage. If Meta can’t reach your webhook, messages stop arriving even though nothing looks wrong locally. Verify OpenClaw is online with pm2 status, then confirm nginx is proxying your HTTPS URL to port 18789 and the URL is publicly reachable.

Telegram or Discord stopped responding

These channels are simpler - it’s almost always the bot token.

For Telegram, the token from BotFather doesn’t expire on its own, but it becomes invalid if someone revokes it via BotFather. Confirm the token in config/openclaw.yaml matches what BotFather shows, then restart.

For Discord, remember the token is shown only once at creation. If you clicked Reset Token in the Discord Developer Portal at any point, the old token in your config is dead - update the bot_token in your config with the new one. Also confirm the bot’s intents are still enabled in the portal; the Discord setup guide shows where.

Why won’t OpenClaw start?

A process that refuses to start leaves fingerprints in the logs. Run this and read from the top of the crash:

pm2 logs openclaw --lines 100

Three causes cover most cases.

Config syntax errors. OpenClaw’s config lives at config/openclaw.yaml, and YAML is unforgiving - one bad indent and the process dies at startup. If your log shows a parse or config error immediately after launch, diff the file against your last working backup, or re-run the onboarding wizard to regenerate a clean config:

cd /opt/openclaw
npm run onboard

Port conflicts. OpenClaw listens on port 18789 by default. If another process grabbed it (or a zombie OpenClaw instance never released it), the new process can’t bind. Check what’s holding the port:

sudo ss -tlnp | grep 18789

If a stale process owns it, kill it and let PM2 start fresh. If it’s a legitimate second service, change one of the ports.

Wrong Node version. OpenClaw requires Node 24. If the server was rebuilt, or a system update swapped the Node binary, startup fails in confusing ways. Verify:

node --version   # must be v24.x.x

If it isn’t, reinstall Node 24 from NodeSource as shown in the install guide, then run npm install again and restart.

Why does OpenClaw keep restarting or running out of memory?

If pm2 status shows a climbing restart counter, or the process shows as online but dies every few minutes, you’re likely hitting the Linux out-of-memory killer. Confirm it:

free -h
sudo dmesg | grep -i "out of memory"

An OOM kill line in dmesg naming your Node process is the smoking gun.

The realistic sizing: 1-2 GB of RAM on 1 vCPU handles OpenClaw comfortably - that’s a $6/month DigitalOcean Basic Droplet or a Hetzner CX11. Below 1 GB, you’ll limp along until an npm install, an update, or a busy hour with multiple channels pushes memory over the edge, and then PM2 restarts the process in a loop.

Fixes, in order of preference:

1. Resize the VPS to at least 1-2 GB. This is the real fix and costs a dollar or two more per month.
2. Add swap as a stopgap - it prevents hard OOM kills at the cost of slower responses under pressure.
3. Disable channels you don’t use in config/openclaw.yaml to trim the baseline footprint.

Restart loops that aren’t memory-related usually trace back to a config or dependency error - the logs will show the same crash message repeating, which sends you back to the previous section.

Why did an update break OpenClaw?

OpenClaw installs from a git clone, which means updates are code pulls - and a pull can bring breaking changes, new dependency requirements, or config format changes.

Diagnosis: if OpenClaw worked before the update and crashes after, the update is the cause. Check the logs for missing module errors (dependencies out of sync) or config validation errors (format changed).

First response - sync dependencies. An update without a matching npm install is the most common self-inflicted breakage:

cd /opt/openclaw
npm install
pm2 restart openclaw

If it’s still broken - roll back. Because the install is a git repository, you can return to the exact code that worked. Note the version or commit you were on, then check it out, reinstall dependencies, and restart. A working older version buys you time to read the release notes and find out what actually changed.

Prevention - pin your version. Don’t run blind git pull on a production assistant. Update to a specific release tag, take a backup first, and keep the previous tag written down so rollback is a one-liner. Better yet, test updates somewhere that isn’t the instance your business depends on.

Why is the OpenClaw dashboard unreachable?

When the browser can’t reach your dashboard, debug from the inside out - each layer has a distinct symptom.

Layer 1: is OpenClaw running? pm2 status should show openclaw as online. If not, this is a startup problem - see above.

Layer 2: is it answering locally? From the server itself:

curl -I http://localhost:18789

A response here means OpenClaw is healthy and the problem is in front of it.

Layer 3: nginx. A 502 Bad Gateway means nginx is up but can’t reach OpenClaw - usually a wrong proxy_pass port or OpenClaw briefly down. Run sudo nginx -t to validate the config and check that the server block points at localhost:18789. Our nginx reverse proxy guide covers the correct server block, including the WebSocket upgrade headers the dashboard needs.

Layer 4: firewall. A connection that times out (rather than erroring) usually means a firewall is dropping packets. Ports 80 and 443 must be open to the world; port 18789 should not be. The firewall rules guide has the exact rule set.

Layer 5: SSL. Certificate warnings or ERR_SSL errors point at an expired or misissued Let’s Encrypt certificate. Check expiry and renew with Certbot. And if your error involves a self-signed certificate, that’s a separate path - see the self-signed certificate guide.

When should I wipe and restore from backup?

Some failures aren’t worth debugging. If the config is corrupted, a failed update left node_modules in a state that npm install can’t repair, or you’ve burned an hour without a diagnosis, a clean restore is faster than forensics: fresh install, restore your config and credentials, restart, verify each channel.

The catch is that this only works if backups exist before the incident. At minimum, keep copies of config/openclaw.yaml, your channel tokens and API keys, and any conversation data you care about - off the server itself. The backup and restore guide covers what to back up, how to automate it, and the exact restore procedure.

A good rule: if you’re about to try your third speculative fix, stop and restore instead. Speculative fixes on top of an unknown failure compound the mess.

How to read OpenClaw logs: a 2-minute primer

Every section above starts with the logs, so here’s how to use them well.

The commands. PM2 captures everything OpenClaw writes to stdout and stderr:

pm2 logs openclaw               # live stream
pm2 logs openclaw --lines 200   # recent history
pm2 status                      # uptime, restart count, memory

Read from the first error, not the last. When something breaks, the log fills with follow-on noise - reconnect attempts, timeouts, retries. Scroll back to the last clean startup and find the first error after it. That’s your root cause; everything below it is fallout.

Match the error to the failure bucket. TLS strings like certificate verify failed mean the trust store. A bind or port error means a conflict on 18789. An auth or token error names its channel. Repeated identical crashes a few seconds apart mean a restart loop - check dmesg for OOM kills before blaming the code.

Check the restart counter. pm2 status shows how many times the process has restarted. A number that climbs while you watch is a crash loop even if the status says online - PM2 is just relentlessly resurrecting a dying process.

Ten minutes with these commands beats an hour of guessing. And if you’d rather never open the logs at all, that’s literally what we’re for.