OpenClaw setup, and the parts that go wrong

Installing OpenClaw takes a few minutes. Keeping it running is where people lose an afternoon — a PATH that doesn't include the npm global bin, a package manager that installs it but can't run it, a Mac that quietly stops answering after it sleeps.

This is the short version of all of that, with the commands that actually work.

Last updated 2026-07-30 · Written against OpenClaw v2026.7.1 · Every command here is from the official docs, linked at the end

What OpenClaw is

OpenClaw is a self-hosted gateway. You run one process on a machine you control, and it sits between a messaging app and an LLM agent. The docs describe the gateway as "the single source of truth for sessions, routing, and channel connections" — everything else (the CLI, the web UI, the phone apps) talks to it.

In practice that means several pieces share one name:

a CLI — openclaw …
a daemon — launchd on macOS, a systemd user service on Linux and WSL2, a Scheduled Task on Windows
a web Control UI at http://127.0.0.1:18789/
a Docker image — ghcr.io/openclaw/openclaw:latest
optional companion apps — a macOS menu-bar app, a Windows Hub, iOS and Android nodes

Port 18789 is the one to remember. It shows up again in half the failures below.

Name collision: there is an unrelated project also called OpenClaw — a C++ reimplementation of the 1997 platformer Captain Claw. If a search result mentions SDL2 and Box2D, that's the other one.

Before you install

Node. You need 22.22.3+, 24.15+, or 25.9+. Anything below 22.22.3 will not work.

The two official sources disagree on what to prefer: the docs recommend Node 26, the README says "Node 24.15+ (recommended)". Either satisfies the floor. If you have no reason to pick, the install script will sort it out for you.

An API key for one model provider. The onboarding wizard asks for it; you don't need to place it in a file yourself. OpenClaw supports a long list of providers — Anthropic, OpenAI, Google, xAI, Bedrock, Azure, Groq, Mistral, DeepSeek, OpenRouter and many more — plus local models through Ollama, LM Studio, vLLM and SGLang, and any OpenAI- or Anthropic-compatible endpoint.

It can also reuse a subscription you already pay for: a signed-in Claude CLI (Pro/Max/Team/Enterprise), OpenAI Codex OAuth, GitHub Copilot, or the Gemini CLI. Note the tradeoff the docs point out — reusing a subscription burns your plan's limits, so for a host that runs all day "an Anthropic API key is the more predictable choice".

pnpm, but only if you build from source. A plain npm install at the repo root is explicitly not supported, because it's a pnpm workspace.

Installing

The install script (what the docs recommend)

It detects your OS and installs Node if you need it.

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

Windows, in PowerShell:

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

To install without being walked through onboarding:

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

If you don't want it touching your system Node

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

npm, pnpm, bun

npm install -g openclaw@latest
openclaw onboard --install-daemon

npm 12 blocks lifecycle scripts by default, which breaks this install. You need:

npm install -g openclaw@latest --allow-scripts openclaw

pnpm has the same shape of problem:

pnpm add -g --allow-build=openclaw openclaw@latest

bun installs it but cannot run it. bun add -g openclaw@latest succeeds, and then the gateway won't start, because bun has no node:sqlite. Use bun to install if you like — run it with Node.

From source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

Check it worked

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

openclaw doctor is the one to run first whenever something is off. It catches most of the failures in the troubleshooting section below without you having to diagnose them.

Docker

./scripts/docker/setup.sh

The image is ghcr.io/openclaw/openclaw:latest, mirrored on Docker Hub as openclaw/openclaw:latest. It's built on node:24-bookworm-slim with tini as PID 1. There are variant tags — slim, and latest-browser which ships Chromium for the browser tool.

Give the build at least 2 GB of RAM. On a 1 GB host pnpm install gets OOM-killed and you'll see exit 137, which reads like a mystery until you know what it is.

Health check:

curl -fsS http://127.0.0.1:18789/healthz

Connecting a channel

This is the part where the docs surprise people. Only three channels are built into the core: iMessage, Telegram, and WebChat. Everything else — WhatsApp, Discord, Slack, Signal, Teams, Matrix, LINE, and the rest — is an official plugin you install separately, followed by a gateway restart.

Channel	How you connect	Packaging
Telegram	BotFather bot token	core
iMessage	`imsg` bridge on a signed-in Mac	core
WhatsApp	QR code only	plugin
Discord	bot token	plugin
Slack	workspace app credentials	plugin
Signal	delegates to `signal-cli`	plugin

Telegram — the fastest one

Message @BotFather, send /newbot, take the token it gives you.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Telegram does not use openclaw channels login. That command is for the QR-based channels. If you run it for Telegram you'll just be confused. Token precedence is tokenFile > botToken > environment variable.

WhatsApp — two separate steps

openclaw plugins install clawhub:@openclaw/whatsapp
openclaw channels login --channel whatsapp
openclaw pairing approve whatsapp <CODE>

Login is QR-only; it runs on Baileys, i.e. WhatsApp Web. Credentials land in ~/.openclaw/credentials/whatsapp/<accountId>/creds.json.

The thing to internalise: the QR login and the pairing approval are two different gates. The QR connects your WhatsApp account to the gateway. The pairing approval decides which humans are allowed to talk to the agent. Doing the first does not do the second.

On a headless or remote host, getting the QR to a phone is genuinely awkward, and the docs warn that a terminal QR or a screenshot "can expire in transit". Plan for that before you SSH into a VPS to set it up.

The config file

~/.openclaw/openclaw.json, in JSON5 — so comments and trailing commas are fine, and keys don't need quotes.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

Other paths worth knowing:

`~/.openclaw/workspace`	the agent's working directory
`~/.openclaw/state/openclaw.sqlite`	gateway state
`~/.openclaw/agents/<id>/agent/openclaw-agent.sqlite`	session history
`~/.openclaw/agents/<id>/agent/auth-profiles.json`	credentials

OPENCLAW_HOME, OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH move these.

Two rules about editing this file by hand. A hand edit must contain the whole JSON5 config, not just the object you changed. And if the result is invalid, the gateway fails closed — it doesn't start at all, rather than starting with defaults. So an unrelated typo reads as "OpenClaw is broken".

Don't hard-code API keys here; the docs say so explicitly. Use the onboarding wizard, which writes them to the auth profile instead.

Memory is just files

The agent's memory lives in markdown in the workspace, injected as Project Context on the first turn of a new session:

AGENTS.md — operating instructions and memory
SOUL.md — persona
IDENTITY.md, USER.md
MEMORY.md — long-term memory, but only when it's at the workspace root
BOOTSTRAP.md — runs once, then deletes itself

Large files get truncated with a marker and the agent opens them itself if it needs the rest.

When it breaks

`openclaw: command not found`

The docs are blunt: "almost always a PATH issue". Your npm global bin isn't on PATH.

npm config get prefix

Add that directory's bin to PATH. On Windows the location is usually %AppData%\npm.

It installed, but the gateway won't start

If you installed with bun, this is why — no node:sqlite. Reinstall under Node.

`EADDRINUSE`, or the gateway keeps restarting

Something else is on 18789, or you have two service definitions — a duplicate launchd job or systemd unit, often left behind by installing twice by different methods. Check for both.

Channels vanished after an update

plugin load failed: dependency tree corrupted; run openclaw doctor --fix

Run exactly that.

Service commands refuse to do anything

A "split-brain" install: an older binary still on PATH is touching a newer config. Find and remove the stale one — usually one of the install methods above was run twice.

On macOS it stops answering after a while, with no error

This one is nasty because nothing looks wrong. During Power Nap or Maintenance Sleep the Wi-Fi flaps, and a launchd restart gate stops it coming back. Three things together fix it:

upgrade past version 2026.5.26
sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
run an external watchdog, so you find out from something other than silence

Docker build dies with `exit 137`

Out of memory. Build on a host with at least 2 GB.

`docs.openclaw.ai` won't load

If you're on Comcast/Xfinity, Advanced Security has been blocking that domain by mistake. Read the docs mirror on GitHub instead.

"critical memory pressure bundle written"

Session transcripts (.jsonl) have grown large. Prune old sessions.

Raspberry Pi

A Pi 5, or a Pi 4 with 2 GB or more, on a 64-bit OS. The docs say a Pi Zero 2 W at 512 MB is not recommended — believe them.

Security defaults worth knowing

OpenClaw's own documentation is unusually candid here, and it's worth reading before you expose anything.

The gateway assumes one trusted operator. In the project's words, it is "not a hostile multi-tenant security boundary for multiple adversarial users sharing one agent or gateway". If you were planning to give a group of people access to one gateway, that is not the shape it was built for.

Prompt injection is listed as unsolved. The docs are explicit that system-prompt guardrails are "soft guidance; hard enforcement comes from tool policy, exec approvals, sandboxing, and channel allowlists" — and that "the content itself is a threat surface, not just the sender". Any web page, email or attachment the agent reads counts.

The defaults are conservative and you should leave them that way. dmPolicy: "pairing" means an unknown sender gets a pairing code and their message is not processed. Codes expire after an hour. Opening it up is deliberately awkward — you have to set dmPolicy: "open" and put "*" in an allowlist.

Things the docs tell you not to do: bind to 0.0.0.0 without auth, set allowedOrigins: ["*"], point browser control at your everyday browser profile, or use your home directory as the workspace root. Plugins run in-process and are treated as trusted code — installing one is a decision, not a convenience.

openclaw security audit --deep

There is also a public advisory index on the GitHub repo. It is long. That is partly a function of how fast the project moves and how much attention it gets, but read it before deciding what to connect.

If the single-operator shape is the problem

Everything above assumes what OpenClaw assumes: one person, one gateway, an agent living in a messenger you already use. That is a good design and for a lot of people it's the right one.

It stops fitting when you want several people and several agents in the same place — because then the messenger is carrying human conversation too, and the gateway's own docs tell you it isn't a boundary between users.

UFO is built for that second case: a team chat where the AI agents are channel members alongside people, each agent running on a machine you've paired, with human-only channels the agents can't see. Different shape, different tradeoffs — it's hosted rather than self-hosted, so you give up the thing OpenClaw is best at.

A longer, fairer comparison →

Sources

Everything on this page comes from OpenClaw's own documentation and repository, read on 2026-07-30 against v2026.7.1. Where the official sources contradict each other — the recommended Node version, the count of model providers — this page says so rather than picking one.

Not affiliated with the OpenClaw project. If something here is wrong or has gone out of date, tell us and we'll fix it.