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

TL;DR: Most OpenClaw errors fall into four categories: install path problems, gateway auth token failures, model API key issues, and channel-specific misconfigurations. Run openclaw doctor first, since it catches the majority of problems automatically. This guide covers the exact commands for every error that the doctor command misses.

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. 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 the first-week setup guide 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<YOUR_TOKEN>/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

OpenClaw is designed to run locally. When users expose it to the public internet without authentication, they turn a safe local tool into an open endpoint anyone can hit.

This is a deployment mistake, not an OpenClaw bug. The gateway binds to localhost by default, which is the safe mode. The problem is that users who want remote access often forward ports or deploy to a VPS without enabling the auth token requirement.

Security researchers documented compromised third-party skills performing data exfiltration via prompt injection in early 2026. A malicious skill embeds instructions that cause the agent to leak data to an external endpoint, and it all looks like normal tool use in the session log.

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. A VPN with split tunneling keeps your gateway local while still accessible from anywhere, 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. The permanent memory setup guide covers persistence in detail if you prefer the self-hosted approach.

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. 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:

   OPENCLAW_LOG_LEVEL=debug openclaw gateway run

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.

Frequently Asked Questions

The most common questions about OpenClaw errors cover gateway token issues, Telegram setup, memory persistence, and VPS security.

Why is OpenClaw not working after installation?

OpenClaw install failures are almost always from a Node.js version below 20, npm’s global bin directory missing from PATH, or missing Linux build tools. Run openclaw doctor first, then check node --version and upgrade via nvm if needed.

How do I fix the OpenClaw gateway token error?

Newer versions use gateway.auth.token instead of the old gateway.token key. Check which is populated with openclaw config get gateway.auth.token, then run openclaw doctor --generate-gateway-token to create a fresh one.

Why does my Telegram bot ignore messages in OpenClaw?

Privacy mode is almost always the cause. Open BotFather in Telegram, select your bot, choose /setprivacy, and set it to Disabled. Verify your token is still valid: curl -s https://api.telegram.org/bot/getMe

How do I fix OpenClaw memory loss between sessions?

In-session chat history is temporary by default. Ask your agent to save key information to ~/.openclaw/workspace/MEMORY.md during conversations, or install the ClawVault plugin for structured persistence.

Is it safe to run OpenClaw on a public VPS?

Running OpenClaw with the gateway exposed to the public internet without authentication is not safe. Always require an auth token and use a VPN for remote access rather than port forwarding. The gateway’s “Refusing to bind without auth” error is the safety check working correctly.

What should I do when the OpenCLAW doctor does not fix the problem?

Enable debug logging with OPENCLAWLOGLEVEL=debug openclaw gateway run. If schema errors persist after running openclaw doctor --fix, restore from a config backup, then re-apply settings one section at a time using openclaw config set rather than direct JSON edits.

Quick Takeaways – Run openclaw doctor before anything else. It catches the majority of config and setup errors automatically. – The single most common error is a missing or misconfigured gateway auth token. Check gateway.auth.token, not gateway.token, which is the old key from pre-Moltbot versions. – Port conflicts on 9090 or 18789 are the second most common gateway failure. Use lsof -i :18789 or ss -tlnp to find what’s occupying the port. – Each messaging platform has one specific thing to check first: Telegram (privacy mode via BotFather), Discord (Message Content Intent in Developer Portal), WhatsApp (delete session files and rescan QR). – OpenClaw memory is temporary by default. Save important facts to ~/.openclaw/workspace/MEMORY.md to persist them across restarts. – More than 40,000 publicly exposed OpenClaw instances have been found with 60%+ showing exploitable vulnerabilities. Never expose your gateway without authentication, and audit every third-party skill you install.