跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

OpenClaw 跨平台安装指南 (Windows/macOS)

OpenClaw 是一款基于 Node.js 运行的网关服务，支持 macOS 和 Windows 系统。档详细介绍了两个平台的完整安装流程，包括前置依赖 Node.js 的安装、OpenClaw 的三种安装方式（官方脚本、npm 手动安装、源码安装）、初始化配置向导 onboarding 的使用、以及验证安装和常见问题排查。此外还涵盖了首次使用 Web 控制台或聊天应用的方法、更新与卸载步骤，旨在帮助用户快速部署 OpenClaw Gateway 服务。

指针猎手发布于 2026/3/22更新于 2026/8/2257 浏览

OpenClaw 安装教程

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

1. 系统要求

项目要求
Node.js22 或更高版本（安装时自动包含 npm）
macOS支持原生安装
Windows支持原生 PowerShell 安装
磁盘空间建议预留 1 GB 以上
网络可访问 openclaw.ai 和 npmjs.com

为什么需要 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 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
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 安装：

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
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 -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
问题：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 / 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

目录

  1. OpenClaw 安装教程
  2. 1. 系统要求
  3. 2. macOS 安装
  4. 2.1 安装 Node.js
  5. 安装 fnm
  6. 安装并激活 Node.js 24（符合 >=22 要求）
  7. 将 fnm 加入 shell 配置（以 zsh 为例）
  8. 示例输出：v24.14.0
  9. 示例输出：10.x.x
  10. 2.2 安装 OpenClaw
  11. 方式一：官方安装脚本（推荐）
  12. 方式二：手动 npm 安装
  13. 安装 Xcode 命令行工具
  14. 安装 node-gyp
  15. 然后重试安装
  16. 方式三：从源码安装（开发者/贡献者）
  17. 克隆仓库
  18. 安装依赖（需要 pnpm）
  19. 构建
  20. 首次运行会自动安装 UI 依赖
  21. 2.3 初始化配置（onboarding）
  22. 2.4 验证安装
  23. 检查整体健康状态（发现并自动修复常见问题）
  24. 检查 Gateway 运行状态
  25. 查看 Gateway 和连接状态摘要
  26. 打开 Web 控制台（浏览器中与 AI 对话）
  27. 2.5 macOS 常见问题
  28. 问题：openclaw: command not found
  29. 查看 npm 全局安装路径
  30. 查看当前 PATH
  31. 将以下内容添加到 ~/.zshrc（或 ~/.bashrc）
  32. 使配置立即生效
  33. 问题：sharp 安装失败
  34. 绕过本地编译，使用预构建二进制
  35. 问题：Gateway 无法启动
  36. 运行诊断工具（会自动尝试修复）
  37. 查看实时日志
  38. 3. Windows 安装
  39. 3.1 安装 Node.js
  40. 安装 fnm（使用 winget）
  41. 重启 PowerShell 后，安装 Node.js
  42. 配置 fnm 自动激活（添加到 PowerShell profile）
  43. 示例输出：v24.14.0
  44. 示例输出：10.x.x
  45. 3.2 安装 OpenClaw
  46. 方式一：官方安装脚本（推荐）
  47. 方式二：手动 npm 安装
  48. 方式三：从 GitHub 源码安装
  49. 通过安装脚本指定 git 方式
  50. 指定安装目录
  51. 3.3 初始化配置（onboarding）
  52. 3.4 验证安装
  53. 检查整体健康状态
  54. 检查 Gateway 运行状态
  55. 打开 Web 控制台
  56. 3.5 Windows 常见问题
  57. 问题："openclaw" is not recognized（命令无法识别）
  58. 查看 npm 全局路径（通常是 %AppData%\npm）
  59. 问题：npm error spawn git / ENOENT
  60. 问题：PowerShell 执行策略限制脚本运行
  61. 临时允许运行脚本（仅当前会话有效）
  62. 问题：Gateway 无法启动
  63. 运行诊断工具
  64. 查看实时日志
  65. 4. 首次使用
  66. 方式一：Web 控制台（最快，无需配置频道）
  67. 方式二：通过聊天应用（WhatsApp / Telegram 等）
  68. 发送测试消息
  69. 5. 更新 OpenClaw
  70. 推荐：重新运行安装脚本（会自动检测并升级）
  71. 手动 npm 更新
  72. 更新后操作
  73. 执行健康检查和配置迁移
  74. 重启 Gateway
  75. 确认运行正常
  76. 切换发布频道
  77. 切换到测试版
  78. 切回稳定版
  79. 回退到指定版本
  80. 查看当前发布的版本号
  81. 安装指定版本
  82. 重启并验证
  83. 6. 卸载 OpenClaw
  84. 一键卸载（推荐）
  85. 静默卸载（自动化场景）
  86. 手动完整卸载
  87. macOS / Linux
  88. Windows（PowerShell）
  89. 附录：常用命令速查
  • 免费图片AI生成工具免费生成了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 免费图片视频在线生成30秒，将你的创意变成现实开始设计
  • X/Twitter免费视频下载器免登陆无限额度免费视频解析下载了解详情
  • 100+免费在线小游戏爽一把
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • Spring Boot 结合 MyBatis-Plus 实现分库分表实战
  • VSCode AI Copilot 智能补全失效修复指南
  • 无人机安全测试工具 Drone Hacking Tool 使用指南
  • OpenClaw 本地部署及远程监控实操教程
  • LazyLLM 多 Agent 应用实战：源码部署与可视化调试指南
  • 大模型压缩技术：量化、剪枝与蒸馏原理详解
  • Python 与前端集成：构建全栈应用
  • Python 为何成为 AI 开发首选？技术特性与生态全景解析
  • 11 个实用 Python 爬虫项目实战案例汇总
  • MacOS 下使用 Docker 极简安装 OpenClaw 并对接飞书
  • Retinaface+CurricularFace 镜像 Python 3.11.14 安全补丁升级方法
  • RabbitMQ 消息确认机制详解：自动与手动模式
  • C++与Rust函数调用性能优化技巧
  • 内网环境下通过代理自动下载模型
  • ClawX 可视化 AI 智能体工具介绍与使用指南
  • Ollama 模型下载慢？国内镜像 + LLama-Factory 微调实战
  • 动态规划核心原理与经典例题解析
  • Midjourney 线上入口与中文环境使用指南
  • Playwright 与 Puppeteer 模拟人工操作攻克纯前端渲染页面
  • Git 版本控制常用命令与场景指南

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online