[OpenClaw 文档]安装--安装概览

本文档汇总了 OpenClaw 官方文档站 安装 > 安装概览 子模块下的全部 2 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 安装

原文：https://docs.openclaw.ai/zh-CN/install

系统要求

• Node 24（推荐）或 Node 22.16+ - 安装脚本会自动处理这一点
• macOS、Linux 或 Windows - 支持原生 Windows 和 WSL2；WSL2 更稳定。参见 Windows。
• 只有从源码构建时才需要 pnpm

推荐：安装脚本

最快的安装方式。它会检测你的 OS，在需要时安装 Node，安装 OpenClaw，并启动新手引导。

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


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

安装但不运行新手引导：

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


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

有关所有标志和 CI/自动化选项，请参见安装器内部机制。

替代安装方法

本地前缀安装器（install-cli.sh）

当你希望将 OpenClaw 和 Node 保存在本地前缀（例如
~/.openclaw）下，而不依赖系统范围的 Node 安装时，请使用此方法：

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

它默认支持 npm 安装，也支持在同一个
前缀流程下进行 git-checkout 安装。完整参考：安装器内部机制。

已经安装了？使用 openclaw update --channel dev 和 openclaw update --channel stable 在 package 和 git 安装之间切换。参见
更新。

npm、pnpm 或 bun

如果你已经自行管理 Node：

bash
npm install -g openclaw@latest
openclaw onboard --install-daemon


bash
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

<Note>
pnpm 对带有构建脚本的 package 需要显式批准。首次安装后运行 `pnpm approve-builds -g`。
</Note>

bash
bun add -g openclaw@latest
openclaw onboard --install-daemon

<Note>
全局 CLI 安装路径支持 Bun。对于 Gateway 网关运行时，Node 仍然是推荐的 daemon 运行时。
</Note>

如果 sharp 因全局安装的 libvips 而失败：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

从源码安装

适用于贡献者或任何想从本地 checkout 运行的人：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

或者跳过链接，在 repo 内部使用 pnpm openclaw ...。完整开发工作流请参见设置。

从 GitHub main 安装

npm install -g github:openclaw/openclaw#main

容器和 package manager

容器化或无头部署。


Docker 的无 root 容器替代方案。


通过 Nix flake 进行声明式安装。


自动化集群预配。


通过 Bun 运行时进行仅 CLI 使用。

验证安装

openclaw --version      # confirm the CLI is available
openclaw doctor         # check for config issues
openclaw gateway status # verify the Gateway is running

如果你希望安装后启用托管启动：

• macOS：通过 openclaw onboard --install-daemon 或 openclaw gateway install 使用 LaunchAgent
• Linux/WSL2：通过相同命令使用 systemd 用户服务
• 原生 Windows：优先使用计划任务；如果任务创建被拒绝，则回退到按用户的 Startup 文件夹登录项

托管和部署

在云服务器或 VPS 上部署 OpenClaw：

任何 Linux VPS
共享 Docker 步骤
K8s
Fly.io
Hetzner
Google Cloud
Azure
Railway
Render
Northflank

更新、迁移或卸载

让 OpenClaw 保持最新。


迁移到新机器。


完全移除 OpenClaw。

故障排除：找不到 openclaw

如果安装成功但你的终端中找不到 openclaw：

node -v           # Node installed?
npm prefix -g     # Where are global packages?
echo "$PATH"      # Is the global bin dir in PATH?

如果 $(npm prefix -g)/bin 不在你的 $PATH 中，请将它添加到你的 shell 启动文件（~/.zshrc 或 ~/.bashrc）：

export PATH="$(npm prefix -g)/bin:$PATH"

然后打开新的终端。更多详情请参见 Node 设置。

📄 安装程序内部机制

原文：https://docs.openclaw.ai/zh-CN/install/installer

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

快速命令

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 -- --help
```

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 -- --help
```

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

```powershell
& ([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 时安装它。


检查 Node 版本，并在需要时安装 Node 24（macOS 上使用 Homebrew，Linux apt/dnf/yum 上使用 NodeSource 设置脚本）。为保持兼容性，OpenClaw 仍支持 Node 22 LTS，目前为 22.16+。


如果缺少 Git，则安装 Git。


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

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

源码 checkout 检测

如果在 OpenClaw checkout（package.json + pnpm-workspace.yaml）内运行，脚本会提供：

• 使用 checkout（git），或
• 使用全局安装（npm）

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

对于无效的方法选择或无效的 --install-method 值，脚本会以代码 2 退出。

示例 (install.sh)

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 -- --version main


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

install-cli.sh

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

流程 (install-cli.sh)

将固定的受支持 Node LTS tarball（版本嵌入在脚本中并独立更新）下载到 <prefix>/tools/node-v<version> 并验证 SHA-256。


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


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

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

示例 (install-cli.sh)

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

install.ps1

流程（install.ps1）

需要 PowerShell 5+。


如果缺失，会尝试通过 winget 安装，然后是 Chocolatey，再然后是 Scoop。Node 22 LTS（当前为 22.16+）仍受支持以保持兼容性。


- npm 方法（默认）：使用选定的 -Tag 进行全局 npm 安装，并从可写的安装器临时目录启动，因此在 C:\ 等受保护文件夹中打开的 shell 仍可正常工作
- git 方法：克隆/更新仓库，使用 pnpm 安装/构建，并在 %USERPROFILE%\.local\bin\openclaw.cmd 安装包装器

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

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

示例（install.ps1）

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))) -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 git 且缺少 Git，脚本会退出并打印 Git for Windows 链接。

CI 和自动化

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

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。对于 npm 安装，仍会检查/安装 Git，以避免依赖项使用 git URL 时出现 spawn git ENOENT 失败。

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

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

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

安装 Git for Windows，重新打开 PowerShell，然后重新运行安装器。

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

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

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

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

相关

• 安装概览
• 更新
• 卸载