OpenClaw 安装教程(Windows&&macOS)

OpenClaw 安装教程

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

目录

1. 系统要求
2. macOS 安装
   • 2.1 安装 Node.js
   • 2.2 安装 OpenClaw
   • 2.3 初始化配置（onboarding）
   • 2.4 验证安装
   • 2.5 常见问题
3. Windows 安装
   • 3.1 安装 Node.js
   • 3.2 安装 OpenClaw
   • 3.3 初始化配置（onboarding）
   • 3.4 验证安装
   • 3.5 常见问题
4. 首次使用
5. 更新 OpenClaw
6. 卸载 OpenClaw

1. 系统要求

为什么需要 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 安装包（最简单）

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

替代方式：使用 Homebrew

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

brew installnode

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

# 安装 fnm brew install fnm # 安装并激活 Node.js 24（符合 >=22 要求） fnm install24 fnm use 24# 将 fnm 加入 shell 配置（以 zsh 为例）echo'eval "$(fnm env --use-on-cd)"'>> ~/.zshrc source ~/.zshrc 

验证 Node.js 安装成功：

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

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

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 安装：

npminstall-g openclaw@latest 

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

SHARP_IGNORE_GLOBAL_LIBVIPS=1npminstall-g openclaw@latest 

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

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

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

# 克隆仓库git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装依赖（需要 pnpm）npminstall-gpnpmpnpminstall# 构建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-vnpm-vnpm prefix -g# 查看 npm 全局安装路径echo$PATH# 查看当前 PATH

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

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

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

问题：sharp 安装失败

# 绕过本地编译，使用预构建二进制SHARP_IGNORE_GLOBAL_LIBVIPS=1npminstall-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 / Linuxrm-rf ~/.openclaw # Windows（PowerShell） Remove-Item -Recurse-Force"$env:USERPROFILE\.openclaw"

3. 卸载 CLI：

npmrm-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