�� 安装指南

OpenClaw 安装与更新

覆盖 Windows、Linux、macOS、iOS、Android 全平台的安装教程。含所有必备环境、源码安装、一键安装、更新与修复命令。命令来自 docs.openclaw.ai 官网核实。点击右上角「版本同步」可免费检测是否有新版本（直连 GitHub，无需任何 Key）。

平台支持

��

Windows 11

原生 PowerShell，计划任务自启

��

Linux / Ubuntu

一键脚本或源码，systemd 服务

��

macOS

Homebrew + launchd + 菜单栏 App

��

iOS

内测阶段，仅作节点，需配对桌面端

��

Android

未公开发布，可源码编译

��

移动端说明：iOS 和 Android 均为「伴侣节点」，本身不运行 Gateway，需连接桌面端 Gateway 才能使用。

环境要求

工具	版本	平台	说明
Node.js	v24 推荐 / v22.14+ 最低	Win / Linux / macOS	当前最新 LTS v24.14.1
npm	v11+（随 Node 自带）	Win / Linux / macOS	无需单独安装
pnpm	v10+	Win / Linux / macOS	源码构建必须，`npm i -g pnpm`
Git	v2.40+	Win / Linux / macOS	源码安装、版本更新必须
VS Build Tools 2022	最新	Windows 专属	需勾选「C++ 桌面开发」，约 3 GB
Xcode CLI Tools	最新	macOS 专属	`xcode-select --install`
build-essential	系统包	Linux 专属	`sudo apt install build-essential`
Homebrew	最新	macOS 推荐	最方便的 macOS 包管理器
Java 17	≥ 17	Android 编译	编译 Android App 必须

安装方式对比

方式	典型命令	适合	特点
一键脚本	curl … \| bash	新手 / 快速体验	全自动，最省事
npm 全局	npm install -g openclaw	已有 Node 环境	无需 pnpm / git
pnpm 全局	pnpm add -g openclaw	习惯用 pnpm	需要额外 `approve-builds`
源码构建	git clone + pnpm build	开发者 / 贡献者	最新代码，可修改

�� Windows 11

Windows 11 安装指南

原生 PowerShell，不需要 WSL2。所有命令在 PowerShell 7 中执行。

⚠️遇到「无法运行脚本」：先执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1. 安装必备环境

1

安装 PowerShell 7 必须

以管理员身份打开旧版 PowerShell 或 CMD：

PowerShell（管理员）

# 安装 PowerShell 7
winget install --id Microsoft.PowerShell --source winget

# 关闭终端，重新打开 PowerShell 7（标签显示 pwsh），验证：
$PSVersionTable.PSVersion   # Major 应为 7

2

安装 Git for Windows 必须

PowerShell 7

winget install --id Git.Git --source winget

# 关闭终端重新打开，验证
git --version

# 配置身份（替换为你的信息）
git config --global user.name "你的名字"
git config --global user.email "邮箱@example.com"
git config --global core.autocrlf true

3

安装 Node.js v24 LTS 必须

官网要求 ≥ v22.14，推荐 v24（当前 LTS：v24.14.1）

PowerShell 7

winget install --id OpenJS.NodeJS.LTS --source winget

# 关闭终端重新打开，验证
node --version   # 应显示 v24.x.x
npm --version    # 应显示 11.x.x

4

安装 Visual Studio Build Tools 2022 必须

sharp 等原生模块编译依赖 C++ 工具链：

PowerShell 7（管理员）

winget install --id Microsoft.VisualStudio.2022.BuildTools --source winget

⚠️安装后打开 Visual Studio Installer → 修改，勾选「使用 C++ 的桌面开发」，点安装（约 3 GB）

5

安装 pnpm 源码必须

PowerShell 7

npm install -g pnpm
pnpm --version   # 应显示 10.x.x

2. 一键安装

PowerShell 7 — 官方一键脚本

# 完整安装（自动安装 Node + OpenClaw + onboard 向导）
iwr -useb https://openclaw.ai/install.ps1 | iex

# 跳过 onboard 向导
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

PowerShell 7 — npm 全局安装

npm install -g openclaw@latest
openclaw onboard --install-daemon
# 仅 CLI，不安装 Gateway 系统服务
openclaw onboard --non-interactive --skip-health

3. 源码安装

PowerShell 7 — 源码构建（五步）

# 1. 克隆源码
git clone https://github.com/openclaw/openclaw.git $env:USERPROFILE\openclaw
cd $env:USERPROFILE\openclaw

# 2. 安装依赖
pnpm install
# sharp 报错时改用：$env:SHARP_IGNORE_GLOBAL_LIBVIPS="1"; pnpm install

# 3. 构建前端 UI（必须在 pnpm build 之前）
pnpm ui:build

# 4. 构建项目（生成 dist/）
pnpm build

# 5. 全局链接，使 openclaw 命令可用
pnpm link --global

openclaw --version   # 验证

��openclaw 找不到？执行 pnpm bin -g 获取路径，将该路径加入系统 PATH 环境变量。

4. 初始化 & 服务管理

PowerShell 7

# 交互式初始化向导（推荐）
openclaw onboard

# 非交互式（CI / 脚本场景）
openclaw onboard --non-interactive --skip-health

# 前台启动 Gateway（可见日志）
openclaw gateway --port 18789 --verbose

# 安装为计划任务（开机自启）
openclaw gateway install

# 验证安装
openclaw --version
openclaw doctor
openclaw gateway status

�� Linux / Ubuntu

Linux / Ubuntu 安装指南

适用于 Ubuntu 22.04 / 24.04 LTS、Debian，以及 WSL2 内的 Ubuntu。

1. 安装必备环境

1

更新系统 & 安装基础工具必须

Bash

sudo apt update && sudo apt upgrade -y

# 编译工具 + git + curl（原生模块必须）
sudo apt install -y build-essential python3 curl wget git

git --version   # 验证

2

安装 Node.js v24 LTS 必须

方式 A — NodeSource 官方源（推荐）

Bash

# 添加 NodeSource Node.js 24 源
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs

node --version   # v24.x.x
npm --version    # 11.x.x

方式 B — nvm（可管理多版本）

Bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

nvm install 24
nvm use 24
nvm alias default 24
node --version

3

安装 pnpm 源码必须

Bash

npm install -g pnpm
pnpm --version

# 国内网络加速（可选）
pnpm config set registry https://registry.npmmirror.com

2. 一键安装

Bash — 官方一键脚本

# 完整安装（自动安装 Node.js 24 + OpenClaw + onboard 向导）
curl -fsSL https://openclaw.ai/install.sh | bash

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

# 本地前缀安装（装在 ~/.openclaw，不影响系统）
curl -fsSL https://openclaw.ai/install-cli.sh | bash

Bash — npm / pnpm / bun

# npm
npm install -g openclaw@latest && openclaw onboard --install-daemon

# pnpm（推荐）
pnpm add -g openclaw@latest
pnpm approve-builds -g          # pnpm 必须执行此步！
openclaw onboard --install-daemon

# bun
bun add -g openclaw@latest && openclaw onboard --install-daemon

3. 源码安装

Bash — 源码构建

git clone https://github.com/openclaw/openclaw.git ~/openclaw
cd ~/openclaw

pnpm install        # 安装依赖
pnpm ui:build       # 构建前端 UI（必须先于 build）
pnpm build          # 构建项目
pnpm link --global  # 全局链接（也可不链接，在目录内用 pnpm openclaw）

openclaw --version  # 验证

4. 初始化 & systemd 服务

Bash

# 交互式初始化 + 安装 systemd 服务
openclaw onboard --install-daemon

# 安装为 systemd 用户服务（开机自启）
openclaw gateway install

# 关键：持久化（注销后服务不停止，必须执行）
sudo loginctl enable-linger "$(whoami)"

# 验证服务
systemctl --user is-enabled openclaw-gateway.service
systemctl --user status openclaw-gateway.service --no-pager

# 全面验证
openclaw --version
openclaw doctor
openclaw gateway status

�� macOS

macOS 安装指南

支持 macOS 13 Ventura 及以上，有菜单栏 Companion App，launchd 服务管理。

1. 安装必备环境

1

安装 Xcode Command Line Tools 必须

Terminal

xcode-select --install
xcode-select -p   # 验证，应返回路径

2

安装 Homebrew 强烈推荐

Terminal

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Apple Silicon (M1/M2/M3/M4) 需要加入 PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

brew --version

3

安装 Node.js v24 + Git + pnpm 必须

Terminal

brew install node git

node --version   # v24.x.x
git --version

npm install -g pnpm
pnpm --version

2. 一键安装

Terminal — 官方一键脚本

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

# npm 安装
npm install -g openclaw@latest && openclaw onboard --install-daemon

3. 源码安装

Terminal

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

4. 初始化 & launchd 服务

Terminal

openclaw onboard --install-daemon
openclaw gateway install

# launchd 手动控制
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

openclaw --version && openclaw doctor && openclaw gateway status

�� iOS

iOS 安装指南

iOS 是「伴侣节点 App」，本身不运行 Gateway，需连接桌面端 Gateway 才能使用。

前提：在桌面设备运行 Gateway

在 macOS / Linux / Windows 上执行

openclaw gateway --port 18789 --verbose
openclaw gateway status

从源码编译（需要 Mac + Xcode）

Terminal (macOS)

cd ~/openclaw/apps/ios
cat README.md             # 查看编译说明
open OpenClaw.xcodeproj   # 用 Xcode 打开，选择签名并构建到真机

配对连接 Gateway

在 Gateway 主机上执行

openclaw devices list
openclaw devices approve <requestId>
openclaw pairing list
openclaw pairing approve <channel> <code>
openclaw nodes status

发现方式	场景	配置
Bonjour (mDNS)	同一 Wi-Fi	自动，无需配置
Tailscale	跨网络	`gateway.bind: "tailnet"`
手动输入	任意网络	App 内填 host:port

�� Android

Android 安装指南

Android 同样是伴侣节点，不运行 Gateway，需配合桌面端使用。

安装 Java 17

Bash (Ubuntu / Linux)

sudo apt install -y openjdk-17-jdk
java --version   # openjdk 17.x

编译 APK（官网命令）

Bash

cd ~/openclaw/apps/android
cat README.md   # 查看编译说明

# 编译 Debug APK（官网命令）
./gradlew :app:assemblePlayDebug

# APK 输出：app/build/outputs/apk/play/debug/app-play-debug.apk
# 安装到 USB 连接的设备（需开启 USB 调试）
adb install app/build/outputs/apk/play/debug/app-play-debug.apk

配对连接 Gateway

在 Gateway 主机上执行

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

�� 更新管理

更新管理

所有平台通用。openclaw update 自动检测安装类型，是官网首推方式。

方式一：openclaw update（官网首推）

自动检测安装类型（npm 或 git），拉取最新版，运行 doctor，重启 Gateway，一步到位。

任意平台

# 更新到最新稳定版
openclaw update

# 切换到 beta 频道
openclaw update --channel beta

# 切换到 dev 频道
openclaw update --channel dev

# 模拟预览（不实际执行）
openclaw update --dry-run

# 指定 tag
openclaw update --tag main

# 查看更新状态
openclaw update status

频道	行为	适合
stable	延迟 6 小时应用，12 小时内随机分散	普通用户
beta	每小时检查，立即应用	测试者
dev	不自动应用，需手动执行	开发者

方式二：重新运行安装脚本

Linux / macOS

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

# 源码方式
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

Windows PowerShell

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

方式三：包管理器手动更新

任意平台

npm i -g openclaw@latest
# 或
pnpm add -g openclaw@latest
# 或
bun add -g openclaw@latest

npm view openclaw version   # 查看 npm 最新版本

方式四：源码更新

Bash / PowerShell

cd ~/openclaw            # Linux/macOS
# cd $env:USERPROFILE\openclaw  # Windows

git fetch origin
git log --oneline HEAD..origin/main | head -20   # 预览新提交
git pull origin main

pnpm install      # lockfile 变化时需要
pnpm ui:build
pnpm build

openclaw gateway restart
openclaw --version
openclaw doctor

自动更新配置

~/.openclaw/openclaw.json

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

版本回滚

任意平台

npm i -g openclaw@<version>
openclaw doctor && openclaw gateway restart

# 源码回滚
git fetch origin
git checkout "$(git rev-list -n 1 --before="2026-01-01" origin/main)"
pnpm install && pnpm build && openclaw gateway restart
# 恢复到最新
git checkout main && git pull && pnpm install && pnpm build

�� 修复 & 卸载

修复命令 & 卸载手册

遇到问题先跑 openclaw doctor，绝大多数问题可以自动修复。

① doctor — 首选工具

任意平台

openclaw doctor                                    # 基础诊断
openclaw doctor --repair                           # 自动修复
openclaw doctor --deep                             # 深度扫描
openclaw doctor --repair --yes --non-interactive   # 非交互式修复
openclaw doctor --generate-gateway-token           # 生成新 Gateway Token

② Gateway 修复

任意平台

openclaw gateway status --deep      # 深度状态
openclaw gateway status --json      # JSON 输出
openclaw gateway --force            # 强制启动（端口占用时）
openclaw gateway health             # 健康探测
openclaw gateway restart            # 重启
openclaw logs --limit 100           # 查看最近日志
openclaw logs --follow              # 实时追踪
openclaw secrets reload             # Secrets 热更新（不重启 Gateway）
openclaw gateway uninstall && openclaw gateway install   # 重装系统服务

③ 配置修复

任意平台

openclaw config validate               # 验证配置
openclaw config file                   # 查看配置文件路径
openclaw security audit --fix          # 安全审计 + 自动修复权限
openclaw secrets audit                 # Secrets 审计
openclaw reset --scope config --yes    # 重置配置（保留 CLI）
openclaw reset --scope config+creds+sessions --yes   # 重置配置+凭证+会话
openclaw reset --scope full --yes      # 全部重置

④ 系统服务手动修复

Linux — systemd

Bash

systemctl --user daemon-reload
systemctl --user restart openclaw-gateway.service
sudo loginctl enable-linger "$(whoami)"

# 手动清理（CLI 不可用时）
systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

macOS — launchd

Terminal

launchctl bootout gui/$UID/ai.openclaw.gateway
launchctl kickstart -k gui/$UID/ai.openclaw.gateway

# 手动清理
launchctl bootout gui/$UID/ai.openclaw.gateway
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Windows — 计划任务

PowerShell 7

Get-ScheduledTask | Where-Object { $_.TaskName -like "*OpenClaw*" }
Unregister-ScheduledTask -TaskName "OpenClaw Gateway" -Confirm:$false
openclaw gateway uninstall && openclaw gateway install

⑤ 卸载

任意平台

# 一键卸载（推荐）
openclaw uninstall

# 非交互式完整卸载
openclaw uninstall --all --yes --non-interactive

# CLI 不可用时通过 npx
npx -y openclaw uninstall --all --yes --non-interactive

# 手动卸载步骤
openclaw gateway stop
openclaw gateway uninstall
rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
npm rm -g openclaw                  # 或 pnpm remove -g / bun remove -g
rm -rf /Applications/OpenClaw.app  # macOS 专属

⑥ 常见问题速查

现象	解决办法
`openclaw` 命令找不到	`npm prefix -g` 查路径，将 `/bin` 加入 PATH，重开终端
Gateway 端口 18789 占用	`openclaw gateway --force` 强制接管
`sharp` 安装失败	设 `SHARP_IGNORE_GLOBAL_LIBVIPS=1` 后重新 `pnpm install`
pnpm 报 approve-builds 错误	补执行 `pnpm approve-builds -g`
Linux 注销后 Gateway 停止	`sudo loginctl enable-linger $(whoami)`
Windows 计划任务无法创建	自动降级到 Startup 文件夹，登录后自启，功能正常
onboard 向导卡住	加 `--non-interactive --skip-health`
更新后 Gateway 无法启动	`openclaw doctor --repair` 后 `openclaw gateway restart`
Windows 脚本无法运行	`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`