Why OpenClaw Uses Three Install Scripts: Design Philosophy and Practical Guide

Background

OpenClaw is an open‑source autonomous AI agent with over 310 000 GitHub stars, supporting more than 30 messaging platforms. This article does not cover its features but focuses on the engineering behind its installer.

Why the Installer Matters

The installer is the first impression for users of a high‑profile project. Users may run OpenClaw on macOS, Linux servers, Windows, or inside restricted corporate networks, so a single script cannot cover all scenarios. Hence three dedicated scripts were created.

Three Installer Scripts

install.sh

– Standard installer for macOS, Linux and WSL. Assumes system permissions and can install Node.js globally. install-cli.sh – Local installer for environments without root access. Downloads a self‑contained Node.js runtime into ~/.openclaw and installs everything under the user’s prefix. install.ps1 – Windows PowerShell installer that uses native Windows package managers (winget, Chocolatey, Scoop) and updates the PATH.

install.sh: Five‑Step Flow

Step 1 – Detect Operating System

# macOS detection example
if [[ "$OSType" == "Darwin" ]]; then
  # macOS‑specific logic
fi

If the OS is macOS and Homebrew is missing, the script installs Homebrew automatically instead of aborting.

Step 2 – Ensure Node.js 24 (or compatible)

# Check existing Node version
if command -v node >/dev/null; then
  node_version=$(node --version | cut -d' ' -f1 | tr -d 'v')
  # version comparison logic
fi

Node 24 present → continue

Node 22.16+ present → compatible, continue

None → install

Installation uses Homebrew on macOS and the official NodeSource scripts on Linux, preserving LTS stability and avoiding forced upgrades.

Step 3 – Ensure Git

If Git is missing, the script installs it automatically, following the same “solve, don’t fail” principle.

Step 4 – Install OpenClaw

Two modes are available:

npm (default) : npm install -g openclaw git :

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

The git mode is intended for developers who need to modify source code or test unreleased features, at the cost of longer install time and larger disk usage.

Step 5 – Post‑Installation Tasks

# Verify configuration
openclaw doctor --non-interactive
# Onboarding (if applicable)
# Set environment variable for sharp/libvips issues
SHARP_IGNORE_GLOBAL_LIBVIPS=1

The openclaw doctor command proactively checks the environment, a design worth emulating.

install-cli.sh: Local Installation

Step 1 – Install Local Node Runtime

# Download fixed Node LTS tarball
wget https://nodejs.org/dist/v${version}/node-v${version}.tar.gz
# Extract to prefix
tar -xzf node-v${version}.tar.gz -C <prefix>/tools/node-v${version}
# Verify SHA‑256 checksum
sha256sum -c node-v${version}.tar.gz | sha256_expected

This guarantees version consistency across machines.

Step 2 – Ensure Git

Same auto‑install logic as install.sh.

Step 3 – Install OpenClaw

# Use local Node to install
<prefix>/tools/node-v${version}/bin/npm --prefix <prefix> install openclaw
# Write wrapper script
cat > <prefix>/bin/openclaw <<'EOF'
#!/bin/sh
<prefix>/lib/node_modules/openclaw/bin/openclaw.js "$@"
EOF
chmod +x <prefix>/bin/openclaw

All files reside under ~/.openclaw by default; removing the directory cleanly uninstalls the tool.

install.ps1: Windows Support

Step 1 – Detect PowerShell Environment

Ensures PowerShell 5+ is available.

Step 2 – Ensure Node.js

# Installation order
$managers = @('winget','choco','scoop')
foreach ($mgr in $managers) {
  if (Get-Command $mgr -ErrorAction SilentlyContinue) {
    & $mgr install OpenJS.NodeJS.LTS
    break
  }
}

The script tries each manager and stops at the first successful installation.

Step 3 – Install OpenClaw

Supports both npm and git modes, identical to the Unix scripts.

Step 4 – Configure PATH

# Append npm global bin to user PATH
$env:Path += ";$(npm prefix -g)\bin"
[Environment]::SetEnvironmentVariable('Path', $env:Path, 'User')

This automatic PATH update removes the need for manual user intervention.

Choosing Between npm and git Modes

Speed : npm is fast; git requires building.

Disk Space : npm uses little space; git includes the full source tree.

Customization : npm offers none; git allows code changes.

Version Control : npm installs released versions only; git can use any commit.

Suitable Scenarios : npm for everyday use; git for development, debugging, or trying unreleased features.

Configuration Options

Command‑Line Flags

--install-method

(npm | git, default npm) --version (npm version or dist‑tag, default latest) --beta (use beta dist‑tag) --git-dir (checkout directory, default ~/openclaw) --no-onboard (skip onboarding) --dry-run (show actions without executing) --verbose (enable debug output)

Environment Variables

OPENCLAW_INSTALL_METHOD

OPENCLAW_VERSION

OPENCLAW_NO_ONBOARD

OPENCLAW_DRY_RUN

SHARP_IGNORE_GLOBAL_LIBVIPS

CLI flags are convenient for one‑off runs, while environment variables are ideal for CI/CD pipelines.

CI/CD Automation

Non‑interactive npm install:

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

Non‑interactive git install via environment variables:

OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL https://openclaw.ai/install.sh | bash

Specify installation directory and JSON output for downstream processing:

curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

GitHub Actions example:

- name: Install OpenClaw
  run: |
    curl -fsSL https://openclaw.ai/install.sh | \
      bash -s -- --no-prompt --no-onboard

Common Troubleshooting

openclaw not found

– PATH missing npm bin; add $(npm prefix -g)/bin to PATH. npm EACCES – No write permission to global npm directory; script falls back to ~/.npm-global and reconfigures npm prefix. sharp/libvips issue – System lacks libvips; set SHARP_IGNORE_GLOBAL_LIBVIPS=1.

Windows “spawn git ENOENT” – Install Git for Windows.

Windows “openclaw is not recognized” – Update PATH with npm prefix.

Network timeout – Use a proxy or switch to a mirror.

Quick checklist:

Verify CLI availability: openclaw --version Run diagnostic: openclaw doctor Check service status:

openclaw gateway status

Security Considerations & Best Practices

OpenClaw can execute shell commands, read/write files, and chain skills, which introduces risk. Microsoft security guidance recommends:

Run in an isolated VM or container with default‑deny outbound rules.

Apply least‑privilege service accounts.

Verify source of skills/extensions before installation.

Regularly audit the agent’s memory, state, and behavior.

Docker isolation example:

# Create internal network
docker network create --internal openclaw-net
# Run container with volume
docker run -d --network openclaw-net \
  -v openclaw-data:/data \
  openclaw/openclaw

The --internal flag restricts the container to an internal network, preventing unwanted outbound traffic.

Conclusion

The OpenClaw installer embodies three key principles: automatic detection, intelligent downgrade, and local‑first installation. Instead of forcing users to satisfy prerequisites, it creates the required conditions automatically. This design improves user experience and provides a solid template for other open‑source tools.

Takeaways for Other Projects

Avoid a monolithic script; separate scripts for distinct platforms simplify maintenance.

Provide a dedicated diagnostic command (e.g., your-tool doctor) to help users troubleshoot.

Offer CI/CD‑friendly configuration via environment variables and JSON output.

Respect existing user environments by supporting older versions and avoiding forced upgrades.

Design with deep understanding of varied user scenarios; a high‑profile project’s installer must be robust.