OpenClaw Not Working? Every Error I Hit and How I Fixed It

When OpenClaw hit 250,000 GitHub stars, I figured setup would be the easy part. I was wrong.

Between gateway auth failures, port conflicts, and Telegram bots that go silent for no obvious reason, I spent way too many hours in the terminal before it all worked the way I expected.

This guide covers the most common OpenClaw errors from install through runtime, what causes each one, and the exact commands to fix them.

I’ve organized everything by the stage where it usually hits, so you can skip straight to whatever’s breaking for you right now.

If you’re new to the platform and want background on how OpenClaw’s agent architecture works, that’s a good place to start before coming back here.

One thing worth knowing upfront: OpenClaw is still evolving fast. The project was renamed twice in three months. It was Clawdbot, then Moltbot (after trademark complaints in late January 2026), and now OpenClaw.

Each rename came with config key changes that silently break existing setups. If you’ve been running an older version, some of these fixes will look familiar.

Before anything else, run: `openclaw doctor`. It catches a surprising number of problems automatically and usually tells you exactly what’s wrong before you have to go hunting.

Why OpenClaw Is Not Working at Install or Startup

OpenClaw installation failures come from three sources: a Node.js version that’s too old, npm’s global bin directory missing from PATH, or Linux build tools that aren’t installed.

The most common thing I see: someone installs OpenClaw, types `openclaw`, and gets “command not found.” This isn’t an OpenClaw bug. npm installs global packages to a bin directory that most systems don’t include in PATH by default.

Here’s what to check, in order:

1. 1. Check your Node version: `node –version`. OpenClaw requires Node 20 or newer. If you’re on anything older, that’s your first problem.
   2. Upgrade via nvm if needed: `nvm install 20 && nvm use 20`
   3. Fix PATH by adding this to your shell config (`~/.bashrc` or `~/.zshrc`):

“` export PATH=”$(npm config get prefix)/bin:$PATH” “`

1. Reload your shell: `source ~/.zshrc`
2. Confirm OpenClaw is now visible: `which openclaw`

On Linux (Debian/Ubuntu), native module compilation failures during install mean build tools are missing. Fix with: “` sudo apt install build-essential git python3 “`

After install, the setup wizard writes an `openclaw.json` config file. If you quit the wizard early or something went wrong midway, that file can be malformed.

Validate it with: “` python3 -m json.tool ~/.openclaw/openclaw.json “` If it throws a parse error, run `openclaw doctor –fix` to attempt auto-repair. If that doesn’t resolve it, check our full installation walkthrough for a clean setup path.

What is openclaw doctor: A built-in diagnostic command that validates your config, checks for conflicting processes, and flags known issues. Run it before anything else when something breaks.

Gateway Errors and How to Diagnose Them

OpenClaw gateway failures come from four sources: port conflicts, missing or outdated auth tokens, stale PID lock files, or an uninitialized gateway mode.

The gateway is the core of OpenClaw. Every messaging channel, cron job, and model connection runs through it. When it doesn’t start, nothing else works.

Here’s a quick reference for the most common gateway errors I’ve hit:

The Token Problem (Most Common)

This one gets more people than any other error. Older versions of OpenClaw used `gateway.token` as the config key. Newer versions moved to `gateway.auth.token`.

If you’re seeing the token missing error after an upgrade, the old key is being silently ignored.

Check which key you’re using: “` openclaw config get gateway.token openclaw config get gateway.auth.token “`

If the first returns a value but the second is empty, migrate it: “` openclaw config set gateway.auth.token “$(openclaw config get gateway.token)” “`

Or generate a fresh token in one command: “` openclaw doctor –generate-gateway-token “`

Port Conflicts

OpenClaw uses ports 9090 and 18789. Find what’s occupying them: “` ss -tlnp | grep -E ‘9090|18789’ “` Or on macOS: “` lsof -i :18789 “` Kill the conflicting process, or move OpenClaw to a different port: “` openclaw config set gateway.port 9091 “`

Stale PID Lock

If OpenClaw crashed hard, it may have left a lock file that blocks the next startup.

Confirm no process is still running first: “` ps aux | grep openclaw “` If nothing comes back, remove the lock: “` rm ~/.openclaw/gateway.pid “` Then restart: `openclaw gateway restart`

Your LLM Connection Keeps Failing

LLM connection errors in OpenClaw come from three sources: invalid or expired API keys (401), account tier restrictions (403), and rate limiting (429). Each has a different fix.

When I first connected Claude to OpenClaw, I hit a 401 within five minutes because I’d copied the API key wrong by one character. After that I started verifying keys directly against the provider dashboard before pasting them anywhere.

For 401 errors: Check the key character-for-character against your provider’s dashboard. Copy-pasting from a document that reformatted the key is a common source of silent errors.

For 403 errors: Your account tier doesn’t have access to the model you’re requesting. Check which models your API tier allows and adjust the model name in config accordingly.

For 429 errors: Rate limits. Add a rate-limiting proxy or reduce concurrency in OpenClaw’s settings.

There’s a less obvious one worth flagging: the “All models failed” error, which happens when OpenClaw sends experimental beta headers to providers that don’t accept them.

The fix is to clear the beta features list: “` openclaw config set beta_features [] “`

If you’re running local Ollama models and hitting “Model not allowed,” it’s almost always a case-sensitivity mismatch. OpenClaw treats model names as case-sensitive strings.

Vague config: “` model: “llama3” “`

Specific config (using exact `ollama list` output): “` model: “llama3.2:latest” “`

The difference looks minor. To OpenClaw it’s a completely different model name that doesn’t match anything in its allowlist.

Channel-Specific Failures by Platform

Each messaging platform OpenClaw supports has one specific misconfiguration that silently kills the connection. Knowing which one to check first saves hours of trial and error.

I’ve tested OpenClaw across all four main channels and found that most “bot is online but won’t respond” problems trace back to the same handful of root causes.

Telegram is generally the cleanest channel to set up, but privacy mode catches almost everyone the first time. When privacy mode is on, bots can only read messages that directly mention them.

OpenClaw expects to read all messages. Fix it through BotFather: open BotFather in Telegram, select your bot, choose `/setprivacy`, set to Disabled.

You can verify your Telegram token is still valid without even touching OpenClaw: “` curl -s https://api.telegram.org/bot/getMe “` If you get a JSON response with your bot’s details, the token is fine. If you get `{“ok”:false}`, the token is expired or wrong.

Discord trips most people on the Message Content Intent setting. It’s buried in the Discord Developer Portal under your bot’s settings. Without it enabled, your bot literally cannot read what users type. It’s not a permissions issue, it’s a gateway intent, and Discord won’t surface it in any error message. Enable it under Privileged Gateway Intents.

The Security Problem Nobody Mentions

More than 40,000 OpenClaw instances are running exposed on the public internet, and over 60% of them have vulnerabilities that could let attackers take control of the setup.

This isn’t a knock on the project. It’s a warning about how people deploy it. OpenClaw is designed to run locally. The gateway binds to localhost by default, which is safe.

The problem is that many users forward ports or deploy to a VPS to access OpenClaw from anywhere, and they do it without enabling authentication.

Security researchers found that compromised third-party skills were performing data exfiltration in February 2026, with prompt injection as the underlying mechanism.

A malicious skill can embed instructions that cause your agent to leak data or take unintended actions, and it all looks normal in the UI.

Three things to do if you’re running OpenClaw right now:

1. Never bind the gateway to a non-loopback interface without an auth token. The error “Refusing to bind gateway without auth” is the safety check doing its job. Don’t suppress it.
2. Audit every third-party skill you’ve installed. If a skill came from an unverified source, remove it. Skills that perform data exfiltration look completely normal to the user.
3. Use a VPN to access your OpenClaw instance remotely instead of opening the gateway to the public internet. I use Surfshark for this since it handles split tunneling cleanly for home-server setups without requiring port forwarding.

If you’re running OpenClaw on a VPS for remote access and haven’t addressed this yet, now is the right time.

Memory Resets and Context Loss Between Sessions

OpenClaw loses memory between sessions because in-session chat history is temporary by default. Only files saved to the workspace directory persist across gateway restarts.

This one confused me for longer than I’d like to admit. I’d have a detailed conversation, shut down the gateway, restart it the next day, and OpenClaw had no memory of anything. I assumed there was a bug. There wasn’t. In-session history is ephemeral by design.

The fix is to explicitly save important information during conversations by asking your agent to write to a memory file: “` Save the following to ~/.openclaw/workspace/MEMORY.md: [key facts to remember] “`

For more structured persistence, the ClawVault and Cognee plugins handle this better than manual file writes. ClawVault is lightweight and built specifically for this use case.

Context loss mid-conversation (not just between sessions) is a different problem: context window compaction. When token counts get high, older parts of the conversation get pruned.

The answer is the same: write key facts to files proactively rather than relying on the conversation history staying intact.

If managing all of this sounds like a lot of overhead on top of everything else in this guide, that’s worth taking seriously. ClawTrust is a managed OpenClaw hosting service that handles memory persistence, gateway configuration, auth setup, and most of what this guide covers, without requiring you to manage any of it yourself.

For teams or people who want the capability without the maintenance, it’s the path of least friction. You can also explore what a fully configured setup enables in our OpenClaw automation ideas roundup.

Post-Upgrade Errors and Config Drift

Most OpenClaw upgrade problems come from renamed config keys and stricter schema validation in newer versions. Running `openclaw doctor –fix` immediately after upgrading resolves the majority of them.

If you’ve been running this since the Clawdbot or Moltbot era, your config may have key names that no longer exist, keys that moved to different locations, and default values that changed between versions without announcement.

The reliable approach:

1. 1. Back up your config before any upgrade: `cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup`
   2. Run the upgrade
   3. Immediately run: `openclaw doctor –fix`
   4. If errors persist, enable debug logging: “` OPENCLAWLOGLEVEL=debug openclaw gateway run “`
   5. Use `openclaw config get/set` for all modifications, not direct JSON edits. Manual edits frequently break schema validation in ways that produce cryptic error messages.

If you’re seeing a cascade of schema errors and `openclaw doctor –fix` can’t resolve them, restore from your backup, note which settings you’ve customized, then start fresh with a minimal valid config and re-apply settings one section at a time.

Cron Jobs That Never Execute

OpenClaw cron jobs silently fail when the scheduler is disabled, the gateway isn’t running as a persistent service, or the delivery target points to a misconfigured channel.

Check these three things in order:

1. Confirm the scheduler is on: `openclaw config get cron.enabled` should return `true`
2. Confirm the gateway is running as a persistent service, not a one-shot process. `openclaw status` will tell you
3. Check the `delivery.to` field in your job definition. It must point to a valid channel and session identifier

One pattern that trips people up: a HEARTBEAT.md file structured so the “HEARTBEATOK” message fires before the agent checks for actual work. OpenClaw sees the heartbeat output and stops processing.

Restructure HEARTBEAT.md to check for pending tasks first, then send HEARTBEATOK as the final message only.

Diagnostic Commands Quick Reference

These are the OpenClaw commands I run every time something breaks. Start with `openclaw doctor` and work down the list.