完整安装指南

OpenClaw 支持一键脚本、npm 手动安装和 Docker 三种部署方式。

一键安装脚本（推荐）

macOS / Linux / WSL2

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

Windows PowerShell

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

仅安装不进入向导：

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

npm 手动安装

# 确保 Node.js 22+
node --version

# 全局安装
npm install -g openclaw@latest

# 运行配置向导
openclaw onboard --install-daemon

Docker 部署

docker pull openclaw/openclaw:latest

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e ANTHROPIC_API_KEY=sk-ant-xxx \
  openclaw/openclaw:latest

安装验证

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

openclaw dashboard 能正常打开即表示网关可用。

---

安装疑难排查

命令找不到（macOS / Linux）

安装后终端找不到 openclaw 命令，是因为 npm 全局 bin 目录不在 PATH 里。

# 找到 npm 全局 bin 目录
npm prefix -g
# 输出示例：/usr/local

# 临时生效（本次终端）
export PATH="$(npm prefix -g)/bin:$PATH"

# 永久生效 — 根据你的 Shell 选一个：
# zsh（macOS 默认）
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Fish
set -Ux fish_user_paths (npm prefix -g)/bin $fish_user_paths

命令找不到（Windows）

1. 运行 npm prefix -g 获取全局目录（例如 C:\Users\你的用户名\AppData\Roaming\npm）
2. 打开"系统属性 → 高级 → 环境变量"
3. 在"用户变量"的 Path 中，点击"新建"，粘贴上述路径
4. 重新打开 PowerShell 或 CMD

pnpm 安装提示 approve-builds

用 pnpm 安装时可能遇到：

 WARN  Some packages have executable scripts that were not run.
       Run `pnpm approve-builds` to review and approve them.

执行以下三步：

pnpm approve-builds
pnpm install -g openclaw@latest
openclaw --version

Node.js 版本不够

OpenClaw 要求 Node.js 22+。推荐用 nvm 管理版本：

# 安装 nvm（如还没有）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装并切换到 Node 22
nvm install 22
nvm use 22

# 设为默认版本（避免重启终端后回到旧版本）
nvm alias default 22

# 验证
node --version   # 应输出 v22.x.x

sharp 编译失败

方法一：跳过本地 libvips（最快）

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

方法二：使用预构建二进制

npm install -g openclaw@latest --prefer-offline

方法三：pnpm 下的解法

pnpm config set sharp-dist-url "https://cdn.npmmirror.com/binaries/sharp-libvips/v0.33.5/"
pnpm install -g openclaw@latest

macOS Arm (M1/M2/M3)：如果上述方法失败，先安装 libvips：

brew install vips
npm install -g openclaw@latest

postinstall 脚本被跳过警告

如果看到 postinstall script skipped 警告，手动运行：

openclaw onboard

端口冲突（18789 已被占用）

# 查看占用进程
lsof -i :18789

# 换端口启动
openclaw gateway --port 19000

网关无法启动

openclaw doctor          # 自动诊断
openclaw doctor --fix    # 尝试自动修复
openclaw logs --follow   # 实时查看错误日志

---

安装后检查清单

完成安装后，逐项检查确认一切正常：

• openclaw --version 输出版本号
• node --version 输出 v22 或更高
• openclaw doctor 无错误（绿色✓）
• openclaw gateway status 显示 Running
• openclaw dashboard 在浏览器中正常打开
• 至少配置了一个渠道（Telegram / 飞书 / Discord）
• 在渠道中发消息，机器人有响应