OpenClaw 在 macOS 和 Windows 上的安装与配置

如果你要跳过 onboarding，适合自动化场景：

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

查看脚本参数：

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

手动 npm 安装

npm install -g openclaw@latest

如果装 sharp 的时候报错，先试这个：

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，把 API Key、工作区、Gateway 和后台服务这些基础项配置好：

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 并验证运行状态
• 技能（可选）：安装推荐的内置技能

重新执行 openclaw onboard 不会清掉已有配置，改参数时可以放心再跑一遍。

验证安装

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

如果 openclaw dashboard 能正常打开 http://127.0.0.1:18789/，基本就说明安装链路没问题了。

macOS 常见问题

openclaw: command not found

通常不是 OpenClaw 没装上，而是 npm 的全局 bin 目录没进 PATH。

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

修复方式很直接，把 npm 全局 bin 目录加进去：

# 将以下内容添加到 ~/.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

Windows 安装

安装 Node.js

先去 https://nodejs.org/zh-cn/download 下载 Node.js。

Windows 这边最稳的是 .msi：

1. 打开链接，页面会自动识别 Windows。
2. 选 LTS（长期支持）版本，下载 .msi。
3. 双击安装包，按向导完成。
4. 安装时把 Add to PATH 勾上，默认一般已经勾好，这一步别漏。
5. 安装完成后，npm 会一起装好。

如果你想管理多个 Node 版本，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 --version
# 示例输出：v24.14.0
npm --version
# 示例输出：10.x.x

如果命令找不到，先关掉 PowerShell 再打开一次，让 PATH 生效。

安装 OpenClaw

官方安装脚本

以管理员身份打开 PowerShell，然后执行：

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

这个脚本会检查 Node.js 22+，必要时引导你用 winget、Chocolatey 或 Scoop 装 Node，再通过 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

初始化配置

安装结束后，重新打开一个 PowerShell 窗口，再运行 onboarding：

openclaw onboard --install-daemon

--install-daemon 会把 OpenClaw Gateway 注册成 Windows 计划任务，后台自动运行。

向导会处理这些配置：

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

验证安装

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

如果浏览器打开了 http://127.0.0.1:18789/，页面也能正常加载，安装就算完成了。

Windows 常见问题

"openclaw" is not recognized

多半还是 PATH 没配好，先确认 npm 的全局前缀：

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，再执行安装命令。

PowerShell 执行策略限制脚本运行

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

然后重新运行安装命令。

Gateway 无法启动

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

如果计划任务残留，可以手动清理：

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

首次使用

装好并完成 onboarding 后，通常有两条路可走。

Web 控制台

openclaw dashboard

浏览器打开后就能直接跟 AI 对话。这个方式最快，也最适合先确认服务是否正常。

聊天应用

如果在 onboarding 里已经连好了 WhatsApp、Telegram 之类的频道，直接在对应 App 里给机器人发消息就行。

后面再补频道也可以：

openclaw channels login

测试发送一条消息：

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

更新 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

一键卸载

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"

常用命令速查

这份流程基本按官方文档的安装与启动路径整理，Node.js 下载页仍然是：https://nodejs.org/zh-cn/download。