Installation

This guide covers all the ways to install and run better-openclaw, including global installation, one-off usage with npx, and system requirements.

System Requirements

Option 1: Run with npx (No Install)

The easiest way to use better-openclaw. No global install needed — npx downloads and runs the latest version automatically:

npx create-better-openclaw@latest my-stack

This always fetches the latest published version. Use this if you only generate stacks occasionally.

With pnpm

pnpm create better-openclaw@latest my-stack

With bun

bun create better-openclaw@latest my-stack

Option 2: Global Install

Install globally if you generate stacks frequently. This avoids the download on every run:

# With npm
npm install -g create-better-openclaw

# With pnpm
pnpm add -g create-better-openclaw

# With bun
bun add -g create-better-openclaw

Then run directly:

create-better-openclaw my-stack

Updating a Global Install

# Check current version
create-better-openclaw --version

# Update to latest
npm update -g create-better-openclaw

# Or reinstall
npm install -g create-better-openclaw@latest

Option 3: Direct Install (OpenClaw on Host)

Instead of running OpenClaw inside Docker, you can install it directly on your host machine. This is useful if you want more control over the OpenClaw process, need access to local GPU drivers, or prefer a lighter Docker footprint (companion services only).

During the CLI wizard, select "Direct install (host)" when asked "How would you like to install OpenClaw itself?". Or use the--openclaw-install direct flag:

npx create-better-openclaw my-stack --openclaw-install direct --yes

This generates a stack where:

• docker-compose.yml contains only companion services (no openclaw-gateway or openclaw-cli)
• scripts/install-openclaw.sh runs the official installer: curl -fsSL https://openclaw.ai/install.sh | bash
• scripts/install-openclaw.ps1 handles Windows (via WSL)

Usage

cd my-stack
cp .env.example .env

# Install OpenClaw on the host
chmod +x scripts/install-openclaw.sh
./scripts/install-openclaw.sh

# Start companion services in Docker
docker compose up -d

# Run onboarding
openclaw onboard

Verify Installation

Run the following commands to verify everything is set up correctly:

# Check Node.js version (must be 20+)
node --version

# Check Docker is running
docker info

# Check Docker Compose version
docker compose version

# Test the CLI
npx create-better-openclaw --help

Expected output from --help:

create-better-openclaw <project-name>

Generate a production-ready OpenClaw stack with Docker Compose

Options:
  --preset <name>     Use a preset configuration
  --services <list>   Comma-separated services to include
  --skills <list>     Comma-separated skill packs
  --proxy <type>      Reverse proxy: caddy | traefik | nginx | none
  --domain <name>     Domain name for reverse proxy
  --gpu               Enable GPU passthrough for AI services
  --yes               Skip all prompts (use defaults + flags)
  --output <dir>      Output directory (default: ./<project-name>)
  --dry-run           Show what would be generated without writing
  --version           Show version number
  --help              Show this help message

Troubleshooting

Node.js Version Too Old

If you see errors about unsupported syntax or missing APIs, update Node.js:

# Using nvm (recommended)
nvm install 20
nvm use 20

# Using volta
volta install node@20

# Or download from https://nodejs.org

Docker Not Running

# macOS / Windows — start Docker Desktop

# Linux — start the Docker daemon
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to the docker group (avoids sudo)
sudo usermod -aG docker $USER
# Log out and back in for the group change to take effect

Permission Errors on Linux

If you get EACCES errors when installing globally:

# Fix npm global directory permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Then install again
npm install -g create-better-openclaw

WSL2 Docker Integration

On Windows with WSL2:

1. Install Docker Desktop for Windows
2. Enable "Use the WSL 2 based engine" in Docker Desktop settings
3. Enable your WSL distro under Settings → Resources → WSL Integration
4. Run docker info inside WSL to verify the connection

Next Steps

• Quick Start guide — create your first stack
• CLI reference — all flags and options
• MCP Server — let AI agents generate stacks