安装程序内部机制

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

脚本	平台	功能
install.sh	macOS / Linux / WSL	如需要则安装 Node，通过 OpenClaw（默认）或 git 安装 npm，并可运行新手引导。
install-cli.sh	macOS / Linux / WSL	将 Node + OpenClaw 安装到本地前缀（~/.openclawnpm），支持 npm 或 git checkout 模式。无需 root 权限。
install.ps1	Windows (PowerShell)	如需要则安装 Node，通过 OpenClaw（默认）或 git 安装 npm，并可运行新手引导。

快速命令

install.shinstall-cli.shinstall.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

Note

如果安装成功但在新终端中未找到

openclaw

，请参阅

Node.js 故障排除

。

---

install.sh

Tip

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

Flow (install.sh)

1. 检测操作系统

   支持 macOS 和 Linux（包括 WSL）。

2. 确保默认安装 Node.js 24

   检查 Node 版本，并在需要时安装 Node 24（macOS 上的 Homebrew，Linux 上的 NodeSource 设置脚本 apt/dnf/yum）。在 macOS 上，仅当安装程序需要 Node 或 Git 时才会安装 Homebrew。为了兼容性，OpenClaw 目前仍支持 Node 22 LTS，即 22.19+。 在 Alpine/musl Linux 上，安装程序使用 apk 包而不是 NodeSource；配置的 Alpine 仓库必须提供 Node 22.19+（撰写时为 Alpine 3.21 或更高版本）。

3. 确保 Git

   如果缺失，则使用检测到的包管理器安装 Git，包括 macOS 上的 Homebrew 和 Alpine 上的 apk。

4. OpenClaw安装 OpenClaw

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

5. 安装后任务

   • 尽力刷新已加载的网关服务（openclaw gateway install --force，然后重启）
   • 在升级和 git 安装时运行 openclaw doctor --non-interactive（尽力）
   • 在适当时尝试新手引导（TTY 可用、未禁用新手引导，且 bootstrap/config 检查通过）

Source checkout detection

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

• 使用检出目录（git），或
• 使用全局安装（npm）

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

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

示例 (install.sh)

默认跳过新手引导Git 安装GitHubGitHub main 检出试运行

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

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

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

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

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

标志参考

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

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

| 检出目录（默认：~/openclaw）。别名：—dir | |—no-git-update | 跳过现有检出的git pull | |—no-prompt | 禁用提示 | |—no-onboard | 跳过新手引导 | |—onboard | 启用新手引导 | |—dry-run | 打印操作而不应用更改 | |—verbose | 启用调试输出（set -xnpm，npm notice-level 日志） | | —help | 显示用法（-h`） |

环境变量参考

变量	描述
OPENCLAW_INSTALL_METHOD=git|npm	安装方式
`OPENCLAW_VERSION=latest|next|

|

npm | npm 版本、dist-tag 或包规格 | | OPENCLAW_BETA=0|1 | 如果可用则使用 beta 版 | |OPENCLAW_HOME=

OpenClaw | OpenClaw 状态和默认 git/新手引导 路径的基础目录 | | 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 | npm 日志级别 |

---

install-cli.sh

Info

旨在用于需要将所有内容置于本地前缀 （默认为

~/.openclaw

npm）下且没有系统 Node 依赖的环境。默认支持 npm 安装， 外加在同一前缀流程下的 git-checkout 安装。

Flow (install-cli.sh)

1. 安装本地 Node 运行时

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

   /tools/node-v

   Linux 并验证 SHA-256。 在 Alpine/musl Linux 上，由于 Node 不为固定运行时发布兼容的压缩包，会使用 apk安装nodejs和npm，并将该运行时链接到前缀包装路径中。Alpine 仓库必须提供 Node 22.19+`；如果较旧的仓库仅提供 Node 20 或 21，请使用 Alpine 3.21 或更新版本。

2. 确保已安装 Git

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

3. OpenClaw在指定前缀下安装 OpenClaw

   • npmnpm 方法（默认）：通过 npm 在前缀路径下安装，然后将包装器写入 `

   /bin/openclaw -git方法：克隆/更新检出（默认~/openclaw），并仍然将包装器写入

   /bin/openclaw`

4. 刷新已加载的网关服务

   如果网关服务已从同一前缀加载，脚本将运行 openclaw gateway install --force，然后 openclaw gateway restart，并 尽力探测网关健康状况。

示例 (install-cli.sh)

默认自定义前缀 + 版本Git 安装自动化 JSON 输出运行新手引导

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

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

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

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

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

Flags reference

Flag	Description
`—prefix

| 安装前缀（默认：~/.openclaw） | | —install-method npm|git | 选择安装方法（默认：npm）。别名：—method | |—npmnpm | npm 方法的快捷方式 | | —git, —github | git 方法的快捷方式 | |—git-dir

| Git 检出目录（默认：~/openclaw）。别名：—dir | |—version

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

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

环境变量参考

变量	描述
`OPENCLAW_PREFIX=

| 安装前缀 | |OPENCLAW_INSTALL_METHOD=git|npm | 安装方式 | |OPENCLAW_VERSION=

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

| Node 版本 | |OPENCLAW_HOME=

| OpenClaw 状态及默认 git/新手引导 路径的基目录 | |OPENCLAW_GIT_DIR=

| Git 安装的 git checkout 目录 | |OPENCLAW_GIT_UPDATE=0|1 | 切换现有 checkout 的 git 更新 | |OPENCLAW_NO_ONBOARD=1 | 跳过 新手引导 | |OPENCLAW_NPM_LOGLEVEL=error|warn|notice` | npm 日志级别 |

---

install.ps1

Flow (install.ps1)

1. 确保 PowerShell + Windows 环境

   需要 PowerShell 5+。

2. 默认确保 Node.js 24

   如果缺失，会尝试通过 winget、然后 Chocolatey、再然后 Scoop 进行安装。如果没有可用的包管理器，脚本会将官方的 Node.js Windows zip 包下载到 %LOCALAPPDATA%\OpenClaw\deps\portable-node 并将其添加到当前进程和用户的 PATH 中。Node 22 LTS（当前为 22.19+）仍受支持以保持兼容性。

3. 安装 OpenClaw

   • npm 方法（默认）：使用所选的 -Tag 进行全局 npm 安装，从可写的安装程序临时目录启动，以便在受保护文件夹（如 C:\）中打开的 shell 仍能正常工作
   • git 方法：克隆/更新仓库，使用 pnpm 安装/构建，并在 %USERPROFILE%\.local\bin\openclaw.cmd 安装包装器。如果缺少 Git，脚本将在 %LOCALAPPDATA%\OpenClaw\deps\portable-git 下引导用户本地 MinGit 并将其添加到当前进程和用户 PATH 中。

4. 安装后任务

   • 尽可能将所需的 bin 目录添加到用户 PATH
   • 尽最大努力刷新已加载的网关服务（openclaw gateway install --force，然后重启）
   • 在升级和 git 安装时运行 openclaw doctor --non-interactive（尽最大努力）

5. 处理失败

   iwr ... | iex 和脚本块安装会报告终止错误，而不会关闭当前的 PowerShell 会话。直接的 powershell -File / pwsh -File 安装仍会以非零状态退出以支持自动化。

示例 (install.ps1)

默认Git 安装GitHub main 签出自定义 git 目录试运行调试跟踪

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

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

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

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

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

powershell # install.ps1 has no dedicated -Verbose flag yet. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0

标志参考

标志	描述
-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` | 试运行模式 |

Note

如果使用了

-InstallMethod git

且未安装 Git，脚本会在打印 Git for Windows 链接之前尝试进行用户本地的 MinGit 引导。

---

CI 和自动化

使用非交互式标志/环境变量以获得可预测的运行结果。

install.sh（非交互式 npm）install.sh（非交互式 git）install-cli.sh (JSON)install.ps1（跳过新手引导）

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

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

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

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

---

故障排除

为什么需要 Git？

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

npmLinux为什么 npm 在 Linux 上遇到 EACCES 错误？

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

Windowsnpm：“npm error spawn git / ENOENT”

重新运行安装程序，以便它可以引导用户本地 MinGit，或者为 Windows 安装 Git 并重新打开 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 故障排除。

相关

• 安装概述
• 更新
• 卸载