安装程序内部机制

OpenClaw 提供三个安装脚本，托管于 openclaw.ai。

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

这三个脚本均支持 Node 22.22.3+、24.15+ 或 25.9+；全新安装默认以 Node 24 为目标版本。

快速命令

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）。

默认确保使用 Node.js 24

检查 Node 版本，并在需要时安装 Node 24（macOS 使用 Homebrew，Linux 使用 NodeSource 的 apt/dnf/yum 设置脚本）。在 macOS 上，仅当安装程序需要用它安装 Node 或 Git 时才会安装 Homebrew。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。在 Alpine/musl Linux 上，安装程序使用 apk 软件包而非 NodeSource，并验证实际链接的 SQLite 版本。当前稳定版 Alpine 软件包源可能提供版本足够新的 Node，但其系统 SQLite 存在漏洞；出现这种情况时，请改用官方 node:24-alpine 容器或基于 glibc 的主机。

确保 Git 可用

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

安装 OpenClaw

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

安装后任务

解析刚安装的 openclaw 二进制文件，以便运行后续命令
对于尚未配置的安装，会先启动新手引导，然后再运行 Doctor 或 Gateway 网关探测。使用 --no-onboard 或无 TTY 时，它会输出稍后完成设置所需的命令。
对于已配置的安装，会尽力刷新并重启已加载的 Gateway 网关服务，然后运行 Doctor。升级时会尽可能更新插件；如果是在无界面但启用提示的运行中，则输出手动命令。
运行 --verify 时，它会检查已安装的版本，并且仅在配置存在后检查 Gateway 健康。

源码检出检测

如果脚本在 OpenClaw 检出目录（package.json + pnpm-workspace.yaml）内运行，它会提供以下选项：

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

如果没有可用的 TTY 且未设置安装方式，则默认使用 npm 并发出警告。如果安装方式选择无效或 --install-method 值无效，脚本会以代码 2 退出。

示例 (install.sh)

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 -- --install-method git --version main

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

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

标志参考

标志	描述
`--install-method \| --method npm\|git`	选择安装方式（默认：`npm`）
`--npm`	npm 方式的快捷选项
`--git \| --github`	git 方式的快捷选项
`--version <version\|dist-tag\|spec>`	npm 版本、dist-tag 或软件包规范（默认：`latest`）
`--beta`	使用 beta dist-tag（如果可用），否则回退到 `latest`
`--git-dir \| --dir <path>`	检出目录（默认：`~/openclaw`）
`--no-git-update`	对现有检出目录跳过 `git pull`
`--no-prompt`	禁用提示
`--no-onboard`	跳过新手引导
`--onboard`	启用新手引导
`--verify`	运行安装后冒烟验证（`--version`，如果 Gateway 网关已加载则检查其健康状态）
`--dry-run`	输出操作但不应用更改
`--verbose`	启用调试输出（`set -x`、npm notice 级别日志）
`--help \| -h`	显示用法

环境变量参考

变量	描述
`OPENCLAW_INSTALL_METHOD=git\|npm`	安装方式
`OPENCLAW_VERSION=latest\|next\|<semver>\|<spec>`	npm 版本、dist-tag 或软件包规范
`OPENCLAW_BETA=0\|1`	使用 beta（如果可用）
`OPENCLAW_HOME=<path>`	OpenClaw 状态及默认 git/新手引导路径的基础目录
`OPENCLAW_GIT_DIR=<path>`	检出目录
`OPENCLAW_GIT_UPDATE=0\|1`	切换 git 更新
`OPENCLAW_NO_PROMPT=1`	禁用提示
`OPENCLAW_VERIFY_INSTALL=1`	运行安装后冒烟验证
`OPENCLAW_NO_ONBOARD=1`	跳过新手引导
`OPENCLAW_DRY_RUN=1`	试运行模式
`OPENCLAW_VERBOSE=1`	调试模式
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日志级别（默认：`error`，隐藏 npm 弃用提示干扰）

install-cli.sh

适用于希望将所有内容置于本地前缀下（默认 ~/.openclaw）且不依赖系统 Node 的环境。默认支持 npm 安装，也支持在同一前缀流程下进行 git 检出安装。

流程 (install-cli.sh)

安装本地 Node 运行时

将固定版本且受支持的 Node LTS tarball（版本嵌入脚本中并独立更新，默认 24.15.0）下载到 <prefix>/tools/node-v<version>，并验证 SHA-256。 Linux ARMv7 使用 Node 22.22.3，因为没有官方 Node 24+ ARMv7 二进制文件。在 Alpine/musl Linux 上，由于 Node 不为固定版本的运行时发布兼容 tarball，因此使用 apk 安装 nodejs 和 npm，然后验证 Node 和实际链接的 SQLite 库。当前稳定版 Alpine 软件包源即使提供版本足够新的 Node，仍可能链接存在漏洞的 SQLite；当安全检查拒绝该软件包时，请使用官方 node:24-alpine 容器或基于 glibc 的主机。

确保 Git 可用

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

在前缀下安装 OpenClaw

npm 方式（默认）：使用 npm 安装到该前缀下，然后将包装器写入 <prefix>/bin/openclaw
git 方式：克隆/更新检出目录（默认 ~/openclaw），并仍将包装器写入 <prefix>/bin/openclaw

刷新已加载的 Gateway 网关服务

如果已从同一前缀加载 Gateway 网关服务，脚本会运行 openclaw gateway install --force，从而激活替换后的服务，然后尽力探测 Gateway 健康。

示例 (install-cli.sh)

默认
自定义前缀 + 版本
Git 安装
自动化 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 -- --install-method git --git-dir ~/openclaw

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`）
`--install-method \| --method npm\|git`	选择安装方式（默认值：`npm`）
`--npm`	npm 方式的快捷选项
`--git \| --github`	git 方式的快捷选项
`--git-dir \| --dir <path>`	Git 检出目录（默认值：`~/openclaw`）
`--version <ver>`	OpenClaw 版本或 dist-tag（默认值：`latest`）
`--node-version <ver>`	Node 版本（默认值：`24.15.0`；Linux ARMv7 上为 `22.22.3`）
`--json`	输出 NDJSON 事件
`--onboard`	安装后运行 `openclaw onboard`
`--no-onboard`	跳过新手引导（默认）
`--set-npm-prefix`	在 Linux 上，如果当前前缀不可写，则强制将 npm 前缀设为 `~/.npm-global`
`--help \| -h`	显示用法

环境变量参考

变量	说明
`OPENCLAW_PREFIX=<path>`	安装前缀
`OPENCLAW_INSTALL_METHOD=git\|npm`	安装方式
`OPENCLAW_VERSION=<ver>`	OpenClaw 版本或 dist-tag
`OPENCLAW_NODE_VERSION=<ver>`	Node 版本
`OPENCLAW_HOME=<path>`	OpenClaw 状态以及默认 git/新手引导路径的基础目录
`OPENCLAW_GIT_DIR=<path>`	git 安装的 Git 检出目录
`OPENCLAW_GIT_UPDATE=0\|1`	切换现有检出目录的 git 更新
`OPENCLAW_NO_ONBOARD=1`	跳过新手引导
`OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice`	npm 日志级别（默认值：`error`）

openclaw@main 和其他 GitHub 源规范不能作为 npm 安装的有效 --version 目标。请改用 --install-method git --version main。

install.ps1

流程（install.ps1）

确保 PowerShell + Windows 环境

需要 PowerShell 5+。

确保默认使用 Node.js 24

如果缺失，将依次尝试通过 winget、Chocolatey、Scoop 安装。如果没有可用的包管理器，脚本会将官方 Node.js 24 Windows zip 下载到 %LOCALAPPDATA%\OpenClaw\deps\portable-node，并将其添加到当前进程和用户 PATH。支持 Node 22.22.3+、Node 24.15+ 和 Node 25.9+；不支持 Node 23。

安装 OpenClaw

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

安装后任务

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

处理失败

iwr ... | iex 和脚本块安装会报告终止错误，但不会关闭当前 PowerShell 会话。直接使用 powershell -File / pwsh -File 安装时，仍会以非零状态退出，以便自动化流程检测。

示例（install.ps1）

默认
Git 安装
GitHub main 检出
自定义 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 -Tag main

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

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

标志参考

标志	说明
`-InstallMethod npm\|git`	安装方式（默认值：`npm`）
`-Tag <tag\|version\|spec>`	npm dist-tag、版本或包规范（默认值：`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，脚本会先尝试引导安装用户本地 MinGit，然后再显示 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 失败。

为什么 npm 在 Linux 上遇到 EACCES？

某些 Linux 配置会将 npm 的全局前缀指向 root 所有的路径。install.sh 可以将前缀切换到 ~/.npm-global，并将 PATH 导出语句附加到 shell rc 文件（如果这些文件存在）。

Windows：“npm error spawn git / ENOENT”

重新运行安装程序，让它引导安装用户本地 MinGit；或者安装 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 故障排查。

安装概览

维护

安装方式

托管与部署

Advanced setup

安装程序内部机制

快速命令

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 和自动化

故障排查

相关内容