OCDIR

Troubleshooting Common Errors

Fix installation failures, gateway crashes, API errors, channel disconnects, memory issues, and performance problems. Includes openclaw doctor commands.

Platform: Any
Cost: Free
Time: 10 minutes
Difficulty: Beginner

Troubleshooting OpenClaw

When something goes wrong, this guide will help you diagnose and fix the most common OpenClaw issues. Start with the quick diagnostics, then dive into specific error categories.

Quick Diagnostics

Run these commands first to get a picture of what's happening:

# Check if OpenClaw is running and healthy
openclaw status

# Check gateway status specifically
openclaw gateway status

# Run the built-in doctor (auto-fixes many issues)
openclaw doctor

# Watch logs in real-time
openclaw logs --follow

# Test channel connections
openclaw channels status --probe

Pro tip: openclaw doctor --fix automatically repairs common issues like permission problems, missing directories, and invalid config.

Installation Errors

"command not found: openclaw"

Cause: OpenClaw isn't in your PATH or wasn't installed globally.

Fix:

# Reinstall globally
npm install -g openclaw

# Or check where it's installed
npm list -g openclaw

# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm root -g)/.bin"

"EACCES: permission denied" during install

Cause: npm doesn't have permission to write to the global directory.

Fix:

# Option 1: Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw

# Option 2: Use sudo (not recommended)
sudo npm install -g openclaw

"Node.js version X is not supported"

Cause: OpenClaw requires Node.js 20 or higher.

Fix:

# Check your version
node --version

# Install Node.js 22 via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Reinstall OpenClaw
npm install -g openclaw

Gateway Won't Start

"gateway already running pid lock timeout"

Cause: A previous gateway process didn't shut down cleanly.

Fix:

# Kill any stuck processes
pkill -f "openclaw gateway"

# Remove stale lock file
rm -f ~/.openclaw/gateway.pid

# Start fresh
openclaw gateway start

"Port 3000 is already in use"

Cause: Another service is using the gateway port.

Fix:

# Find what's using the port
lsof -i :3000

# Kill the process (replace PID with actual number)
kill -9 <PID>

# Or change OpenClaw's port in config
openclaw config set gateway.port 3001

"ENOENT: no such file or directory, open 'openclaw.json'"

Cause: No configuration file exists yet.

Fix:

# Initialize a new config
openclaw init

# Or create minimal config manually
mkdir -p ~/.openclaw
echo '{"llm": {"provider": "anthropic"}}' > ~/.openclaw/openclaw.json

LLM / API Errors

"HTTP 401: Invalid API key"

Cause: Your API key is wrong, expired, or not set.

Fix:

# Check if key is set
openclaw config get llm.apiKey

# Set your API key
openclaw config set llm.apiKey "sk-ant-..."

# Or set via environment variable
export ANTHROPIC_API_KEY="sk-ant-..."

"HTTP 429: Rate limit exceeded"

Cause: You've hit the API provider's rate limits.

Fix:

  • Wait a few minutes and try again
  • Check your API tier limits in the provider dashboard
  • Consider upgrading your API plan
  • Enable request queuing:
openclaw config set llm.rateLimit.enabled true
openclaw config set llm.rateLimit.requestsPerMinute 50

"HTTP 429: rate_limit_error: Extra usage is required for long context"

Cause: You're hitting Anthropic's extended thinking limits without the right tier.

Fix:

  • Upgrade to Anthropic's higher tier for extended thinking
  • Or disable extended thinking:
openclaw config set llm.thinking "none"

"Connection refused" or "ECONNREFUSED"

Cause: Can't reach the LLM provider's API.

Fix:

# Test connectivity
curl -I https://api.anthropic.com

# Check if you're behind a proxy
echo $HTTP_PROXY $HTTPS_PROXY

# Configure proxy if needed
openclaw config set network.proxy "http://proxy.company.com:8080"

Channel Connection Issues

Telegram: "Bot token invalid"

Cause: The Telegram bot token is wrong or the bot was deleted.

Fix:

  1. Open @BotFather on Telegram
  2. Send /mybots → select your bot → API Token
  3. Copy the token and update config:
openclaw config set channels.telegram.token "123456:ABC-DEF..."

Telegram: "Conflict: terminated by other getUpdates request"

Cause: Another instance is polling the same bot.

Fix:

  • Stop any other OpenClaw instances using this bot
  • Or use webhook mode instead of polling:
openclaw config set channels.telegram.mode "webhook"
openclaw config set channels.telegram.webhookUrl "https://your-domain.com/telegram"

Discord: "Invalid token" or "Authentication failed"

Cause: Discord bot token is wrong or bot was removed from server.

Fix:

  1. Go to Discord Developer Portal
  2. Select your app → Bot → Reset Token
  3. Update config:
openclaw config set channels.discord.token "MTIz..."
  1. Re-invite bot to server with correct permissions

Discord: Bot is online but doesn't respond

Cause: Missing message intent or wrong channel permissions.

Fix:

  1. In Discord Developer Portal → Bot → Enable "Message Content Intent"
  2. Check bot has these permissions in server:
    • Read Messages
    • Send Messages
    • Read Message History
  3. Verify allowed channels in config:
openclaw config get channels.discord.allowedChannels

WhatsApp: "Session expired" or QR code issues

Cause: WhatsApp Web session needs re-authentication.

Fix:

# Clear the session and re-authenticate
openclaw whatsapp logout
openclaw whatsapp login

# Scan the new QR code with your phone

Memory & Context Issues

"Agent doesn't remember previous conversations"

Cause: Memory persistence isn't configured or files are missing.

Fix:

# Check workspace directory exists
ls -la ~/.openclaw/workspace/

# Create memory directory if missing
mkdir -p ~/.openclaw/workspace/memory

# Check MEMORY.md exists
cat ~/.openclaw/workspace/MEMORY.md

# Verify memory is enabled in config
openclaw config get memory.enabled

"Context window exceeded" or truncation issues

Cause: Conversation history is too long for the model's context.

Fix:

# Reduce context window usage
openclaw config set context.maxMessages 50
openclaw config set context.maxTokens 100000

# Enable automatic summarization
openclaw config set context.autoSummarize true

Cron / Scheduled Tasks

Cron jobs not running

Cause: Gateway needs to be running for cron to work.

Fix:

# Check gateway is running
openclaw gateway status

# Check cron scheduler status
openclaw cron status

# List scheduled jobs
openclaw cron list

# Check logs for cron errors
openclaw logs | grep -i cron

"Job failed: timeout exceeded"

Cause: The scheduled task took too long to complete.

Fix:

# Increase timeout for specific job
openclaw cron update <job-id> --timeout 300

# Or set global timeout
openclaw config set cron.defaultTimeout 300

Skill Issues

"Skill not found" after installation

Cause: Skill installed but not registered in config.

Fix:

# List installed skills
openclaw skills list

# Re-register the skill
openclaw skills refresh

# Check skill directory
ls -la ~/.openclaw/skills/

Skill throws "permission denied" errors

Cause: Skill trying to access restricted resources.

Fix:

# Check skill permissions
openclaw skills info <skill-name>

# Grant additional permissions (if trusted)
openclaw config set skills.<skill-name>.permissions.fileSystem true
openclaw config set skills.<skill-name>.permissions.network true

Docker-Specific Issues

Container exits immediately

Cause: Missing environment variables or bad config.

Fix:

# Check container logs
docker logs openclaw

# Run interactively to debug
docker run -it --entrypoint /bin/bash openclaw/openclaw

# Verify environment variables
docker exec openclaw env | grep -i openclaw

"Cannot connect to Docker daemon"

Cause: Docker isn't running or user lacks permissions.

Fix:

# Start Docker daemon
sudo systemctl start docker

# Add user to docker group (logout/login after)
sudo usermod -aG docker $USER

# Or run with sudo
sudo docker compose up -d

Volume permissions issues

Cause: Container user doesn't match host file ownership.

Fix:

# Fix ownership
sudo chown -R 1000:1000 ~/.openclaw

# Or run container as root (less secure)
docker run --user root openclaw/openclaw

Performance Issues

High CPU usage

Cause: Infinite loops, excessive polling, or memory leaks.

Fix:

# Check what's consuming CPU
top -p $(pgrep -f openclaw)

# Reduce heartbeat frequency
openclaw config set heartbeat.intervalMs 60000

# Disable unused channels
openclaw config set channels.telegram.enabled false

Slow response times

Cause: Network latency, rate limiting, or overloaded system.

Fix:

# Test LLM latency
time curl -s https://api.anthropic.com/v1/messages -X POST \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Check system resources
free -h
df -h

# Consider upgrading your server

Getting More Help

If none of these solutions work:

  1. Check official docs: docs.openclaw.ai
  2. Search Discord: discord.gg/clawd — most issues have been discussed
  3. GitHub Issues: github.com/openclaw/openclaw/issues
  4. Run full diagnostics:
openclaw doctor --verbose > diagnostics.txt

When asking for help, include:

  • Output of openclaw status
  • Output of openclaw doctor
  • Relevant error messages from openclaw logs
  • Your OS and Node.js version

Get More OpenClaw Tips

Weekly guides, new skills, and workflow recipes. No spam.