From 18b480dd3ee7fc79605988c474b6f440f8083436 Mon Sep 17 00:00:00 2001 From: Seb Slight <19554889+sebslight@users.noreply.github.com> Date: Fri, 6 Feb 2026 08:55:05 -0500 Subject: [PATCH] Docs: sharpen Install tab to stop duplicating Getting Started (#10416) * 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 --- docs/docs.json | 11 +- docs/install/index.md | 264 ++++++++++++++++++++------------------ docs/install/installer.md | 52 +++++++- docs/install/node.md | 154 +++++++++++++++------- 4 files changed, 295 insertions(+), 186 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 62a3959366..48dcaa6ee5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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", diff --git a/docs/install/index.md b/docs/install/index.md index 70e66d73a5..8cf14ccb34 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -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 + +On Windows, we strongly recommend running OpenClaw under [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install). + -### 1) Installer script (recommended) +## Install methods -Installs `openclaw` globally via npm and runs onboarding. + +The **installer script** is the recommended way to install OpenClaw. It handles Node detection, installation, and onboarding in one step. + -```bash -curl -fsSL https://openclaw.ai/install.sh | bash -``` + + + Downloads the CLI, installs it globally via npm, and launches the onboarding wizard. -Installer flags: + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash + ``` + + + ```powershell + iwr -useb https://openclaw.ai/install.ps1 | iex + ``` + + -```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): + + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard + ``` + + + ```powershell + & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard + ``` + + -```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) + -If you already have Node: + + If you already have Node 22+ and prefer to manage the install yourself: -```bash -npm install -g openclaw@latest -``` + + + ```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: + + 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. + + + + ```bash + pnpm add -g openclaw@latest + pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc. + openclaw onboard --install-daemon + ``` -Or with pnpm: + + 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. + + + -```bash -pnpm add -g openclaw@latest -pnpm approve-builds -g # approve openclaw, node-llama-cpp, sharp, etc. -``` + -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. + + For contributors or anyone who wants to run from a local checkout. -Then: + + + 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 + ``` + + + 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. + + + ```bash + openclaw onboard --install-daemon + ``` + + -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). + + -### 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) + + + Containerized or headless deployments. + + + Declarative install via Nix. + + + Automated fleet provisioning. + + + CLI-only usage via the Bun runtime. + + ## 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 ` (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: + + 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). + ## Update / uninstall -- Updates: [Updating](/install/updating) -- Migrate to a new machine: [Migrating](/install/migrating) -- Uninstall: [Uninstall](/install/uninstall) + + + Keep OpenClaw up to date. + + + Move to a new machine. + + + Remove OpenClaw completely. + + diff --git a/docs/install/installer.md b/docs/install/installer.md index 99c265cd6f..1fb7061bdf 100644 --- a/docs/install/installer.md +++ b/docs/install/installer.md @@ -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 ` | 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 ` | 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 ` | 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=` | 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: diff --git a/docs/install/node.md b/docs/install/node.md index 00327b2cb4..8c57fde4f7 100644 --- a/docs/install/node.md +++ b/docs/install/node.md @@ -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: + + + **Homebrew** (recommended): + + ```bash + brew install node + ``` + + Or download the macOS installer from [nodejs.org](https://nodejs.org/). + + + + **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). + + + + **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/). + + + + + + 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: + + 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. + + -- 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). + + + ```bash + npm prefix -g + ``` + + + ```bash + echo "$PATH" + ``` -On Windows, add the output of `npm prefix -g` to your PATH. + Look for `/bin` (macOS/Linux) or `` (Windows) in the output. -## Fix: avoid `sudo npm install -g` / permission errors (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). + + + Add the output of `npm prefix -g` to your system PATH via Settings → System → Environment Variables. + + + + + + +### 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.