OpenClaw 安装教程
本教程覆盖 macOS 和 Windows 两个平台的完整安装流程,包括前置依赖、安装方式、初始化配置、常见问题排查,以及后续的更新与卸载。
1. 系统要求
| 项目 |
|---|
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