安装总览

除非有特殊原因，否则请使用官方安装脚本。它会自动安装 CLI 并引导你运行新手引导。

---

快速安装（推荐）

macOS / Linux

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

Windows（PowerShell）

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

安装完成后，如果跳过了新手引导：

openclaw onboard --install-daemon

---

系统要求

要求	说明
Node.js	≥ 22（必须）
操作系统	macOS、Linux，或 Windows 通过 WSL2
pnpm	仅从源码构建时需要

---

安装方式选择

方式 1：安装脚本（推荐）

通过 npm 全局安装 openclaw 并自动运行新手引导。

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

查看安装脚本选项：

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

非交互式安装（跳过新手引导，适合 CI）：

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

常用安装脚本标志：

标志	说明
--install-method npm|git	安装方式（npm 为默认）
--git-dir <path>	git 安装目录（默认 ~/openclaw）
--no-git-update	使用现有 checkout，跳过 git pull
--no-prompt	禁用交互提示（CI 必需）
--dry-run	打印将要执行的操作，不做任何更改
--no-onboard	跳过新手引导

等效环境变量（适合自动化）：OPENCLAW_INSTALL_METHOD、OPENCLAW_NO_PROMPT、OPENCLAW_DRY_RUN、OPENCLAW_NO_ONBOARD 等。

方式 2：npm / pnpm 全局安装

如果已经安装了 Node：

npm install -g openclaw@latest

如果 sharp 安装失败（macOS 通过 Homebrew 安装了 libvips 时常见）：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

使用 pnpm：

pnpm add -g openclaw@latest
pnpm approve-builds -g      # 批准 openclaw、node-llama-cpp、sharp 等
pnpm add -g openclaw@latest # 重新运行以执行 postinstall 脚本

注意：pnpm 需要显式批准带构建脚本的包。首次安装出现 "Ignored build scripts" 警告时，运行 pnpm approve-builds -g 后再次安装。

安装完成后运行向导：

openclaw onboard --install-daemon

方式 3：从源码（贡献者/开发）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build    # 首次运行时自动安装 UI 依赖
pnpm build
openclaw onboard --install-daemon

提示：如果没有全局安装，通过 pnpm openclaw ... 运行仓库命令。

方式 4：其他安装选项

方式	文档
Docker	Docker 安装
Node.js 详细指南	Node.js 安装
云端部署（Fly.io / Railway / Render）	云端部署

---

安装后步骤

openclaw onboard --install-daemon   # 运行新手引导
openclaw doctor                     # 快速环境检查
openclaw status && openclaw health  # Gateway 健康检查
openclaw dashboard                  # 打开控制面板

---

故障排除：找不到 openclaw 命令（PATH 问题）

快速诊断：

node -v
npm -v
npm prefix -g
echo "$PATH"

如果 $(npm prefix -g)/bin（macOS/Linux）或 $(npm prefix -g)（Windows）不在 PATH 中：

# 添加到 ~/.zshrc 或 ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"

添加后，打开新终端（或在 zsh 中执行 rehash / bash 中执行 hash -r）。

Linux npm 权限错误（EACCES）

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"
# 将上面这行加入 ~/.bashrc 或 ~/.zshrc

---

更新与卸载

操作	方法
更新	重新运行安装脚本，或 npm install -g openclaw@latest
卸载	npm uninstall -g openclaw