setup

OpenClaw Installation and Setup

Overview

Install, configure, and verify an OpenClaw deployment. OpenClaw is an open-source AI gateway that routes LLM traffic through a local runtime, providing a unified API surface, usage dashboards, and multi-model orchestration. This skill covers prerequisites, six installation methods, the interactive onboarding wizard, and post-install health checks.

---

Prerequisites

Before installing, confirm the target system meets these requirements:

• Node.js 22+ (mandatory). Verify with node --version. Install from https://nodejs.org or via a version manager (nvm install 22).
• Memory: 1 GB RAM minimum, 4 GB recommended for production workloads.
• Port 18789 available. The gateway binds to this port by default. Check availability with lsof -i :18789.
• LLM API key: At least one provider key is required. Anthropic Claude is the recommended default. Keys from OpenAI, Google, Mistral, and other providers also work.
• Operating system: macOS (full support), Linux (full support), Windows (WSL2 only; native Windows is not supported).

For expanded hardware guidance, network requirements, and provider-specific key setup, read ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/prerequisites.md.

---

Installation Methods

OpenClaw offers six installation paths. Choose the one that fits the target environment.

1. Installer Script (recommended for most users)

The fastest path. Downloads the latest release, installs the binary, and drops a starter config.

macOS / Linux / WSL2:

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

Windows (PowerShell, inside WSL2):

irm https://openclaw.ai/install.ps1 | iex

2. npm Global Install

Useful when Node.js is already present and npm is the preferred package manager.

npm install -g openclaw@latest

Confirm with openclaw --version.

3. Source Build

Build from the monorepo when contributing or running a custom fork.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

Requires pnpm (install with npm install -g pnpm if missing).

4. Docker

Run the gateway in an isolated container. Use the setup script bundled in the repo root.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

The script builds the image, creates a named volume for persistence, and starts the container with port 18789 mapped.

5. Ansible (Debian/Ubuntu servers)

Automated provisioning for headless Debian 11+ or Ubuntu 20.04+ hosts.

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

The playbook installs Node.js, creates a dedicated service user, deploys OpenClaw, and enables a systemd unit.

6. Nix (Home Manager)

Declarative installation via the nix-openclaw Home Manager module.

Add the module to home.nix, then rebuild:

imports = [ nix-openclaw.homeManagerModules.default ];
services.openclaw.enable = true;

For full command-line flags, environment variable overrides, and platform-specific notes for every method, read ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/install-methods.md.

---

Onboarding Wizard

After installation, run the interactive onboarding wizard to configure the runtime:

openclaw onboard --install-daemon

The --install-daemon flag tells the wizard to also register a background service (systemd on Linux, launchd on macOS) so the gateway starts automatically.

Wizard Steps

1. Profile selection -- Choose QuickStart (sensible defaults, minimal prompts) or Advanced (full control over every setting).
2. Model and API key -- Select a default LLM provider and paste the API key. The wizard validates the key with a test call before continuing.
3. Workspace directory -- Set the working directory where OpenClaw stores configs, logs, and cached responses. Default: ~/.openclaw/.
4. Gateway bind address -- Choose how the gateway listens:
   • Loopback (127.0.0.1:18789) -- local-only, safest default.
   • LAN (0.0.0.0:18789) -- accessible to other machines on the same network.
   • Tailnet -- bind to Tailscale IP for secure remote access.
   • Custom -- specify an arbitrary address and port.
5. Channels -- Configure named routing channels (e.g., fast routes to Haiku, heavy routes to Opus). QuickStart creates one default channel; Advanced allows defining multiple.
6. Daemon registration -- When --install-daemon is passed, the wizard writes and enables a systemd service or launchd plist.
7. Health check -- The wizard starts the gateway and runs a self-test to confirm the runtime is responsive.

For a complete step-by-step walkthrough of every wizard prompt and the config files it generates, read ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/onboarding-wizard.md.

---

Post-Install Verification

Run these three checks after installation to confirm the system is healthy.

1. openclaw doctor

A built-in diagnostic tool that validates Node.js version, port availability, config file syntax, API key reachability, and daemon status.

openclaw doctor

All checks should report green. If any check fails, re-run with the auto-repair flag:

openclaw doctor --fix

The --fix flag attempts corrective actions automatically: restarting the daemon, regenerating corrupt config files, and re-binding the port.

2. openclaw gateway status

Confirm the gateway runtime is operational.

openclaw gateway status

Expected output includes:

Runtime: running
RPC probe: ok

If the runtime shows stopped, start it with openclaw gateway start.

3. openclaw dashboard

Open the web-based management UI.

openclaw dashboard

This launches the default browser to http://127.0.0.1:18789/. The dashboard displays active channels, request logs, and model usage metrics. If the page does not load, verify the gateway is running with openclaw gateway status.

For the full verification checklist and advanced diagnostic commands, read ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/post-install-verification.md.

---

Common First-Run Issues

openclaw: command not found

The binary is not on PATH. The installer script prints the install location at the end of its output. Common fixes:

• npm global: Ensure the npm global bin directory is on PATH. Find it with npm config get prefix and add <prefix>/bin to the shell profile.
• Installer script: Source the shell profile (source ~/.bashrc or source ~/.zshrc) or open a new terminal.

ECONNREFUSED on port 18789

The gateway is not running. Restart it:

openclaw gateway restart

If the daemon was not installed, start the gateway in the foreground for debugging:

openclaw gateway start --foreground

Port 18789 already in use

Another process holds the port. Identify it:

lsof -i :18789

Either stop the conflicting process or reconfigure OpenClaw to use a different port in ~/.openclaw/config.yaml under the gateway.port key.

Docker permission errors

Container file ownership mismatch. Fix by aligning the volume owner to UID 1000 (the default container user):

sudo chown -R 1000:1000 ~/.openclaw

Then restart the container.

---

Reference Files

Load these resources for expanded detail on each topic:

• ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/prerequisites.md -- Detailed system requirements including hardware sizing, supported Node.js versions, network and firewall rules, and provider API key setup.
• ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/install-methods.md -- All six installation methods with complete command sequences, environment variable overrides, platform-specific notes, and upgrade instructions.
• ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/onboarding-wizard.md -- Full step-by-step walkthrough of every onboarding wizard prompt, generated config file locations, and daemon management commands.
• ${CLAUDE_PLUGIN_ROOT}/skills/setup/references/post-install-verification.md -- Expanded verification commands, openclaw doctor check descriptions, log file locations, and advanced troubleshooting procedures.