ClawAid → OpenClaw Not Working

OpenClaw Not Working?
Complete Troubleshooting Guide

Every common OpenClaw problem, diagnosed and fixed. Updated March 2026.

⚡ Skip the Manual — Auto-Fix Everything

ClawAid scans your system, finds the root cause, and fixes it. One command:

npx clawaid

94% fix rate across 19,000+ users. Free, no API key needed.

📋 Jump to Your Issue

Installation Fails

openclaw: command not found

Very Common

Node.js/npm installed OpenClaw but your shell can't find it. This is a PATH issue.

# Find where openclaw was installed
npm list -g --depth=0 2>/dev/null | head -1

# Typical fix — add npm global bin to PATH
export PATH="$(npm config get prefix)/bin:$PATH"

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

Install script fails halfway

Re-run with verbose output to see the exact failure:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Gateway Won't Start

Gateway "not running" / crashes on start

Very Common

Multiple possible causes: port conflict, corrupt config, stale service file, or Node.js version.

→ Full gateway troubleshooting guide

Quick check:

openclaw status
openclaw doctor
openclaw logs --follow

Config Errors

Invalid JSON / unknown fields / validation errors

Config

→ Full config troubleshooting guide

Quick fix:

# Validate
openclaw doctor

# Reset if needed
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
openclaw setup

Network / Proxy Issues

AI just spins / "connection refused" / timeout errors

Network

Common in China, corporate networks, or when using VPN/proxy tools:

# Check if proxy is set
echo $HTTP_PROXY $HTTPS_PROXY

# If proxy is dead, clear it
unset HTTP_PROXY HTTPS_PROXY
openclaw gateway restart

# If you need a proxy (e.g., in China), make sure it's running
# Common setup: Clash on port 7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
openclaw gateway restart

⚠️ The LaunchAgent plist also has its own environment variables — they override shell settings:

# Check plist proxy settings (macOS)
/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables" \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

Model Errors (HTTP 400 / 401 / 429)

HTTP 400 — Bad model ID

Model

Your provider doesn't recognize the model string. Each provider has its own format.

# Check current model
openclaw config get models.primary

# Fix with a known-good model
openclaw config set models.primary "openai/gpt-4o"
openclaw gateway restart

HTTP 401 — Invalid API key

Key expired, rotated, or has extra whitespace.

openclaw config set providers.openai.apiKey "sk-your-new-key"
openclaw gateway restart

HTTP 429 — Rate limit

You're hitting your provider's rate limit. Wait a minute, or switch to a provider with higher limits.

Channels Not Connecting

Telegram / Discord / WhatsApp won't connect

Check channel status:

openclaw channels status --probe
openclaw logs --follow | grep -i "telegram\|discord\|whatsapp"

Common fixes:

Broke After Updating

Everything worked before the update

Very Common

Updates can leave stale service files (LaunchAgent), change config schemas, or introduce breaking changes.

# Reinstall the service
openclaw gateway install
openclaw gateway restart

# If that doesn't help, check for config changes
openclaw doctor

Last resort: downgrade to the previous version:

npm install -g openclaw@previous-version-number

Control UI Won't Load

"Connecting..." forever / blank page

The Control UI needs a running gateway and valid authentication.

# Is the gateway actually running?
openclaw gateway status

# Check the URL and port
openclaw status

# Common fix: clear browser cache or try incognito mode

When Nothing Else Works

🤖 Let ClawAid Figure It Out

ClawAid reads your actual system state — logs, config, processes, network, versions — and diagnoses the exact root cause. It handles complex multi-issue scenarios that manual debugging misses.

npx clawaid

Used by 19,000+ people worldwide · 94% fix rate · Free · Open source

Community Help