OpenClaw Won't Start?
Fix Every Common Error.

This is the single most reported error across OpenClaw tutorials. 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 your existing gateway token and paste it into the Control UI:

# 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

This happens when the gateway configuration hasn't been initialized after Docker setup, or when running 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, start with the official Docker setup script:

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

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

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.

OpenClaw can browse the web, read/write files, and run commands, but if your tools aren't responding at all, there are a few things to check.

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.
• ▶ 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.

You set up Ollama with a local model, but OpenClaw keeps trying to use an Anthropic model. This is a configuration issue where the default model hasn't been updated.

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 shell variables that might be taking priority:

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

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

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

The fix

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

# Verify Git is installed and accessible
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 for the change to take effect.

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

Only one gateway can run per host. This error means 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, you can force-reinstall the service metadata:

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

Quick Reference: Error to Fix

Official Resources

Every fix in this guide comes from or is supported by the official OpenClaw documentation. Here are the source pages:

• ▶ 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