OpenClaw 安装教程(Windows&&macOS)

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

1. 系统要求
2. [macOS 安装](#macOS 安装)
   • 2.1 [安装 Node.js](#安装 Node.js)
   • 2.2 [安装 OpenClaw](#安装 OpenClaw)
   • 2.3 初始化配置（onboarding）
   • 2.4 验证安装
   • 2.5 常见问题
3. [Windows 安装](#Windows 安装)
   • 3.1 [安装 Node.js](#安装 Node.js)
   • 3.2 [安装 OpenClaw](#安装 OpenClaw)
   • 3.3 初始化配置（onboarding）
   • 3.4 验证安装
   • 3.5 常见问题
4. 首次使用
5. [更新 OpenClaw](#更新 OpenClaw)
6. [卸载 OpenClaw](#卸载 OpenClaw)

为什么需要 Node.js？

OpenClaw 是一个基于 Node.js 运行的网关服务，npm（Node 包管理器）用于安装和管理 OpenClaw 本身。安装 Node.js 时 npm 会一并安装，无需单独处理。

2.1 安装 Node.js

前往 https://nodejs.org/zh-cn/download 下载并安装 Node.js。

推荐方式：下载 安装包（最简单）

1. 打开上述链接，页面会自动识别 macOS 系统。
2. 选择 LTS（长期支持）版本 ，点击下载 文件。
3. 双击下载的 文件，按照安装向导完成安装。
4. 安装完成后，npm 已一并安装，无需额外操作。

替代方式：使用 Homebrew

如果你已经安装了 Homebrew，可以直接在终端执行：

替代方式：使用 fnm（支持多版本管理）

验证 Node.js 安装成功：

打开「终端」（Terminal），执行以下命令，确认版本号 ≥ 22：

2.2 安装 OpenClaw

Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。

方式一：官方安装脚本（推荐）

打开「终端」，执行：

该脚本会自动完成以下操作：

• 检测当前系统和已安装的 Node.js 版本
• 通过 npm 全局安装最新版
• 运行健康检查（升级时）

静默安装（跳过 onboarding 向导，适合自动化场景）：

查看安装脚本的所有可用参数：

方式二：手动 npm 安装

如果已有 Node.js 22+，也可以直接用 npm 安装：

如果遇到 相关报错（常见于通过 Homebrew 安装了 libvips 的 Mac）：

如果遇到 报错，需要安装构建工具：

方式三：从源码安装（开发者/贡献者）

2.3 初始化配置（onboarding）

安装完成后，必须运行 onboarding 向导完成初始配置：

参数会将 OpenClaw Gateway 安装为 macOS 系统服务（LaunchAgent），使其在后台自动运行并随开机启动。

向导会引导你完成以下配置：

1. 模型和认证 — 配置 AI 提供商的 API Key（支持 Anthropic、OpenAI 等）
2. 工作区 — 设置 agent 文件的存储位置（默认 ）
3. Gateway — 配置端口（默认 ）、绑定地址和认证模式
4. 频道（可选） — 连接 WhatsApp、Telegram、Discord 等聊天应用
5. 后台服务 — 安装 LaunchAgent 使 Gateway 随系统启动
6. 健康检查 — 启动 Gateway 并验证运行状态
7. 技能（可选） — 安装推荐的内置技能

重新运行 不会清除已有配置，可以安全地用于修改配置。

2.4 验证安装

执行 后，浏览器会自动打开 ，若控制台页面正常加载，即表示安装成功。

2.5 macOS 常见问题

问题：

原因：npm 全局 bin 目录不在系统 PATH 中。

诊断：

修复： 将 npm 全局 bin 目录加入 PATH：

重新打开终端后，再次尝试 。

问题： 安装失败

问题：Gateway 无法启动

3.1 安装 Node.js

前往 https://nodejs.org/zh-cn/download 下载并安装 Node.js。

推荐方式：下载 安装包（最简单）

1. 打开上述链接，页面会自动识别 Windows 系统。
2. 选择 LTS（长期支持）版本 ，点击下载 文件。
3. 双击下载的 文件，按照安装向导完成安装。
4. 安装时务必勾选 “Add to PATH” 选项（默认已勾选），确保命令行可以直接使用 和 。
5. 安装完成后，npm 已一并安装。

替代方式：使用 fnm（PowerShell，支持多版本管理）

替代方式：使用 Chocolatey

验证 Node.js 安装成功：

打开「PowerShell」，执行以下命令，确认版本号 ≥ 22：

如果提示找不到命令，请关闭并重新打开 PowerShell，让 PATH 变更生效。

3.2 安装 OpenClaw

Node.js 安装完成后，选择以下任意一种方式安装 OpenClaw。

方式一：官方安装脚本（推荐）

以管理员身份打开 PowerShell（在开始菜单中右键点击 PowerShell → 以管理员身份运行），执行：

该脚本会自动完成以下操作：

• 检测 Node.js 22+（若未安装，引导通过 winget/Chocolatey/Scoop 安装）
• 通过 npm 全局安装最新版
• 升级时运行健康检查

查看安装脚本所有可用参数：

方式二：手动 npm 安装

方式三：从 GitHub 源码安装

也可以通过环境变量控制安装行为：

3.3 初始化配置（onboarding）

安装完成后，打开新的 PowerShell 窗口，运行 onboarding 向导：

参数会将 OpenClaw Gateway 注册为 Windows 计划任务（Scheduled Task），在后台自动运行。

openclaw skills 教程

向导会引导你完成以下配置：

1. 模型和认证 — 配置 AI 提供商的 API Key（支持 Anthropic、OpenAI 等）
2. 工作区 — 设置 agent 文件的存储位置（默认 ）
3. Gateway — 配置端口（默认 ）和认证模式
4. 频道（可选） — 连接 WhatsApp、Telegram、Discord 等聊天应用
5. 后台服务 — 注册 Windows 计划任务使 Gateway 自动运行
6. 健康检查 — 启动 Gateway 并验证运行状态

3.4 验证安装

执行 后，浏览器会自动打开 ，若控制台页面正常加载，即表示安装成功。

3.5 Windows 常见问题

问题：（命令无法识别）

原因：npm 全局 bin 目录不在系统 PATH 中。

诊断：

修复：

1. 打开「系统属性」→「高级」→「环境变量」
2. 在「用户变量」或「系统变量」中找到 ，点击「编辑」
3. 添加上一步查到的路径（如 ）
4. 点击确定，重新打开 PowerShell

问题：

原因：系统中没有安装 Git。

修复： 安装 Git for Windows，安装完成后重新打开 PowerShell，再次运行 openclaw 安装命令。

问题：PowerShell 执行策略限制脚本运行

然后重新运行安装命令。

问题：Gateway 无法启动

手动停止/删除 Windows 计划任务（服务异常时）：

安装并完成 onboarding 后，有两种方式开始使用 OpenClaw：

方式一：Web 控制台（最快，无需配置频道）

浏览器打开后即可直接与 AI 对话。

方式二：通过聊天应用（WhatsApp / Telegram 等）

在 onboarding 向导中已连接频道的情况下，直接在对应 App 中给机器人发消息即可。

也可以事后通过以下命令添加频道：

发送测试消息

需要已配置频道（如 WhatsApp）：

推荐：重新运行安装脚本（会自动检测并升级）

macOS / Linux：

Windows（PowerShell）：

手动 npm 更新

更新后操作

切换发布频道

回退到指定版本

一键卸载（推荐）

交互式确认，适合普通用户。

静默卸载（自动化场景）

手动完整卸载

如果 CLI 已失效但服务仍在运行，按以下步骤手动清理：

1. 停止并卸载 Gateway 服务：

2. 删除配置和状态文件：

3. 卸载 CLI：

4. 删除 macOS App（如有）：

Windows 手动删除计划任务（服务残留时）：

本文档根据 OpenClaw 官方文档（ 和 ）整理，Node.js 下载地址：https://nodejs.org/zh-cn/download