🔧 Troubleshooting
Solve OpenClaw Issues Fast
Step-by-step solutions to the most common OpenClaw problems. Get back to automating in minutes.
🩺 Quick Diagnosis
Start here if you're not sure what's wrong. These commands check OpenClaw's health:
# Check OpenClaw status
openclaw status
# View system information
openclaw info
# Check logs for errors
openclaw logs --tail 50
# Test configuration
openclaw config validate
# Run health check
openclaw doctor
Copied!
💡 Pro Tip: Run these commands in order. The output will help identify which section below you need.
📦 Installation Issues
"command not found: openclaw"
OpenClaw isn't in your system PATH. Try these solutions:
Solution 1: Check npm global path
# Verify installation
npm list -g openclaw
# Get npm global bin path
npm config get prefix
# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm config get prefix)/bin:$PATH"
Copied!
Solution 2: Use npx (no installation needed)
# Run directly with npx
npx openclaw@latest start
# Create an alias (add to ~/.bashrc or ~/.zshrc)
alias openclaw='npx openclaw@latest'
Copied!
Permission denied when installing
npm needs permissions to install global packages:
# Option 1: Fix npm permissions (recommended)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
# Option 2: Use sudo (not recommended)
sudo npm install -g openclaw
# Option 3: Use Homebrew (macOS)
brew install openclaw
Copied!
"Cannot find module" errors
Missing dependencies or corrupted installation:
# Clear npm cache
npm cache clean --force
# Uninstall and reinstall
npm uninstall -g openclaw
npm install -g openclaw
# Or force reinstall
npm install -g openclaw --force
Copied!
🚀 Startup Issues
"Port 18789 already in use"
Another process is using OpenClaw's default port:
# Find what's using the port
lsof -i :18789 # macOS/Linux
netstat -ano | findstr :18789 # Windows
# Kill the process
kill -9 <PID> # macOS/Linux
taskkill /PID <PID> /F # Windows
# Or use a different port
openclaw start --port 18790
Copied!
✅ Better solution: Check if OpenClaw is already running with openclaw status
"Config file not found" error
OpenClaw can't locate your configuration file:
# Generate default config
openclaw config init
# Specify config location
openclaw --config /path/to/config.yaml start
# Check default config path
openclaw config path
Copied!
OpenClaw crashes on startup
Check logs for detailed error messages:
# View error logs
openclaw logs --errors
# Start with verbose output
openclaw start --verbose
# Enable debug mode
openclaw start --debug
# Check system compatibility
openclaw doctor
Copied!
🔐 Authentication Issues
"Unauthorized" or "401" errors
Your API key or authentication method is misconfigured:
Check your API key is set
# Verify environment variable
echo $OPENCLAW_API_KEY
# Test with inline key
OPENCLAW_API_KEY=test-key openclaw start
# Regenerate API key
openclaw auth regenerate
Copied!
Test authentication
# Test with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://localhost:18789/health
# Expected response: {"status":"ok"}
Copied!
Environment variables not loading
Your .env file isn't being read by OpenClaw:
# Load .env file explicitly
source .env
openclaw start
# Or use dotenv CLI
npx dotenv-cli -- openclaw start
# Verify variable is set
env | grep OPENCLAW
Copied!
🧩 Skill Issues
"Skill not found" error
The skill isn't installed or the name is incorrect:
# Search for the skill
openclaw search web-scraper
# List installed skills
openclaw list
# Install the skill
openclaw install web-scraper-pro
# Update skill index
openclaw update
Copied!
Skill execution timeout
Skills take too long or hang indefinitely:
# Increase timeout in config.yaml
skills:
timeout: "10m" # Default is 5m
# Or override per execution
openclaw run web-scraper --timeout 15m
# Check what's blocking
openclaw logs --follow
Copied!
"Permission denied" when running skills
Skills don't have required permissions:
# Check skill permissions
openclaw skill info web-scraper-pro
# Grant permissions interactively
openclaw run web-scraper-pro --grant-permissions
# Or configure in config.yaml
skills:
permissions:
allow_network: true
allow_filesystem: true
allow_subprocess: false
Copied!
Skill outputs are garbled or empty
Encoding or formatting issues with skill output:
# Run with verbose output
openclaw run web-scraper --verbose
# Save to file instead
openclaw run web-scraper --output result.json
# Check skill logs
openclaw logs --skill web-scraper
# Reinstall the skill
openclaw reinstall web-scraper-pro
Copied!
🌐 Network Issues
Can't access OpenClaw from another machine
OpenClaw is only accessible from localhost:
# Check what host OpenClaw is bound to
openclaw config get gateway.host
# Change to all interfaces (use with auth!)
openclaw config set gateway.host 0.0.0.0
# Restart OpenClaw
openclaw restart
Copied!
⚠️ Security Warning: Binding to 0.0.0.0 requires authentication. See our security guide.
Firewall blocking connections
Configure your firewall to allow OpenClaw:
# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/openclaw
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/local/bin/openclaw
# Linux (ufw)
sudo ufw allow 18789/tcp
# Linux (firewalld)
sudo firewall-cmd --add-port=18789/tcp --permanent
sudo firewall-cmd --reload
# Test connectivity
telnet YOUR_SERVER_IP 18789
Copied!
"Connection refused" errors
OpenClaw isn't running or is bound to wrong interface:
# Check if OpenClaw is running
openclaw status
# Check listening ports
netstat -tuln | grep 18789
ss -tuln | grep 18789
# Restart OpenClaw
openclaw restart
# Check logs for errors
openclaw logs --tail 20
Copied!
⚡ Performance Issues
OpenClaw is slow or unresponsive
Performance optimization tips:
# Check resource usage
openclaw stats
# Increase concurrent executions
skills:
max_concurrent: 10 # Default is 5
# Enable caching
cache:
enabled: true
type: "memory"
max_size: "1GB"
# Clear old data
openclaw cleanup
Copied!
High memory usage
Limit memory consumption per skill:
skills:
memory_limit: "2GB" # Per-skill limit
memory_warning: "1.5GB" # Warning threshold
enforce_limits: true # Kill exceeding skills
# Clear cache
openclaw cache clear
# Restart to free memory
openclaw restart
Copied!
Skills are running slowly
Skill-specific performance issues:
# Check skill execution time
openclaw run web-scraper --timing
# Profile skill performance
openclaw run web-scraper --profile
# Update to latest skill version
openclaw update web-scraper-pro
# Disable unused skills
openclaw disable slow-skill
Copied!
🆘 Still Need Help?
📋 Before Asking for Help
- ✓ Run
openclaw doctorand save output - ✓ Check logs with
openclaw logs --tail 100 - ✓ Search existing issues first
- ✓ Include your OpenClaw version
- ✓ Share minimal reproducible example
💬 Where to Get Help
- 📖 Documentation: docs.openclaw.ai
- 💬 Discord Community: discord.gg/openclaw
- 🐦 Twitter: @openclaw_ai
- 🐛 GitHub Issues: github.com/openclaw/issues
- 📧 Enterprise Support: [email protected]
📤 Generate Bug Report
Automatically generate a bug report with all necessary information:
# Generate bug report
openclaw report --bug > bug-report.txt
# Include system diagnostics
openclaw doctor > diagnostics.txt
# Share both files when asking for help
Copied!
🔢 Common Error Codes
| Error Code | Meaning | Solution |
|---|---|---|
E001 | Config file not found | Run openclaw config init |
E002 | Invalid YAML syntax | Validate with yamllint config.yaml |
E003 | Authentication failed | Check API key in config |
E004 | Port already in use | Change port or kill existing process |
E005 | Skill not found | Install with openclaw install <skill> |
E006 | Permission denied | Check skill permissions |
E007 | Network timeout | Check network connection and firewall |
E008 | Memory limit exceeded | Increase memory limit or optimize skill |