OpenClaw 安装教程(Windows&&macOS)

OpenClaw 安装教程

本教程覆盖 macOS 和 Windows 两个平台的完整安装流程，包括前置依赖、安装方式、初始化配置、常见问题排查，以及后续的更新与卸载。

系统要求
[macOS 安装](#macOS 安装)
- 2.1 [安装 Node.js](#安装 Node.js)
- 2.2 [安装 OpenClaw](#安装 OpenClaw)
- 2.3 初始化配置（onboarding）
- 2.4 验证安装
- 2.5 常见问题
[Windows 安装](#Windows 安装)
- 3.1 [安装 Node.js](#安装 Node.js)
- 3.2 [安装 OpenClaw](#安装 OpenClaw)
- 3.3 初始化配置（onboarding）
- 3.4 验证安装
- 3.5 常见问题
首次使用
[更新 OpenClaw](#更新 OpenClaw)
[卸载 OpenClaw](#卸载 OpenClaw)

1. 系统要求

项目	要求
Node.js	22 或更高版本（安装时自动包含 npm）
macOS	支持原生安装
Windows	支持原生 PowerShell 安装
磁盘空间	建议预留 1 GB 以上
网络	可访问 `openclaw.ai` 和 `npmjs.com`

为什么需要 Node.js？

OpenClaw 是一个基于 Node.js 运行的网关服务，npm（Node 包管理器）用于安装和管理 OpenClaw 本身。安装 Node.js 时 npm 会一并安装，无需单独处理。

2. macOS 安装

2.1 安装 Node.js

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

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

打开上述链接，页面会自动识别 macOS 系统。
选择 LTS（长期支持）版本 ，点击下载 .pkg 文件。
双击下载的 .pkg 文件，按照安装向导完成安装。
安装完成后，npm 已一并安装，无需额外操作。

替代方式：使用 Homebrew

如果你已经安装了 Homebrew，可以直接在终端执行：

bash 复制代码

brew install node

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

bash 复制代码

# 安装 fnm
brew install fnm

# 安装并激活 Node.js 24（符合 >=22 要求）
fnm install 24
fnm use 24

# 将 fnm 加入 shell 配置（以 zsh 为例）
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
source ~/.zshrc

验证 Node.js 安装成功：

打开「终端」（Terminal），执行以下命令，确认版本号 ≥ 22：

bash 复制代码

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

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

2.2 安装 OpenClaw

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

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

打开「终端」，执行：

bash 复制代码

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

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

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

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

bash 复制代码

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

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

bash 复制代码

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

方式二：手动 npm 安装

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

bash 复制代码

npm install -g openclaw@latest

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

bash 复制代码

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

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

bash 复制代码

# 安装 Xcode 命令行工具
xcode-select --install

# 安装 node-gyp
npm install -g node-gyp

# 然后重试安装
npm install -g openclaw@latest

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

bash 复制代码

# 克隆仓库
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 向导完成初始配置：

bash 复制代码

openclaw onboard --install-daemon

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

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

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

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

2.4 验证安装

bash 复制代码

# 检查整体健康状态（发现并自动修复常见问题）
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 中。

诊断：

bash 复制代码

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

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

bash 复制代码

# 将以下内容添加到 ~/.zshrc（或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"

# 使配置立即生效
source ~/.zshrc

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

问题：`sharp` 安装失败

bash 复制代码

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

问题：Gateway 无法启动

bash 复制代码

# 运行诊断工具（会自动尝试修复）
openclaw doctor

# 查看实时日志
openclaw logs --follow

3. Windows 安装

3.1 安装 Node.js

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

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

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

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

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

powershell 复制代码

choco install nodejs

验证 Node.js 安装成功：

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

powershell 复制代码

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

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

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

3.2 安装 OpenClaw

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

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

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

powershell 复制代码

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

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

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

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

powershell 复制代码

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

方式二：手动 npm 安装

powershell 复制代码

npm install -g openclaw@latest

方式三：从 GitHub 源码安装

powershell 复制代码

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

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

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

powershell 复制代码

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

3.3 初始化配置（onboarding）

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

powershell 复制代码

openclaw onboard --install-daemon

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

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

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

3.4 验证安装

powershell 复制代码

# 检查整体健康状态
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 中。

诊断：

powershell 复制代码

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

修复：

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

问题：`npm error spawn git / ENOENT`

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

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

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

powershell 复制代码

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

然后重新运行安装命令。

问题：Gateway 无法启动

powershell 复制代码

# 运行诊断工具
openclaw doctor

# 查看实时日志
openclaw logs --follow

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

powershell 复制代码

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

4. 首次使用

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

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

bash 复制代码

openclaw dashboard

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

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

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

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

bash 复制代码

openclaw channels login

发送测试消息

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

bash 复制代码

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

5. 更新 OpenClaw

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

macOS / Linux：

bash 复制代码

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

Windows（PowerShell）：

powershell 复制代码

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

手动 npm 更新

bash 复制代码

npm i -g openclaw@latest

更新后操作

bash 复制代码

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

切换发布频道

bash 复制代码

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

回退到指定版本

bash 复制代码

# 查看当前发布的版本号
npm view openclaw version

# 安装指定版本
npm i -g openclaw@<版本号>

# 重启并验证
openclaw doctor
openclaw gateway restart

6. 卸载 OpenClaw

一键卸载（推荐）

bash 复制代码

openclaw uninstall

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

静默卸载（自动化场景）

bash 复制代码

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

手动完整卸载

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

1. 停止并卸载 Gateway 服务：

bash 复制代码

openclaw gateway stop
openclaw gateway uninstall

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

bash 复制代码

# macOS / Linux
rm -rf ~/.openclaw

# Windows（PowerShell）
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

3. 卸载 CLI：

bash 复制代码

npm rm -g openclaw

4. 删除 macOS App（如有）：

bash 复制代码

rm -rf /Applications/OpenClaw.app

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

powershell 复制代码

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

附录：常用命令速查

命令	说明
`openclaw onboard --install-daemon`	运行初始化向导并安装后台服务
`openclaw doctor`	健康检查并自动修复常见问题
`openclaw health`	查看 Gateway 和连接状态
`openclaw dashboard`	打开 Web 控制台
`openclaw gateway status`	查看 Gateway 运行状态
`openclaw gateway restart`	重启 Gateway
`openclaw logs --follow`	实时查看日志
`openclaw configure`	修改配置
`openclaw channels login`	添加聊天频道
`openclaw update`	更新 OpenClaw
`openclaw uninstall`	卸载 OpenClaw

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

OpenClaw 安装教程(Windows&&macOS)