OpenClaw Windows Errors: Fix Script Policy, Config Edit, Ports, And Message Delivery

Start With The Exact Error Text

If OpenClaw fails on Windows, do not start by changing random settings.

First classify the error:

If you see this	Start here
running scripts is disabled on this system	Windows execution policy
config edit / too many arguments	command syntax, quoting, and config path
gateway starts but messages do not arrive	channel integration and webhook state
port already in use	local process and listener checks
install or update fails	Node.js, shell, network, and permissions

This guide is long because OpenClaw can fail in several different layers. The fastest path is not to read every section. Match the exact symptom first, fix that layer, then move down.

Quick Fix Map For Common OpenClaw Windows Errors

If you arrived from Google with one of these phrases, start here:

Search phrase or error	What it usually means	First action
openclaw.ps1 cannot be loaded because running scripts is disabled on this system	Windows blocked the script before OpenClaw really ran	use a process-level or current-user execution policy fix
openclaw "config edit" error too many arguments	the shell parsed the command differently than expected	reduce the command, check quoting, then run config validation
openclaw common errors and solutions	the failure layer is not yet known	classify install, config, runtime, integration, or production
gateway ready, but messages do not arrive	OpenClaw may be running while the channel is not connected	inspect webhook URL, channel credentials, and logs

This is the reason the first command in a real troubleshooting session is often not a fix command. It is a classification step.

Why OpenClaw Has Several Different Failure Modes

OpenClaw is a cross-platform, self-hosted AI gateway supporting 20+ chat platforms and multiple AI providers. This “Jack-of-all-trades” capability also means:

• Huge environment variations: Windows/Linux/macOS, WSL2/Docker/native
• Complex dependencies: Node.js, AI providers, platform APIs
• Flexible configuration: gateway, models, plugins, and channels across several config layers

The practical order is:

Installation -> Configuration -> Runtime -> Integration -> Production

If you keep that order, the error usually becomes much less mysterious.

---

1. Installation Phase Errors (5 Frequent Issues)

1.1 Installer Download Fails

Symptoms:

curl: (60) SSL certificate problem

Or extremely slow/download timeout

Cause:

• Slow GitHub access (especially in China)
• SSL certificate verification failure

Solutions:

Option A: Use Chinese mirrors (recommended)

# Configure Taobao npm mirror
npm config set registry https://registry.npmmirror.com/

# Manual download
curl -k https://openclaw.ai/install.sh -o install.sh
bash install.sh

Option B: Skip SSL verification (temporary)

curl -k https://openclaw.ai/install.sh | bash

Option C: Windows PowerShell manual install

# Download script
iwr -useb https://openclaw.ai/install.ps1 -OutFile install.ps1

# Run as Administrator
.\install.ps1

---

1.2 Node.js Version Incompatibility

Symptoms:

Error: Node.js version 18.x is not supported. Please use Node.js 24.x

OpenClaw requires Node.js 24.x+; older versions fail.

Solutions:

WSL2/Linux/macOS (using nvm):

# Install nvm (if not installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc

# Install Node.js 24
nvm install 24
nvm use 24

# Verify
node --version  # should show v24.x.x

Windows native (using nvm-windows):

1. Download: https://github.com/coreybutler/nvm-windows
2. Install nvm

3. nvm install 24
   nvm use 24

---

1.3 PowerShell Execution Policy (Windows)

Symptoms:

File cannot be loaded because running scripts is disabled on this system.

Cause: Windows PowerShell blocks script execution by default

Solutions:

Temporary bypass (current session):

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Permanent change (current user):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Run as Administrator: Right-click PowerShell → “Run as administrator”

---

1.4 WSL2 Installation Issues (Windows Users)

Symptoms: WSL2 fails to install or Ubuntu won’t start

Solutions:

Step 1: Enable WSL feature

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Step 2: Enable Virtual Machine Platform

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Step 3: Update WSL kernel and set default

wsl --update
wsl --set-default-version 2

Step 4: Install Ubuntu Search “Ubuntu” in Microsoft Store and install

---

1.5 Installer Hangs/Timeout

Symptoms: curl ... | bash hangs or times out

Diagnosis:

# Check real-time logs
openclaw logs --follow

# Test connectivity
ping openclaw.ai
curl -I https://openclaw.ai

Common causes:

• Invalid API key (OpenAI/Anthropic)
• Network proxy issues
• Firewall blocking

Solutions:

1. Retry: Ctrl+C and run again
2. Check network proxy settings
3. Disable firewall temporarily
4. Use --verbose for detailed output

---

2. Configuration Phase Errors (3 Typical Issues)

2.1 Invalid API Key

Symptoms:

Error: Invalid API key

Cause:

• Wrong format (OpenAI should start with sk-)
• Expired/inactive key
• Extra spaces included when copying

Solutions:

Verify API key format:

• OpenAI: sk-... (~40 chars)
• Anthropic: sk-ant-...
• Google: AIza...

Test API key:

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

# Should return 200; 401 means invalid key

Re-copy carefully: Copy from official website, paste in plain text mode, ensure no extra whitespace.

---

2.2 Config File Syntax Error

Symptoms:

Error: Invalid JSON in config file at line 42

Cause: ~/.openclaw/config.json JSON malformed

Solutions:

Option A: Use validation command

openclaw config validate

Option B: Online JSON validator Copy config.json to https://jsonlint.com/

Option C: Reset config

openclaw config reset
# Then re-run onboarding
openclaw onboard --install-daemon

Common JSON mistakes:

• Missing commas
• Mismatched quotes (must be double quotes)
• Trailing commas (last field must not have comma)
• Unescaped Unicode characters

---

2.3 openclaw config edit Says Too Many Arguments

Symptoms:

openclaw "config edit" error too many arguments
too many arguments

What it usually means:

This is usually not an AI provider problem. It is more often a command parsing problem:

• quotes were copied from a web page or chat window
• PowerShell parsed the command differently than Bash examples
• extra arguments were passed after config edit
• the config path is being edited indirectly instead of validated directly

Fix order:

openclaw config validate
openclaw config edit

If config edit keeps failing, open the config file directly in a plain text editor, make the smallest change possible, then validate again:

openclaw config validate

Do not change model keys, ports, and channel settings in the same pass. One bad comma can look like a much larger OpenClaw failure.

---

2.4 Ollama Connection Fails

Symptoms:

Cannot connect to Ollama at http://localhost:11434

Cause:

• Ollama not running
• Wrong port
• WSL2/Windows network isolation (if Ollama on Windows, OpenClaw in WSL2)

Solutions:

Check Ollama status:

# Linux/WSL2
systemctl status ollama

# Or check process
ps aux | grep ollama

Start Ollama:

ollama serve &

Test connection:

curl http://localhost:11434/api/tags
# Should return list of downloaded models

WSL2 specific:

• If Ollama installed on Windows, WSL2 cannot access localhost:11434
• Solution: Install Ollama inside WSL2 too, or use Windows IP address

---

3. Runtime Errors (5 Common Issues)

3.1 Port 8080 Already in Use

Symptoms:

Error: listen EADDRINUSE: :::8080

Cause: Another process is using port 8080

Solutions:

Step 1: Find the occupying process

# Windows
netstat -ano | findstr :8080

# Linux/macOS
lsof -i :8080

Step 2: Stop the process

# Windows (after finding PID)
taskkill /PID <PID> /F

# Linux/macOS
kill -9 <PID>

Step 3: Change OpenClaw port (recommended)

openclaw config edit
# Modify: "gateway": { "port": 8081 }
openclaw restart

---

3.2 Messages Not Arriving

Symptoms: Bot is online but doesn’t respond

Checklist:

✅ Gateway status

openclaw status
# Confirm gateway is running

✅ Platform bot status

• Telegram: @BotFather → /mybots confirm bot online
• Discord: Developer Portal confirm bot status
• Feishu: Developer console confirm app enabled

✅ Config file

openclaw config validate

✅ Firewall Ensure port (8080 or custom) is allowed

✅ Logs

openclaw logs --follow
# Look for errors or received messages

Common causes:

• Event subscription URL wrong (Feishu)
• Bot not installed in current chat
• Insufficient permissions (check im:message etc.)
• Bot blocked/banned by user

---

3.3 Feishu Webhook Verification Fails

Symptoms: Feishu developer console says “URL verification failed”

Cause:

• Domain not ICP-filed (required in China)
• Invalid/expired HTTPS certificate
• Nginx reverse proxy misconfigured
• OpenClaw not running or wrong port

Solutions:

Checklist:

1. ICP filing: Domain must be filed in China
2. SSL certificate: Use valid cert (Let’s Encrypt etc.)
3. Nginx config:

   server {
       listen 443 ssl;
       server_name your-domain.com;
   
       ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
   
       location / {
           proxy_pass http://127.0.0.1:8080;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
       }
   }

4. OpenClaw running: openclaw status
5. Correct URL: openclaw urls copy Feishu event URL

Test webhook:

curl -X POST https://your-domain.com/api/plugins/feishu/events \
  -H "Content-Type: application/json" \
  -d '{"type":"url_verification","challenge":"test"}'

---

3.4 Telegram Bot Privacy Mode Issues

Symptoms: Bot doesn’t receive group messages

Cause: Telegram Bot’s “Privacy Mode” is ON by default, only receives @mentions

Solutions:

Step 1: Disable Privacy Mode

1. Open @BotFather
2. Send /mybots
3. Select your bot
4. Click “Bot Settings”
5. Click “Group Privacy”
6. Choose “Turn off”

Step 2: Re-invite bot to group If bot already in group, remove and re-add.

---

3.5 Gateway Fails to Start

Symptoms:

Error: Failed to start gateway

Diagnosis:

Step 1: Check detailed logs

openclaw logs --level error --tail 50

Step 2: Validate config

openclaw config validate

Step 3: Check port usage

netstat -ano | findstr :8080  # Windows
lsof -i :8080                 # Linux/macOS

Step 4: Check file permissions

# Ensure ~/.openclaw is readable/writable
ls -la ~/.openclaw/
# Should be 755 (drwxr-xr-x)

Common causes:

• Port in use → change port (see 3.1)
• Config error → reset config (see 2.2)
• Permission denied → run as admin or fix permissions

---

4. Platform-Specific Integration Issues

4.1 Feishu: Event Subscription URL Format Error

Symptoms: Feishu says “URL format incorrect”

Correct URL format:

https://your-domain.com/api/plugins/feishu/events

How to get it:

openclaw urls
# Output includes: Feishu event URL: https://...

Important:

• Must be HTTPS (Feishu requirement)
• No query parameters (e.g., /api/plugins/feishu/events?token=xxx)

---

4.2 Discord: 401/403 Permission Errors

Symptoms:

HTTP 401 Unauthorized
HTTP 403 Forbidden

Cause:

• Bot token wrong
• Message Content Intent not enabled
• Channel permissions insufficient

Solutions:

Step 1: Verify Bot Token

• Go to Developer Portal
• Copy fresh token, update config

Step 2: Enable Intents

• Developer Portal → Bot → Privileged Gateway Intents
• Enable:
  • ✅ PRESENCE INTENT (optional)
  • ✅ SERVER MEMBERS INTENT (optional)
  • ✅ MESSAGE CONTENT INTENT (required)

Step 3: Check channel permissions

• Bot must have in server:
  • ✅ Send Messages
  • ✅ Read Message History
  • ✅ View Channel

---

4.3 WhatsApp: QR Code Unscannable

Symptoms: openclaw urls QR URL inaccessible or scan fails

Cause:

• Gateway not running
• Port not exposed to internet (cloud server needs security group rules)
• Browser cache issue

Solutions:

Step 1: Confirm gateway running

openclaw status

Step 2: Check port

# Local test
curl http://localhost:8080/api/plugins/whatsapp/qr
# Should return QR code image (base64 or URL)

Cloud server config:

• Security group: open port 8080 (or custom)
• Or use Nginx reverse proxy on 80/443

Step 3: Clear cache

• Restart gateway: openclaw restart
• Re-get QR URL: openclaw urls

---

4.4 Multi-Platform Message Conflicts

Symptoms: One message triggers on multiple platforms

Cause: Same user on different platforms sends identical message; OpenClaw can’t distinguish identities

Solutions:

Option A: Enable User Mapping

{
  "plugins": {
    "common": {
      "userMapping": true
    }
  }
}

Option B: Channel Isolation Use channels config to give each platform a separate identity:

{
  "channels": {
    "telegram": {
      "agent": { "name": "TG Assistant" }
    },
    "discord": {
      "agent": { "name": "Discord Bot" }
    }
  }
}

---

5. Performance & Stability (2 Optimization Points)

5.1 High Response Latency

Symptoms: Message response time > 5 seconds

Diagnosis:

# Check latency in logs
openclaw logs | grep latency

# Test AI provider network
ping api.openai.com
curl -I https://api.openai.com/v1/models

Optimizations:

Option 1: Use local Ollama

{
  "models": {
    "default": {
      "provider": "ollama",
      "model": "llama3.2:3b",
      "baseUrl": "http://localhost:11434"
    }
  }
}

Local model latency can drop below 1 second

Option 2: Enable caching

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": 1000
  }
}

Cache identical queries for 1 hour, reduce API calls

Option 3: Choose faster models

• OpenAI: gpt-4o-mini faster & cheaper than gpt-4o
• Anthropic: claude-3-haiku is fastest
• Local: llama3.2:3b or mistral lightweight models

---

5.2 Excessive Memory Usage

Symptoms: Memory grows continuously, eventually OOM crash

Cause:

• Unlimited cache growth
• Long-running session history accumulation

Solutions:

Limit cache size:

{
  "cache": {
    "enabled": true,
    "maxSize": 1000,    // Max 1000 cached items
    "ttl": 3600         // 1 hour TTL
  }
}

Set log rotation:

{
  "logging": {
    "maxSize": "10m",    // Max log file 10MB
    "maxFiles": 5        // Keep 5 historical files
  }
}

Periodic restart (temporary):

# Restart daily at 2 AM
0 2 * * * systemctl restart openclaw

---

6. Production Environment Issues (2 Critical Points)

6.1 SSL Certificate Expired

Symptoms: Browser shows “Not Secure” or “NET::ERR_CERT_DATE_INVALID”

Solutions:

Auto-renewal (Let’s Encrypt + Certbot):

# Test renewal
certbot renew --dry-run

# Actual renewal
certbot renew

# Reload nginx to use new cert
systemctl reload nginx

Set up cron auto-renewal:

# crontab -e
0 3 * * * /usr/bin/certbot renew --quiet

---

6.2 Service Crashes Unexpectedly

Symptoms: OpenClaw service stops, needs manual restart

Solutions:

systemd auto-restart config (/etc/systemd/system/openclaw.service):

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=yourname
WorkingDirectory=/home/yourname/.openclaw
ExecStart=/usr/local/bin/openclaw gateway
Restart=always
RestartSec=10
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

Check logs:

sudo journalctl -u openclaw -f

---

7. Prevention & Best Practices

7.1 Pre-Installation Checklist

Environment check:

• Node.js version >= 24 (node --version)
• System meets minimum requirements (4GB RAM)
• Network connectivity (ping openclaw.ai)

Permissions check:

• Admin privileges (Windows)
• Directory read/write (~/.openclaw)

Port check:

• Port 8080 not in use (netstat -ano | findstr :8080)

---

7.2 Configuration Best Practices

Use validation:

openclaw config validate  # after each config change

Test small, scale later:

• Test locally first, then production
• Use free models (Ollama) before cloud APIs

Version control:

cd ~/.openclaw
git init
git add config.json
git commit -m "Initial config"
# Backup before major changes

---

7.3 Monitoring & Alerting

Log monitoring:

# Real-time error monitoring
openclaw logs --level error --follow

# Periodic check (cron)
*/30 * * * * openclaw logs --level error --tail 10 > /var/log/openclaw/errors.log

Port monitoring:

# Check if gateway is running
netstat -ano | findstr :8080 || echo "OpenClaw is down" | mail -s "Alert" [email protected]

API quota monitoring (OpenAI etc.):

• Set budget alerts in provider dashboard
• Check usage regularly

---

8. Getting Help

If the solutions above don’t fix your problem:

8.1 Official Resources

• Docs: https://docs.openclaw.ai
• GitHub Issues: https://github.com/openclaw/openclaw/issues
• Discord Community: https://discord.gg/clawd (recommended for fast response)

8.2 Provide Useful Information

When submitting an issue or asking for help, include:

# Version info
openclaw --version

# Config validation
openclaw config validate

# Error logs (last 50 lines)
openclaw logs --level error --tail 50

# OS info
uname -a  # Linux/macOS
systeminfo  # Windows

# Reproduction steps
# 1. xxx
# 2. xxx
# 3. See error "yyy"

8.3 Search Community

Search Discord or GitHub for similar issues:

• Keywords: “error”, “failed”, “cannot connect”
• Sort by recent for latest solutions

---

9. Summary

Most OpenClaw errors come from environment differences, command parsing, permissions, and channel configuration. Treat the exact error text as the starting point, not as noise.

Key takeaways:

1. Check Node.js version before install (must be 24+)
2. Run openclaw config validate after each config change
3. Feishu integration requires ICP-filed domain and valid HTTPS
4. Local Ollama avoids network and API key problems
5. Regularly backup config.json, use version control

Stuck with a new issue? Search official docs, GitHub issues, and community discussions first. Many problems already have a trace you can compare against.

Feedback: If you have a new Windows-specific OpenClaw error, keep the exact command, log line, operating system, and reproduction steps. That evidence is what makes the next fix easier.