Troubleshooting Guide¶

Common OpenClaw problems and their fixes. Start with openclaw doctor --fix -- it catches most issues automatically.

Last updated: February 14, 2026

Table of Contents¶

First Steps
Installation Issues
Authentication & API Errors
Gateway & Port Issues
Docker Problems
Channel Connection Issues
Context & Memory Issues
MCP Plugin Issues
Performance Tuning
Security Issues
Quick Fix Reference

First Steps¶

Always run these first:

# Auto-diagnose and fix common issues
openclaw doctor --fix

# Restart the gateway
openclaw restart

# Check gateway health
curl http://localhost:18789/health

# View recent logs
openclaw logs --tail 50

openclaw doctor catches 80%+ of issues before you need to dig deeper.

Installation Issues¶

npm Install Fails¶

Error	Fix
`EACCES: permission denied`	Don't use `sudo`. Fix npm permissions: `npm config set prefix ~/.npm-global`
`node: command not found`	Install Node.js 22+: `nvm install 22 && nvm use 22`
`gyp ERR! build error`	Install build tools: `sudo apt install build-essential` (Linux) or Xcode CLI (macOS)
Old version installed	`npm uninstall -g openclaw && npm install -g openclaw@latest`

Onboarding Wizard Fails¶

# Re-run just the channel step
openclaw onboard

# If wizard quits mid-setup, reset and retry
openclaw config reset
openclaw onboard --install-daemon

Version Mismatch¶

# Check current version
openclaw --version

# Latest as of Feb 2026: v2026.2.12
npm update -g openclaw

# Force clean install
npm uninstall -g openclaw && npm cache clean --force && npm install -g openclaw@latest

Authentication & API Errors¶

401 Unauthorized¶

The most common error. Usually an API key issue.

Cause	Fix
Invalid API key	Regenerate at provider dashboard (console.anthropic.com, platform.openai.com)
Key not set	`openclaw config set anthropic.apiKey sk-ant-...`
Wrong provider configured	Check `~/.openclaw/openclaw.json` -- verify `defaultProvider` matches your key
Key expired/revoked	Check provider dashboard for key status
Whitespace in key	Copy-paste carefully. No leading/trailing spaces.

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

429 Too Many Requests (Rate Limit)¶

Tier	Requests/min	Tokens/min	Fix
Tier 1 (new)	50	40K	Wait, reduce frequency, or upgrade tier
Tier 2	1,000	80K	Usually sufficient
Tier 3	2,000	160K	Production tier
Tier 4	4,000	400K	Enterprise

Fixes: 1. Add retry logic with exponential backoff 2. Reduce heartbeat/cron frequency 3. Use model routing (ClawRouter) to spread across providers 4. Upgrade Anthropic usage tier (automatic based on spend) 5. Set agents.defaults.rateLimitRetries: 3 in openclaw.json

Gateway Token Mismatch¶

# Check current token
openclaw config get gateway.token

# Reset token
openclaw config set gateway.token "your-new-token"

# Restart gateway
openclaw restart

Gateway & Port Issues¶

Port 18789 Already in Use¶

# Find what's using the port
lsof -i :18789    # macOS/Linux
netstat -ano | findstr :18789  # Windows

# Kill the process
kill -9 $(lsof -ti :18789)

# Or use a different port
openclaw gateway --port 18790

Gateway Won't Start¶

Symptom	Fix
Silently exits	Check logs: `openclaw logs`
"Address in use"	Kill existing process (see above)
Crash loop	`openclaw doctor --fix` then restart
Permission denied	Don't run as root. Fix file permissions.

Gateway Not Responding¶

# Full cleanup and restart
pkill -f openclaw
openclaw gateway &

# If using systemd
systemctl --user restart openclaw-gateway.service

# Verify it's running
curl -sf http://localhost:18789/health && echo "OK" || echo "FAILED"

Docker Problems¶

Docker Install Broken (Most Common)¶

The Docker setup breaks frequently with new OpenClaw versions. Known fix:

# Option A: Use official Docker setup script
bash <(curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh)

# Option B: Manual docker-compose.yml

# docker-compose.yml
services:
  openclaw:
    image: alpine/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-token-here
      - OPENCLAW_CONFIG_PATH=/config/openclaw.json
    volumes:
      - ./openclaw.json:/config/openclaw.json:ro
      - openclaw-data:/data
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

volumes:
  openclaw-data:

Container Can't Reach Host Network¶

# Add to docker-compose.yml
extra_hosts:
  - "host.docker.internal:host-gateway"

Or use network_mode: host (less secure but simpler).

Container OOM (Out of Memory)¶

# Increase memory limit
services:
  openclaw:
    deploy:
      resources:
        limits:
          memory: 1G  # Default 512MB may be too low

Image Pull Fails¶

# Use community image instead of official
docker pull alpine/openclaw:latest

# Set env var to skip local build
export OPENCLAW_IMAGE=alpine/openclaw

OAuth in Docker¶

OAuth redirect fails because the callback URL points to localhost inside the container.

Fix: Copy the localhost URL from the error message, paste it into your browser manually to complete auth. (Per Simon Willison's guide)

Docker Logs¶

# View container logs
docker logs openclaw --tail 100 -f

# Log rotation (prevent disk fill)
# Add to docker-compose.yml:
services:
  openclaw:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "5"

Channel Connection Issues¶

Telegram Not Responding¶

Issue	Fix
Bot doesn't reply	Check BotFather token is correct
"Unauthorized"	Regenerate token via @BotFather
Messages delayed	Check webhook vs polling mode
Bot responds to old messages only	Restart gateway to clear queue

# Re-add Telegram channel
openclaw channel remove telegram
openclaw channel add telegram --token YOUR_BOT_TOKEN
openclaw restart

Channel Routing Issues¶

If channels are up but nothing answers:

# Check routing configuration
openclaw config get channels

# Verify agent is assigned to channel
openclaw config get agents.default.channels

# Test with direct message
openclaw chat --message "test"

WhatsApp Business Issues¶

WhatsApp requires the Meta Business API, which has its own verification process. Common issues: - Phone number not verified - Business account not approved - Webhook URL not accessible from Meta's servers (needs public HTTPS URL)

Context & Memory Issues¶

context_length_exceeded¶

The most frustrating error. Your conversation exceeded the model's context window.

Immediate fixes:

# Summarize older history
/compact

# Start fresh session
/new

# Clear all sessions
openclaw session clear

Permanent prevention:

// openclaw.json
{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokens": 40000
      },
      "maxContextTokens": 100000
    }
  }
}

Agent Forgets Previous Context¶

Context was compacted (normal behavior)
Session was cleared
Different session/channel routed to different agent
Fix: Use skills with persistent state, or configure longer context retention

High Token Usage¶

# Check token usage
openclaw usage

# Reduce by:
# 1. Shorter system prompts
# 2. More aggressive compaction
# 3. Smaller models for simple tasks
# 4. Disable verbose tool output

MCP Plugin Issues¶

Plugin Not Found¶

# List installed plugins
openclaw mcp list

# Re-install
openclaw mcp install <plugin-name>

# Check if plugin is community (not native)
# MCP is NOT native in OpenClaw -- all plugins are community-built

Plugin Connection Failed¶

Error	Fix
`ECONNREFUSED`	Plugin server not running. Start it first.
`timeout`	Increase timeout in plugin config
`auth failed`	Check plugin-specific credentials
`incompatible version`	Update plugin: `openclaw mcp update <name>`

MCP Known Limitations¶

MCP is NOT native in OpenClaw (GitHub issues #4834, #8188)
Community plugin: openclaw-mcp-plugin
Some MCP servers may not work with OpenClaw's plugin system
Claude Code has native MCP support -- consider using both tools together

Performance Tuning¶

Slow Response Times¶

Cause	Fix	Impact
Large context window	Enable compaction, reduce `maxContextTokens`	2-5x faster
Wrong model	Use faster models for simple tasks (Haiku, Flash)	3-10x faster
Too many tools loaded	Disable unused skills/MCP plugins	20-40% faster
Network latency	Use closest API region, or local models via Ollama	Varies
Docker overhead	Use host networking or native install	10-20% faster

Memory Usage High¶

# Check process memory
ps aux | grep openclaw

# Reduce memory:
# 1. Limit concurrent sessions
# 2. Reduce context window size
# 3. Disable unused channels
# 4. Use Docker memory limits

Optimal Configuration¶

{
  "agents": {
    "defaults": {
      "temperature": 0.2,
      "maxContextTokens": 100000,
      "compaction": {
        "reserveTokens": 40000
      }
    }
  },
  "gateway": {
    "maxConcurrentSessions": 5,
    "sessionTimeout": 3600
  }
}

Security Issues¶

"The security problems are structural, not just bugs." -- @kilocode (citing ZDNET, Cisco, CrowdStrike analysis)

Known CVEs¶

CVE	CVSS	Attack Vector	Impact	Fixed In
CVE-2026-25253	8.8 HIGH	Visit malicious webpage → OpenClaw auto-connects via WebSocket → auth token stolen → sandbox disabled → full RCE	Complete system compromise	v2026.1.20
CVE-2026-25593	HIGH	Remote code execution	RCE	v2026.1.20
Malicious skills	HIGH	341 Atomic Stealer payloads on ClawHub	Credential theft, crypto drain	v2026.2.6 (scanner)

Always update to latest version. v2026.2.14 shipped 50+ security fixes. Run openclaw security audit --deep --fix after every update.

Attack Vectors (Community-Documented)¶

1. Prompt Injection (Biggest Structural Risk)

The core problem: agents read untrusted content (emails, web pages, documents) that can contain hidden instructions.

Vector	How It Works	Source
Email injection	Malicious prompt hidden in email → agent reads it → executes attacker's instructions → hands over private keys	Kaspersky research
Web page injection	Prompts hidden in webpage HTML/metadata → agent browses → follows hidden instructions	Trend Micro
Document injection	Malicious instructions embedded in PDFs, docs → agent processes them → executes commands	Palo Alto Networks
Memory amplification	Injected prompt persists in agent memory → affects ALL future conversations	Palo Alto Networks
Channel injection	Attacker sends crafted message via Telegram/WhatsApp → agent follows malicious instructions	Community reports

"Prompt injection turns email → remote shell. Strip HTML, sandbox reads, gate tools." -- @Flowgrammers

"Risk stems from agent design rather than a patchable vulnerability." -- eSecurity Planet

2. Malicious Skills (Supply Chain)

Stat	Source
341 malicious skills found on ClawHub	@OneZeroEight_ai
15% of 18,000 community skills contain malicious instructions	r/MachineLearning research
VirusTotal scanning now integrated	OpenClaw v2026.2.6+

"Stay away from unaudited skills." -- @benfromdallas "literally just a stack of vulnerabilities you're installing yourself" -- r/selfhosted

3. Exposed Instances

Stat	Detail
135,000+ exposed OpenClaw instances found publicly accessible	Security researchers
$750/mo runaway API costs from compromised instances	@OneZeroEight_ai
API keys exposed via Moltbook and other tools	@alignmentwen / Palo Alto Networks

4. The "Lethal Trifecta" (Palo Alto Networks)

Three properties that make agents uniquely dangerous when combined: 1. Access to private data (files, keys, databases) 2. Exposure to untrusted content (emails, web, documents) 3. External communications (can send messages, make API calls)

Fixes and Hardening¶

Immediate (Do These Now):

# 1. Update to latest (v2026.2.14+ has 50+ security fixes)
npm update -g openclaw

# 2. Run security audit
openclaw security audit --deep --fix  # 51 automated checks

# 3. Bind gateway to localhost ONLY
openclaw config set gateway.host "127.0.0.1"

Configuration Hardening:

// openclaw.json
{
  "gateway": {
    "host": "127.0.0.1",
    "token": "strong-random-token-here"
  },
  "sandbox": {
    "enabled": true,
    "permissions": {
      "network": "restricted",
      "filesystem": "readonly"
    }
  },
  "security": {
    "denyCommands": [
      "rm -rf", "curl | bash", "chmod 777",
      "wget | sh", "eval", "exec"
    ],
    "pairingMode": true,
    "skillAllowlist": true
  }
}

Community-Recommended Security Stack:

Layer	What	Why
Docker isolation	Separate container per agent	Blast radius containment
Bind 127.0.0.1	Never expose gateway port	Prevents 135K+ exposed instance problem
No community skills	Write your own or audit line-by-line	15% are malicious
Sandbox mode ON	`sandbox.enabled: true`	Restricts file/network access
Pairing mode	Requires human approval for dangerous actions	Prevents prompt injection escalation
denyCommands	Block dangerous shell commands	Prevents RCE
Separate VLAN/network	Isolate from other services	Network segmentation
API spending caps	Set limits on provider dashboards	Prevents $750/mo runaway costs
openclaw-shield	Secret detection in agent output	Prevents credential leaks
No channels initially	Add channels only when needed	Each channel = attack surface

"Install on separate machine or VM, don't setup channels unless you have a very good reason (attack vectors for prompt injection)." -- @NotNotARealBot

"Takes a certain level nerd to do it safely: vm/container/isolated vlan/vpn." -- @benfromdallas

@LeoYe_AI's Security Checklist (Battle-Tested): 1. denyCommands in config -- block dangerous shell commands 2. Isolated VM or container -- never bare metal 3. Hardware wallet only for crypto-related agents 4. Audit ALL PicoClaw forks before use 5. Review every skill's source code

Exposed Gateway (135,000+ Instances Found Public)¶

# Check if your gateway is exposed
curl https://your-server-ip:18789/health  # Should NOT work from outside

# Fix: Bind to localhost only
# In openclaw.json:
{
  "gateway": {
    "host": "127.0.0.1"
  }
}

# Use reverse proxy for external access with auth
# Caddy example:
# openclaw.yourdomain.com {
#   basicauth {
#     admin $2a$14$hashed_password
#   }
#   reverse_proxy localhost:18789
# }

API Key Leaked / Cost Runaway¶

# 1. Immediately revoke at provider dashboard
# 2. Rotate all credentials
openclaw config set anthropic.apiKey NEW_KEY_HERE

# 3. Audit what was accessed
# Check provider dashboard for usage spikes

# 4. Set spending caps
# Anthropic: console.anthropic.com → Usage → Set limit
# OpenAI: platform.openai.com → Settings → Limits

# 5. Use Docker secrets instead of env vars
# docker secret create anthropic_key key.txt

Security Research Sources¶

Source	Finding
ZDNET	Called OpenClaw "a security nightmare"
Cisco	Flagged malicious skill execution
CrowdStrike	Raised prompt injection concerns
Kaspersky	Demonstrated email → private key theft via prompt injection
Trend Micro	Malicious prompts hidden in webpages and documents
Palo Alto Networks	"Lethal trifecta" warning, memory amplification
Jamf Threat Labs	Prompt injection and token theft analysis
eSecurity Planet	"Risk is structural, not patchable"
The Hacker News	One-click RCE via malicious link
r/selfhosted	"Stack of vulnerabilities you install yourself"
r/MachineLearning	15% of community skills are malicious

Quick Fix Reference¶

Problem	One-Liner Fix
Everything broken	`openclaw doctor --fix`
Gateway won't start	`pkill -f openclaw && openclaw gateway`
API key error	`openclaw config set anthropic.apiKey sk-ant-...`
Rate limited	Wait 60s, or add model routing
Context too long	`/compact` or `/new`
Docker broken	`docker pull alpine/openclaw:latest && docker compose up -d`
Port conflict	`kill -9 $(lsof -ti :18789)`
Channel not working	`openclaw channel remove X && openclaw channel add X`
Old version	`npm update -g openclaw`
Security audit	`openclaw security audit --deep --fix`
MCP plugin fails	`openclaw mcp update <name>` or reinstall
High memory	Reduce `maxConcurrentSessions` and `maxContextTokens`
Slow responses	Use faster model, enable compaction, disable unused tools

Getting Help¶

Resource	URL
Official troubleshooting	https://docs.openclaw.ai/gateway/troubleshooting
GitHub issues	https://github.com/openclaw/openclaw/issues
Error code reference	https://www.aifreeapi.com/en/posts/openclaw-error-troubleshooting-center
Reddit community	r/openclaw, r/LocalLLM, r/AI_Agents
Docker guide	https://docs.openclaw.ai/install/docker

Still stuck? Open a GitHub issue with: 1. openclaw --version output 2. openclaw doctor output 3. Relevant log lines (openclaw logs --tail 50) 4. Your OS and Node.js version