source/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-02-09 05:19:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs: sharpen Install tab to stop duplicating Getting Started (#10416)

Browse Source 
* docs(install): reframe install overview to stop duplicating getting started

* docs(install): link default installer row to getting started, not internals

* docs(install): use Mintlify components for install overview

* docs(install): fix card grid layout with CardGroup

* docs(install): platform tabs for global install, npm/pnpm as accordion

* docs(install): add PowerShell no-onboard alternative

* docs(install): add repo link to from-source clone step

* docs(install): capitalize OpenClaw in repo link

* docs(install): add pnpm link --global to from-source steps

* docs(install): rewrite install overview for clarity and flow

* docs(install): use tooltip for Windows WSL2 recommendation

* docs(install): use Note box for Windows WSL2 recommendation

* docs(install): group install methods under single heading

* docs(install): standardize tab labels across installer sections

* docs(install): rewrite Node.js page with install instructions and better structure

* docs(install): clarify Node.js page intro

* docs(install): scope auto-install note to installer script, link Node page

* docs(install): fix installer script link to internals page

* docs: rename Install methods nav group to Other install methods

* docs(install): link to on-page anchor, use Tip box for recommended

* docs(install): wrap install methods in AccordionGroup with Tip box

* docs: move Node.js page from Install to Help > Environment and debugging

* docs(install): add complete flags and env vars reference to installer internals

* docs(install): use stable troubleshooting anchor for Node.js link

* docs(install): fix Node page installer anchor

* docs(install): fix broken installer script anchor in requirements note
This commit is contained in:
Seb Slight
2026-02-06 08:55:05 -05:00
committed by GitHub
parent c75275f109
commit 18b480dd3e
4 changed files with 295 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/docs.json
View File

@@ -801,14 +801,8 @@
"pages": ["install/index", "install/installer"]
},
{
"group": "Install methods",
"pages": [
"install/node",
"install/docker",
"install/nix",
"install/ansible",
"install/bun"
]
"group": "Other install methods",
"pages": ["install/docker", "install/nix", "install/ansible", "install/bun"]
},
{
"group": "Maintenance",
@@ -1221,6 +1215,7 @@
{
"group": "Environment and debugging",
"pages": [
"install/node",
"environment",
"debugging",
"testing",

264
docs/install/index.md
View File

@@ -1,164 +1,172 @@
---
summary: "Install OpenClaw (recommended installer, global install, or from source)"
summary: "Install OpenClaw — installer script, npm/pnpm, from source, Docker, and more"
read_when:
- Installing OpenClaw
- You want to install from GitHub
title: "Install Overview"
- You need an install method other than the Getting Started quickstart
- You want to deploy to a cloud platform
- You need to update, migrate, or uninstall
title: "Install"
---
# Install Overview
# Install
Use the installer unless you have a reason not to. It sets up the CLI and runs onboarding.
## Quick install (recommended)
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
Windows (PowerShell):
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
Next step (if you skipped onboarding):
```bash
openclaw onboard --install-daemon
```
Already followed [Getting Started](/start/getting-started)? You're all set — this page is for alternative install methods, platform-specific instructions, and maintenance.
## System requirements
- **Node >=22**
- macOS, Linux, or Windows via WSL2
- **[Node 22+](/install/node)** (the [installer script](#install-methods) will install it if missing)
- macOS, Linux, or Windows
- `pnpm` only if you build from source
## Choose your install path
<Note>
On Windows, we strongly recommend running OpenClaw under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install).
</Note>
### 1) Installer script (recommended)
## Install methods
Installs `openclaw` globally via npm and runs onboarding.
<Tip>
The **installer script** is the recommended way to install OpenClaw. It handles Node detection, installation, and onboarding in one step.
</Tip>
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
<AccordionGroup>
<Accordion title="Installer script" icon="rocket" defaultOpen>
Downloads the CLI, installs it globally via npm, and launches the onboarding wizard.
Installer flags:
<Tabs>
<Tab title="macOS / Linux / WSL2">
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
</Tab>
</Tabs>
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
```
That's it — the script handles Node detection, installation, and onboarding.
Details: [Installer internals](/install/installer).
To skip onboarding and just install the binary:
Non-interactive (skip onboarding):
<Tabs>
<Tab title="macOS / Linux / WSL2">
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
</Tab>
<Tab title="Windows (PowerShell)">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```
</Tab>
</Tabs>
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
For all flags, env vars, and CI/automation options, see [Installer internals](/install/installer).
### 2) Global install (manual)
</Accordion>
If you already have Node:
<Accordion title="npm / pnpm" icon="package">
If you already have Node 22+ and prefer to manage the install yourself:
```bash
npm install -g openclaw@latest
```
<Tabs>
<Tab title="npm">
```bash
npm install -g openclaw@latest
openclaw onboard --install-daemon
```
If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, force prebuilt binaries:
<Accordion title="sharp build errors?">
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
```
```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 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
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.
</Accordion>
</Tab>
<Tab title="pnpm">
```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc.
openclaw onboard --install-daemon
```
Or with pnpm:
<Note>
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.
</Note>
</Tab>
</Tabs>
```bash
pnpm add -g openclaw@latest
pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc.
```
</Accordion>
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.
<Accordion title="From source" icon="github">
For contributors or anyone who wants to run from a local checkout.
Then:
<Steps>
<Step title="Clone and build">
Clone the [OpenClaw repo](https://github.com/openclaw/openclaw) and build:
```bash
openclaw onboard --install-daemon
```
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
```
</Step>
<Step title="Link the CLI">
Make the `openclaw` command available globally:
### 3) From source (contributors/dev)
```bash
pnpm link --global
```
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon
```
Alternatively, skip the link and run commands via `pnpm openclaw ...` from inside the repo.
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --install-daemon
```
</Step>
</Steps>
Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`.
For deeper development workflows, see [Setup](/start/setup).
For deeper development workflows, see [Setup](/start/setup).
</Accordion>
</AccordionGroup>
### 4) Other install options
## Other install methods
- Docker: [Docker](/install/docker)
- Nix: [Nix](/install/nix)
- Ansible: [Ansible](/install/ansible)
- Bun (CLI only): [Bun](/install/bun)
<CardGroup cols={2}>
<Card title="Docker" href="/install/docker" icon="container">
Containerized or headless deployments.
</Card>
<Card title="Nix" href="/install/nix" icon="snowflake">
Declarative install via Nix.
</Card>
<Card title="Ansible" href="/install/ansible" icon="server">
Automated fleet provisioning.
</Card>
<Card title="Bun" href="/install/bun" icon="zap">
CLI-only usage via the Bun runtime.
</Card>
</CardGroup>
## After install
- Run onboarding: `openclaw onboard --install-daemon`
- Quick check: `openclaw doctor`
- Check gateway health: `openclaw status` + `openclaw health`
- Open the dashboard: `openclaw dashboard`
## Install method: npm vs git (installer)
The installer supports two methods:
- `npm` (default): `npm install -g openclaw@latest`
- `git`: clone/build from GitHub and run from a source checkout
### CLI flags
Verify everything is working:
```bash
# Explicit npm
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
# Install from GitHub (source checkout)
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
openclaw doctor # check for config issues
openclaw status # gateway status
openclaw dashboard # open the browser UI
```
Common flags:
## Troubleshooting: `openclaw` not found
- `--install-method npm|git`
- `--git-dir <path>` (default: `~/openclaw`)
- `--no-git-update` (skip `git pull` when using an existing checkout)
- `--no-prompt` (disable prompts; required in CI/automation)
- `--dry-run` (print what would happen; make no changes)
- `--no-onboard` (skip onboarding)
### Environment variables
Equivalent env vars (useful for automation):
- `OPENCLAW_INSTALL_METHOD=git|npm`
- `OPENCLAW_GIT_DIR=...`
- `OPENCLAW_GIT_UPDATE=0|1`
- `OPENCLAW_NO_PROMPT=1`
- `OPENCLAW_DRY_RUN=1`
- `OPENCLAW_NO_ONBOARD=1`
- `SHARP_IGNORE_GLOBAL_LIBVIPS=0|1` (default: `1`; avoids `sharp` building against system libvips)
## Troubleshooting: `openclaw` not found (PATH)
Quick diagnosis:
<Accordion title="PATH diagnosis and fix">
Quick diagnosis:
```bash
node -v
@@ -167,21 +175,29 @@ npm prefix -g
echo "$PATH"
```
If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `openclaw`).
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 (zsh: `~/.zshrc`, bash: `~/.bashrc`):
Fix — add it to your shell startup file (`~/.zshrc` or `~/.bashrc`):
```bash
# macOS / Linux
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).
</Accordion>
## Update / uninstall
- Updates: [Updating](/install/updating)
- Migrate to a new machine: [Migrating](/install/migrating)
- Uninstall: [Uninstall](/install/uninstall)
<CardGroup cols={3}>
<Card title="Updating" href="/install/updating" icon="refresh-cw">
Keep OpenClaw up to date.
</Card>
<Card title="Migrating" href="/install/migrating" icon="arrow-right">
Move to a new machine.
</Card>
<Card title="Uninstall" href="/install/uninstall" icon="trash-2">
Remove OpenClaw completely.
</Card>
</CardGroup>

52
docs/install/installer.md
View File

@@ -11,9 +11,9 @@ title: "Installer Internals"
OpenClaw ships two installer scripts (served from `openclaw.ai`):
- `https://openclaw.ai/install.sh` — “recommended” installer (global npm install by default; can also install from a GitHub checkout)
- `https://openclaw.ai/install-cli.sh` — non-root-friendly CLI installer (installs into a prefix with its own Node)
- `https://openclaw.ai/install.ps1` — Windows PowerShell installer (npm by default; optional git install)
- `https://openclaw.ai/install.sh` - "recommended" installer (global npm install by default; can also install from a GitHub checkout)
- `https://openclaw.ai/install-cli.sh` - non-root-friendly CLI installer (installs into a prefix with its own Node)
- `https://openclaw.ai/install.ps1` - Windows PowerShell installer (npm by default; optional git install)
To see the current flags/behavior, run:
@@ -27,7 +27,45 @@ Windows (PowerShell) help:
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
```
If the installer completes but `openclaw` is not found in a new terminal, it’s usually a Node/npm PATH issue. See: [Install](/install#nodejs--npm-path-sanity).
If the installer completes but `openclaw` is not found in a new terminal, it's usually a Node/npm PATH issue. See: [Node.js](/install/node#troubleshooting).
## Flags and environment variables
### CLI flags (install.sh)
| Flag | Description |
| --------------------------- | ------------------------------------------------ |
| `--install-method npm\|git` | Choose install method (default: `npm`) |
| `--git-dir <path>` | Source checkout location (default: `~/openclaw`) |
| `--no-git-update` | Skip `git pull` when using an existing checkout |
| `--no-prompt` | Disable prompts (required in CI/automation) |
| `--dry-run` | Print what would happen; make no changes |
| `--no-onboard` | Skip onboarding after install |
### PowerShell flags (install.ps1)
| Flag | Description |
| ------------------------- | ----------------------------------------------- |
| `-InstallMethod npm\|git` | Choose install method (default: `npm`) |
| `-GitDir <path>` | Source checkout location |
| `-NoOnboard` | Skip onboarding after install |
| `-NoGitUpdate` | Skip `git pull` when using an existing checkout |
| `-DryRun` | Print what would happen; make no changes |
| `-Tag <tag>` | npm dist-tag to install (default: `latest`) |
### Environment variables
Equivalent env vars (useful for CI/automation):
| Variable | Description |
| ---------------------------------- | ------------------------------------------------------------ |
| `OPENCLAW_INSTALL_METHOD=git\|npm` | Install method |
| `OPENCLAW_GIT_DIR=<path>` | Source checkout location |
| `OPENCLAW_GIT_UPDATE=0\|1` | Toggle git pull |
| `OPENCLAW_NO_PROMPT=1` | Disable prompts |
| `OPENCLAW_DRY_RUN=1` | Dry run mode |
| `OPENCLAW_NO_ONBOARD=1` | Skip onboarding |
| `SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1` | Avoid `sharp` building against system libvips (default: `1`) |
## install.sh (recommended)
@@ -43,13 +81,13 @@ What it does (high level):
- For git installs: runs `openclaw doctor --non-interactive` after install/update (best effort).
- Mitigates `sharp` native install gotchas by defaulting `SHARP_IGNORE_GLOBAL_LIBVIPS=1` (avoids building against system libvips).
If you _want_ `sharp` to link against a globally-installed libvips (or you’re debugging), set:
If you _want_ `sharp` to link against a globally-installed libvips (or you're debugging), set:
```bash
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
```
### Discoverability / “git install” prompt
### Discoverability / "git install" prompt
If you run the installer while **already inside a OpenClaw source checkout** (detected via `package.json` + `pnpm-workspace.yaml`), it prompts:
@@ -74,7 +112,7 @@ On some Linux setups (especially after installing Node via the system package ma
## install-cli.sh (non-root CLI installer)
This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don’t want to touch the system Node/npm.
This script installs `openclaw` into a prefix (default: `~/.openclaw`) and also installs a dedicated Node runtime under that prefix, so it can work on machines where you don't want to touch the system Node/npm.
Help:

154
docs/install/node.md
View File

@@ -1,58 +1,133 @@
---
title: "Node.js + npm (PATH sanity)"
summary: "Node.js + npm install sanity: versions, PATH, and global installs"
title: "Node.js"
summary: "Install and configure Node.js for OpenClaw — version requirements, install options, and PATH troubleshooting"
read_when:
- "You installed OpenClaw but `openclaw` is “command not found”"
- "You’re setting up Node.js/npm on a new machine"
- "npm install -g ... fails with permissions or PATH issues"
- "You need to install Node.js before installing OpenClaw"
- "You installed OpenClaw but `openclaw` is command not found"
- "npm install -g fails with permissions or PATH issues"
---
# Node.js + npm (PATH sanity)
# Node.js
OpenClaw’s runtime baseline is **Node 22+**.
OpenClaw requires **Node 22 or newer**. The [installer script](/install#install-methods) will detect and install Node automatically — this page is for when you want to set up Node yourself and make sure everything is wired up correctly (versions, PATH, global installs).
If you can run `npm install -g openclaw@latest` but later see `openclaw: command not found`, it’s almost always a **PATH** issue: the directory where npm puts global binaries isn’t on your shell’s PATH.
## Quick diagnosis
Run:
## Check your version
```bash
node -v
npm -v
npm prefix -g
echo "$PATH"
```
If `$(npm prefix -g)/bin` (macOS/Linux) or `$(npm prefix -g)` (Windows) is **not** present inside `echo "$PATH"`, your shell can’t find global npm binaries (including `openclaw`).
If this prints `v22.x.x` or higher, you're good. If Node isn't installed or the version is too old, pick an install method below.
## Fix: put npm’s global bin dir on PATH
## Install Node
1. Find your global npm prefix:
<Tabs>
<Tab title="macOS">
**Homebrew** (recommended):
```bash
brew install node
```
Or download the macOS installer from [nodejs.org](https://nodejs.org/).
</Tab>
<Tab title="Linux">
**Ubuntu / Debian:**
```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**Fedora / RHEL:**
```bash
sudo dnf install nodejs
```
Or use a version manager (see below).
</Tab>
<Tab title="Windows">
**winget** (recommended):
```powershell
winget install OpenJS.NodeJS.LTS
```
**Chocolatey:**
```powershell
choco install nodejs-lts
```
Or download the Windows installer from [nodejs.org](https://nodejs.org/).
</Tab>
</Tabs>
<Accordion title="Using a version manager (nvm, fnm, mise, asdf)">
Version managers let you switch between Node versions easily. Popular options:
- [**fnm**](https://github.com/Schniz/fnm) — fast, cross-platform
- [**nvm**](https://github.com/nvm-sh/nvm) — widely used on macOS/Linux
- [**mise**](https://mise.jdx.dev/) — polyglot (Node, Python, Ruby, etc.)
Example with fnm:
```bash
npm prefix -g
fnm install 22
fnm use 22
```
2. Add the global npm bin directory to your shell startup file:
<Warning>
Make sure your version manager is initialized in your shell startup file (`~/.zshrc` or `~/.bashrc`). If it isn't, `openclaw` may not be found in new terminal sessions because the PATH won't include Node's bin directory.
</Warning>
</Accordion>
- zsh: `~/.zshrc`
- bash: `~/.bashrc`
## Troubleshooting
Example (replace the path with your `npm prefix -g` output):
### `openclaw: command not found`
```bash
# macOS / Linux
export PATH="/path/from/npm/prefix/bin:$PATH"
```
This almost always means npm's global bin directory isn't on your PATH.
Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
<Steps>
<Step title="Find your global npm prefix">
```bash
npm prefix -g
```
</Step>
<Step title="Check if it's on your PATH">
```bash
echo "$PATH"
```
On Windows, add the output of `npm prefix -g` to your PATH.
Look for `<npm-prefix>/bin` (macOS/Linux) or `<npm-prefix>` (Windows) in the output.
## Fix: avoid `sudo npm install -g` / permission errors (Linux)
</Step>
<Step title="Add it to your shell startup file">
<Tabs>
<Tab title="macOS / Linux">
Add to `~/.zshrc` or `~/.bashrc`:
If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```
Then open a new terminal (or run `rehash` in zsh / `hash -r` in bash).
</Tab>
<Tab title="Windows">
Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables.
</Tab>
</Tabs>
</Step>
</Steps>
### Permission errors on `npm install -g` (Linux)
If you see `EACCES` errors, switch npm's global prefix to a user-writable directory:
```bash
mkdir -p "$HOME/.npm-global"
@@ -60,19 +135,4 @@ npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
```
Persist the `export PATH=...` line in your shell startup file.
## Recommended Node install options
You’ll have the fewest surprises if Node/npm are installed in a way that:
- keeps Node updated (22+)
- makes the global npm bin dir stable and on PATH in new shells
Common choices:
- macOS: Homebrew (`brew install node`) or a version manager
- Linux: your preferred version manager, or a distro-supported install that provides Node 22+
- Windows: official Node installer, `winget`, or a Windows Node version manager
If you use a version manager (nvm/fnm/asdf/etc), ensure it’s initialized in the shell you use day-to-day (zsh vs bash) so the PATH it sets is present when you run installers.
Add the `export PATH=...` line to your `~/.bashrc` or `~/.zshrc` to make it permanent.