diff --git a/docs/docs.json b/docs/docs.json index 956f33ed4be..56eec9b18c0 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -867,7 +867,7 @@ "pages": ["install/index", "install/installer", "install/node"] }, { - "group": "Other install methods", + "group": "Containers and package managers", "pages": [ "install/docker", "install/podman", diff --git a/docs/install/index.md b/docs/install/index.md index 7130cf9faac..8830e377059 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -9,158 +9,113 @@ title: "Install" # Install -Already followed [Getting Started](/start/getting-started)? You're all set — this page is for alternative install methods, platform-specific instructions, and maintenance. +## Recommended: installer script + +The fastest way to install. It detects your OS, installs Node if needed, installs OpenClaw, and launches onboarding. + + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + + +To install without running onboarding: + + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard + ``` + + + +For all flags and CI/automation options, see [Installer internals](/install/installer). ## System requirements -- **[Node 24 (recommended)](/install/node)** (Node 22 LTS, currently `22.16+`, is still supported for compatibility; the [installer script](#install-methods) will install Node 24 if missing) -- macOS, Linux, or Windows -- `pnpm` only if you build from source +- **Node 24** (recommended) or Node 22.16+ — the installer script handles this automatically +- **macOS, Linux, or Windows** — both native Windows and WSL2 are supported; WSL2 is more stable. See [Windows](/platforms/windows). +- `pnpm` is only needed if you build from source - -On Windows, we strongly recommend running OpenClaw under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). - +## Alternative install methods -## Install methods +### npm or pnpm - -The **installer script** is the recommended way to install OpenClaw. It handles Node detection, installation, and onboarding in one step. - - - -For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possible. Prefer a clean base OS image (for example Ubuntu LTS), then install OpenClaw yourself with the installer script. - - - - - Downloads the CLI, installs it globally via npm, and launches onboarding. - - - - ```bash - curl -fsSL https://openclaw.ai/install.sh | bash - ``` - - - ```powershell - iwr -useb https://openclaw.ai/install.ps1 | iex - ``` - - - - That's it — the script handles Node detection, installation, and onboarding. - - To skip onboarding and just install the binary: - - - - ```bash - curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard - ``` - - - ```powershell - & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard - ``` - - - - For all flags, env vars, and CI/automation options, see [Installer internals](/install/installer). - - - - - If you already manage Node yourself, we recommend Node 24. OpenClaw still supports Node 22 LTS, currently `22.16+`, for compatibility: - - - - ```bash - npm install -g openclaw@latest - openclaw onboard --install-daemon - ``` - - - If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails, force prebuilt binaries: - - ```bash - SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest - ``` - - If you see `sharp: Please add node-gyp to your dependencies`, either install build tooling (macOS: Xcode CLT + `npm install -g node-gyp`) or use the env var above. - - - - ```bash - pnpm add -g openclaw@latest - pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc. - openclaw onboard --install-daemon - ``` - - - pnpm requires explicit approval for packages with build scripts. After the first install shows the "Ignored build scripts" warning, run `pnpm approve-builds -g` and select the listed packages. - - - - - Want the current GitHub `main` head with a package-manager install? +If you already manage Node yourself: + + ```bash - npm install -g github:openclaw/openclaw#main + npm install -g openclaw@latest + openclaw onboard --install-daemon + ``` + + + ```bash + pnpm add -g openclaw@latest + pnpm approve-builds -g + openclaw onboard --install-daemon ``` - ```bash - pnpm add -g github:openclaw/openclaw#main - ``` + + pnpm requires explicit approval for packages with build scripts. Run `pnpm approve-builds -g` after the first install. + - + + - - For contributors or anyone who wants to run from a local checkout. + + If `sharp` fails due to a globally installed libvips: - - - Clone the [OpenClaw repo](https://github.com/openclaw/openclaw) and build: +```bash +SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest +``` - ```bash - git clone https://github.com/openclaw/openclaw.git - cd openclaw - pnpm install - pnpm ui:build - pnpm build - ``` - - - Make the `openclaw` command available globally: + - ```bash - pnpm link --global - ``` +### From source - Alternatively, skip the link and run commands via `pnpm openclaw ...` from inside the repo. - - - ```bash - openclaw onboard --install-daemon - ``` - - +For contributors or anyone who wants to run from a local checkout: - For deeper development workflows, see [Setup](/start/setup). +```bash +git clone https://github.com/openclaw/openclaw.git +cd openclaw +pnpm install && pnpm ui:build && pnpm build +pnpm link --global +openclaw onboard --install-daemon +``` - - +Or skip the link and use `pnpm openclaw ...` from inside the repo. See [Setup](/start/setup) for full development workflows. -## Other install methods +### Install from GitHub main + +```bash +npm install -g github:openclaw/openclaw#main +``` + +### Containers and package managers Containerized or headless deployments. - Rootless container: run `setup-podman.sh` once, then the launch script. + Rootless container alternative to Docker. - Declarative install via Nix. + Declarative install via Nix flake. Automated fleet provisioning. @@ -170,50 +125,32 @@ For VPS/cloud hosts, avoid third-party "1-click" marketplace images when possibl -## After install - -Verify everything is working: +## Verify the install ```bash +openclaw --version # confirm the CLI is available openclaw doctor # check for config issues -openclaw status # gateway status -openclaw dashboard # open the browser UI +openclaw gateway status # verify the Gateway is running ``` -If you need custom runtime paths, use: +## Hosting and deployment -- `OPENCLAW_HOME` for home-directory based internal paths -- `OPENCLAW_STATE_DIR` for mutable state location -- `OPENCLAW_CONFIG_PATH` for config file location +Deploy OpenClaw on a cloud server or VPS: -See [Environment vars](/help/environment) for precedence and full details. + + Any Linux VPS + Shared Docker steps + K8s + Fly.io + Hetzner + Google Cloud + Azure + Railway + Render + Northflank + -## Troubleshooting: `openclaw` not found - - - Quick diagnosis: - -```bash -node -v -npm -v -npm prefix -g -echo "$PATH" -``` - -If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** in your `$PATH`, your shell can't find global npm binaries (including `openclaw`). - -Fix — add it to your shell startup file (`~/.zshrc` or `~/.bashrc`): - -```bash -export PATH="$(npm prefix -g)/bin:$PATH" -``` - -On Windows, add the output of `npm prefix -g` to your PATH. - -Then open a new terminal (or `rehash` in zsh / `hash -r` in bash). - - -## Update / uninstall +## Update, migrate, or uninstall @@ -226,3 +163,21 @@ Then open a new terminal (or `rehash` in zsh / `hash -r` in bash). Remove OpenClaw completely. + +## Troubleshooting: `openclaw` not found + +If the install succeeded but `openclaw` is not found in your terminal: + +```bash +node -v # Node installed? +npm prefix -g # Where are global packages? +echo "$PATH" # Is the global bin dir in PATH? +``` + +If `$(npm prefix -g)/bin` is not in your `$PATH`, add it to your shell startup file (`~/.zshrc` or `~/.bashrc`): + +```bash +export PATH="$(npm prefix -g)/bin:$PATH" +``` + +Then open a new terminal. See [Node setup](/install/node) for more details.