← All tutorials

Troubleshooting OpenClaw — fix the install, the Gateway and the channels

A field guide to the most common OpenClaw problems: doctor diagnostics, Gateway crashes, channel disconnects, model errors and update rollbacks.

Every release of OpenClaw is tested by the maintainers, but the real world is messy: corporate proxies, locked-down system keychains, half-installed macOS profiles. This guide collects the failure modes we see most often, with the exact commands that fix them.

Run the doctor first

openclaw doctor

doctor walks through every check the Gateway performs when starting up:

• Node.js version (24.16+ or 26.1+)
• Disk space and file permissions
• Model provider authentication
• Channel reachability (Telegram, Discord, Slack, WhatsApp, iMessage)
• Memory database integrity
• Update channel availability

A healthy install prints a green ✓ next to every check. A red ✗ prints the failing component and the suggested fix.

✓ Node.js 26.1.0
✓ Disk space (12.4 GB free)
✓ Model provider: anthropic (authenticated)
✗ Telegram channel: HTTP 401 from api.telegram.org
   → Token rejected. Run `openclaw channels rotate telegram`.
✓ Memory database (842 facts)
✓ Update channel: stable

Read live logs

openclaw logs --follow

Adds --channel telegram, --skill weather or --level warn to narrow the stream:

openclaw logs --channel telegram --level error --follow

Logs are JSON-structured and are written to ~/.openclaw/logs/gateway.log with a 14-day rotation by default.

Gateway will not start

Most Gateway startup failures fall into one of three buckets.

Port 18789 is already in use

Error: listen EADDRINUSE :::18789

Either another OpenClaw instance is already running (check openclaw status), or another process has grabbed the port. Find the offender:

lsof -i :18789

On Linux you can also just bind a different port:

openclaw serve --port 28889

Permission denied on the home folder

Error: EACCES: permission denied, open '/Users/me/.openclaw/gateway.pid'

Either fix the ownership:

sudo chown -R "$USER" ~/.openclaw

…or run with a different OPENCLAW_HOME:

OPENCLAW_HOME=~/work/.openclaw openclaw serve

Stale lock file

Error: gateway.pid exists but process 41823 is not running

rm ~/.openclaw/gateway.pid
openclaw serve

Model provider returns 401 or 429

A 401 means the API key is wrong or expired. Rotate it:

openclaw config set providers.anthropic.apiKey ""
openclaw gateway reload

A 429 means rate limiting. doctor will surface the retry-after header:

✗ Provider anthropic: 429 Too Many Requests (retry-after: 17s)
   → Lower your `requestsPerMinute` setting or upgrade your tier.

Tune the per-provider budget:

openclaw config set providers.anthropic.requestsPerMinute 30

A channel keeps disconnecting

openclaw doctor --channel whatsapp --verbose

Verbose mode prints the last ten reconnect attempts with timestamps and the underlying error.

For WhatsApp specifically, the linked-device session expires every ~14 days. You can pin a session with:

openclaw channels set whatsapp --keep-alive true

For Discord, a missing privileged intent is the most common cause of silence:

✗ Discord: messages not received. Enable "Message Content Intent" in the
   developer portal under Bot → Privileged Gateway Intents.

For iMessage, the Full Disk Access prompt sometimes resets after a macOS update. Re-add OpenClaw in System Settings → Privacy & Security → Full Disk Access.

An update broke something

OpenClaw keeps the previous release on disk for 30 days, so rolling back is a one-liner:

openclaw update --rollback

If you cannot even boot the Gateway after an update, run the rollback from the CLI-only installer:

curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --channel stable

To find out what changed between the version you were on and the current one:

openclaw update --notes

Resetting everything (last resort)

When you have tried everything and the install is wedged, a full reset is the cleanest path. This will delete all memory and uninstall all skills.

openclaw uninstall --purge
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard

You can restore a backup afterwards:

tar xzf openclaw-memory-2026-09-21.tgz -C ~

Asking for help

Before writing in, please run and capture:

openclaw doctor > doctor.txt 2>&1
openclaw --version > version.txt
openclaw logs --since 24h > logs.txt

Attach all three files to a contact form ticket along with the page URL of the guide you were following. The output above tells us most of what we need to reproduce the issue.

Next steps

• Walk through a clean install with Getting Started.
• Wire the install to chat apps via Integrations.
• Persist context with Memory and automate with Skills.

Found an issue or have a correction? Get in touch.