跳转到内容
OpenClaw Docs

安装程序内部原理

安装程序内部机制

Section titled “安装程序内部机制”

OpenClaw 附带三个安装程序脚本，从 openclaw.ai 提供。

脚本平台功能
install.shmacOS / Linux / WSL如果需要则安装 Node，通过 OpenClaw（默认）或 git 安装 npm，并且可以运行新手引导。
install-cli.shmacOS / Linux / WSL将 Node + OpenClaw 安装到本地前缀 (~/.openclaw) 中。不需要 root 权限。
install.ps1Windows (PowerShell)如果需要则安装 Node，通过 OpenClaw（默认）或 git 安装 npm，并且可以运行新手引导。

快速命令

Section titled “快速命令”
Terminal window
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
Terminal window
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help

install.sh

Section titled “install.sh”

Flow (install.sh)

Section titled “Flow (install.sh)”

  1. Detect OS

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

  2. Ensure Node.js 24 by default

    检查 Node 版号，如需要则安装 Node 24（macOS 上使用 Homebrew，Linux 上使用 NodeSource 设置脚本处理 apt/dnf/yum）。OpenClaw 仍支持 Node 22 LTS，目前为 22.14+，以确保兼容性。

  3. Ensure Git

    如果缺失则安装 Git。

  4. Install OpenClaw

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

  5. Post-install tasks

    • 在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力而为） - 在适当时尝试进行新手引导（TTY 可用、未禁用新手引导且通过引导/配置检查） - 默认 SHARP_IGNORE_GLOBAL_LIBVIPS=1

Source checkout detection

Section titled “Source checkout detection”

如果在 OpenClaw 检出目录 (package.json + pnpm-workspace.yaml) 中运行，脚本会提供：

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

如果没有可用的 TTY 且未设置安装方法，则默认为 npm 并发出警告。

如果方法选择无效或 --install-method 值无效，脚本将以代码 2 退出。

示例 (install.sh)

Section titled “示例 (install.sh)”

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

标志参考
标志描述
--install-method npm|git选择安装方法（默认：npm）。别名：--method
--npmnpm 方法的快捷方式
--gitgit 方法的快捷方式。别名：--github
`—version

| npm 版本、dist-tag 或 package spec（默认：latest） | | —beta | 如果可用，使用 beta dist-tag，否则回退到latest | |—git-dir

| Checkout 目录（默认：~/openclaw）。别名：—dir | |—no-git-update | 对现有的 checkout 跳过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|main|

|

| npm 版本、dist-tag 或 package spec | |OPENCLAW_BETA=0|1 | 如果可用则使用 beta 版本 | |OPENCLAW_GIT_DIR=

| 检出目录 | |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

Section titled “install-cli.sh”

流程 (install-cli.sh)

Section titled “流程 (install-cli.sh)”

  1. 安装本地 Node 运行时

    下载一个固定的受支持的 Node LTS tarball（版本嵌入在脚本中并独立更新）到 `

    /tools/node-v

    ` 并验证 SHA-256。

  2. 确保 Git

    如果缺少 Git，会尝试通过 Linux 上的 apt/dnf/yum 或 macOS 上的 Homebrew 进行安装。

  3. 在前缀下安装 OpenClaw

    使用 npm 通过 `—prefix

    安装，然后将包装器写入

    /bin/openclaw`。

示例 (install-cli.sh)

Section titled “示例 (install-cli.sh)”

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

标志参考
FlagDescription
`—prefix

| 安装前缀（默认：~/.openclaw） | | —version

| OpenClaw 版本或 dist-tag（默认：latest） | | —node-version

| Node 版本（默认：22.22.0） | | —json | 发出 NDJSON 事件 | |—onboard | 安装后运行openclaw onboard | |—no-onboard | 跳过新手引导（默认） | |—set-npm-prefix | 在 Linux 上，如果当前前缀不可写，则强制 npm 前缀为~/.npm-global| |—help | 显示用法（-h`） |

环境变量参考
VariableDescription
`OPENCLAW_PREFIX=

| 安装前缀 | |OPENCLAW_VERSION=

| OpenClaw 版本或 dist-tag | |OPENCLAW_NODE_VERSION=

| Node 版本 | |OPENCLAW_NO_ONBOARD=1 | 跳过新手引导 | |OPENCLAW_NPM_LOGLEVEL=error|warn|notice| npm 日志级别 | |OPENCLAW_GIT_DIR=

| 旧版清理查找路径（用于移除旧的Peekaboo子模块检出时） | |SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 | 控制 sharp/libvips 行为（默认：1`） |

install.ps1

Section titled “install.ps1”

流程 (install.ps1)

Section titled “流程 (install.ps1)”

  1. 确保 PowerShell + Windows 环境

    需要 PowerShell 5+。

  2. 默认确保 Node.js 24

    如果缺失，会尝试通过 winget 安装，然后是 Chocolatey，接着是 Scoop。为保持兼容性，目前仍支持 Node 22 LTS（即 22.14+）。

  3. 安装 OpenClaw

    • npm 方法（默认）：使用选定的 -Tag 进行全局 npm 安装 - git 方法：克隆/更新仓库，使用 pnpm 安装/构建，并在 %USERPROFILE%\.local\bin\openclaw.cmd 安装包装器

  4. 安装后任务

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

示例 (install.ps1)

Section titled “示例 (install.ps1)”

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

标志参考
标志描述
-InstallMethod npm|git安装方法（默认：npm）
`-Tag

| npm dist-tag、版本或包规范（默认：latest） | | -GitDir

| 检出目录（默认：%USERPROFILE%\openclaw） | | -NoOnboard | 跳过新手引导 | |-NoGitUpdate | 跳过git pull | |-DryRun` | 仅打印操作 |

环境变量参考
变量描述
OPENCLAW_INSTALL_METHOD=git|npm安装方法
`OPENCLAW_GIT_DIR=

| 检出目录 | |OPENCLAW_NO_ONBOARD=1 | 跳过新手引导 | |OPENCLAW_GIT_UPDATE=0 | 禁用 git pull | |OPENCLAW_DRY_RUN=1` | 试运行模式 |

CI 和自动化

Section titled “CI 和自动化”

使用非交互式标志/环境变量以实现可预测的运行。

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

故障排除

Section titled “故障排除”
为什么需要 Git？

git 安装方法需要 Git。对于 npm 安装，仍然会检查/安装 Git，以避免当依赖项使用 git URL 时出现 spawn git ENOENT 失败。

为什么在 npm 上 npm 会遇到 EACCES？

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

sharp/libvips 问题

脚本默认设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1 以避免 sharp 针对系统 libvips 进行构建。要覆盖此设置：

Terminal window
SHARP_IGNORE_GLOBAL_LIBVIPS=0 curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
Windows：“npm error spawn git / ENOENT”

安装 npm 版 Git，重新打开 PowerShell，然后重新运行安装程序。

Windows：“openclaw is not recognized”

运行 npm config get prefix 并将该目录添加到您的用户 PATH（在 Windows 上不需要 \bin 后缀），然后重新打开 PowerShell。

Windows：如何获取详细的安装程序输出

install.ps1 目前不暴露 -Verbose 开关。 使用 PowerShell 跟踪进行脚本级诊断：

Terminal window
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
安装后找不到 openclaw

通常是 PATH 问题。请参阅 Node.js 故障排除。