安装器内部原理

OpenClaw 提供三份安装脚本（由 openclaw.ai 提供）：

• https://openclaw.ai/install.sh — “推荐”安装器（默认 npm 全局安装；也可从 GitHub checkout 安装）
• https://openclaw.ai/install-cli.sh — 更适合非 root 环境的 CLI 安装器（安装到一个 prefix，并自带 Node）
• https://openclaw.ai/install.ps1 — Windows PowerShell 安装器（默认 npm；也可选 git 安装）

查看当前 flags/行为：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help

Windows（PowerShell）help：

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

如果安装器完成后，在新终端里找不到 openclaw，通常是 Node/npm 的 PATH 问题。见：Install。

install.sh（推荐）

它做什么（高层）：

• 检测 OS（macOS / Linux / WSL）。
• 确保 Node.js 22+（macOS 通过 Homebrew；Linux 通过 NodeSource）。
• 选择安装方式：
  • npm（默认）：npm install -g openclaw@latest
  • git：clone/build 源码 checkout，并安装一个 wrapper script
• Linux：当需要时，将 npm 的 prefix 切换到 ~/.npm-global，以避免全局 npm 权限错误。
• 如果是在升级已有安装：best-effort 运行 openclaw doctor --non-interactive。
• git 安装：安装/更新后 best-effort 运行 openclaw doctor --non-interactive。
• 默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1，以规避 sharp 原生安装常见坑（避免链接系统 libvips 构建）。

如果你希望 sharp 链接全局安装的 libvips（或你在排查相关问题），可设置：

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

可发现性 / “git install” 提示

如果你在已经位于 OpenClaw 源码 checkout 内时运行安装器（通过 package.json + pnpm-workspace.yaml 检测），它会提示你：

• 更新并使用当前 checkout（git）
• 或迁移到全局 npm 安装（npm）

在非交互环境（无 TTY / --no-prompt）中，你必须传 --install-method git|npm（或设置 OPENCLAW_INSTALL_METHOD），否则脚本会以退出码 2 退出。

为什么需要 Git

--install-method git 路径需要 Git（clone / pull）。

对于 npm 安装，通常不需要 Git，但某些环境仍可能间接需要（例如某个包或依赖通过 git URL 拉取）。安装器目前会确保 Git 存在，以避免在新系统上遇到 spawn git ENOENT 的“意外”。

为什么 npm 在新 Linux 上会遇到 EACCES

在某些 Linux 环境（尤其是通过系统包管理器或 NodeSource 安装 Node 后），npm 的 global prefix 会指向 root 拥有的目录。 此时 npm install -g ... 会因为 EACCES / mkdir 权限错误而失败。

install.sh 会通过切换 prefix 来缓解：

• ~/.npm-global（并在存在时把它加入 ~/.bashrc / ~/.zshrc 的 PATH）

install-cli.sh（非 root CLI 安装器）

该脚本会把 openclaw 安装到一个 prefix（默认：~/.openclaw），并在该 prefix 下安装一份专用 Node runtime。 这样它可以在你不希望修改系统 Node/npm 的机器上工作。

Help：

curl -fsSL https://openclaw.ai/install-cli.sh | bash -s -- --help

install.ps1（Windows PowerShell）

它做什么（高层）：

• 确保 Node.js 22+（winget/Chocolatey/Scoop 或手动）。
• 选择安装方式：
  • npm（默认）：npm install -g openclaw@latest
  • git：clone/build 源码 checkout，并安装 wrapper script
• 在升级与 git 安装时 best-effort 运行 openclaw doctor --non-interactive。

示例：

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

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

iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\\openclaw"

环境变量：

• OPENCLAW_INSTALL_METHOD=git|npm
• OPENCLAW_GIT_DIR=...

Git 要求：

如果你选择 -InstallMethod git 且系统缺少 Git，安装器会打印 Git for Windows 链接（https://git-scm.com/download/win）并退出。

常见 Windows 问题：

• npm error spawn git / ENOENT：安装 Git for Windows 并重开 PowerShell，然后重跑安装器。
• "openclaw" is not recognized：npm 全局 bin 目录没有加入 PATH。多数系统使用 %AppData%\\npm。 你也可以运行 npm config get prefix 并把 \\bin 加到 PATH，然后重开 PowerShell。