@captain-app/openclaw 2026.2.4

package/docs/install/index.md

@@ -0,0 +1,185 @@
+---
+summary: "Install OpenClaw (recommended installer, global install, or from source)"
+read_when:
+  - Installing OpenClaw
+  - You want to install from GitHub
+title: "Install"
+---
+
+# 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
+```
+
+## System requirements
+
+- **Node >=22**
+- macOS, Linux, or Windows via WSL2
+- `pnpm` only if you build from source
+
+## Choose your install path
+
+### 1) Installer script (recommended)
+
+Installs `openclaw` globally via npm and runs onboarding.
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Installer flags:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+Details: [Installer internals](/install/installer).
+
+Non-interactive (skip onboarding):
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
+```
+
+### 2) Global install (manual)
+
+If you already have Node:
+
+```bash
+npm install -g openclaw@latest
+```
+
+If you have libvips installed globally (common on macOS via Homebrew) and `sharp` fails to install, 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 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` workaround above to skip the native build.
+
+Or with pnpm:
+
+```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.
+
+Then:
+
+```bash
+openclaw onboard --install-daemon
+```
+
+### 3) From source (contributors/dev)
+
+```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
+```
+
+Tip: if you don’t have a global install yet, run repo commands via `pnpm openclaw ...`.
+
+### 4) Other install options
+
+- Docker: [Docker](/install/docker)
+- Nix: [Nix](/install/nix)
+- Ansible: [Ansible](/install/ansible)
+- Bun (CLI only): [Bun](/install/bun)
+
+## 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
+
+```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
+```
+
+Common flags:
+
+- `--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:
+
+```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`).
+
+Fix: add it to your shell startup file (zsh: `~/.zshrc`, bash: `~/.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)

package/docs/install/installer.md

@@ -0,0 +1,123 @@
+---
+summary: "How the installer scripts work (install.sh + install-cli.sh), flags, and automation"
+read_when:
+  - You want to understand `openclaw.ai/install.sh`
+  - You want to automate installs (CI / headless)
+  - You want to install from a GitHub checkout
+title: "Installer Internals"
+---
+
+# 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)
+
+To see the current flags/behavior, run:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
+```
+
+Windows (PowerShell) help:
+
+```powershell
+& ([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).
+
+## install.sh (recommended)
+
+What it does (high level):
+
+- Detect OS (macOS / Linux / WSL).
+- Ensure Node.js **22+** (macOS via Homebrew; Linux via NodeSource).
+- Choose install method:
+  - `npm` (default): `npm install -g openclaw@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- On Linux: avoid global npm permission errors by switching npm's prefix to `~/.npm-global` when needed.
+- If upgrading an existing install: runs `openclaw doctor --non-interactive` (best effort).
+- 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:
+
+```bash
+SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+### 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:
+
+- update and use this checkout (`git`)
+- or migrate to the global npm install (`npm`)
+
+In non-interactive contexts (no TTY / `--no-prompt`), you must pass `--install-method git|npm` (or set `OPENCLAW_INSTALL_METHOD`), otherwise the script exits with code `2`.
+
+### Why Git is needed
+
+Git is required for the `--install-method git` path (clone / pull).
+
+For `npm` installs, Git is _usually_ not required, but some environments still end up needing it (e.g. when a package or dependency is fetched via a git URL). The installer currently ensures Git is present to avoid `spawn git ENOENT` surprises on fresh distros.
+
+### Why npm hits `EACCES` on fresh Linux
+
+On some Linux setups (especially after installing Node via the system package manager or NodeSource), npm's global prefix points at a root-owned location. Then `npm install -g ...` fails with `EACCES` / `mkdir` permission errors.
+
+`install.sh` mitigates this by switching the prefix to:
+
+- `~/.npm-global` (and adding it to `PATH` in `~/.bashrc` / `~/.zshrc` when present)
+
+## 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.
+
+Help:
+
+```bash
+curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help
+```
+
+## install.ps1 (Windows PowerShell)
+
+What it does (high level):
+
+- Ensure Node.js **22+** (winget/Chocolatey/Scoop or manual).
+- Choose install method:
+  - `npm` (default): `npm install -g openclaw@latest`
+  - `git`: clone/build a source checkout and install a wrapper script
+- Runs `openclaw doctor --non-interactive` on upgrades and git installs (best effort).
+
+Examples:
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
+```
+
+```powershell
+iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"
+```
+
+Environment variables:
+
+- `OPENCLAW_INSTALL_METHOD=git|npm`
+- `OPENCLAW_GIT_DIR=...`
+
+Git requirement:
+
+If you choose `-InstallMethod git` and Git is missing, the installer will print the
+Git for Windows link (`https://git-scm.com/download/win`) and exit.
+
+Common Windows issues:
+
+- **npm error spawn git / ENOENT**: install Git for Windows and reopen PowerShell, then rerun the installer.
+- **"openclaw" is not recognized**: your npm global bin folder is not on PATH. Most systems use
+  `%AppData%\\npm`. You can also run `npm config get prefix` and add `\\bin` to PATH, then reopen PowerShell.

package/docs/install/migrating.md

@@ -0,0 +1,192 @@
+---
+summary: "Move (migrate) a OpenClaw install from one machine to another"
+read_when:
+  - You are moving OpenClaw to a new laptop/server
+  - You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
+title: "Migration Guide"
+---
+
+# Migrating OpenClaw to a new machine
+
+This guide migrates a OpenClaw Gateway from one machine to another **without redoing onboarding**.
+
+The migration is simple conceptually:
+
+- Copy the **state directory** (`$OPENCLAW_STATE_DIR`, default: `~/.openclaw/`) — this includes config, auth, sessions, and channel state.
+- Copy your **workspace** (`~/.openclaw/workspace/` by default) — this includes your agent files (memory, prompts, etc.).
+
+But there are common footguns around **profiles**, **permissions**, and **partial copies**.
+
+## Before you start (what you are migrating)
+
+### 1) Identify your state directory
+
+Most installs use the default:
+
+- **State dir:** `~/.openclaw/`
+
+But it may be different if you use:
+
+- `--profile <name>` (often becomes `~/.openclaw-<profile>/`)
+- `OPENCLAW_STATE_DIR=/some/path`
+
+If you’re not sure, run on the **old** machine:
+
+```bash
+openclaw status
+```
+
+Look for mentions of `OPENCLAW_STATE_DIR` / profile in the output. If you run multiple gateways, repeat for each profile.
+
+### 2) Identify your workspace
+
+Common defaults:
+
+- `~/.openclaw/workspace/` (recommended workspace)
+- a custom folder you created
+
+Your workspace is where files like `MEMORY.md`, `USER.md`, and `memory/*.md` live.
+
+### 3) Understand what you will preserve
+
+If you copy **both** the state dir and workspace, you keep:
+
+- Gateway configuration (`openclaw.json`)
+- Auth profiles / API keys / OAuth tokens
+- Session history + agent state
+- Channel state (e.g. WhatsApp login/session)
+- Your workspace files (memory, skills notes, etc.)
+
+If you copy **only** the workspace (e.g., via Git), you do **not** preserve:
+
+- sessions
+- credentials
+- channel logins
+
+Those live under `$OPENCLAW_STATE_DIR`.
+
+## Migration steps (recommended)
+
+### Step 0 — Make a backup (old machine)
+
+On the **old** machine, stop the gateway first so files aren’t changing mid-copy:
+
+```bash
+openclaw gateway stop
+```
+
+(Optional but recommended) archive the state dir and workspace:
+
+```bash
+# Adjust paths if you use a profile or custom locations
+cd ~
+tar -czf openclaw-state.tgz .openclaw
+
+tar -czf openclaw-workspace.tgz .openclaw/workspace
+```
+
+If you have multiple profiles/state dirs (e.g. `~/.openclaw-main`, `~/.openclaw-work`), archive each.
+
+### Step 1 — Install OpenClaw on the new machine
+
+On the **new** machine, install the CLI (and Node if needed):
+
+- See: [Install](/install)
+
+At this stage, it’s OK if onboarding creates a fresh `~/.openclaw/` — you will overwrite it in the next step.
+
+### Step 2 — Copy the state dir + workspace to the new machine
+
+Copy **both**:
+
+- `$OPENCLAW_STATE_DIR` (default `~/.openclaw/`)
+- your workspace (default `~/.openclaw/workspace/`)
+
+Common approaches:
+
+- `scp` the tarballs and extract
+- `rsync -a` over SSH
+- external drive
+
+After copying, ensure:
+
+- Hidden directories were included (e.g. `.openclaw/`)
+- File ownership is correct for the user running the gateway
+
+### Step 3 — Run Doctor (migrations + service repair)
+
+On the **new** machine:
+
+```bash
+openclaw doctor
+```
+
+Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches.
+
+Then:
+
+```bash
+openclaw gateway restart
+openclaw status
+```
+
+## Common footguns (and how to avoid them)
+
+### Footgun: profile / state-dir mismatch
+
+If you ran the old gateway with a profile (or `OPENCLAW_STATE_DIR`), and the new gateway uses a different one, you’ll see symptoms like:
+
+- config changes not taking effect
+- channels missing / logged out
+- empty session history
+
+Fix: run the gateway/service using the **same** profile/state dir you migrated, then rerun:
+
+```bash
+openclaw doctor
+```
+
+### Footgun: copying only `openclaw.json`
+
+`openclaw.json` is not enough. Many providers store state under:
+
+- `$OPENCLAW_STATE_DIR/credentials/`
+- `$OPENCLAW_STATE_DIR/agents/<agentId>/...`
+
+Always migrate the entire `$OPENCLAW_STATE_DIR` folder.
+
+### Footgun: permissions / ownership
+
+If you copied as root or changed users, the gateway may fail to read credentials/sessions.
+
+Fix: ensure the state dir + workspace are owned by the user running the gateway.
+
+### Footgun: migrating between remote/local modes
+
+- If your UI (WebUI/TUI) points at a **remote** gateway, the remote host owns the session store + workspace.
+- Migrating your laptop won’t move the remote gateway’s state.
+
+If you’re in remote mode, migrate the **gateway host**.
+
+### Footgun: secrets in backups
+
+`$OPENCLAW_STATE_DIR` contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets:
+
+- store encrypted
+- avoid sharing over insecure channels
+- rotate keys if you suspect exposure
+
+## Verification checklist
+
+On the new machine, confirm:
+
+- `openclaw status` shows the gateway running
+- Your channels are still connected (e.g. WhatsApp doesn’t require re-pair)
+- The dashboard opens and shows existing sessions
+- Your workspace files (memory, configs) are present
+
+## Related
+
+- [Doctor](/gateway/doctor)
+- [Gateway troubleshooting](/gateway/troubleshooting)
+- [Where does OpenClaw store its data?](/help/faq#where-does-openclaw-store-its-data)

package/docs/install/nix.md

@@ -0,0 +1,96 @@
+---
+summary: "Install OpenClaw declaratively with Nix"
+read_when:
+  - You want reproducible, rollback-able installs
+  - You're already using Nix/NixOS/Home Manager
+  - You want everything pinned and managed declaratively
+title: "Nix"
+---
+
+# Nix Installation
+
+The recommended way to run OpenClaw with Nix is via **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — a batteries-included Home Manager module.
+
+## Quick Start
+
+Paste this to your AI agent (Claude, Cursor, etc.):
+
+```text
+I want to set up nix-openclaw on my Mac.
+Repository: github:openclaw/nix-openclaw
+
+What I need you to do:
+1. Check if Determinate Nix is installed (if not, install it)
+2. Create a local flake at ~/code/openclaw-local using templates/agent-first/flake.nix
+3. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
+4. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
+5. Fill in the template placeholders and run home-manager switch
+6. Verify: launchd running, bot responds to messages
+
+Reference the nix-openclaw README for module options.
+```
+
+> **📦 Full guide: [github.com/openclaw/nix-openclaw](https://github.com/openclaw/nix-openclaw)**
+>
+> The nix-openclaw repo is the source of truth for Nix installation. This page is just a quick overview.
+
+## What you get
+
+- Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
+- Launchd service that survives reboots
+- Plugin system with declarative config
+- Instant rollback: `home-manager switch --rollback`
+
+---
+
+## Nix Mode Runtime Behavior
+
+When `OPENCLAW_NIX_MODE=1` is set (automatic with nix-openclaw):
+
+OpenClaw supports a **Nix mode** that makes configuration deterministic and disables auto-install flows.
+Enable it by exporting:
+
+```bash
+OPENCLAW_NIX_MODE=1
+```
+
+On macOS, the GUI app does not automatically inherit shell env vars. You can
+also enable Nix mode via defaults:
+
+```bash
+defaults write bot.molt.mac openclaw.nixMode -bool true
+```
+
+### Config + state paths
+
+OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`.
+
+- `OPENCLAW_STATE_DIR` (default: `~/.openclaw`)
+- `OPENCLAW_CONFIG_PATH` (default: `$OPENCLAW_STATE_DIR/openclaw.json`)
+
+When running under Nix, set these explicitly to Nix-managed locations so runtime state and config
+stay out of the immutable store.
+
+### Runtime behavior in Nix mode
+
+- Auto-install and self-mutation flows are disabled
+- Missing dependencies surface Nix-specific remediation messages
+- UI surfaces a read-only Nix mode banner when present
+
+## Packaging note (macOS)
+
+The macOS packaging flow expects a stable Info.plist template at:
+
+```
+apps/macos/Sources/OpenClaw/Resources/Info.plist
+```
+
+[`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) copies this template into the app bundle and patches dynamic fields
+(bundle ID, version/build, Git SHA, Sparkle keys). This keeps the plist deterministic for SwiftPM
+packaging and Nix builds (which do not rely on a full Xcode toolchain).
+
+## Related
+
+- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — full setup guide
+- [Wizard](/start/wizard) — non-Nix CLI setup
+- [Docker](/install/docker) — containerized setup

package/docs/install/node.md

@@ -0,0 +1,78 @@
+---
+title: "Node.js + npm (PATH sanity)"
+summary: "Node.js + npm install sanity: versions, PATH, and global installs"
+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"
+---
+
+# Node.js + npm (PATH sanity)
+
+OpenClaw’s runtime baseline is **Node 22+**.
+
+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:
+
+```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`).
+
+## Fix: put npm’s global bin dir on PATH
+
+1. Find your global npm prefix:
+
+```bash
+npm prefix -g
+```
+
+2. Add the global npm bin directory to your shell startup file:
+
+- zsh: `~/.zshrc`
+- bash: `~/.bashrc`
+
+Example (replace the path with your `npm prefix -g` output):
+
+```bash
+# macOS / Linux
+export PATH="/path/from/npm/prefix/bin:$PATH"
+```
+
+Then open a **new terminal** (or run `rehash` in zsh / `hash -r` in bash).
+
+On Windows, add the output of `npm prefix -g` to your PATH.
+
+## Fix: avoid `sudo npm install -g` / permission errors (Linux)
+
+If `npm install -g ...` fails with `EACCES`, switch npm’s global prefix to a user-writable directory:
+
+```bash
+mkdir -p "$HOME/.npm-global"
+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.