安装脚本详解

OpenClaw 提供了三个安装脚本（托管在 openclaw.ai）：

  • https://openclaw.ai/install.sh — 推荐的安装脚本（默认使用全局 npm 安装；也可以从 GitHub 源码安装）
  • https://openclaw.ai/install-cli.sh — 无需 root 权限的 CLI 安装脚本（安装到指定目录，自带独立的 Node 环境）
  • https://openclaw.ai/install.ps1 — Windows PowerShell 安装脚本（默认使用 npm；可选 git 源码安装）

查看当前支持的参数和行为，运行：

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

Windows (PowerShell) 查看帮助：

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

如果安装完成后，在新终端中找不到 openclaw 命令，通常是 Node/npm PATH 配置问题。参考：安装指南。

install.sh（推荐）

脚本的主要功能：

  • 检测操作系统（macOS / Linux / WSL）
  • 确保 Node.js 22+ 版本（macOS 通过 Homebrew 安装；Linux 通过 NodeSource 安装）
  • 选择安装方式：
    • npm（默认）：npm install -g openclaw@latest
    • git：克隆源码并构建，安装包装脚本
  • Linux 系统：通过将 npm 的 prefix 切换到 ~/.npm-global 来避免全局 npm 权限错误
  • 升级现有安装时：运行 openclaw doctor --non-interactive（尽力而为）
  • git 安装方式：安装/更新后运行 openclaw doctor --non-interactive（尽力而为）
  • 缓解 sharp 原生模块安装问题，默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1（避免链接系统的 libvips）

如果你想让 sharp 链接全局安装的 libvips（或者你在调试），可以设置：

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

自动发现 / “git 安装”提示

如果你在 OpenClaw 源码目录内运行安装脚本（通过 package.json + pnpm-workspace.yaml 检测），脚本会提示：

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

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

为什么需要 Git

--install-method git 方式需要 Git（用于克隆/拉取代码）。

对于 npm 安装，Git 通常不是必需的，但某些环境仍然需要它（例如当某个包或依赖通过 git URL 获取时）。安装脚本目前会确保 Git 存在，以避免在全新发行版上出现 spawn git ENOENT 错误。

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

在某些 Linux 配置中（特别是通过系统包管理器或 NodeSource 安装 Node 后），npm 的全局 prefix 指向 root 拥有的位置。这时 npm install -g ... 会因 EACCES / mkdir 权限错误而失败。

install.sh 通过将 prefix 切换到以下位置来缓解这个问题：

  • ~/.npm-global（并在 ~/.bashrc / ~/.zshrc 中添加到 PATH）

install-cli.sh（无需 root 权限的 CLI 安装）

这个脚本将 openclaw 安装到指定目录（默认：~/.openclaw），并在该目录下安装独立的 Node Runtime，因此可以在不想修改系统 Node/npm 的机器上使用。

查看帮助：

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：克隆源码并构建，安装包装脚本
  • 升级和 git 安装时运行 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。