How to Download, Install, and Set Up OpenClaw: The Complete Guide

What Is OpenClaw?

OpenClaw is an open-source AI agent framework designed to actually do things — not just chat. It connects to your messaging platforms (Discord, Slack, iMessage, Telegram, Matrix, and more), your infrastructure (SSH, Kubernetes, cloud providers), and your local machine to execute tasks, automate workflows, and operate as a genuine digital assistant. Originally developed by Peter Steinberger and the open-source community, OpenClaw (formerly known as MoltBot/ClawdBot) emphasizes a trust boundary architecture, policy-as-code governance, and versioned state with guarded upgrades.

"True automation is not merely the execution of commands, but the patient discipline of defining what the system is allowed to do — and verifying it did exactly that."

— Hesham Kholef

Choosing Your Installation Path

The official documentation provides multiple installation methods tailored to different platforms and use cases. Your choice depends on your operating system, whether you prefer a GUI or CLI-first experience, and whether you're running a personal instance or a server deployment.

Quick Reference: Installation Methods by Platform

Method 1: Native macOS App (Recommended for macOS Users)

The native macOS application provides the smoothest onboarding experience with a graphical interface for pairing, gateway health checks, and channel configuration.

Step 1: Download the macOS App

1. Visit the OpenClaw Download Center
2. Click Open macOS Guide or navigate directly to the macOS platform docs
3. Download the latest .dmg release from the GitHub Releases page linked in the guide

Step 2: Install and Launch

# Mount the DMG and drag OpenClaw to Applications
# Then launch from Applications or Spotlight

Step 3: Complete Onboarding in the App

The macOS app walks you through:

• Gateway mode selection — local for personal use, remote for server deployments
• Pairing — Link your account via QR code or pairing code
• Channel setup — Add Discord, Slack, iMessage, or other connectors
• CLI installation — Optionally install the openclaw CLI globally for terminal access

Method 2: CLI Installation via npm / pnpm / bun (Universal)

This method works on macOS, Linux, and Windows (via WSL2). It's the most flexible and keeps you on the latest release channel.

Prerequisites

• Node.js ≥ 20 (LTS recommended) — nodejs.org
• npm (bundled with Node), pnpm, or bun
• Git for some integrations

Install the CLI Globally

# Using npm
npm install -g openclaw@latest

# Using pnpm (faster, disk-efficient)
pnpm add -g openclaw@latest

# Using bun (fastest)
bun add -g openclaw@latest

Run Onboarding

# Interactive onboarding — installs daemon, configures gateway, pairs account
openclaw onboard --install-daemon

The onboarding wizard will:

1. Detect your platform and recommend the appropriate gateway mode
2. Install and configure the background daemon (systemd on Linux, launchd on macOS)
3. Prompt for pairing — visit the displayed URL or scan the QR code
4. Verify gateway connectivity and channel registration

Method 3: Standalone Binaries (Zero-Dependency)

Pre-built standalone binaries require no Node.js runtime. Ideal for air-gapped environments, minimal containers, or users who want a single executable.

Download

1. Go to GitHub Releases
2. Download the archive for your platform:
   • macOS (Apple Silicon): openclaw-darwin-arm64.tar.gz
   • macOS (Intel): openclaw-darwin-x64.tar.gz
   • Linux (x64): openclaw-linux-x64.tar.gz
   • Linux (ARM64): openclaw-linux-arm64.tar.gz
   • Windows (x64): openclaw-windows-x64.zip

Install

# Example for Linux/macOS
tar -xzf openclaw-linux-x64.tar.gz
sudo mv openclaw /usr/local/bin/
openclaw --version  # Verify

# Windows PowerShell
Expand-Archive openclaw-windows-x64.zip
Move-Item openclaw.exe C:\Users\$env:USERNAME\.local\bin\
# Add to PATH if needed

Run Onboarding

openclaw onboard --install-daemon

Method 4: Docker & Docker Compose (Server / Always-On)

Docker is the recommended path for headless servers, team deployments, and CI/CD pipelines. The official image supports multiple architectures and includes the gateway, agent runtime, and CLI.

Quick Start with Docker Compose

# docker-compose.yml
version: '3.8'
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    environment:
      - GATEWAY_MODE=remote
      - PAIRING_TOKEN=${PAIRING_TOKEN}  # Set via .env or secrets manager
    volumes:
      - ./data:/data
      - ./config:/config
    ports:
      - "8080:8080"  # Gateway API / Web UI
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

# Create .env with your pairing token (get it from the web pairing flow)
echo "PAIRING_TOKEN=your-token-here" > .env

# Start
docker compose up -d

# Follow logs
docker compose logs -f openclaw

Key Docker Environment Variables

Method 5: Alternative & Advanced Installations

Nix / NixOS

# Flake input
inputs.openclaw.url = "github:openclaw/openclaw";

# Or run directly
nix run github:openclaw/openclaw

Homebrew (macOS/Linux)

brew install openclaw/tap/openclaw

Cloud Platform One-Click Deploys

OpenClaw provides verified deployment templates for:

• Railway — railway up with template
• Render — Blueprint YAML
• Fly.io — fly launch with Dockerfile
• Northflank, Upstash Box, Daytona, exe.dev
• Major cloud VMs: DigitalOcean, Hetzner, GCP, AWS, Azure, Oracle Cloud

Kubernetes / Helm

helm repo add openclaw https://charts.openclaw.ai
helm install my-openclaw openclaw/openclaw --namespace openclaw --create-namespace

Onboarding Deep Dive: What Happens During Setup

Whether you use the macOS app or CLI, the onboarding sequence performs these critical steps:

1. Gateway Mode Selection

• Local Mode — Gateway runs on your machine, connects to platforms via your local network. Best for personal use.
• Remote Mode — Gateway runs on a server, you connect via the CLI/app. Best for teams, always-on bots, and multi-device access.

2. Daemon Installation

The daemon manages the gateway process, handles auto-updates, and ensures the agent stays running.

• macOS: ~/Library/LaunchAgents/io.openclaw.daemon.plist (launchd)
• Linux: /etc/systemd/system/openclaw.service (systemd)
• Windows: Windows Service (via WSL2 or native)

3. Pairing & Identity

Pairing links your local gateway to your OpenClaw identity. You'll receive a pairing token or QR code — complete this in a browser. This establishes:

• Your cryptographic identity (Ed25519 keypair)
• Access groups and roles (policy-as-code)
• Channel registrations

4. Channel Registration

Add connectors for each platform you want OpenClaw to operate on:

• Discord — Bot token, guild IDs, permissions
• Slack — App manifest, OAuth, bot tokens
• iMessage — Requires macOS + imsg private API
• Telegram — BotFather token
• Matrix — Homeserver, access token
• WhatsApp, Signal, Microsoft Teams, Google Chat, and more

Post-Install Verification

Check Daemon Status

# CLI
openclaw status

# Or via systemd (Linux)
systemctl status openclaw

# Or via launchd (macOS)
launchctl list | grep openclaw

Follow Live Logs

openclaw logs --follow

Test a Command

# Send a test message to a paired channel
openclaw send --channel "discord:general" "Hello from OpenClaw!"

Common Issues & Troubleshooting

Error: gateway.mode=local blocked

Cause: The gateway detected a port conflict or network policy preventing local mode startup.

Fix:

1. Ensure port 8080 (or configured port) is free: lsof -i :8080
2. Set GATEWAY_MODE=remote if running on a server
3. Check firewall / antivirus isn't blocking the gateway binary
4. Run openclaw logs --follow for detailed error output

Error: openclaw logs --follow shows no output

Cause: Daemon not running, or logs directed to system journal.

Fix:

1. Verify daemon: openclaw status
2. Linux: journalctl -u openclaw -f
3. macOS: log stream --predicate 'subsystem == "io.openclaw"'
4. Restart daemon: openclaw daemon restart

Pairing Fails or Times Out

1. Ensure your gateway is reachable (local mode: same network; remote mode: public URL accessible)
2. Check GATEWAY_MODE matches your deployment
3. Regenerate pairing token from the web dashboard
4. Verify system clock is synchronized (NTP)

Channel Connection Issues (Discord, Slack, etc.)

• Verify bot tokens haven't expired
• Check required permissions/scopes are granted
• Review channel-specific troubleshooting in docs: docs.openclaw.ai

Updating OpenClaw

# CLI installations
npm update -g openclaw@latest
# or
pnpm update -g openclaw
# or
bun update -g openclaw

# Standalone binary — download new release and replace

# Docker
docker compose pull && docker compose up -d

# Daemon handles automatic updates by default (configurable)

Uninstalling

# CLI
openclaw uninstall --remove-daemon --remove-data

# Or manually
npm uninstall -g openclaw
# Remove ~/.config/openclaw, ~/.local/share/openclaw

# Docker
docker compose down -v

Conclusion

OpenClaw's installation flexibility reflects its core philosophy: you own your agent, your data, and your infrastructure. Whether you're a macOS user wanting a polished native app, a Linux sysadmin deploying via Docker Compose on a Hetzner VPS, or a developer embedding the CLI into CI pipelines — there's a validated path for you.

The onboarding wizard handles the heavy lifting: daemon setup, gateway configuration, cryptographic pairing, and channel registration. Once running, openclaw logs --follow and the built-in Support Agent are your best friends for diagnostics.

Start at the Download Center, pick your platform, and follow the guided path. In under 10 minutes, you'll have an AI agent that doesn't just answer questions — it executes.

This guide is based on the official OpenClaw documentation at docs.openclaw.ai/install and the community Download Center at open-claw.bot/download. For the latest release notes, migration guides, and platform-specific nuances, always refer to the official docs.