跳到主要内容
OpenClaw 在 macOS 和 Windows 上的安装与配置 | 极客日志
PowerShell Node.js SaaS 大前端
OpenClaw 在 macOS 和 Windows 上的安装与配置 OpenClaw 需要先安装 Node.js 22+,然后再通过官方脚本或 npm 完成安装。macOS 推荐用 .pkg、Homebrew 或 fnm,Windows 推荐用 .msi,安装时要确保 PATH 可用。装好后运行 openclaw onboard --install-daemon 完成 API Key、工作区、Gateway 和后台服务配置,再用 openclaw doctor、gateway status 和 dashboard 验证。常见问题主要是 PATH、sharp、Git 和 PowerShell 执行策略,更新可重跑安装脚本,卸载则可用 openclaw uninstall 或手动清理。
OpenClaw 安装与配置
这份记录只保留安装过程中真正会踩到的点:Node.js 要先装到位,OpenClaw 再用官方脚本或 npm 装,最后跑一遍 onboarding 和健康检查。macOS 和 Windows 的流程基本一致,差别主要在命令行和后台服务的注册方式。
系统要求
项目 要求 Node.js 22 或更高版本(安装时自动包含 npm) macOS 支持原生安装 Windows 支持原生 PowerShell 安装 磁盘空间 建议预留 1 GB 以上 网络 可访问 openclaw.ai 和 npmjs.com
OpenClaw 依赖 Node.js 运行,npm 负责安装和管理它本身。这个前置条件不复杂,但版本别太老,低于 22 的 Node.js 后面大概率会出兼容问题。
macOS 安装
安装 Node.js
先到 https://nodejs.org/zh-cn/download 下载并安装 Node.js。
我更倾向于直接下 .pkg,少折腾,也最符合大多数人的使用习惯:
打开链接,页面会自动识别 macOS。
选 LTS(长期支持)版本 ,下载 .pkg 文件。
双击安装包,按向导走完。
安装结束后,npm 会一起装好。
如果你已经在用 Homebrew,也可以直接:
brew install node
更习惯多版本切换的话,fnm 也能用:
brew install fnm
fnm install 24
fnm use 24
echo 'eval "$(fnm env --use-on-cd)"' >> ~/.zshrc
source ~/.zshrc
装完先确认版本:
node -v
npm -v
安装 OpenClaw
Node.js 到位后,OpenClaw 有三种装法。日常使用我会先看官方脚本,省得自己处理升级和兼容细节。
官方安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash
脚本会做这些事:
通过 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 安装 npm install -g openclaw@latest
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
如果提示 sharp: Please add node-gyp,一般是构建工具没齐:
xcode-select --install
npm install -g node-gyp
npm install -g openclaw@latest
从源码安装
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install -g pnpm
pnpm install
pnpm ui:build
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
openclaw gateway status
openclaw health
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
echo $PATH
修复方式很直接,把 npm 全局 bin 目录加进去:
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
打开链接,页面会自动识别 Windows。
选 LTS(长期支持)版本 ,下载 .msi。
双击安装包,按向导完成。
安装时把 Add to PATH 勾上,默认一般已经勾好,这一步别漏。
安装完成后,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'
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)
打开「系统属性」→「高级」→「环境变量」
在「用户变量」或「系统变量」里找到 Path,点「编辑」
添加上一步查到的路径,比如 C:\Users\YourName\AppData\Roaming\npm
保存后重新打开 PowerShell
npm error spawn git / ENOENT
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 控制台 浏览器打开后就能直接跟 AI 对话。这个方式最快,也最适合先确认服务是否正常。
聊天应用 如果在 onboarding 里已经连好了 WhatsApp、Telegram 之类的频道,直接在对应 App 里给机器人发消息就行。
openclaw message send --target +1XXXXXXXXXX --message "Hello from OpenClaw"
更新 OpenClaw 最省事的还是重跑安装脚本,它会自己判断是否需要升级。
curl -fsSL https://openclaw.ai/install.sh | bash
iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw doctor
openclaw gateway restart
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 --all --yes --non-interactive
手动完整卸载 如果 CLI 已经失效,但服务还在跑,就按下面的顺序清理。
openclaw gateway stop
openclaw gateway uninstall
rm -rf ~/.openclaw
Remove-Item -Recurse -Force "$env :USERPROFILE\.openclaw"
rm -rf /Applications/OpenClaw.app
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
相关免费在线工具 Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
Markdown转HTML 将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
HTML转Markdown 将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
JSON 压缩 通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
JSON美化和格式化 将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online