OpenClaw Install Guide: Mac, Linux, and Windows WSL

A local install is the cleanest way to try OpenClaw free: you test the real, open-source software on a machine you already own, and you can stop, inspect, and remove everything if the workflow does not fit. This guide walks through the install on macOS, Linux, and Windows (via WSL), then covers the onboarding flow and the errors new users hit most.

For exact commands, always follow the official Getting Started guide — OpenClaw evolves quickly and the official docs are the source of truth. Treat this page as the decision-making companion to that guide.

Before you start

You need three things:

1. A terminal you are comfortable with. macOS and Linux work directly; on Windows, use WSL (Windows Subsystem for Linux) rather than trying to run the gateway natively.
2. Node.js and npm if you choose the package route. Check the official docs for the currently supported Node version before installing anything.
3. A model provider account. OpenClaw itself is open source, but the AI model is not free. Create the provider account first and set a spending limit if the provider offers one — this keeps your trial cost predictable.

Plan for roughly five to fifteen minutes for the official quick start on a normal connection, plus whatever time your model provider and first channel need.

Install: two official routes

The official documentation offers an installer script and an npm-based route. The installer is the faster path for most people; the npm route suits users who already manage Node versions and want the package in their own toolchain.

Whichever route you pick, take it from the official docs page — do not copy install commands from an unverified video or a random blog comment. After the install completes, verify the binary is on your PATH by running the version command the docs list before moving on.

Onboarding and your first chat

The openclaw onboard flow connects the pieces: it walks you through selecting a model provider, entering credentials, and connecting a first chat channel. Keep the first session deliberately small:

• One provider, one channel. OpenClaw supports many channels — Telegram, iMessage, WebChat, Discord, Slack, WhatsApp, Signal, Microsoft Teams, and others, some via plugins — but a first test needs exactly one. Pick the lowest-risk channel you actually use.
• A defined test task. Write down one outcome in plain language, for example: "summarize the last day of this low-risk group chat." A defined test stops you from connecting every account just because the setup screen offers it.
• A credential note. Keep a list of every token and API key you added. You will need it when you rotate or remove them later.

After one or two useful conversations, review what worked, what data the assistant could reach, and whether the value justifies expanding. Add channels and senders one at a time — not all at once.

The five errors people hit most

1. Command not found after install. The install directory is not on your PATH. Restart the terminal, or add the path shown by the installer output to your shell profile.
2. Unsupported Node version. The npm route fails or misbehaves on old Node. Check the version requirement in the official docs and switch with your version manager.
3. Model provider auth failures. Usually a wrong or expired API key, or a key without billing enabled. Regenerate the key at the provider and re-run onboarding for that provider only.
4. Channel connects but the assistant never replies. Check who is allowed to trigger it. Restrictive defaults are normal — add your own account to the allowlist and, for group chats, check whether replies require a mention.
5. Windows users installing outside WSL. Native Windows is not the supported path; install inside WSL and keep the gateway running there.

Set a security boundary on day one

A local trial still connects an AI agent to your messages and files. Before broadening anything, read the official security documentation, keep the allowed-sender list small, use the official security audit command, and never start with financial accounts or credentials you cannot rotate.

Where to go next

A local install answers "does this fit my work?" — but the gateway is only reachable while your computer is awake. When you need uptime without your laptop open, the next step is a small always-on environment: see Run OpenClaw on a VPS: The Cheap Always-On Setup. If you would rather skip server work entirely, read Hosted OpenClaw vs Self-Hosting: How to Choose first.