Table of Contents

If you’ve just set up OpenClaw and something went wrong or it was working fine yesterday and suddenly isn’t today, you’re not alone. OpenClaw is a powerful self-hosted AI agent, but because it bridges your local machine with external AI models and messaging platforms like WhatsApp, Telegram, and Discord, there are a lot of moving parts that can break. The good news is that most errors come down to the same handful of causes, and almost all of them are fixable in under 10 minutes.

This guide covers 31 common OpenClaw errors, organized by category so you can find your specific issue fast. Whether you’re hitting a connection error during install, a silent bot that refuses to respond, or a mysterious error code you’ve never seen before, there’s a fix here for you, explained in plain language, no deep technical knowledge required.

New to OpenClaw? Start with this step-by-step setup guide first: OpenClaw installation guide.

Quick Recap

Before scrolling through the full guide, try these first. They solve the majority of OpenClaw problems instantly.

For any command listed here, open your Terminal app (Mac: Cmd + Space → type “Terminal” → Enter; Linux: look for Terminal in your apps menu) and paste it there, then press Enter.

Run the built-in diagnostic tool: openclaw doctor --repair — this auto-fixes about 80% of common issues including broken configs, port conflicts, and token mismatches.
Restart the Gateway: openclaw gateway restart — fixes most “not responding” and connection issues.
Start a fresh session: Type /new in your chat app (Telegram, Discord, etc.) — clears a sluggish or stuck conversation without losing your memory files.
Check your API key: Go to your provider dashboard (Anthropic, OpenAI, etc.), make sure your account has credits, and re-copy the key without extra spaces.
Check Node.js version: In Terminal, run node -v — OpenClaw requires v22 or higher.

Group 1: Installation Errors

Getting OpenClaw installed is often where people hit their first wall. These errors appear before you’ve even started using the agent, usually during the install process itself. The good news: they all have clear, specific fixes.

Error 1. Node.js Not Found, or Your Version Is Too Old

What you see: The install command fails, or node -v shows a version below 22.

Node.js is the engine OpenClaw runs on, and many operating systems, especially Ubuntu and Debian, ship with an old version (v12 to v18) that isn’t compatible. The cleanest solution is to install nvm (Node Version Manager), which lets you switch between Node versions without touching your system installation.

You should: Open your Terminal, then paste each line below one at a time, pressing Enter after each one:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash source ~/.bashrc nvm install 24 nvm use 24 node -v # Should show v24.x.x

Here’s what each line does: the first line downloads and installs nvm from the internet. The second refreshes your terminal so it recognizes nvm right away. The third downloads Node.js version 24. The fourth switches your terminal to use it. The fifth check if it worked. If yes, you should see v24.x.x printed back.

On macOS, you can also use Homebrew instead: open Terminal and run: brew install node@24 && brew link --overwrite node@24.

On Windows, download the LTS installer from nodejs.org and run it like any normal installer, no terminal needed. However, if you’re on Windows and plan to do anything more advanced, also see the WSL2 note in Group 6.

Tips for Windows users: Stick to Node v22 specifically when building native modules. Newer versions can cause compatibility errors on Windows.

Error 2. “openclaw: command not found” after a Successful Install

What you see: You ran the install, it seemed to work, but openclaw --version says “command not found.”

This is a PATH issue: your terminal doesn’t know where npm put the openclaw binary. The fastest fix is to reload your shell config. Open Terminal and paste the line that matches your system:

source ~/.bashrc # Linux source ~/.zshrc # macOS

Or simply close the terminal and reopen it. If it’s still not working, run npm config get prefix to find where npm installs global packages. The result plus /bin should appear in your PATH — if it doesn’t, add it manually to your ~/.bashrc or ~/.zshrc file.

Error 3. “npm ERR! node-gyp rebuild failed”

What you see: A long wall of error text involving node-gyp, “native modules,” or sharp during installation.

OpenClaw includes some native Node.js modules that need to be compiled from source, which requires C++ build tools on your machine. If those tools are missing, the install fails at this step.

Open Terminal:

# Ubuntu/Debian sudo apt install -y build-essential python3

# macOS xcode-select --install

# Fedora sudo dnf install -y gcc gcc-c++ make python3

On Windows, install Microsoft C++ Build Tools and check the following options: “Desktop development with C++”, MSVC v143, and Windows 10/11 SDK. Before retrying the install, clean the temp folder:

Remove-Item "$env:TEMP\OpenClaw*" -ErrorAction SilentlyContinue

Error 4. “EACCES: permission denied” during Install

What you see: A permissions error when running npm install -g openclaw.

Npm is trying to write to a folder your user account doesn’t own. The fix is not to use sudo – that creates more problems. Instead, point npm to a folder you own. Open Terminal and paste these lines one at a time:

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

Then re-run the install. On macOS, switching to nvm (see above) avoids this issue entirely.

Error 5. “pnpm install” – Hangs or Fails on Windows

What you see: Building OpenClaw from source on Windows – pnpm install freezes or times out.

Windows Defender scans every file written during installation, which causes timeouts on large installs. A corporate firewall may also be blocking registry.npmjs.org.

Try temporarily disabling Windows Defender’s real-time protection during the install. If you’re on a corporate network, test from a personal network. And again, using WSL2 sidesteps this issue almost entirely.

Group 2: Configuration and Authentication Errors

Once OpenClaw is installed, the next category of problems involves getting it connected to your AI provider and configured correctly. These errors are extremely common because they involve API keys, JSON files, and authentication tokens — all things that are easy to get slightly wrong.

Error 6. Invalid API Key / Authentication Failed (Error 401 or 403)

What you see: OpenClaw installs fine but fails on every request with an error about “invalid API key,” “authentication failed,” 401, or 403.

This is one of the most common OpenClaw errors. Before assuming something is broken, run through this checklist in order:

Go to your provider’s dashboard (Anthropic Console, OpenAI Platform, etc.) and copy the key fresh, don’t copy it from somewhere you pasted it before.
Paste it without any spaces before or after the key. A single invisible space will cause this error.
Check your account balance and credit status. A depleted account causes the exact same 401 error as a wrong key.
Make sure you’re using the right key type. An OpenAI key won’t work in the Anthropic/Claude field, and vice versa.
Re-run openclaw configure to enter the key again cleanly.

Pro tips: Never paste API keys directly into openclaw.json. Use environment variables because it’s both safer and easier to update.

Error 7. “Assistant turn failed before producing content”

What you see: You send a message, and OpenClaw immediately returns this error with no response from the AI.

This is a close cousin of the 401 error. The request got to your AI provider, but was rejected before the model could generate anything. The cause is almost always an empty, expired, or invalid API key or a zero account balance. It can also happen if openclaw.json references a model name the provider doesn’t recognize.

Check your balance first. Then verify the key isn’t empty: openclaw gateway config get

Then run: openclaw doctor --fix

Error 8. Broken Config File – Daemon Refuses to Start

What you see: openclaw doctor reports a config error, or the daemon fails silently after you manually edited openclaw.json.

Hand-editing JSON files is a common source of subtle errors: a missing comma, an extra bracket, or mismatched quotes will break the whole file. Validate it first:

cat ~/.openclaw/openclaw.json | python3 -m json.tool

If that reports an error with a line number, go fix that line. If the file is too broken to salvage, reset to defaults:

openclaw configure --reset

Prevention tip: Always validate your JSON after editing it manually. VS Code and most modern editors will highlight JSON errors before you save.

Error 9. Can’t Connect to AI Provider – Timeout or Connection Refused

What you see: OpenClaw starts, but every request just times out. No response ever comes back.

The issue is almost certainly network-level. Test whether your computer can actually reach the API:

curl -I https://api.anthropic.com # For Claude curl -I https://api.openai.com # For OpenAI

If these commands hang or return errors, check your internet connection, VPN, or corporate proxy settings. Some company firewalls block AI API endpoints entirely. Also check the provider’s status page because outages do happen.

Error 10. “Disconnected (4008): Connect failed. Auth failed”

What you see: You try to open the OpenClaw Dashboard and get immediately rejected with this error.

This happens when the Dashboard and Gateway tokens get out of sync, most often right after a software update. The fix is to force a new token to be generated:

Run openclaw onboard
When it shows your existing Dashboard token, delete it completely and press Enter
Finish setup without changing anything else
The 4008 error will be gone.

Error 11. Disconnected (1008): control ui requires HTTPS or localhost

What you see: You try to access the Dashboard from a browser on your personal computer, pointing at your VPS, and get this error.

This is a browser security feature, not a bug. Browsers refuse device authentication over plain HTTP connections to external IPs. You need either localhost or a proper HTTPS certificate.

The secure fix: Use Tailscale Serve on your VPS to get a free HTTPS certificate automatically. Then access your Dashboard at: https://[vps-name].[tailnet-name].ts.net:18789

The quick fix (less secure): Add this to ~/.openclaw/openclaw.json:

"gateway": { "controlUi": { "allowInsecureAuth": true } }

Error 12. TUI Stuck in a Pairing Loop (gateway connect failed: pairing required)

What you see: You set up OpenClaw on a new VPS, ran openclaw doctor --fix, entered the right token, but openclaw tui keeps cycling through the pairing error.

The auto-generated device file is missing an important permission. It has operator.read but needs operator.admin to control the TUI. Fix it automatically with this one-liner:

python3 -c "import json, os; p = os.path.expanduser('~/.openclaw/devices/paired.json'); d = json.load(open(p)); [v['scopes'].append('operator.admin') for k,v in d.items() if 'operator.admin' not in v['scopes']]; json.dump(d, open(p, 'w'))" systemctl --user restart openclaw-gateway

Or approve it manually:

openclaw devices list # Get the pending device ID openclaw devices approve

Group 3: Gateway and Daemon Errors

The Gateway is the core process that routes messages between your AI model and your messaging channels. When the Gateway has problems, the whole system goes offline. These errors tend to look scarier than they are — most resolve with a restart or a one-line fix.

Error 13. Port 18789 Already in Use (EADDRINUSE)

What you see: The Gateway fails to start with an error about port 18789 or EADDRINUSE.

Something else is already sitting on that port, usually a previous OpenClaw instance that crashed without releasing it. Find and kill the process:

# Linux / macOS lsof -ti:18789 | xargs kill -9

# Windows (PowerShell) netstat -ano | findstr :18789 taskkill /PID /F

Also delete any stale lock file: rm ~/.openclaw/gateway.pid

Then restart the Gateway normally.

Error 14. Gateway Refuses to Start: refusing to bind gateway without auth

What you see: The Gateway explicitly says it won’t start because authentication isn’t configured.

This is a safety feature, OpenClaw won’t run an unauthenticated Gateway that anyone could connect to. Run the setup wizard:

openclaw onboard

This walks you through adding authentication. Don’t skip it.

Error 15. systemd Service Won’t Start (Linux)

What you see: systemctl --user status openclaw-gateway shows failed or inactive.

Always check the actual error before guessing:

journalctl --user -u openclaw-gateway --no-pager -n 30

The three most common causes are: systemd using a different PATH than your shell (so it can’t find node), a missing config file because openclaw onboard was never run, or a port conflict as described above.

Error 16. LaunchAgent Not Starting on Login (macOS)

What you see: The daemon doesn’t start when you log in. The menu bar app shows “stopped.”

Reload the LaunchAgent manually:

launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist launchctl load ~/Library/LaunchAgents/io.openclaw.gateway.plist

If the .plist file is missing entirely, run openclaw onboard --install-daemon to recreate it.

Error 17. Weird Logs or Clashing Behavior After a Restart

What you see: The Gateway restarted but now shows strange log entries and behaves oddly in old conversations.

Old session context is clashing with the fresh Gateway state. The fix is simple: start a new session. In Telegram (or your channel app), type:

/new

This clears the conversation buffer without deleting any of your memory files (SOUL.md, USER.md, MEMORY.md). Everything the bot “knows” about you is preserved.

Group 4: Channel and Messaging Errors

Even with the Gateway running perfectly, getting your bot to actually respond in Telegram, Discord, WhatsApp, or Slack introduces another layer of possible issues. Most of these come down to token expiry, pairing, or a setting you didn’t know existed.

Error 18. Bot Not Responding to Any Messages

What you see: You send a message to your bot and nothing comes back – no reply, no error, just silence.

Start with the diagnostic command:

openclaw doctor

If it shows the Gateway as “stopped,” restart it: systemctl --user start openclaw-gateway (Linux) or the equivalent on macOS. If the Gateway is running but the bot still doesn’t respond, your user likely hasn’t been added to the allowlist yet. The bot sends you a pairing code on first contact, use it:

openclaw pairing approve

Error 19. Bot Only Responds When @Mentioned in a Group

What you see: In a group chat, the bot ignores most messages and only replies when you tag it directly.

This is intentional behavior. In busy group chats, OpenClaw stays quiet unless mentioned, to avoid responding to every message. You can change this:

openclaw configure --channel discord --group-mode all

Replace discord with whichever channel you’re using. The all mode makes the bot respond to every message in the group.

Error 20. WhatsApp Pairing or Connection Drops

What you see: WhatsApp fails to connect during setup, or drops the connection unexpectedly after it was working.

WhatsApp’s QR code sessions expire, and having multiple OpenClaw instances trying to use the same account causes conflicts. Re-pair cleanly:

openclaw channel restart whatsapp

Scan the new QR code from your phone via Settings → Linked Devices → Link a Device. Make sure no other OpenClaw instance is connected to that same WhatsApp account.

Error 21. Android / Termux Crash: CIAO PROBING CANCELLED

What you see: Running OpenClaw on an Android phone through Termux, the app keeps crashing.

Android’s security model blocks the Bonjour network discovery plugin that OpenClaw ships with. Disable it:

openclaw plugins disable bonjour

Restart your phone afterward to clear any sockets that got stuck.

Group 5: Runtime and Performance Issues

Once everything is installed and connected, a second wave of problems can emerge as you actually use OpenClaw day-to-day. These are less about broken settings and more about how you’re using the tool — and a few of them can get expensive if left unchecked.

Error 22. Out of Memory Crash (JavaScript heap out of memory)

What you see: The Gateway crashes, especially on a cheap VPS with 1 GB of RAM.

Add swap space so your server can borrow disk as temporary memory, then raise Node’s heap limit:

sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

openclaw configure --max-old-space-size 512

Error 23. Rate Limit Errors (Error 429)

What you see: OpenClaw starts returning 429 errors, especially during heavy use.

This means you’ve hit your AI provider’s rate limit for your subscription tier.

Options: reduce how many requests OpenClaw sends at once, upgrade your API plan, switch to a faster/higher-limit model (Sonnet handles far more requests per minute than Opus), or add delays between automated batch tasks.

You can also set MAX_REQUESTS_PER_MINUTE in your environment config to cap OpenClaw’s own request rate.

Error 24. Agent Goes Quiet or Forgets Its Instructions Mid-Conversation

What you see: Your bot stops responding, or starts ignoring things you told it in the system prompt.

This is a context window overflow. Every message, tool output, and instruction counts toward the model’s maximum context limit. When the conversation grows large enough, OpenClaw starts compressing older messages and your system prompt instructions can get trimmed in the process. On slower model tiers, a very large context also triggers the default 60-second timeout, making the bot appear frozen.

Keep your core system prompts under 2,000 tokens and use MEMORY.md for long-term context. Start fresh sessions regularly with /new. For large document tasks, increase the timeout in your config: LLM_REQUEST_TIMEOUT=120.

Error 25. Dashboard Is Accessible but Very Slow

What you see: Everything works, but responses take longer and longer over time.

Every message in your current session gets sent with every new API call, including all the history. After weeks of the same session, a simple question carries thousands of tokens of old conversation. Type /new to start a fresh session. Your agent doesn’t lose its memory; it just stops carrying all that dead weight on each request.

Error 26. Your API Costs Are Way Higher Than Expected

What you see: A surprisingly large bill from your AI provider.

The most common causes, in order: using Opus as the default model for everything (it costs 10–15x more than Sonnet for tasks where you won’t notice the difference), agents stuck in silent loops burning tokens, and memory files that have grown huge. Switch your default to Sonnet:

{ "ai": { "model": "claude-sonnet-4-5-20250929" } }

And add anti-loop rules to your SOUL.md or AGENTS.md:

## Anti-Loop Rules - If a task fails twice with the same error, STOP and report it. Do not retry. - Never make more than 5 consecutive tool calls without checking in. - If a command times out, report it. Do not re-run silently.

Error 27. A Custom Skill Installed But Does Nothing

What you see: You install a skill from ClawHub, but the agent completely ignores it.

OpenClaw expects user skills to live in ~/.openclaw/workspace/skills/. If they’re placed directly in ~/.openclaw/skills/, they get silently ignored with no error message. Verify where the system is looking:

openclaw config get skills.directory

Move your skill files to whatever path that command returns.

Error 27. An Update Broke Something

What you see: After running openclaw update, things that worked before now fail.

Newer versions sometimes deprecate config keys. Run the auto-migration tool:

openclaw doctor --repair

This detects old config keys and rewrites them for the new version automatically.

Group 6: OS-Specific Errors

Some errors only appear on specific operating systems. These are short and targeted — find your OS and apply the fix.

Error 28. macOS: Operation not permitted

MacOS’s privacy protections (SIP and TCC) are blocking access. Go to System Settings → Privacy & Security → Full Disk Access and add Terminal to the allowed list.

Error 29. Windows: execution of scripts is disabled

PowerShell is blocking script execution by policy. Run this once to allow signed scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Error 30. Windows: WSL2 Won’t Install – Virtualization not enabled

Restart your PC, enter your BIOS settings, and enable Intel VT-x or AMD-V. The exact menu location varies by manufacturer, search for your motherboard model if you’re unsure.

Please remember: On Windows, always run OpenClaw inside WSL2. Native Windows installation is the source of a disproportionate number of errors.

Error 31. Linux: Config File Permission Warning

chmod 600 ~/.openclaw/openclaw.json

This restricts the file so only your user can read it, which is required for security.

The Simplest Fix: Skip the Setup Headaches Entirely

If you have spent hours debugging OpenClaw errors only to get stuck on dependencies, API keys, Docker issues, broken updates, or permission conflicts, you are not alone. OpenClaw is powerful, but self-hosting it can quickly turn into a sysadmin project instead of an AI productivity tool.

That is exactly why platforms like TryOpenClaw.io exist.

TryOpenClaw is a fully managed cloud version of OpenClaw that comes pre-configured and ready to use. Instead of manually setting up Node.js, Git, APIs, models, channels, and integrations yourself, everything is already connected and maintained for you behind the scenes.

With TryOpenClaw, you get:

No Node.js, Docker, Git, or dependency setup
No API key configuration headaches
No port conflicts, permission issues, or broken local installs
Pre-connected AI models with the ability to switch models instantly
Dedicated cloud instances with automatic recovery and maintenance
Faster onboarding for non-technical users and teams

All you have to do is:

Create an account
Choose a plan
Connect apps like Telegram or Slack
Start chatting with your AI assistant immediately

TryOpenClaw is a perfect option if you:

Are beginner or non-technical users
Want to try OpenClaw quickly
Do not want to manage servers or infrastructure yourself

Plans start at $4/month with a full money-back guarantee.

Summary

Most OpenClaw errors aren’t signs that something is fundamentally broken, they’re the normal friction of connecting several independent systems together for the first time. A wrong API key, a version mismatch, a port that didn’t release cleanly. These are all solved in a few minutes once you know what you’re looking for.

The two habits that can help you prevent the most problems: run openclaw doctor --repair before you start digging, and make changes one at a time so you can tell what broke. If your bot was working and now isn’t, the cause is almost always the last thing you changed – a new skill, an edited config, or an update.

If you’re consistently hitting walls and spending hours debugging, it might also be worth considering the cloud version at TryOpenClaw.io, which handles all the infrastructure and keeps everything pre-configured. But for most people reading this guide, your setup is one or two commands away from working exactly as it should.

Frequently Asked Questions

These are the troubleshooting steps most OpenClaw users end up needing at some point.

Why is my OpenClaw bot not responding?

The most common reason your OpenClaw bot stops responding is that the Gateway process has stopped running. Open your terminal and run openclaw doctor to check its status. If the Gateway shows as “stopped,” restart it with openclaw gateway restart. If the Gateway is running but the bot is still silent, check that your user is on the channel’s allowlist — the bot sends you a pairing code the first time you message it, and you need to approve it with openclaw pairing approve.

Why does OpenClaw say no output?

The “no output” or assistant turn failed before producing content error almost always means your AI provider rejected the request before generating anything. The two most likely causes are an invalid or expired API key, and an account with no remaining credits. Log into your provider dashboard (Anthropic Console, OpenAI Platform, etc.), check your balance, and re-copy your API key. Then run openclaw doctor --fix to sync everything.

What is the OpenClaw 1006 abnormal closure error?

Error 1006 is a WebSocket connection error that means the connection to the Gateway dropped unexpectedly — often because the Gateway process crashed or was killed by the OS. On a low-RAM VPS, this usually means the process ran out of memory. Try restarting the Gateway (openclaw gateway restart) and, if crashes keep happening, add swap space to your server and set a heap limit with openclaw configure --max-old-space-size 512.

How do you reset OpenClaw?

To reset OpenClaw’s configuration without reinstalling: run openclaw configure --reset to restore default settings, or run openclaw onboard to go through the full setup wizard again. If you want to keep your existing values and just repair broken ones, run openclaw doctor --repair. This is the safest option after an update causes issues.

How do I delete OpenClaw and start again completely?

To fully uninstall and start fresh: first uninstall the npm package with npm uninstall -g openclaw, then delete the config folder with rm -rf ~/.openclaw. On Linux, also disable the systemd service: systemctl --user disable --now openclaw-gateway. On macOS, remove the LaunchAgent: launchctl unload ~/Library/LaunchAgents/io.openclaw.gateway.plist and delete the plist file. After that, you can reinstall from scratch as if it’s a new machine.

How can I force a factory reset?

The closest thing to a factory reset without uninstalling is to back up and then remove your config file, then re-run the onboarding wizard. First rename the config as a backup: mv ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak. Then run openclaw onboard --install-daemon to generate a completely fresh config. When prompted, you can choose “use existing values” to carry over settings from your backup, or answer each question fresh to start truly from zero.

OpenClaw Errors & Fixes? 31 Common Errors and How to Fix Them