OpenClaw from Zero to Production — Without Losing an Evening to Troubleshooting

The demo took three minutes. Your installation took three hours. You are not alone — and it is not your fault.

OpenClaw is a powerful tool, but the documentation assumes you already know what can go wrong. This guide does not. It starts with what actually stops people, and how to fix it on the first try.

The Foundation: Three Commands That Reveal Everything

Before you install anything, run this:

• node --version
• npm --version
• git --version

What you need:

• Node 22+ — this is non-negotiable
• Git — installed and available in PATH
• Docker — only if you actually plan on a container/sandbox path (most don't need it on Day 1)

Most installation problems we see start with the wrong Node version. It produces error messages that point to the completely wrong place — and you can troubleshoot for hours without realizing the root problem is three versions too old.

The Recommended Path: Works for 90% of Everyone

Run the official install script:

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

Then three commands in sequence:

The dashboard normally opens in your browser. If not: manually go to http://127.0.0.1:18789/ on the machine running the gateway.

Windows: Where Most Setups Die

OpenClaw documentation points to WSL2 for a very good reason. Native Windows installation is a path of pain with unpredictable results.

The recipe that actually works:

The classic Windows mistake: half the setup in PowerShell, half in WSL. Then neither works.

It is tempting to start in PowerShell because it feels familiar. Resist the temptation. The moment you mix two environments, you get path conflicts, wrong Node versions, and a gateway that starts in one environment and dies in the other.

Docker: Powerful, but Not Day 1

Docker is the right choice when you need isolation, are running on a VPS, or need stable long-term operation. But for a local first-time installation, it is usually overkill.

If you want to anyway:

• Fast track: ./docker-setup.sh from the repo
• Requires Docker + Compose v2

The main rule: get the standard install green first. Then consider Docker for production.

The Five Errors That Stop Most People — and the Solutions

1. openclaw: command not found

The CLI is not in your PATH, or the installation stopped halfway. Happens more often than people think.

Fix: Run the installer script again. Open a new terminal (important — the old terminal has the old PATH). Verify with which openclaw and openclaw --version.

2. Gateway Won't Start or Dies After Login

Old state from a previous installation, or a migration that stalled.

Fix: Start with openclaw doctor. For headless/CI environments: openclaw doctor --repair --yes. Restart the gateway with openclaw gateway restart. Read the logs with openclaw logs --follow — they almost always tell you what actually failed.

3. Dashboard at 127.0.0.1:18789 is Dead

Either the gateway isn't running, the port is wrong, or the daemon was never correctly set up during onboarding.

Fix: Check openclaw gateway status. Test foreground mode: openclaw gateway --port 18789. Run openclaw dashboard again.

4. An Update Broke Something That Worked Yesterday

Config and state change between versions. OpenClaw is under active development — this happens.

Fix: Update via the official installer script (not manual git pull). Run openclaw doctor immediately after. Test gateway + dashboard before you turn on automation.

5. Sandboxing Blocks Everything You Try to Do

Policy and Docker setups don't match workloads yet. This is because sandboxing is the last thing you should configure, not the first.

Fix: Start with sandbox mode off. Activate gradually (non-main first). Use openclaw sandbox explain to understand exactly what is blocking.

Operations That Don't Explode After Week Two

Installation is Day 1. Operations is the rest. Some rules to keep things stable:

• Keep ~/.openclaw private — this contains config and credentials, not something that belongs in a shared folder
• Least possible privileges on keys and tokens — don't give admin access where viewer suffices
• Don't give full host access if a sandbox is enough for your workload
• Run openclaw doctor regularly — not just when everything is already red. Preventive maintenance is cheaper than firefighting

The Checklist: Are You Actually Operational?

Before you declare yourself finished, run through this:

• openclaw --version responds with the correct version
• openclaw gateway status is green
• openclaw dashboard opens without errors
• A test message goes through the entire pipeline
• openclaw doctor gives green or manageable warnings

When this list is green, you aren't just installed. You are operational with control — and there is a significant difference.

When everything lights up green, you have a setup that survives updates, that you can troubleshoot systematically, and that doesn't collapse the first time something changes. That is the difference between "it works on my machine" and actual production-ready infrastructure.