OpenClaw 是一款基于 Node.js 运行的网关服务，支持 macOS 和 Windows 系统。档详细介绍了两个平台的完整安装流程，包括前置依赖 Node.js 的安装、OpenClaw 的三种安装方式（官方脚本、npm 手动安装、源码安装）、初始化配置向导 onboarding 的使用、以及验证安装和常见问题排查。此外还涵盖了首次使用 Web 控制台或聊天应用的方法、更新与卸载步骤，旨在帮助用户快速部署 OpenClaw Gateway 服务。
本教程覆盖 macOS 和 Windows 两个平台的完整安装流程，包括前置依赖、安装方式、初始化配置、常见问题排查，以及后续的更新与卸载。
| 项目 |
|---|
| 要求 |
|---|
| Node.js | 22 或更高版本（安装时自动包含 npm） |
| macOS | 支持原生安装 |
| Windows | 支持原生 PowerShell 安装 |
| 磁盘空间 | 建议预留 1 GB 以上 |
| 网络 | 可访问 openclaw.ai 和 npmjs.com |
为什么需要 Node.js？
OpenClaw 是一个基于 Node.js 运行的网关服务，npm（Node 包管理器）用于安装和管理 OpenClaw 本身。安装 Node.js 时 npm 会一并安装，无需单独处理。
前往 https://nodejs.org/zh-cn/download 下载并安装 Node.js。
推荐方式：下载 .pkg 安装包（最简单）
.pkg 文件。.pkg 文件，按照安装向导完成安装。替代方式：使用 Homebrew
如果你已经安装了 Homebrew，可以直接在终端执行：
brew install node
替代方式：使用 fnm（支持多版本管理）
# 安装 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：
node -v
# 示例输出：v24.14.0
npm -v
# 示例输出：10.x.x
Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。
打开「终端」，执行：
curl -fsSL https://openclaw.ai/install.sh | bash
该脚本会自动完成以下操作：
openclaw静默安装（跳过 onboarding 向导，适合自动化场景）：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
查看安装脚本的所有可用参数：
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --help
如果已有 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
安装完成后，必须运行 onboarding 向导完成初始配置：
openclaw onboard --install-daemon
--install-daemon 参数会将 OpenClaw Gateway 安装为 macOS 系统服务（LaunchAgent），使其在后台自动运行并随开机启动。
向导会引导你完成以下配置：
~/.openclaw/workspace）18789）、绑定地址和认证模式重新运行
openclaw onboard不会清除已有配置，可以安全地用于修改配置。
# 检查整体健康状态（发现并自动修复常见问题）
openclaw doctor
# 检查 Gateway 运行状态
openclaw gateway status
# 查看 Gateway 和连接状态摘要
openclaw health
# 打开 Web 控制台（浏览器中与 AI 对话）
openclaw dashboard
执行 openclaw dashboard 后，浏览器会自动打开 http://127.0.0.1:18789/，若控制台页面正常加载，即表示安装成功。
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
# 运行诊断工具（会自动尝试修复）
openclaw doctor
# 查看实时日志
openclaw logs --follow
前往 https://nodejs.org/zh-cn/download 下载并安装 Node.js。
推荐方式：下载 .msi 安装包（最简单）
.msi 文件。.msi 文件，按照安装向导完成安装。node 和 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 变更生效。
Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。
以管理员身份打开 PowerShell（在开始菜单中右键点击 PowerShell → 以管理员身份运行），执行：
iwr -useb https://openclaw.ai/install.ps1 | iex
该脚本会自动完成以下操作：
openclaw查看安装脚本所有可用参数：
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -?
npm install -g openclaw@latest
# 通过安装脚本指定 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
安装完成后，打开新的 PowerShell 窗口，运行 onboarding 向导：
openclaw onboard --install-daemon
--install-daemon 参数会将 OpenClaw Gateway 注册为 Windows 计划任务（Scheduled Task），在后台自动运行。
向导会引导你完成以下配置：
%USERPROFILE%\.openclaw\workspace）18789）和认证模式# 检查整体健康状态
openclaw doctor
# 检查 Gateway 运行状态
openclaw gateway status
# 打开 Web 控制台
openclaw dashboard
执行 openclaw dashboard 后，浏览器会自动打开 http://127.0.0.1:18789/，若控制台页面正常加载，即表示安装成功。
"openclaw" is not recognized（命令无法识别）原因：npm 全局 bin 目录不在系统 PATH 中。
诊断：
npm config get prefix
# 查看 npm 全局路径（通常是 %AppData%\npm）
修复：
Path，点击「编辑」C:\Users\YourName\AppData\Roaming\npm）npm error spawn git / ENOENT原因：系统中没有安装 Git。
修复： 安装 Git for Windows，安装完成后重新打开 PowerShell，再次运行 openclaw 安装命令。
# 临时允许运行脚本（仅当前会话有效）
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
然后重新运行安装命令。
# 运行诊断工具
openclaw doctor
# 查看实时日志
openclaw logs --follow
手动停止/删除 Windows 计划任务（服务异常时）：
schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"
安装并完成 onboarding 后，有两种方式开始使用 OpenClaw：
openclaw dashboard
浏览器打开后即可直接与 AI 对话。
在 onboarding 向导中已连接频道的情况下，直接在对应 App 中给机器人发消息即可。
也可以事后通过以下命令添加频道：
openclaw channels login
需要已配置频道（如 WhatsApp）：
openclaw message send --target +1XXXXXXXXXX --message "Hello from OpenClaw"
macOS / Linux：
curl -fsSL https://openclaw.ai/install.sh | bash
Windows（PowerShell）：
iwr -useb https://openclaw.ai/install.ps1 | iex
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
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 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
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online