安装

除非有特殊原因,否则请使用安装器。它会设置 CLI 并运行初始化配置。

快速安装(推荐)

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

Windows (PowerShell):

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

下一步(如果你跳过了初始化配置):

openclaw onboard --install-daemon

系统要求

• Node >=22
• macOS、Linux 或通过 WSL2 的 Windows
• pnpm 仅在从源码构建时需要

选择你的安装方式

1) 安装器脚本(推荐)

通过 npm 全局安装 openclaw 并运行初始化配置。

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

安装器标志:

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

详情:安装器内部机制。

非交互式(跳过初始化配置):

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

2) 全局安装(手动)

如果你已经安装了 Node:

npm install -g openclaw@latest

如果你已全局安装 libvips(在 macOS 上通过 Homebrew 安装很常见)并且 sharp 安装失败,强制使用预构建的二进制文件:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

如果你看到 sharp: Please add node-gyp to your dependencies,要么安装构建工具(macOS: Xcode CLT + npm install -g node-gyp),要么使用上面的 SHARP_IGNORE_GLOBAL_LIBVIPS=1 解决方法跳过原生构建。

或者使用 pnpm:

pnpm add -g openclaw@latest
pnpm approve-builds -g                # approve openclaw, node-llama-cpp, sharp, etc.

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 # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon

提示:如果你还没有全局安装,通过 pnpm openclaw ... 运行仓库命令。

4) 其他安装选项

• Docker: Docker
• Nix: Nix
• Ansible: Ansible
• Bun(仅 CLI): Bun

安装后

• 运行初始化配置: openclaw onboard --install-daemon
• 快速检查: openclaw doctor
• 检查网关健康状态: openclaw status + openclaw health
• 打开控制面板: openclaw dashboard

安装方法: npm vs git(安装器)

安装器支持两种方法:

• npm(默认): npm install -g openclaw@latest
• git: 从 GitHub 克隆/构建并从源码检出运行

CLI 标志

# Explicit npm
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

# Install from GitHub (source checkout)
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

常用标志:

• --install-method npm|git
• --git-dir <path>(默认: ~/openclaw)
• --no-git-update(使用现有检出时跳过 git pull)
• --no-prompt(禁用提示;在 CI/自动化中必需)
• --dry-run(打印将要发生的操作;不做任何更改)
• --no-onboard(跳过初始化配置)

环境变量

等效的环境变量(用于自动化):

• OPENCLAW_INSTALL_METHOD=git|npm
• OPENCLAW_GIT_DIR=...
• OPENCLAW_GIT_UPDATE=0|1
• OPENCLAW_NO_PROMPT=1
• OPENCLAW_DRY_RUN=1
• OPENCLAW_NO_ONBOARD=1
• SHARP_IGNORE_GLOBAL_LIBVIPS=0|1(默认: 1;避免 sharp 针对系统 libvips 构建)

故障排除: openclaw 未找到(PATH)

快速诊断:

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

如果 $(npm prefix -g)/bin(macOS/Linux)或 $(npm prefix -g)(Windows)不在 echo "$PATH" 中,你的 shell 无法找到全局 npm 二进制文件(包括 openclaw)。

修复方法:将其添加到你的 shell 启动文件(zsh: ~/.zshrc,bash: ~/.bashrc):

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

在 Windows 上,将 npm prefix -g 的输出添加到你的 PATH 中。

然后打开一个新终端(或在 zsh 中执行 rehash / 在 bash 中执行 hash -r)。

更新 / 卸载

• 更新:更新
• 迁移到新机器:迁移
• 卸载:卸载