OpenClaw 跨平台安装指南 (Windows/macOS)

2.2 安装 OpenClaw

Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。

方式一：官方安装脚本（推荐）

打开「终端」，执行：

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

该脚本会自动完成以下操作：

• 检测当前系统和已安装的 Node.js 版本
• 通过 npm 全局安装最新版 openclaw
• 运行健康检查（升级时）

静默安装（跳过 onboarding 向导，适合自动化场景）：

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

查看安装脚本的所有可用参数：

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

方式二：手动 npm 安装

如果已有 Node.js 22+，也可以直接用 npm 安装：

npm install -g openclaw@latest

如果遇到 sharp 相关报错（常见于通过 Homebrew 安装了 libvips 的 Mac）：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

如果遇到 sharp: Please add node-gyp 报错，需要安装构建工具：

# 安装 Xcode 命令行工具
xcode-select --install
# 安装 node-gyp
npm install -g node-gyp
# 然后重试安装
npm install -g openclaw@latest

方式三：从源码安装（开发者/贡献者）

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
# 安装依赖（需要 pnpm）
npm install -g pnpm
pnpm install
# 构建
pnpm ui:build
# 首次运行会自动安装 UI 依赖
pnpm build

2.3 初始化配置（onboarding）

安装完成后，必须运行 onboarding 向导完成初始配置：

openclaw onboard --install-daemon

--install-daemon 参数会将 OpenClaw Gateway 安装为 macOS 系统服务（LaunchAgent），使其在后台自动运行并随开机启动。

向导会引导你完成以下配置：

1. 模型和认证 — 配置 AI 提供商的 API Key（支持 Anthropic、OpenAI 等）
2. 工作区 — 设置 agent 文件的存储位置（默认 ~/.openclaw/workspace）
3. Gateway — 配置端口（默认 18789）、绑定地址和认证模式
4. 频道（可选） — 连接 WhatsApp、Telegram、Discord 等聊天应用
5. 后台服务 — 安装 LaunchAgent 使 Gateway 随系统启动
6. 健康检查 — 启动 Gateway 并验证运行状态
7. 技能（可选） — 安装推荐的内置技能

重新运行 openclaw onboard 不会清除已有配置，可以安全地用于修改配置。

2.4 验证安装

# 检查整体健康状态（发现并自动修复常见问题）
openclaw doctor
# 检查 Gateway 运行状态
openclaw gateway status
# 查看 Gateway 和连接状态摘要
openclaw health
# 打开 Web 控制台（浏览器中与 AI 对话）
openclaw dashboard

执行 openclaw dashboard 后，浏览器会自动打开 http://127.0.0.1:18789/，若控制台页面正常加载，即表示安装成功。

2.5 macOS 常见问题

问题：openclaw: command not found

原因：npm 全局 bin 目录不在系统 PATH 中。

诊断：

node -v
npm -v
npm prefix -g
# 查看 npm 全局安装路径
echo $PATH
# 查看当前 PATH

修复： 将 npm 全局 bin 目录加入 PATH：

# 将以下内容添加到 ~/.zshrc（或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"
# 使配置立即生效
source ~/.zshrc

重新打开终端后，再次尝试 openclaw --version。

问题：sharp 安装失败

# 绕过本地编译，使用预构建二进制
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

问题：Gateway 无法启动

# 运行诊断工具（会自动尝试修复）
openclaw doctor
# 查看实时日志
openclaw logs --follow

3. Windows 安装

3.1 安装 Node.js

前往 https://nodejs.org/zh-cn/download 下载并安装 Node.js。

推荐方式：下载 .msi 安装包（最简单）

1. 打开上述链接，页面会自动识别 Windows 系统。
2. 选择 LTS（长期支持）版本，点击下载 .msi 文件。
3. 双击下载的 .msi 文件，按照安装向导完成安装。
4. 安装时务必勾选 'Add to PATH' 选项（默认已勾选），确保命令行可以直接使用 node 和 npm。
5. 安装完成后，npm 已一并安装。

替代方式：使用 fnm（PowerShell，支持多版本管理）

# 安装 fnm（使用 winget）
winget install Schniz.fnm
# 重启 PowerShell 后，安装 Node.js
fnm install 24
fnm use 24
# 配置 fnm 自动激活（添加到 PowerShell profile）
Add-Content $PROFILE 'fnm env --use-on-cd | Out-String | Invoke-Expression'

替代方式：使用 Chocolatey

choco install nodejs

验证 Node.js 安装成功：

打开「PowerShell」，执行以下命令，确认版本号 ≥ 22：

node --version
# 示例输出：v24.14.0
npm --version
# 示例输出：10.x.x

如果提示找不到命令，请关闭并重新打开 PowerShell，让 PATH 变更生效。

3.2 安装 OpenClaw

Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。

方式一：官方安装脚本（推荐）

以管理员身份打开 PowerShell（在开始菜单中右键点击 PowerShell → 以管理员身份运行），执行：

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

该脚本会自动完成以下操作：

• 检测 Node.js 22+（若未安装，引导通过 winget/Chocolatey/Scoop 安装）
• 通过 npm 全局安装最新版 openclaw
• 升级时运行健康检查

查看安装脚本所有可用参数：

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

方式二：手动 npm 安装

npm install -g openclaw@latest

方式三：从 GitHub 源码安装

# 通过安装脚本指定 git 方式
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git
# 指定安装目录
iwr -useb https://openclaw.ai/install.ps1 | iex -InstallMethod git -GitDir "C:\openclaw"

也可以通过环境变量控制安装行为：

$env:OPENCLAW_INSTALL_METHOD = "git"
$env:OPENCLAW_GIT_DIR = "C:\openclaw"
iwr -useb https://openclaw.ai/install.ps1 | iex

3.3 初始化配置（onboarding）

安装完成后，打开新的 PowerShell 窗口，运行 onboarding 向导：

openclaw onboard --install-daemon

--install-daemon 参数会将 OpenClaw Gateway 注册为 Windows 计划任务（Scheduled Task），在后台自动运行。

向导会引导你完成以下配置：

1. 模型和认证 — 配置 AI 提供商的 API Key（支持 Anthropic、OpenAI 等）
2. 工作区 — 设置 agent 文件的存储位置（默认 %USERPROFILE%\.openclaw\workspace）
3. Gateway — 配置端口（默认 18789）和认证模式
4. 频道（可选） — 连接 WhatsApp、Telegram、Discord 等聊天应用
5. 后台服务 — 注册 Windows 计划任务使 Gateway 自动运行
6. 健康检查 — 启动 Gateway 并验证运行状态

3.4 验证安装

# 检查整体健康状态
openclaw doctor
# 检查 Gateway 运行状态
openclaw gateway status
# 打开 Web 控制台
openclaw dashboard

执行 openclaw dashboard 后，浏览器会自动打开 http://127.0.0.1:18789/，若控制台页面正常加载，即表示安装成功。

3.5 Windows 常见问题

问题："openclaw" is not recognized（命令无法识别）

原因：npm 全局 bin 目录不在系统 PATH 中。

诊断：

npm config get prefix
# 查看 npm 全局路径（通常是 %AppData%\npm）

修复：

1. 打开「系统属性」→「高级」→「环境变量」
2. 在「用户变量」或「系统变量」中找到 Path，点击「编辑」
3. 添加上一步查到的路径（如 C:\Users\YourName\AppData\Roaming\npm）
4. 点击确定，重新打开 PowerShell

问题：npm error spawn git / ENOENT

原因：系统中没有安装 Git。

修复： 安装 Git for Windows，安装完成后重新打开 PowerShell，再次运行 openclaw 安装命令。

问题：PowerShell 执行策略限制脚本运行

# 临时允许运行脚本（仅当前会话有效）
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

然后重新运行安装命令。

问题：Gateway 无法启动

# 运行诊断工具
openclaw doctor
# 查看实时日志
openclaw logs --follow

手动停止/删除 Windows 计划任务（服务异常时）：

schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"

4. 首次使用

安装并完成 onboarding 后，有两种方式开始使用 OpenClaw：

方式一：Web 控制台（最快，无需配置频道）

openclaw dashboard

浏览器打开后即可直接与 AI 对话。

方式二：通过聊天应用（WhatsApp / Telegram 等）

在 onboarding 向导中已连接频道的情况下，直接在对应 App 中给机器人发消息即可。

也可以事后通过以下命令添加频道：

openclaw channels login

发送测试消息

需要已配置频道（如 WhatsApp）：

openclaw message send --target +1XXXXXXXXXX --message "Hello from OpenClaw"

5. 更新 OpenClaw

推荐：重新运行安装脚本（会自动检测并升级）

macOS / Linux：

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

Windows（PowerShell）：

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

手动 npm 更新

npm i -g openclaw@latest

更新后操作

openclaw doctor
# 执行健康检查和配置迁移
openclaw gateway restart
# 重启 Gateway
openclaw health
# 确认运行正常

切换发布频道

openclaw update --channel beta
# 切换到测试版
openclaw update --channel stable
# 切回稳定版

回退到指定版本

# 查看当前发布的版本号
npm view openclaw version
# 安装指定版本
npm i -g openclaw@<版本号>
# 重启并验证
openclaw doctor
openclaw gateway restart

6. 卸载 OpenClaw

一键卸载（推荐）

openclaw uninstall

交互式确认，适合普通用户。

静默卸载（自动化场景）

openclaw uninstall --all --yes --non-interactive

手动完整卸载

如果 CLI 已失效但服务仍在运行，按以下步骤手动清理：

1. 停止并卸载 Gateway 服务：

openclaw gateway stop
openclaw gateway uninstall

2. 删除配置和状态文件：

# macOS / Linux
rm -rf ~/.openclaw
# Windows（PowerShell）
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

3. 卸载 CLI：

npm rm -g openclaw

4. 删除 macOS App（如有）：

rm -rf /Applications/OpenClaw.app

Windows 手动删除计划任务（服务残留时）：

schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"

附录：常用命令速查

本文档根据 OpenClaw 官方文档（docs/install/ 和 docs/start/）整理，Node.js 下载地址：https://nodejs.org/zh-cn/download