安装器内部原理

OpenClaw 提供了三个安装脚本，由 openclaw.ai 提供。

脚本	平台	功能
`install.sh`	macOS / Linux / WSL	如有必要安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行引导流程。
`install-cli.sh`	macOS / Linux / WSL	在本地前缀目录（`~/.openclaw`）安装 Node + OpenClaw，无需 root 权限。
`install.ps1`	Windows (PowerShell)	如有必要安装 Node，通过 npm（默认）或 git 安装 OpenClaw，并可运行引导流程。

快速命令

install.sh
install-cli.sh
install.ps1

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help

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

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun

如果安装成功但新终端中找不到 openclaw，请参见 Node.js 故障排查。

install.sh

推荐用于 macOS/Linux/WSL 上的大多数交互式安装。

流程（install.sh）

检测操作系统

支持 macOS 和 Linux（包括 WSL）。检测到 macOS 时，如缺少 Homebrew，则安装 Homebrew。

确保 Node.js 22+

检查 Node 版本，必要时安装 Node 22（macOS 使用 Homebrew，Linux 使用 NodeSource 设置脚本 apt/dnf/yum）。

确保 Git

如缺少 Git，则进行安装。

安装 OpenClaw

通过 npm 方法（默认）：全局 npm 安装
通过 git 方法：克隆/更新仓库，使用 pnpm 安装依赖，构建，然后在 ~/.local/bin/openclaw 安装包装器

安装后任务

在升级和 git 安装时运行 openclaw doctor --non-interactive（尽最大努力）
在合适时尝试引导（有 TTY，有权限，未禁用引导，且通过 bootstrap/config 检查）
默认设定环境变量 SHARP_IGNORE_GLOBAL_LIBVIPS=1

源码检出检测

如果在 OpenClaw 源码检出目录下运行（存在 package.json 和 pnpm-workspace.yaml），脚本会提供选择：

使用源码检出 (git)，或
使用全局安装 (npm)

若无 TTY 且未指定安装方式，默认为 npm 并给出警告。如选择方式无效或 --install-method 值不正确，脚本以代码 2 退出。

示例（install.sh）

默认
跳过引导
Git 安装
演练模式

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run

参数参考

参数	描述
`--install-method npm\|git`	选择安装方式（默认：`npm`）。别名：`--method`
`--npm`	npm 方式快捷参数
`--git`	git 方式快捷参数。别名：`--github`
`--version <version\|dist-tag>`	npm 版本或分发标签（默认：`latest`）
`--beta`	使用 beta 分发标签（可用时），否则回退到 `latest`
`--git-dir <path>`	源码检出目录（默认：`~/openclaw`）。别名：`--dir`
`--no-git-update`	跳过已有源码检出的 `git pull`
`--no-prompt`	禁用交互提示
`--no-onboard`	跳过引导
`--onboard`	启用引导
`--dry-run`	打印操作但不执行更改
`--verbose`	启用调试输出（`set -x`，npm notice-level 日志）
`--help`	显示用法帮助（`-h`）

环境变量参考

变量	描述
`OPENCLAW_INSTALL_METHOD=git\|npm`	安装方式
`OPENCLAW_VERSION=latest\|next\|<semver>`	npm 版本或分发标签
`OPENCLAW_BETA=0\|1`	是否使用 beta 版本
`OPENCLAW_GIT_DIR=<path>`	源码检出目录
`OPENCLAW_GIT_UPDATE=0\|1`	是否允许 git 更新
`OPENCLAW_NO_PROMPT=1`	禁用交互提示
`OPENCLAW_NO_ONBOARD=1`	跳过引导
`OPENCLAW_DRY_RUN=1`	演练模式
`OPENCLAW_VERBOSE=1`	调试模式
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日志级别
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行为（默认：`1`）

install-cli.sh

设计用于希望将所有内容安装到本地前缀目录（默认 ~/.openclaw）且无系统 Node 依赖的环境。

流程（install-cli.sh）

安装本地 Node 运行时

下载 Node 压缩包（默认 22.22.0）到 <prefix>/tools/node-v<version> 并校验 SHA-256。

确保 Git

如缺少 Git，尝试在 Linux 上通过 apt/dnf/yum，macOS 上通过 Homebrew 安装。

在前缀目录安装 OpenClaw

使用 npm 并加 --prefix <prefix> 安装，然后写入包装器到 <prefix>/bin/openclaw。

示例（install-cli.sh）

默认
自定义前缀与版本
自动化 JSON 输出
运行引导

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard

参数参考

参数	描述
`--prefix <path>`	安装前缀目录（默认：`~/.openclaw`）
`--version <ver>`	OpenClaw 版本或分发标签（默认：`latest`）
`--node-version <ver>`	Node 版本（默认：`22.22.0`）
`--json`	输出 NDJSON 事件
`--onboard`	安装后运行 `openclaw onboard`
`--no-onboard`	跳过引导（默认）
`--set-npm-prefix`	Linux 下，如当前 prefix 不可写，强制将 npm prefix 设置为 `~/.npm-global`
`--help`	显示用法帮助（`-h`）

环境变量参考

变量	描述
`OPENCLAW_PREFIX=<path>`	安装前缀
`OPENCLAW_VERSION=<ver>`	OpenClaw 版本或分发标签
`OPENCLAW_NODE_VERSION=<ver>`	Node 版本
`OPENCLAW_NO_ONBOARD=1`	跳过引导
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日志级别
`OPENCLAW_GIT_DIR=<path>`	旧版清理查找路径（移除早期 `Peekaboo` 子模块源码时使用）
`SHARP_IGNORE_GLOBAL_LIBVIPS=0\|1`	控制 sharp/libvips 行为（默认：`1`）

install.ps1

流程（install.ps1）

确保 PowerShell + Windows 环境

需要 PowerShell 5 及以上版本。

确保 Node.js 22+

如缺少 Node，尝试先通过 winget 安装，再尝试 Chocolatey，最后尝试 Scoop。

安装 OpenClaw

通过 npm 方法（默认）：使用选定 -Tag 的全局 npm 安装
通过 git 方法：克隆/更新仓库，使用 pnpm 安装依赖并构建，然后安装包装器到 %USERPROFILE%\.local\bin\openclaw.cmd

安装后任务

尽可能将需要的 bin 目录添加到用户 PATH，然后升级和 git 安装时运行 openclaw doctor --non-interactive（尽最大努力）。

示例（install.ps1）

默认
Git 安装
自定义 Git 目录
演练模式
调试跟踪

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

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

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"

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

# install.ps1 目前没有专门的 -Verbose 参数。
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

参数参考

参数	描述
`-InstallMethod npm\|git`	安装方式（默认：`npm`）
`-Tag <tag>`	npm 分发标签（默认：`latest`）
`-GitDir <path>`	源码检出目录（默认：`%USERPROFILE%\openclaw`）
`-NoOnboard`	跳过引导
`-NoGitUpdate`	跳过执行 `git pull`
`-DryRun`	只打印操作，不实际执行

环境变量参考

变量	描述
`OPENCLAW_INSTALL_METHOD=git\|npm`	安装方式
`OPENCLAW_GIT_DIR=<path>`	源码检出目录
`OPENCLAW_NO_ONBOARD=1`	跳过引导
`OPENCLAW_GIT_UPDATE=0`	禁用 git pull
`OPENCLAW_DRY_RUN=1`	演练模式

如果使用 -InstallMethod git 且缺少 Git，脚本会退出并打印 Git for Windows 链接。

CI 与自动化

使用非交互参数/环境变量以确保运行可预测。

install.sh（非交互 npm）
install.sh（非交互 git）
install-cli.sh（JSON 输出）
install.ps1（跳过引导）

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
  curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw

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

故障排查

为什么需要 Git？

Git 是 git 安装方式的必备工具。即使是 npm 安装方式，也会检测并安装 Git，以避免依赖回退到 git URL 导致的 spawn git ENOENT 错误。

为什么 Linux 上 npm 会遇到 EACCES 权限错误？

部分 Linux 配置会将 npm 全局前缀目录指向由 root 拥有的路径。install.sh 可以切换前缀到 ~/.npm-global 并向 shell rc 文件追加 PATH 导出（当这些文件存在时）。

sharp/libvips 相关问题

脚本默认设置了 SHARP_IGNORE_GLOBAL_LIBVIPS=1 避免 sharp 编译时链接系统 libvips。如需覆盖：

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

Windows: "npm error spawn git / ENOENT" 错误

请安装 Git for Windows，重新打开 PowerShell 后重新运行安装脚本。

Windows: "openclaw is not recognized" 错误

运行 npm config get prefix，将该目录添加到用户 PATH（Windows 上无须 \bin 后缀），然后重新打开 PowerShell。

Windows: 如何获取安装器详细输出

install.ps1 目前不支持 -Verbose 参数。你可以使用 PowerShell 跟踪功能获取脚本级别诊断：

Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

安装后找不到 openclaw 命令

通常是 PATH 配置问题。请参考 Node.js 故障排查。

安装概述

其他安装方法

维护

托管和部署

高级用法

安装器内部原理

安装器内部原理

快速命令

install.sh

流程（install.sh）

源码检出检测

示例（install.sh）

install-cli.sh

流程（install-cli.sh）

示例（install-cli.sh）

install.ps1

流程（install.ps1）

示例（install.ps1）

CI 与自动化

故障排查

安装概述

其他安装方法

维护

托管和部署

高级用法

​安装器内部原理

​快速命令

​install.sh

​流程（install.sh）

​源码检出检测

​示例（install.sh）

​install-cli.sh

​流程（install-cli.sh）

​示例（install-cli.sh）

​install.ps1

​流程（install.ps1）

​示例（install.ps1）

​CI 与自动化

​故障排查

安装器内部原理

快速命令

install.sh

流程（install.sh）

源码检出检测

示例（install.sh）

install-cli.sh

流程（install-cli.sh）

示例（install-cli.sh）

install.ps1

流程（install.ps1）

示例（install.ps1）

CI 与自动化

故障排查