Getting OpenClaw Up and Running

Setting up new development tools is usually a headache. I often find myself stuck in dependency hell or wrestling with permissions before I can even see if a tool works. It is frustrating when the installation process takes longer than the actual task I am trying to finish.

I prefer installers that just work. I want something that handles the environment for me so I can get straight to the code.

What You’ll Need

A machine running macOS, Linux, WSL, or Windows.
An active internet connection to reach openclaw.ai.

Quick Start

If you are on macOS, Linux, or WSL, I recommend the standard install.sh. It handles Node for you and gets everything ready. Run this in your terminal:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

If you want to see what else you can do with the script, you can check the help flags:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

For those who do not have root access or prefer a local setup, use install-cli.sh. This script puts everything into ~/.openclaw:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

Windows users can use PowerShell. This command gets the job done quickly:

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

If you need more control on Windows, like testing a beta version or skipping the onboarding flow, use these flags:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

Troubleshooting

Sometimes the installation finishes but you cannot find the command. If openclaw is not found when you open a new terminal, you should check the path settings. You can find specific steps to fix this in the Node.js troubleshooting guide.

If you run into other issues during the process, you can ask for help here: AI Setup Assistant

What’s Next

We’ve all been there—cloning a new project only to find out your Node version is out of date, or you’re missing a critical system dependency. I hate spending the first twenty minutes of a project just fighting with my terminal environment instead of actually building something.

I prefer tools that handle the heavy lifting for me. That is why the install.sh script is the recommended way to get OpenClaw running on your machine. It automates the boring parts so you can get straight to work.

What You’ll Need

Before you run the script, make sure you are using one of these environments:

macOS
Linux (including WSL)

The script handles the rest. It will check for Node.js 22+ and Git, and it will even install them for you if they are missing.

Quick Start

For most people, the standard interactive install is the way to go. Just run this command in your terminal:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

What happens under the hood?

When you run that command, the script follows a specific flow:

OS Detection: It identifies if you are on macOS or Linux. On macOS, it checks for Homebrew and installs it if it’s gone.
Environment Check: It ensures you have Node.js 22 or higher. On Linux, it uses NodeSource setup scripts for apt, dnf, or yum to get you up to date.
Dependency Check: It installs Git if you don’t have it.
OpenClaw Installation: You can choose between two methods. The npm method (default) does a global install. The git method clones the repo, installs dependencies with pnpm, builds the project, and sets up a wrapper at ~/.local/bin/openclaw.
Final Touches: It runs openclaw doctor --non-interactive for upgrades and sets SHARP_IGNORE_GLOBAL_LIBVIPS=1.

Source checkout detection

If you run the script while you are already inside an OpenClaw checkout (look for package.json and pnpm-workspace.yaml), the script is smart enough to notice. It will ask if you want to use that checkout via the git method or stick with a global npm install.

Configuration Options

I like having control over my installs. You can pass flags to the script to change how it behaves.

Common Examples

If you want to skip the onboarding process:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

If you prefer the Git-based installation:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

To see what the script would do without actually changing anything:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

Flags Reference

Flag	Description
`--install-method npm\|git`	Choose install method (default: `npm`). Alias: `--method`
`--npm`	Shortcut for npm method
`--git`	Shortcut for git method. Alias: `--github`
`--version <version\|dist-tag>`	npm version or dist-tag (default: `latest`)
`--beta`	Use beta dist-tag if available, else fallback to `latest`
`--git-dir <path>`	Checkout directory (default: `~/openclaw`). Alias: `--dir`
`--no-git-update`	Skip `git pull` for existing checkout
`--no-prompt`	Disable prompts
`--no-onboard`	Skip onboarding
`--onboard`	Enable onboarding
`--dry-run`	Print actions without applying changes
`--verbose`	Enable debug output (`set -x`, npm notice-level logs)
`--help`	Show usage (`-h`)

Environment Variables

You can also configure the installer using environment variables:

Variable	Description
`OPENCLAW_INSTALL_METHOD=git\|npm`	Install method
`OPENCLAW_VERSION=latest\|next\|<semver>`	npm version or dist-tag
`OPENCLAW_BETA=0\|1`	Use beta if available
`OPENCLAW_GIT_DIR=<path>`	Checkout directory
`OPENCLAW_GIT_UPDATE=0\|1`	Toggle git updates
`OPENCLAW_NO_PROMPT=1`	Disable prompts
`OPENCLAW_NO_ONBOARD=1`	Skip onboarding
`OPENCLAW_DRY_RUN=1`	Dry run mode
`OPENCLAW_VERBOSE=1`	Debug mode
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	Control sharp/libvips behavior (default: `1`)

Troubleshooting

If things don’t go as planned, here are the two most common issues:

Invalid Method Selection: If you provide an invalid value to --install-method or select an invalid option during the prompt, the script will exit with code 2.
No TTY Available: If you run the script in an environment without a TTY (like some CI runners) and you haven’t specified an install method, it will default to npm and issue a warning.

If you hit a wall, you can always use the AI Setup Assistant for help.

What’s Next

Once you have OpenClaw installed, you might want to check out these resources:

I hate it when a new tool forces me to mess with my global Node.js version or clutters my system directories. It usually leads to version conflicts that take hours to fix. If you want to try OpenClaw without worrying about your existing setup, I recommend using the install-cli.sh script.

This script is built for environments where you want everything kept under a local prefix. It handles the Node dependency for you by installing a local runtime, so your system’s global state stays exactly as it is.

What You’ll Need

Before running the script, make sure your environment meets these basic requirements mentioned in our setup:

A Linux distribution (using apt, dnf, or yum) or macOS (with Homebrew) if you need the script to auto-install Git.
Internet access to download the Node tarball and OpenClaw packages.

Quick Start

You can get OpenClaw running in less than five minutes. By default, the script puts everything in ~/.openclaw and sets up a local Node runtime (version 22.22.0).

Run this command to start the default installation:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

The script follows a specific flow:

Local Node runtime: It downloads the Node tarball to <prefix>/tools/node-v<version> and verifies the SHA-256 hash.
Git Check: If Git is missing, it tries to install it using your system’s package manager.
Local Install: It installs OpenClaw using npm with the --prefix flag and creates a wrapper at <prefix>/bin/openclaw.

Customizing Your Setup

I often need to change where tools are installed or trigger the onboarding process immediately. You can pass arguments to the script using the -s -- syntax.

Custom Prefix and Version

If you want to install OpenClaw to a specific directory like /opt/openclaw and use the latest version, use this:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

Automation and Onboarding

For those who want to jump straight into configuration or need machine-readable output:

# Run onboarding immediately after install
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard

# Get NDJSON events for automation
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

Reference Guides

CLI Flags

Flag	Description
`--prefix <path>`	Install prefix (default: `~/.openclaw`)
`--version <ver>`	OpenClaw version or dist-tag (default: `latest`)
`--node-version <ver>`	Node version (default: `22.22.0`)
`--json`	Emit NDJSON events
`--onboard`	Run `openclaw onboard` after install
`--no-onboard`	Skip onboarding (default)
`--set-npm-prefix`	On Linux, force npm prefix to `~/.npm-global` if current prefix is not writable
`--help`	Show usage (`-h`)

Environment Variables

Variable	Description
`OPENCLAW_PREFIX=<path>`	Install prefix
`OPENCLAW_VERSION=<ver>`	OpenClaw version or dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node version
`OPENCLAW_NO_ONBOARD=1`	Skip onboarding
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm log level
`OPENCLAW_GIT_DIR=<path>`	Legacy cleanup lookup path (used when removing old `Peekaboo` submodule checkout)
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	Control sharp/libvips behavior (default: `1`)

Troubleshooting

If you run into issues during the installation, check these two scenarios covered by the script:

Missing Git: The script attempts to install Git automatically. If this fails, ensure your package manager (apt, dnf, yum, or brew) is working correctly.
Permissions Issues: If your chosen prefix is not writable on Linux, use the --set-npm-prefix flag. This forces the npm prefix to ~/.npm-global.

If you need more help with your specific environment, check out the AI Setup Assistant.

What’s Next

Setting up a new development tool can be a real headache. You often end up chasing down missing dependencies, fixing broken PATH variables, or realized half an hour later that you have the wrong version of a runtime installed. I prefer when things just work without the manual chores.

The OpenClaw installation script for Windows handles the heavy lifting for you. It checks your environment, grabs the right version of Node.js if you don’t have it, and sets up the CLI so you can start working immediately.

What You’ll Need

Before you run the script, make sure you meet these requirements:

Windows environment with PowerShell 5+.
Node.js 22+ (If you don’t have this, the script tries to install it via winget, Chocolatey, or Scoop).
Git (Only required if you choose the Git installation method).

Quick Start

The fastest way to get started is the default NPM installation. Open your PowerShell terminal and run this command:

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

This one-liner downloads the script and executes it. Here is what happens behind the scenes:

It verifies your PowerShell and Node.js versions.
It installs OpenClaw globally via npm.
It adds the necessary binary directory to your user PATH.
If you are upgrading, it runs openclaw doctor to check for issues.

Alternative: Git Install

If you want to work with the source code or stay on the bleeding edge, you can use the Git method. This clones the repository to your machine and builds it locally.

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git

This method puts a wrapper at %USERPROFILE%\.local\bin\openclaw.cmd so you can call the command from anywhere.

Customizing the Install

You can pass flags to the script to change its behavior. For example, if you want to install via Git but into a specific folder:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

If you are worried about what the script might change, run a dry run first to see the actions without executing them:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun

Reference

Flags Reference

Flag	Description
`-InstallMethod npm\|git`	Install method (default: `npm`)
`-Tag <tag>`	npm dist-tag (default: `latest`)
`-GitDir <path>`	Checkout directory (default: `%USERPROFILE%\openclaw`)
`-NoOnboard`	Skip onboarding
`-NoGitUpdate`	Skip `git pull`
`-DryRun`	Print actions only

Environment Variables Reference

You can also control the script by setting these environment variables before execution:

Variable	Description
`OPENCLAW_INSTALL_METHOD=git\|npm`	Install method
`OPENCLAW_GIT_DIR=<path>`	Checkout directory
`OPENCLAW_NO_ONBOARD=1`	Skip onboarding
`OPENCLAW_GIT_UPDATE=0`	Disable git pull
`OPENCLAW_DRY_RUN=1`	Dry run mode

Troubleshooting

Missing Git

If you try to use -InstallMethod git but don’t have Git installed, the script will exit. It will provide you with the official Git for Windows link so you can install it and try again.

Node.js Installation

The script attempts to install Node.js 22+ using common Windows package managers. If winget, Chocolatey, and Scoop are all missing or fail, you will need to install Node.js manually from the official website.

If you hit a wall during the setup, you can get help from the AI Setup Assistant.

What’s Next

I have spent too many hours watching a CI pipeline hang because a script was waiting for a “yes/no” confirmation I could not provide. It is a waste of time. When you automate your setup, you want it to be quiet and predictable.

If you are setting up OpenClaw in a CI environment, you should avoid interactive prompts. I recommend using specific flags and environment variables to make the process run without manual input.

What You’ll Need

Before you start your automation script, make sure your environment has these ready:

Git (required for git installs or git-based dependencies)
Node.js and npm

Quick Start

You can get OpenClaw running in your CI in about five minutes. Here are the best ways to handle the installation depending on your environment.

Using npm (Linux/macOS)

If you want a non-interactive npm install, use the --no-prompt and --no-onboard flags:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

Using Git

If you prefer the git method, you can pass environment variables directly to the command:

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

JSON Output and Custom Paths

If you need the CLI specifically with a custom prefix and JSON output, use this:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

Windows (PowerShell)

For Windows-based automation, use the -NoOnboard flag to skip the initial setup steps:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Troubleshooting

CI environments can be picky. Here are the common issues I found in the documentation and how to fix them.

Why is Git required? Git is required for the git install method. Even if you use npm, the script checks for Git. This helps avoid spawn git ENOENT failures when your dependencies use git URLs.

Why does npm hit EACCES on Linux? Some Linux setups point the npm global prefix to paths owned by root. The install.sh script can help by switching the prefix to ~/.npm-global and adding PATH exports to your shell rc files.

sharp/libvips issues The scripts set SHARP_IGNORE_GLOBAL_LIBVIPS=1 by default. This stops sharp from building against system libvips. If you need to override this, run:

SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

Windows: “npm error spawn git / ENOENT” You need to install Git for Windows. After that, reopen PowerShell and run the installer again.

Windows: “openclaw is not recognized” Run npm config get prefix. Take that path, add \bin to the end, and add that full directory to your user PATH. Reopen PowerShell for the changes to take effect.

openclaw not found after install This is almost always a PATH issue. You should check your environment variables to ensure the install directory is included.

If you hit a wall that isn’t covered here, check out the AI Setup Assistant.

What’s Next

Node.js troubleshooting

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.