🔧 Ultimate Troubleshooting Guide

OpenClaw Not Working?

Fix gateway errors, unauthorized issues, connection problems fast. Step-by-step solutions with copy-paste commands. Get running in 5 minutes.

Find Your Fix Gateway Error →
Quick Diagnosis

What's Your Issue?

Click the card that matches your problem to see the fix.

🔒
"Unauthorized" Error

Control UI shows "Unauthorized" or can't connect. Config file is empty.

# Option 1: Get existing token openclaw config get gateway.auth.token # Option 2: Generate new token openclaw doctor --generate-gateway-token # Option 3: Auto-connect (quickest) openclaw dashboard --no-open

Copy the token and paste into Control UI → Overview → Gateway Token field.

⚠️
"command not found"

Terminal says "openclaw: command not found" after installation.

# Add npm global to PATH (macOS/Linux) echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc source ~/.zshrc # For Linux/bash users: echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
🐳
Docker Won't Start

Docker Desktop won't launch or containers fail to start on Apple Silicon.

# Install Rosetta 2 (Apple Silicon only) softwareupdate --install-rosetta --agree-to-license # Restart Docker Desktop killall Docker && open -a Docker
🔌
Port 18789 in Use

Error says port 18789 is already occupied by another process.

# Find and kill process using port 18789 lsof -ti:18789 | xargs kill -9 # Or use a different port openclaw gateway --port 18790
🔐
Permission Denied

OpenClaw can't write to directories or access files.

# Fix ownership of OpenClaw directory sudo chown -R $(whoami) ~/.openclaw # Fix permissions chmod -R 755 ~/.openclaw
📦
Sharp/libvips Errors

Installation fails with errors about sharp or libvips during npm install.

# Force prebuilt binaries (ignore system libvips) SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest # Ensure Xcode CLI tools installed xcode-select --install
Step-by-Step

Fix Gateway "Unauthorized" Error

The most common OpenClaw issue — solved in 3 steps.

1

Check if Gateway Token Exists

First, let's see if you already have a token configured:

openclaw config get gateway.auth.token
  • If you see a long string (token) → Go to Step 3
  • If you see nothing or "undefined" → Go to Step 2
2

Generate a New Gateway Token

If no token exists, generate one:

openclaw doctor --generate-gateway-token

✅ This creates a secure token and saves it to your config file.

Now retrieve it to copy:

openclaw config get gateway.auth.token
3

Paste Token into Control UI

Copy the token from Step 1 or 2, then:

  • Open OpenClaw Control UI in your browser
  • Go to Overview page
  • Find the Gateway Token field
  • Paste your token
  • Click Connect

💡 Quickest method: Run openclaw dashboard --no-open and open the printed URL — it includes the token and auto-connects!

FAQ

Common Questions

Quick answers to frequent troubleshooting questions.

Why is my OpenClaw not working? +
OpenClaw typically fails due to: 1) Missing gateway auth token (shows 'Unauthorized'), 2) PATH not configured (command not found), 3) Port conflicts, 4) Docker issues, or 5) Permission problems. Each has a specific fix — click the cards above or follow our step-by-step guides.
How do I fix OpenClaw unauthorized error? +
The 'Unauthorized' error means the Control UI lacks the gateway auth token. Fix it by running openclaw config get gateway.auth.token in terminal, then paste the token into the Control UI's Gateway Token field. Or use openclaw dashboard --no-open for automatic token injection.
Why does OpenClaw say command not found? +
This happens when npm global binaries aren't in your PATH. Fix by adding: export PATH="$(npm prefix -g)/bin:$PATH" to your ~/.zshrc (macOS) or ~/.bashrc (Linux), then run source ~/.zshrc to apply.
How do I reset OpenClaw gateway? +
Stop the gateway with openclaw gateway stop, then clear the config: rm ~/.openclaw/openclaw.json, then restart: openclaw gateway. If issues persist, run openclaw doctor --generate-gateway-token to regenerate auth.
Can I run OpenClaw without Docker? +
Yes! OpenClaw runs natively with Node.js. Docker is optional. Install with npm install -g openclaw and run openclaw gateway directly. Docker is only needed if you prefer containerized deployment.
People Also Ask

Related Questions

More troubleshooting questions from searchers.

How do I know if OpenClaw gateway is running?

Run openclaw gateway status or check if port 18789 is listening with lsof -i :18789. You can also visit http://localhost:18789 in your browser.

Why is OpenClaw Control UI blank?

Usually means the gateway isn't running or the auth token is wrong. Start the gateway with openclaw gateway and ensure your token is set correctly in the UI.

Can I change OpenClaw's default port?

Yes! Start with a different port: openclaw gateway --port 3000. Or set it permanently in your config file.

Where are OpenClaw logs stored?

Logs are in /tmp/openclaw/ by default. View with tail -f /tmp/openclaw/gateway.log for real-time monitoring.

How do I update OpenClaw?

Run npm update -g openclaw or pnpm update -g openclaw

Is there an OpenClaw Discord for help?

Yes! Join the official OpenClaw Discord at discord.com/invite/clawd for community support and troubleshooting help.

Still Stuck?

Get help from the OpenClaw community or start fresh with managed hosting.

Get Help on Discord Try Managed Hosting