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 errors come up over and over. Whether you’re on macOS, Windows, or Linux, running Docker or bare metal, connecting Telegram or using the web UI, here are the 9 most common problems and their fixes.

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

unauthorized gateway token mismatch

Why it happens: The gateway enforces token authentication by default, including on localhost. If you missed copying the token during setup, the Control UI doesn’t have it, or you regenerated a token without updating all connected clients, you get locked out. This is the single most common OpenClaw error on both macOS and Linux.

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

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

What you see:

Missing config. Run `openclaw setup` or 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

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 fix: Work through this diagnostic checklist:

# 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.
• Context too large. Use /compact to summarize older turns, or /new to start a fresh conversation.

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
openclaw config get agents.defaults.models

Common causes: “Model is not allowed” means the model name isn’t in the provider list. “SYSTEM_RUN_DENIED” means the command needs approval. Small local models (under 7B parameters) often struggle with tool-use tasks.

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:

# Set your Ollama model as the default
openclaw config set agents.defaults.models.chat "ollama/qwen3:30b"

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

6. "Bundled Chrome Extension Is Missing"

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: go to chrome://extensions, enable Developer mode, click “Load unpacked”, and select the folder.

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

What you see:

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

Add %AppData%\npm to your user PATH via System Properties > Environment Variables. Then close and reopen PowerShell.

If you see garbled text:

chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
openclaw gateway restart

8. macOS: Gateway Won't Stay Running / Telegram Bot Not Responding

Gateway dying on terminal close: Register as a persistent launchd service:

openclaw gateway install
openclaw gateway status

Telegram bot not responding: Check openclaw channels status and verify your BotFather API token. If gateway binding is set to loopback, Telegram webhooks can’t reach it.

macOS permissions: Grant Full Disk Access, Accessibility, and Screen Recording in System Settings > Privacy & Security.

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

What you see:

timed out after 60s waiting for gateway port 18709 to become healthy

The fix:

openclaw gateway status
openclaw gateway restart

# If stuck:
openclaw gateway install --force
openclaw gateway restart

10. Fix: Claude Over-Explains, Ignores Constraints, Writes Unrequested Code

What you see: You ask the agent to rename one variable. It rewrites three files, adds error handling you never asked for, refactors a neighboring function “while it’s there,” and ends with a four-paragraph summary of what it did. Or you ask for a specific, narrow change and the response opens with “I’ve analyzed your request and I’ll walk through my approach…” followed by 200 words of preamble. Or you say “only edit config.ts” and it edits four other files too.

Why it happens: This is not a bug in OpenClaw or Claude. It is the absence of behavioral constraints in your system prompt. By default, Claude-family models optimize for helpfulness, which the model interprets as “do the thing plus anything adjacent that seems useful, then explain it thoroughly.” Without an explicit ceiling on scope and verbosity, you get all of that whether you want it or not. OpenClaw reads CLAUDE.md from the project root the same way Claude Code does, so a single file fixes the behavior for both.

The fix: Drop a CLAUDE.md into your project root with behavioral rules. The viral Andrej-Karpathy-Skills repo (4,700 likes on X, 3,700 GitHub stars) popularized this pattern. A concise, effective template:

# CLAUDE.md

## Scope
- Only do what is asked. No additional features, refactoring, or cleanup.
- Do not touch files outside the requested change unless explicitly told to.
- No error handling unless specifically requested.
- Use existing patterns in the codebase. Do not introduce new abstractions.

## Communication
- Respond concisely. No preamble, no summary, no "I've done X".
- Do not restate the request before answering.
- If requirements are ambiguous, ask one clarifying question. Do not guess.
- When finished, stop. Do not volunteer next steps.

## Code
- Match existing formatting and naming conventions exactly.
- Do not add comments unless they explain non-obvious intent.
- Do not add tests unless asked.

## When in doubt
- Prefer the smaller, more conservative change.
- Prefer asking over assuming.

Save this as CLAUDE.md at the root of the repo where OpenClaw is running. Restart the gateway with openclaw gateway restart so the new system prompt is picked up. You should see immediate behavioral change on the next turn: shorter responses, narrower edits, and fewer “I’ve also updated…” surprises.

This works for both Claude Code and OpenClaw because OpenClaw inherits the same CLAUDE.md convention. If you use both, one file covers both.

Quick Reference: Error to Fix

Watch: Full OpenClaw Setup on AWS Lightsail