OpenClaw Not Working in 2026: Fix 7 Common Errors Step by Step
Triage First: Before reading the full guide, run these commands immediately. They cover 80% of all OpenClaw issues and take less than 60 seconds:
openclaw status
openclaw gateway status
openclaw doctor
openclaw logs --follow
If openclaw doctor flags a blocking error, fix that first before anything else. The doctor command knows about all common misconfigurations.
OpenClaw is powerful but complex. It involves multiple moving parts: a Node.js gateway process, API authentication for one or more AI providers, channel integrations (Telegram, WhatsApp, Discord), scheduled jobs, and a persistent memory system. When something breaks, it could be any layer. This guide systematically covers every common failure mode, from first install errors to runtime issues that appear after months of working perfectly.
We have organized these by frequency — the errors most users encounter are covered first. Each section includes diagnostic commands, the exact error message you will see, root cause explanation, and step-by-step fix instructions.
Error 1: Gateway Not Starting
Common error messages:
- Gateway start blocked: set gateway.mode=local
- refusing to bind gateway ... without auth
- another gateway instance is already listening
- EADDRINUSE: port 18789 already in use
Fix A Gateway Mode Not Set
# Check current config
openclaw config show | grep gateway
# Set to local mode
openclaw config set gateway.mode local
# Restart
openclaw gateway restart
This happens when gateway.mode was never configured during onboarding or was accidentally set to "remote" mode.
Fix B Port Already in Use
# Find what is using port 18789
lsof -i :18789
# or
netstat -tlnp | grep 18789
# Kill the process (replace PID with actual process ID)
kill -9 [PID]
# Or change the gateway port in config
openclaw config set gateway.port 18790
# Restart with new port
openclaw gateway restart
This typically means a previous gateway instance did not shut down cleanly. The lsof command will show you exactly which process to kill.
Fix C Auth Not Configured
# Re-run onboarding to set up auth
openclaw onboard
# Or configure auth manually
openclaw configure --auth
OpenClaw refuses to bind on non-loopback interfaces without authentication. Run onboarding again to reconfigure.
Error 2: No Replies from the Agent
Symptoms: You send a message but the agent never responds. No error shown. The bot appears online.
Diagnose First
# Watch logs while you send a message
openclaw logs --follow
# Check channel status
openclaw channels status --probe
# Check pairing status (for DM channels)
openclaw pairing list --channel telegram
The log stream will show you exactly what happens when your message arrives. Common log signatures to look for:
drop guild message (mention required)
Cause: In Discord servers, OpenClaw requires you to @mention the bot. DMs work without mention, but server messages need it.
Fix: Type @YourBotName /status in Discord. Or configure channels.discord.activation: "always" to remove the mention requirement.
pairing request / sender unapproved
Cause: Your sender ID is not in the approved list. OpenClaw has a pairing system to prevent unauthorized users from controlling the agent.
Fix: Check your DMs from the bot — it should have sent a pairing request. Approve it. Or add yourself to the allowlist: openclaw pairing approve [senderId].
blocked / allowlist miss
Cause: Your phone number or username is not in the channel's allowlist.
# Find your sender ID
/whoami
# Add yourself (from CLI)
openclaw allowlist add --channel telegram --sender [your-id]
API auth error / 401 Unauthorized
Cause: Your API key for Claude or OpenAI is invalid or expired.
# Re-run onboarding to update API keys
openclaw onboard
# Or update the key directly
openclaw secrets set ANTHROPIC_API_KEY sk-ant-your-new-key
Error 3: API Authentication Failures
Common error messages:
- HTTP 401: invalid_api_key
- AuthenticationError: incorrect API key provided
- HTTP 403: permission_error
- credential validation failed
# Check which credentials are configured
openclaw secrets list
# Test Anthropic API key
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{"model":"claude-haiku-4","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
# Update a secret
openclaw secrets set ANTHROPIC_API_KEY sk-ant-your-new-key
openclaw secrets set OPENAI_API_KEY sk-your-openai-key
# Clear and re-enter a credential
openclaw secrets delete ANTHROPIC_API_KEY
openclaw onboard # will prompt for new key
Anthropic Issues
Get key at: console.anthropic.com → API Keys. Key starts with sk-ant-. If billing is not set up, API calls fail even with valid key.
OpenAI Issues
Get key at: platform.openai.com → API Keys. Key starts with sk-. Need at least $5 credit. Check usage limits in dashboard.
Ollama (Local)
No API key needed. Just ensure ollama serve is running on port 11434. Test: curl localhost:11434/api/tags
Error 4: Channel Connection Problems
Symptoms: Telegram bot not responding, WhatsApp link expired, Discord bot offline.
Telegram Not Working
# Check Telegram channel status
openclaw channels status --probe
# Verify bot token is correct
openclaw secrets list | grep TELEGRAM
# Re-configure Telegram
openclaw configure --channel telegram
# Test by sending a message
openclaw message send --channel telegram --target @yourusername --message "Test"
Common cause: bot token was regenerated in BotFather (happens if you click "Revoke token" accidentally). Get a new token and update: openclaw secrets set TELEGRAM_BOT_TOKEN your-new-token
WhatsApp QR Code Expired
# Re-generate the QR code
openclaw qr --channel whatsapp
# Or open the dashboard to scan
openclaw dashboard
# Navigate to Channels → WhatsApp → Reconnect
WhatsApp sessions expire. Re-scan the QR code to reconnect. This is a WhatsApp limitation, not an OpenClaw bug.
Discord Bot Offline
# Check Discord token
openclaw channels status --probe --channel discord
# Common error: 401 Forbidden = invalid token
# Common error: missing_scope = bot permissions missing in Discord dev portal
# Verify bot is invited with correct permissions
# Bot needs: Read Messages, Send Messages, Read Message History
# Slash commands need: applications.commands scope
If the bot was kicked from the server or permissions were changed, re-invite it using the OAuth URL from the Discord Developer Portal with all required scopes.
Error 5: Node.js Version Issues
Common error messages:
- Error: Cannot find module '...'
- SyntaxError: Unexpected token '?'
- Node.js version 18 required, but 16 found
- ERR_REQUIRE_ESM: require() of ES Module not supported
OpenClaw requires Node.js 22 or newer. This is a hard requirement. Many systems come with Node 18 or even 16 by default, especially on older Ubuntu, macOS with Homebrew not updated, or Windows with a legacy install.
# Check your Node.js version first
node --version
# Must show v22.x.x or higher
# macOS: Update via Homebrew
brew install node@22
brew link node@22 --force
# Linux: Update via NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# Windows: Download from nodejs.org, or use nvm-windows
# https://nodejs.org/en/download/ → choose v22 LTS
# Using nvm (any platform)
nvm install 22
nvm use 22
nvm alias default 22
# Verify
node --version # should show v22.x.x
npm --version # should show v10.x.x or higher
# Reinstall OpenClaw after Node update
npm install -g openclaw
Error 6: Cron Jobs and Heartbeat Not Firing
Symptoms: Scheduled tasks never run. Heartbeat messages stop arriving. No proactive activity.
# Check cron status
openclaw cron status
# List all cron jobs
openclaw cron list
# Check recent run history
openclaw cron runs --limit 20
# Look at the logs for cron-related messages
openclaw logs --follow | grep cron
cron: scheduler disabled; jobs will not run automatically
Fix: Enable the cron scheduler in your config:
openclaw config set cron.enabled true
heartbeat skipped — reason=quiet-hours
Fix: Your heartbeat active hours are configured to exclude the current time. Check your HEARTBEAT.md and heartbeat.activeHours config. Or simply wait until your configured active window.
unknown accountId — heartbeat delivery failed
Fix: The account ID configured for heartbeat delivery no longer exists. Re-run channel setup to update the delivery target. Check your HEARTBEAT.md for the configured recipient.
requests-in-flight — heartbeat deferred
Cause: Another task is running in the main lane, so the heartbeat is deferred to avoid interference. Not an error — it will fire when the current task completes.
Error 7: Browser Tool and Dashboard Not Working
Symptoms: "Browser tool fails", "Failed to start Chrome CDP", Dashboard won't load, Control UI shows blank page.
# Check browser tool status
openclaw browser status
# Check dashboard connectivity
openclaw gateway status
# Look for: Dashboard: http://127.0.0.1:18789
# Run doctor for browser-specific checks
openclaw doctor
# Try opening dashboard manually
openclaw dashboard
# If on Linux, install missing Chrome dependencies
sudo apt-get install -y \
libgbm-dev libxss1 libatk-bridge2.0-0 \
libdrm2 libxkbcommon0 libgtk-3-0
Failed to start Chrome CDP on port — chrome not found
Fix: Install Chrome or Chromium and update the path in config: openclaw config set browser.executablePath /usr/bin/chromium-browser
Chrome extension relay running but no tab connected
Fix: Install the OpenClaw Chrome extension from the extensions page and open a browser tab. The extension must be active for relay mode to work.
Dashboard: device identity required
Fix: The Control UI requires a secure (HTTPS) or localhost context to complete device auth. Access it at http://127.0.0.1:18789 not http://0.0.0.0:18789.
Master Diagnostic Ladder
When OpenClaw is not working and you are not sure where to start, run this complete diagnostic sequence in order:
# Step 1: Quick overview
openclaw status
# Step 2: Full status report
openclaw status --all
# Step 3: Test gateway reachability
openclaw gateway probe
# Step 4: Check gateway runtime state
openclaw gateway status
# Step 5: Run automated health check
openclaw doctor
# Step 6: Test channel connectivity
openclaw channels status --probe
# Step 7: Watch live logs while testing
openclaw logs --follow
# Good outputs to look for:
# openclaw status → configured channels, no auth errors
# openclaw gateway status → Runtime: running, RPC probe: ok
# openclaw doctor → no blocking errors
# openclaw channels status → connected/ready
# openclaw logs → steady activity, no repeating fatal errors
Post-Fix Verification: How to Confirm Everything Works
After applying any fix, always verify the entire system is healthy before considering the issue resolved. This prevents the frustrating scenario of thinking the problem is fixed, only to discover it comes back five minutes later.
Complete Verification Sequence
# Run the full diagnostic ladder
openclaw status # expect: channels listed, no errors
openclaw gateway status # expect: Runtime: running, RPC probe: ok
openclaw doctor # expect: no blocking errors
openclaw channels status --probe # expect: connected/ready
# Send a test message from each channel
# (in Telegram/WhatsApp/Discord, send:)
/status # should get a system status reply
/whoami # should show your sender ID
hello # should get a response from the AI
# Check the last 50 log lines for any errors
openclaw logs --lines 50
How VPN Connections Affect OpenClaw Stability
A frequently overlooked factor in OpenClaw instability is the quality of your internet connection to the AI API endpoints. If you are running OpenClaw at home on a consumer ISP, or in a country with suboptimal routing to Anthropic or OpenAI data centers (US/EU), every API call adds unpredictable latency. When latency spikes cause API timeouts, OpenClaw logs confusing error messages that look like auth failures but are actually just network timeouts.
Additionally, some ISPs in Asia, the Middle East, and parts of Europe throttle or inspect HTTPS traffic to well-known AI API endpoints. This can cause intermittent failures that are nearly impossible to debug without understanding the network layer. A VPN with optimized routing to US/EU data centers resolves this class of problem entirely — your traffic routes through a clean path rather than through your ISP's potentially problematic network.
VPN07 — Keep OpenClaw Always Connected
Stable API connections in 70+ countries, 1000Mbps gigabit speed
VPN07 is the trusted choice for power users running AI agents globally. Our 1000Mbps nodes in 70+ countries ensure your OpenClaw requests always reach Anthropic and OpenAI APIs through clean, fast routes — dramatically reducing timeout errors and improving agent reliability. Ten years of operation, no logs, 30-day refund.
Related Articles
OpenClaw Token Limit: Switch Claude to OpenAI Fast
Hit your Claude API quota? This guide covers every method to switch providers and keep running.
Read More →OpenClaw Commands 2026: Every CLI & Slash Command
The complete reference for all OpenClaw commands — from openclaw onboard to /compact.
Read More →