OpenClaw Troubleshooting: Common Errors and Fixes

Running into issues while installing or using OpenClaw is completely normal. This article compiles the most frequently encountered problems from the community along with their solutions, so you can diagnose and fix things quickly. Before diving into troubleshooting, it's highly recommended to run OpenClaw's built-in diagnostic tool first. For additional help, visit OpenClaw.

First Line of Defense: openclaw doctor

OpenClaw ships with a powerful self-diagnostic command that automatically checks your runtime environment, configuration files, network connectivity, and more:

openclaw doctor

The command produces a detailed report covering:

• Whether the Node.js version meets the requirements
• Whether the configuration file exists and is valid
• Whether the Gateway service is running
• Connection status for each configured AI provider
• Connection status for each configured channel

Most issues can be pinpointed quickly from the openclaw doctor output. It's a good habit to run it first whenever something goes wrong.

Node.js Version Too Old

Symptoms:

Error: OpenClaw requires Node.js >= 22.0.0, current version: 18.x.x

Or you see syntax errors or missing module exceptions during installation.

Fix:

OpenClaw requires Node.js 22 or later. Check your current version:

node --version

If it's below 22, upgrade:

# Using the NodeSource repository (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Or using nvm
nvm install 22
nvm use 22
nvm alias default 22

After upgrading, reinstall OpenClaw:

npm install -g openclaw@latest

Gateway Token Missing or Invalid

Symptoms:

Error: Gateway token is missing or invalid

Or the Dashboard shows "Unauthorized."

Fix:

The Gateway token is automatically generated during the initial openclaw onboard run and saved in the configuration file. Check the file:

cat ~/.config/openclaw/openclaw.json5

Confirm that the gateway section contains a valid token field. If the token is missing or corrupted, regenerate it:

openclaw gateway reset-token

Then restart the Gateway:

openclaw gateway restart

If you manage the service with systemd:

sudo systemctl restart openclaw

Port 18789 Already in Use

Symptoms:

Error: listen EADDRINUSE: address already in use :::18789

Fix:

First, find out what's using the port:

# Linux
sudo lsof -i :18789
# or
sudo ss -tlnp | grep 18789

Possible scenarios:

1. Another OpenClaw instance is already running: Stop the existing instance first

openclaw gateway stop
# Or force-kill the process
kill $(lsof -t -i:18789)

2. A different application is using the port: Change OpenClaw's port

nano ~/.config/openclaw/openclaw.json5

{
  gateway: {
    port: 18790,  // Use a different port
  }
}

If you've set up an Nginx reverse proxy, remember to update the upstream address in your Nginx configuration as well.

API Key Errors

Symptoms:

Error: 401 Unauthorized - Invalid API key

Or the AI model fails to respond to messages.

Fix:

Check your API key configuration step by step:

nano ~/.config/openclaw/openclaw.json5

Anthropic Claude:

• The key should start with sk-ant-api03-...
• Verify at console.anthropic.com that the key hasn't expired and has available credits

OpenAI:

• The key should start with sk-proj-... or sk-...
• Confirm the account has a positive balance

Ollama (local models):

• The apiKey can be any non-empty string, such as "ollama"
• Make sure the Ollama service is running: curl http://localhost:11434/api/tags

A common mistake is accidentally copying extra whitespace before or after the key, or forgetting to wrap it in quotes in the configuration file.

Channel Connection Failures

Telegram connection failure:

Error: Telegram Bot API: 401 Unauthorized

Fix:

• Verify the Bot Token is correct and hasn't been revoked
• Check the bot's status through BotFather: send /mybots
• If the token was compromised, regenerate it with /revoke

Discord connection failure:

Error: Discord Gateway: Authentication failed

Fix:

• Verify the Bot Token is correct
• In the Discord Developer Portal, confirm the bot has the Message Content Intent enabled
• Make sure the bot has been invited to the target server

WhatsApp connection failure:

WhatsApp uses QR code authentication. If the connection drops:

openclaw channel reconnect whatsapp

Then follow the prompts to scan the QR code again.

Configuration File Syntax Errors

Symptoms:

Error: Failed to parse config file
SyntaxError: Unexpected token ...

Fix:

OpenClaw uses the JSON5 format for configuration files, which is more lenient than standard JSON (it supports comments and trailing commas), but still has syntax rules. Common mistakes include:

• Missing commas between fields
• String values not wrapped in quotes
• Mismatched braces

You can validate the configuration with:

openclaw doctor

The diagnostic tool will point to the exact location of errors in the configuration file. If the file is badly corrupted, back it up and reinitialize:

cp ~/.config/openclaw/openclaw.json5 ~/.config/openclaw/openclaw.json5.bak
openclaw onboard

Out-of-Memory Crashes

Symptoms: The Gateway restarts frequently, and the logs show JavaScript heap out of memory.

Fix:

Increase the Node.js memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"

If you manage the service with systemd, add the environment variable to the service file:

Environment=NODE_OPTIONS=--max-old-space-size=4096

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart openclaw

If the problem persists, consider upgrading your server's RAM.

Getting More Help

If none of the solutions above resolve your issue, here are additional resources:

1. Official documentation: The OpenClaw official documentation has the most comprehensive configuration reference
2. Search GitHub Issues: Search for your error message on the OpenClaw GitHub repository — chances are someone has already encountered the same problem
3. File a new Issue: If you've confirmed it's a bug, include the full output of openclaw doctor and relevant logs when submitting
4. Check the logs: Detailed logs can help pinpoint deeper issues

# View real-time Gateway logs
sudo journalctl -u openclaw -f

# View the last 100 lines
sudo journalctl -u openclaw -n 100

Keeping OpenClaw up to date is also important, as many bugs are fixed in newer releases:

npm update -g openclaw@latest