Installing OpenClaw: Onboarding, Node Versions and Your First Message

Installing OpenClaw is genuinely a few minutes of work. Installing it in a state you’ll still be happy with in three months takes a little longer, because a handful of decisions made in the first ten minutes — which machine, which Node, daemon or not, which channel first — are annoying to reverse later.

This page walks the whole path: prerequisites, the three install routes and when each is right, what onboard actually does, how to verify the thing is genuinely working rather than merely running, and the failures that account for most of the “it won’t start” reports.

Before You Install: Pick the Right Machine

This decision matters more than the install command.

OpenClaw’s value comes from being reachable and awake. An assistant on a laptop you close at 18:00 misses every scheduled job between then and morning, and every message you send from the train.

One point people miss: whatever machine you choose, the agent inherits that machine’s access. A home server that can reach your NAS, your router’s admin page, and your local Git remotes is a home server whose agent can reach all of those. Choose the host with that in mind, not just uptime.

Prerequisites

Node.js. OpenClaw needs a recent runtime — Node 22.22.3+, 24.15+, or 25.9+, with Node 26 currently recommended. These are unusually specific minor-version floors, and they exist because the project relies on runtime behaviour that landed in those patch releases. “I have Node 22” is not the same as “I have Node 22.22.3.”

Check what you actually have:

node --version

If you’re below the floor, don’t panic and don’t start manually upgrading system Node — the shell installer provisions a compatible runtime for you. Manual upgrades are only worth it if you’re going the npm route.

Operating system. macOS and Linux natively; Windows through WSL2. WSL2 is a real requirement, not a suggestion — native Windows Node is not the supported path.

A model provider. An Anthropic or OpenAI key, an OpenRouter key, or a local model endpoint. Have it in your clipboard before you start onboarding; the wizard asks for it.

Disk and memory. Budget a couple of GB. The Gateway itself is light, but browser automation pulls a Chromium build and session transcripts accumulate.

The Three Install Routes

Route 1 — The shell installer (recommended for most people)

macOS, Linux, and inside WSL2:

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

Windows PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

This is the path the project optimises for. It resolves the Node problem for you, puts the binary somewhere sensible on PATH, and hands you off to onboarding.

A word on curl | bash, since somebody always raises it and the objection is fair: you are executing a remote script with your user’s privileges, sight unseen. If that bothers you — and it reasonably might, on a machine that matters — download and read it first:

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

That takes ninety seconds and is a habit worth having generally, not just here.

Route 2 — npm

npm install -g openclaw@latest

Choose this when you already manage Node versions deliberately — nvm, fnm, asdf, Volta — and don’t want a second runtime appearing on your system. The trade is that you now own the Node compatibility problem. When a release bumps the floor, your install breaks and the fix is yours.

If you use nvm, pin the version so a shell that defaults to an older Node doesn’t silently break the daemon:

nvm install 26
nvm alias default 26

Route 3 — Docker

Running the whole Gateway in a container is the strongest isolation posture available, and it’s covered properly in Sandboxing OpenClaw. It’s the right destination for a hardened setup, but a poor first install: you’ll be debugging volume mounts and channel authentication simultaneously, and won’t know which layer is at fault.

Get it working natively first. Containerise once you know what “working” looks like.

Onboarding

One command does the real setup:

openclaw onboard --install-daemon

This is an interactive wizard, and it performs several distinct jobs:

1. Verifies model access. Prompts for your provider and key, then makes a live test call. If your key is wrong or has no credit, you find out here rather than three steps later when a message silently fails.
2. Creates the workspace. The ~/.openclaw/ directory: config, credentials, agent state, memory files.
3. Writes the initial config. Generates ~/.openclaw/openclaw.json with conservative defaults — loopback binding, pairing-based DM policy.
4. Installs the daemon. That’s the --install-daemon flag: a launchd job on macOS, a systemd unit on Linux. Without it, the Gateway only runs while your terminal is open, which defeats the purpose.
5. Offers channel setup. You can connect one now or defer.

Should you use --install-daemon?

Yes, if this is a machine you intend to keep it on. The scheduler is a headline feature and it requires the Gateway to survive logouts and reboots.

Skip it only when you’re evaluating on a laptop and want a clean removal path. You can always install the daemon later.

Verify It Actually Works

“The command didn’t error” is not verification. Three checks, in order.

1. Is the Gateway up?

openclaw gateway status

You want a running process, a bind address, and a port — 18789 unless you changed it. If this reports nothing, the daemon didn’t install or didn’t start, and that’s your problem to solve before anything else.

2. Does the Control UI load?

openclaw dashboard

This opens the web Control UI at http://127.0.0.1:18789. It’s the friendliest surface for inspecting config, watching sessions live, and reading logs without tailing files. If the CLI says running but the UI won’t load, you have a binding or port conflict.

3. Does a real message round-trip?

The only test that counts. Connect one channel, message the bot, get a reply. Everything before this is infrastructure; this is the system working.

Connecting Your First Channel

Start with Telegram. Not because it’s better, but because it’s the least entangled: you create a bot through BotFather, get a token, and nothing is bound to your personal identity. If you decide to tear it all down, you delete a bot. Compare with WhatsApp, where you’re pairing a real account via QR code and a mistake is more visible to more people.

The minimum config, in ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      botToken: "123456:ABC-your-token-here",
      dmPolicy: "pairing",
      allowFrom: ["tg:YOUR_NUMERIC_USER_ID"]
    }
  }
}

Note the file is JSON5 — comments and trailing commas are legal, which makes it far more pleasant to annotate than strict JSON.

The Gateway watches this file and hot-reloads most changes, so you generally don’t need to restart after an edit. Some sections restart just their own subsystem (the channel, cron, the heartbeat, the health monitor) rather than the whole process.

The pairing handshake

With dmPolicy: "pairing" — the default, and the right one — an unrecognised sender doesn’t get service. They get a one-time code, and you approve it explicitly:

openclaw pairing approve telegram 428913

This trips people up constantly: “I messaged my bot and it ignored me.” It didn’t ignore you. It doesn’t know you yet. Check pending requests, approve the code, message again.

Pairing codes expire after an hour, and pending requests are capped at three per account — so a stranger who finds your bot can’t flood you with approval prompts.

Common Install Failures

openclaw: command not found right after a successful install. The install directory isn’t on your PATH in this shell. Open a new terminal. If it persists, the installer printed a line to add to your shell profile and you skipped past it — scroll back.

Gateway starts, then immediately exits. Almost always Node version. Run node --version and compare against the floors above. On npm installs, a shell whose nvm default is old will start the daemon under the wrong runtime even though your interactive shell looks fine.

Port 18789 already in use. Either a previous Gateway didn’t shut down, or something else claimed it. Find the culprit:

lsof -i :18789

WSL2: the daemon dies when I close the terminal. WSL2 shuts down the VM when the last session ends. You need systemd enabled inside your distro (systemd=true under [boot] in /etc/wsl.conf) and a wsl --shutdown to apply it. This is a WSL configuration issue, not an OpenClaw one.

Messages arrive but nothing happens. Work through it in order: is the sender approved (pairing)? Is allowFrom populated correctly? In a group, did you actually mention the bot — requireMention defaults to on. The Control UI’s live session view answers this in seconds and saves a lot of guessing.

Model calls fail with an auth error after onboarding said it was fine. Usually a key with no remaining credit, or an environment variable shadowing the configured key. Check what’s actually in play:

openclaw config get agents.defaults.model

The diagnostic that beats all of the above

openclaw doctor --fix

Run this before opening a browser tab to search an error message. It checks the environment, spots common misconfigurations, and repairs a fair number of them on its own.

Set Up Costs Before You Set Up Features

Do this on day one, while you’re still paying attention.

A heartbeat that fires every 30 minutes is 48 model invocations a day, ~1,400 a month, each carrying a system prompt and whatever memory context has accumulated. That is not a rounding error. It is the single most common source of “why is my bill like this” surprise.

Start deliberately slow:

openclaw config set agents.defaults.heartbeat.every "4h"

Tighten it once you know what the agent actually does with those wake-ups. Most people find that a heartbeat every few hours delivers nearly all the value of one every thirty minutes, at a tenth of the cost. You can also point cheap routine work at a smaller model and reserve the expensive one for real reasoning — per-agent model configuration makes that straightforward.

Upgrading and Removing

Upgrade — shell installs re-run the installer; npm installs:

npm install -g openclaw@latest

This project moves quickly and config keys do change between releases. Read release notes before jumping several versions, and run openclaw config validate afterwards to catch anything that stopped being legal.

Back up first. ~/.openclaw/ holds your config, credentials, and memory:

tar czf openclaw-backup-$(date +%F).tar.gz ~/.openclaw

That archive contains API keys and channel credentials. Store it somewhere you’d be comfortable storing a password vault export — not a shared drive.

Remove: stop and uninstall the daemon through the CLI, remove the package, then delete ~/.openclaw/. Also revoke the bot tokens and API keys you created, and un-pair any linked messaging accounts. An uninstalled OpenClaw with a live WhatsApp pairing is a loose end.

Lock the Front Door Before You Widen It

Two things worth doing immediately, before you start adding tools:

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

That config file holds provider keys, bot tokens and your allowlists in plaintext. On a shared or multi-user machine, default permissions are too generous.

And leave gateway.bind on loopback until you have read The OpenClaw Threat Model. Exposing the Gateway to your LAN “just to test from my phone” is the most common way a careful install becomes a careless one — and there’s a better answer for remote access that doesn’t involve opening ports at all.

Where to Go Next

You have a Gateway running, one channel connected, and a verified round-trip message. That’s a complete, working install.

Next, understand what you just built: How OpenClaw Works covers the Gateway, sessions, agents and nodes — the mental model that makes every later configuration decision obvious rather than trial-and-error. Then Understanding openclaw.json walks the config file section by section.