OpenClaw Not Working? Fix Every Common Error (2026)

If you've spent hours (or days) trying to get OpenClaw running and keep hitting cryptic errors, you're not alone. After analyzing hundreds of comments across YouTube tutorials, the same 8 errors come up over and over.

openclaw status --all        # Full health report with logs
openclaw doctor              # Auto-repair common issues
openclaw gateway status      # Gateway daemon + RPC check
openclaw logs --follow       # Live log tail

Jump to your error:

1. Gateway Token Missing / "disconnected 1008: unauthorized"

What you see:

disconnected (1008): unauthorized: gateway token missing

Why it happens: The gateway enforces token authentication by default, including on localhost. If you missed copying the token during setup, or the Control UI doesn't have it, you get locked out.

The fix:

# Retrieve the current gateway token
openclaw config get gateway.auth.token

# If no token exists, generate one
openclaw doctor --generate-gateway-token

Then open the OpenClaw dashboard and paste the token into the Control UI settings.

In Docker: The token may be overridden by an environment variable. Check with:

# Check if Docker env is overriding your config
docker exec <container_name> env | grep OPENCLAW

# If OPENCLAW_GATEWAY_TOKEN differs from your config,
# update it to match or remove the env var from docker-compose.yml

Official auth error codes: AUTH_TOKEN_MISSING = no token sent, AUTH_TOKEN_MISMATCH = wrong token, PAIRING_REQUIRED = device needs approval (run openclaw devices approve <requestId>). — Source

2. Docker "Missing config" / Gateway Won't Start

What you see:

Missing config. Run `openclaw setup` or set gateway.mode=local

Gateway start blocked: set gateway.mode=local

Why it happens: The gateway configuration hasn't been initialized after Docker setup, or you ran docker compose up before completing the onboarding wizard.

The fix:

# Set the required gateway configuration
docker compose run --rm openclaw-cli config set gateway.mode local
docker compose run --rm openclaw-cli config set gateway.bind lan

# Restart the gateway
docker compose restart

If you haven't run the setup wizard at all, use the official Docker setup script:

# The official Docker setup (handles image, onboarding, and gateway)
./docker-setup.sh

Common pitfall: The build requires at least 2 GB RAM. On 1 GB hosts, pnpm install gets OOM-killed with exit code 137. Use the pre-built image instead:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

Source: OpenClaw Docker Installation

3. Blank or Empty Responses

What you see: You send a message and get a reply bubble with no text, or no reply at all. The gateway appears to be running but nothing comes back.

The fix: Work through this diagnostic checklist from the official FAQ:

# 1. Is the gateway actually running?
openclaw gateway status

# 2. Is your channel connected?
openclaw channels status

# 3. Is auth configured correctly?
openclaw config get gateway.auth

# 4. Is your model available?
openclaw models status

# 5. Watch the live logs for errors
openclaw logs --follow

Common causes:

• Model not configured or unreachable. Run openclaw models status and verify the model name and provider are correct.
• Channel not connected. Run openclaw channels status --probe to check connectivity.
• Allowlist blocking your account. Check that your sender ID is in the allowlist.
• Context too large. Use /compact to summarize older turns, or /new to start a fresh conversation.

Source: OpenClaw FAQ — Gateway Up But No Replies

4. Tools Don't Work / NO_REPLY / "Model is not allowed"

What you see:

Model ... is not allowed

SYSTEM_RUN_DENIED: approval required

The fix:

# Check which models are available and correctly configured
openclaw models status

# Verify the model name uses the correct provider/model format
# Example: ollama/qwen3:30b, anthropic/claude-opus-4-6
openclaw config get agents.defaults.models

Common causes from the official docs:

• "Model is not allowed": The model name isn't in the provider list. Double-check the exact name with openclaw models status.
• "Unknown model": The provider string is malformed. Use the provider/model format (e.g., ollama/qwen3:30b).
• SYSTEM_RUN_DENIED: The command needs approval. Run openclaw devices to check pending approvals, or review the command allowlist/blocklist.
• Local models and tool use: Small local models (under 7B parameters) often struggle with tool-use tasks. If using Ollama, try a larger model with better instruction-following capability.

Source: Gateway Troubleshooting — Node Tool Failures, FAQ

5. Defaults to Claude / Anthropic Instead of Your Local Model

What you see: You set up Ollama with a local model, but OpenClaw keeps trying to use an Anthropic model.

The fix:

# Check what model is currently configured as default
openclaw config get agents.defaults.models

# Set your Ollama model as the default
# Replace the model name with whatever you've pulled in Ollama
openclaw config set agents.defaults.models.chat "ollama/qwen3:30b"

If your API keys are set as environment variables, they may be overriding your config:

# Check for environment variable overrides
env | grep -i anthropic
env | grep -i openclaw

Note: If running OpenClaw as a systemd/launchd service, shell environment variables aren't inherited. Put your keys in ~/.openclaw/.env or add them to the config env block.

Source: OpenClaw FAQ — Shell Environment Variables

6. "Bundled Chrome Extension Is Missing"

What you see:

Error: Bundled Chrome extension is missing. Reinstall OpenClaw and try again.

Chrome extension relay is running, but no tab is connected

The fix:

# Install the extension files
openclaw browser extension install

# Get the path to the extension folder
openclaw browser extension path

Then load it manually in Chrome:

1. Open chrome://extensions
2. Enable Developer mode (toggle in top right)
3. Click "Load unpacked"
4. Select the folder path from the openclaw browser extension path command

Important: The extension does not auto-attach to tabs. You must manually click the extension button on each tab you want OpenClaw to control.

Source: OpenClaw FAQ — Chrome Extension, Gateway Troubleshooting — Browser Tool Failures

7. Windows: "openclaw not recognized" / PowerShell Errors

What you see:

openclaw : The term 'openclaw' is not recognized as the name of a cmdlet

Why it happens: Most OpenClaw tutorials are recorded on Mac or Linux. Windows requires a few extra steps that creators often skip.

Step 1: Install Git for Windows and verify it's on PATH:

git --version

Step 2: Add npm's global bin folder to your PATH. The typical location is:

%AppData%\npm

Add this to your user PATH via System Properties > Environment Variables. Then close and reopen PowerShell.

Step 3: If you see garbled text in the output, fix the console encoding:

# Fix garbled output in PowerShell
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

# Then restart the gateway
openclaw gateway restart

About nano on Windows: Many tutorials use nano to edit config files. This doesn't exist on Windows by default. Use notepad instead, or install nano via Chocolatey.

Source: OpenClaw FAQ — Windows-Specific Errors

8. "Another gateway instance already listening" / Port Conflict

What you see:

another gateway instance is already listening

EADDRINUSE

Why it happens: Only one gateway can run per host. A previous instance didn't shut down cleanly, or another OpenClaw process is occupying the port.

The fix:

# Check what's running
openclaw gateway status
openclaw status

# Restart the gateway cleanly
openclaw gateway restart

If the gateway is stuck and won't restart:

# Force reinstall and restart
openclaw gateway install --force
openclaw gateway restart

Source: Gateway Troubleshooting — Startup Failures

Quick Reference: Error to Fix

Official Resources

Every fix in this guide comes from the official OpenClaw documentation:

• Gateway Troubleshooting — Auth codes, startup failures, tool errors
• FAQ — Token config, Docker, Windows, Chrome extension, blank responses
• Docker Installation — Setup script, environment variables, common pitfalls
• Gateway Doctor — Auto-diagnosis and repair
• Channel Troubleshooting — WhatsApp, Telegram, Discord, Slack
• Getting Started Guide — Fresh install walkthrough
• GitHub Repository — Source code, issues, releases

Still Stuck?

Run openclaw doctor --fix first — it auto-repairs the majority of configuration issues.

If that doesn't solve it, we can help. We've deployed OpenClaw on AWS, Docker, and bare metal. Most errors take under 15 minutes to resolve on a screen-share.