← Back to Troubleshooting

Troubleshooting Guide

OpenClaw Troubleshooting Guide

Something's broken. Let's fix it.

This guide is organized by problem. Find your exact error, follow the steps. No fluff.

Table of Contents

Gateway API & Models Channels Memory & Context Automation Installation

Gateway Won't Start

Symptoms: You run openclaw gateway start (or the command from the wizard) and nothing happens, or you get an error immediately. Step 1: Check the error message closely.

Run this to start it with visible output: 

openclaw gateway --port 18789

Don't use start (background mode) while debugging — you need to see the output.

Step 2: Common causes: Error: Cannot find module '...' → Your install is corrupted. Reinstall: 
npm install -g openclaw@latest
ENOENT: no such file or directory, open '~/.openclaw/openclaw.json' → Config file doesn't exist. Run the onboarding wizard again: 
openclaw onboard
SyntaxError in openclaw.json → Your config file has broken JSON. Validate it at jsonlint.com or run: 
cat ~/.openclaw/openclaw.json | node -e "const fs=require('fs'); JSON.parse(fs.readFileSync('/dev/stdin','utf8')); console.log('Valid JSON')"
Step 3: Check logs. 
openclaw logs
Scroll to the bottom. The actual error is usually in the last 20 lines.

Gateway Starts But Immediately Crashes

Symptoms: Gateway starts, shows some output, then exits. Nothing responds. Most common cause: bad API key.

Check your config: 

cat ~/.openclaw/openclaw.json | grep -A5 "provider\|apiKey\|model"

Make sure your API key is actually in there and isn't a placeholder like YOURAPIKEY_HERE.

Test the key directly: 

# For Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOURKEYHERE" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-haiku-20240307","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

If you get a 401 error, your key is invalid. Get a new one from your provider's console.

Second most common cause: Node version. 
node --version

If it's below v22, upgrade. OpenClaw requires Node 22+.

Gateway Is Running But Agent Isn't Responding

Symptoms: openclaw gateway status says it's running. The Control UI at http://127.0.0.1:18789 loads. But messages in your chat app get no response. Check 1: Is the channel connected? 
openclaw channels status

Or check in the Control UI under Channels. If your channel shows as disconnected, reconnect it: 

openclaw channels login

Check 2: Are you on the allowlist?

If you've configured allowFrom, your identifier must match exactly. For Telegram, it's your username (no @). For WhatsApp, it's your number in international format (+15555550123). For Discord, it's your user ID (a long number, not your username).

Check your config: 

cat ~/.openclaw/openclaw.json | grep -A3 "allowFrom"

Check 3: Is the Gateway accessible?

For cloud/server setups — make sure your server's firewall allows traffic on the Gateway port. For local setups, this is usually not an issue.

Check 4: Check the logs in real time. 
openclaw logs --follow

Now send a message. Does anything appear in the logs? If nothing shows up at all, the Gateway isn't receiving the message. If something shows up but errors out, that tells you where the problem is.

Port Already In Use

Error: Error: listen EADDRINUSE: address already in use :::18789 Fix: Either kill what's using that port, or use a different port.

Kill the existing process: 

lsof -ti:18789 | xargs kill -9

Or just use a different port: 

openclaw gateway --port 18790

If OpenClaw is already running as a daemon and you're trying to start another instance, stop the daemon first: 

openclaw gateway stop

Gateway Keeps Disconnecting

Symptoms: The Gateway works fine for a while, then stops responding. You have to restart it manually. Fix 1: Run as a daemon (service)

If you're not already running OpenClaw as a daemon, set it up so the OS manages it: 

openclaw onboard --install-daemon

This creates a systemd service (Linux) or launchd service (macOS) that automatically restarts the Gateway if it crashes.

Fix 2: On Linux, check systemd 
# Check if the service is active
systemctl status openclaw

If it's not active, start it

systemctl start openclaw

Enable it to start on boot

systemctl enable openclaw
Fix 3: Memory issues

If the Gateway is dying after hours of use, it might be running out of memory (especially on low-RAM servers). Check: 

free -h

A $4/month Hetzner CAX11 (2GB RAM) handles most single-agent setups fine. If you're running multiple agents or heavy tool use, go to 4GB.

API Key Not Found

Errors:
  • API key not found
  • Invalid API key
  • AuthenticationError
  • 401 Unauthorized
Fix 1: Check that your key is actually in the config 
cat ~/.openclaw/openclaw.json

Look for your API key. If it's missing or shows as a placeholder, add it.

Fix 2: Check which provider is configured

If you set up Anthropic but the config references OpenAI (or vice versa), you'll get auth errors. Make sure the provider and key match.

Fix 3: Check for extra whitespace or characters

API keys are long. If you accidentally copied extra whitespace or missed a character, it won't work. Go back to your provider's dashboard, copy the key fresh, and paste it directly into the config.

Fix 4: Check your account status

If you're on Anthropic, make sure you've added credits. A newly created account with no credits will return auth-like errors even with a valid key.

Rate Limit Errors

Errors:
  • ratelimiterror
  • 429 Too Many Requests
  • RateLimitError
What this means: You're sending too many requests in a short period, or you're hitting a usage tier limit. Fix 1: Wait.

Most rate limits reset within a minute. If you hit one during a burst of messages, just wait and try again.

Fix 2: Check your usage tier.

Anthropic and OpenAI both have tiered rate limits. New accounts start on the lowest tier with the most restrictions. Adding more credits / spending more typically unlocks higher tiers automatically.

Check your tier:

Fix 3: Configure model failover.

OpenClaw supports automatic failover to a backup model when your primary hits limits. This is in the docs under Model Failover.

Model Not Found

Error: modelnotfound or the wrong model is responding. Fix: Check your model name in the config. Model names need to be exact.

Common ones: 

claude-opus-4-5         ← Anthropic
claude-sonnet-4-5       ← Anthropic
claude-haiku-4-5        ← Anthropic (faster/cheaper)
gpt-4o                  ← OpenAI
gpt-4o-mini             ← OpenAI (faster/cheaper)

Model names change when providers release new versions. If you configured a model 6 months ago and it stopped working, check your provider's current model list.

Responses Slow or Timing Out

Symptoms: Messages take 30+ seconds to get a response, or you get timeout errors. Fix 1: Switch to a faster model.

Claude Haiku and GPT-4o Mini are significantly faster than the full models. For most conversational use, the speed tradeoff is worth it: 

{
  "model": "claude-haiku-4-5"
}

Fix 2: Check your internet connection.

If you're on a cloud server, check the server's network performance. A cheap VPS in the wrong region can add meaningful latency.

Fix 3: Check if the model provider has an outage.

Check the status pages:

Discord Bot Not Responding

Symptoms: Your Discord bot is in the server, you can see it online, but messages get no response. Check 1: Message Content Intent is enabled

This is the #1 missed step. Go to discord.com/developers/applications → your app → Bot → Privileged Gateway Intents → enable Message Content Intent.

Without this, your bot can see that messages were sent but can't read what they say. Restart the Gateway after enabling it.

Check 2: Is the bot in the right channel?

The bot needs View Channel and Send Messages permissions in the specific channel you're messaging it in. Check channel permissions (right-click the channel → Edit Channel → Permissions).

Check 3: Are you messaging it correctly?

In a server channel, the bot may require you to @mention it, not just type in the channel. Try:

@YourBotName hello

In DMs, no mention needed — but make sure you're DMing the bot directly.

Check 4: Is your user ID on the allowlist?

Your Discord user ID is a long number — not your username like jkirby. To find it: Discord Settings → Advanced → enable Developer Mode. Then right-click your own username and "Copy User ID."

Check 5: Check the Gateway logs 
openclaw logs --follow
Send a message in Discord and watch the logs. If you see the message being received, the problem is downstream. If you see nothing, Discord isn't connected to the Gateway properly.

Telegram Bot Not Responding

Check 1: Bot token is correct

Go to BotFather in Telegram, send /mybots, select your bot, then "API Token." Copy it fresh and update your config.

Check 2: Did you start a conversation with the bot?

Telegram bots can't initiate conversations — you have to message them first. Open the bot in Telegram and hit Start or send any message.

Check 3: Is the bot token in your config? 
cat ~/.openclaw/openclaw.json | grep -A5 "telegram"
Check 4: Username in allowFrom

If you're using allowFrom, make sure it's your Telegram username without the @. Find your username at Telegram Settings → your profile.

WhatsApp Disconnected

Symptoms: WhatsApp was working, now it's not. You may see "Session expired" in the logs. What happened: WhatsApp Web sessions expire periodically, especially if you haven't used the connection in a while, or if you logged out of WhatsApp Web on another device. Fix: Re-pair 
openclaw channels login

Select WhatsApp. Scan the new QR code with your phone. Connection restored.

To reduce this happening: Keep at least occasional traffic through the WhatsApp channel. Long idle periods sometimes trigger session expiry.

Agent Responds to Some Messages Not Others

Most common cause: allowFrom is filtering you out in some contexts.

If you're messaging from a group chat vs. a DM, the identifiers might differ. Check your config and make sure the identifier for your group context is included.

Second cause: require mention is on for groups.

In group chats, you may need to @mention your agent for it to respond. This is a security feature. Check your config: 

{
  "channels": {
    "discord": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

If you want it to respond to everything in a specific group, you can turn this off per-channel.

Not Allowed / Access Denied

Error message from your agent: Something like "Sorry, I'm not able to help with that" or "Access denied." This is the allowFrom filter working. Your identifier isn't on the allowlist.

For each channel type, the identifier is different:

  • Telegram: your @username (no @)
  • WhatsApp: your phone number with country code (+15555550123)
  • Discord: your user ID (long number, not your username)
Update allowFrom in your config and restart the Gateway.

Agent Doesn't Remember Previous Conversations

Symptoms: Every time you start a conversation, it's like the first time. It doesn't know your name, your projects, nothing. Fix 1: Check that MEMORY.md exists

Look in your agent's workspace folder for a MEMORY.md file. If it's not there, ask your agent:

"Please create a MEMORY.md file in your workspace and save some basic facts about me."

Fix 2: Check that the workspace path is correct

In your config, check where the agent's workspace is pointing. If the path is wrong, it's writing memory somewhere that nothing reads.

Fix 3: Explicitly ask it to remember things

Early on, you need to tell your agent to save things:

"Remember that I'm based in Los Angeles and I run a SaaS marketing consultancy."

It'll write this to MEMORY.md. Over time, it builds automatically.

Agent Forgot Something Important

What happened: It knew something, now it doesn't. Open MEMORY.md and check. It's a file. Read it. If the information isn't there, it was never saved to memory — it was only in the conversation context (which has limits). Fix: Re-tell it and explicitly ask it to save:
"I want you to add to your MEMORY.md that I'm allergic to meetings before 10am and I only check messages twice a day."

Going forward, get in the habit of ending important conversations with:

"Save anything important from this conversation to your memory."

Context Feels Wrong or Outdated

Symptoms: Agent seems to be operating on old information. Thinks you're working on a project you finished months ago. Fix: Read and edit MEMORY.md directly.

The file is at your agent's workspace path. Open it in any text editor. Delete what's stale. Add what's current. Your agent reads it fresh each session.

You can also ask your agent:

"Read your MEMORY.md to me. I want to update it."

Then walk through it together.

Cron / Scheduled Messages Not Firing

Symptoms: You set up a morning briefing or scheduled task and it never runs. Check 1: Is the Gateway running?

Cron jobs need the Gateway to be up. If your laptop was closed or your server rebooted, the Gateway needs to be restarted. Use the daemon install to make this automatic: 

openclaw onboard --install-daemon

Check 2: Check the timezone

If your cron is set for 8am but you didn't specify your timezone, it might be running at 8am UTC — which could be 1am where you are.

Tell your agent:

"My timezone is America/Los_Angeles. Make sure all scheduled tasks use this timezone."

Or set it in your config: 

{
  "timezone": "America/Los_Angeles"
}

Check 3: List your active crons 
openclaw cron list

This shows you what's scheduled and when it last ran.

Check 4: Test the cron manually

Ask your agent:

"Run my morning briefing right now, regardless of schedule."

If that works, the cron job itself is fine — it's a timing or Gateway uptime issue.

Heartbeat Not Running

Same checklist as crons above — heartbeat needs the Gateway up.

Also: heartbeat is configured in your HEARTBEAT.md file (if you're using the agent workspace pattern) or in your config. Check that the file exists and has actual instructions.

To test: 

openclaw gateway status

Then trigger a heartbeat manually:

"Run your heartbeat check now."

Morning Briefing Stopped Working

This is almost always one of these three things:

  1. Gateway went down — check openclaw gateway status
  2. Timezone drifted — your server or cron has a timezone mismatch
  3. Channel connection expired — especially WhatsApp sessions expire
Restart the Gateway, re-pair if needed, and check that the cron is still listed: 
openclaw cron list

If the briefing job is gone, ask your agent to recreate it.

"openclaw: command not found"

Means: The OpenClaw binary isn't in your PATH. Fix: 
# Find where npm puts global binaries
npm config get prefix

The binary is in <prefix>/bin/


Add that to your PATH

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On macOS with default setup, this is usually /usr/local/bin (already in PATH) or /opt/homebrew/bin (if you used Homebrew's Node).

Node Version Error

Error: Something like engine "node" is incompatible with this module. Expected version ">=22.0.0" Fix: Upgrade Node.

The easiest way to manage Node versions is nvm:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Install and use Node 22

nvm install 22
nvm use 22
nvm alias default 22

Verify

node --version  # should show v22.x.x

Then reinstall OpenClaw: 

npm install -g openclaw@latest

Permission Errors During Install

Error: EACCES: permission denied when running npm install -g Do NOT use sudo npm install. That creates more problems. Fix: Configure npm to use a directory you own 
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g openclaw@latest

Still stuck?

If none of this fixed it, run: 

openclaw doctor

This is OpenClaw's built-in diagnostic tool. It checks your setup, flags common issues, and tells you what's wrong in plain language.

Also check:

This guide is maintained as part of the learn.kirbyholdings.ltd course platform. Found an error or missing case? Let us know.