Varidata 新闻资讯

知识库 | 问答 | 最新技术 | IDC 行业新闻

轻松在 Windows 和 Mac 上安装 OpenClaw 的步骤

发布日期：2026-03-12

无论你使用的是 Windows 还是 Mac，都可以按照简单步骤在电脑上安装 OpenClaw。如果你使用的是香港服务器租用，尤其需要遵循推荐流程，以确保获得最佳性能。通过遵循推荐的安装流程，你可以避免常见问题，比如 Node.js 版本不匹配、权限错误以及 API 密钥配置错误。

以下是一些常见坑点及其解决方案：

常见问题	解决方案
Node.js 版本问题	使用 nvm 安装 Node.js 22 以获得兼容性。
npm 权限问题	将全局目录修改为用户目录，或使用 WSL 原生目录。
Docker 容器启动失败	确保至少 2 vCPU 和 4 GB 内存，最好是 4 vCPU 和 8 GB 内存。
API 密钥问题	检查环境变量的格式是否正确。
WSL2 配置问题	正确配置 wsl.conf，并避免跨文件系统操作。
技能（Skill）安装问题	网络超时时重试，并安装缺失的依赖项。
系统化排错	运行 `openclaw doctor` 进行诊断。

通过这些步骤，你可以快速开始使用 OpenClaw，完成新手引导，并配置 Telegram 集成。整个流程适合新手使用，也能帮助你避免那些常见且令人沮丧的错误。

重点速览

在 Windows 和 Mac 上安装 OpenClaw，优先选择安装脚本，这是最快、最简单的方法。
确保系统满足最低要求，特别是 Node.js 版本 22 或更高版本，以保证安装顺利。
如果你想避免依赖冲突，使用 Docker 在干净、隔离的环境中安装是不错的选择。
安装完成后，务必运行引导向导（onboarding wizard），轻松完成 AI 助手的基础配置，并把它连接到 Telegram 等消息平台。
加入 OpenClaw 社区，获取支持与最新动态，确保你及时了解最佳实践和排错技巧。

OpenClaw 安装前提条件

在安装 OpenClaw 之前，你需要确认电脑满足基本要求。这可以帮助你在安装过程中少踩坑，并获得更流畅的使用体验。

系统要求

请检查你的系统是否满足最低及推荐配置。满足推荐配置可以获得更好的性能和更少的问题。

要求项目	最低配置	推荐配置
Node.js	版本 22+	最新 LTS 版本
操作系统	Windows（WSL2）、macOS 12+、Ubuntu 20.04+	最新版本的操作系统
内存（RAM）	2 GB	4 GB+
存储空间	500 MB 可用空间	1 GB+ 可用空间
包管理器	npm、pnpm 或 bun	pnpm（推荐）

💡 提示：将操作系统和 Node.js 升级到最新版本，可以大幅减少兼容性问题。

必备工具

你需要准备一些工具才能开始安装。具体工具取决于你选择的安装方式。

安装方式	平台支持	所需工具
安装脚本（Installer Script）	macOS、Linux、通过 WSL2 的 Windows	Node.js（自动检测并安装）
Docker Compose	所有平台（通过 Docker）	Docker Engine、Docker Compose
原生 npm/pnpm 安装	所有平台	Node.js（需已安装）

同时，请确保你拥有稳定的网络连接，这对下载依赖包和更新非常重要。

选择安装方式

你可以通过三种主要方式安装 OpenClaw，每种方式都有其优点：

安装脚本：该方式可以直接访问本地文件和桌面应用。如果你希望更高的可控性，它非常合适，但可能需要处理少量手动配置。
NPM 或 pnpm：使用包管理器处理依赖，更新和管理都比较方便，但在遇到问题时，你仍可能需要做一些手动修复。
Docker：将所有依赖打包在一个容器中。如果你想快速搭建且不想操心依赖问题，这是非常好的方式。不过需要先安装 Docker，对新手来说会多一点前期步骤。

如果你想要最快、最稳定的安装体验，建议先尝试安装脚本。若想把运行环境和系统隔离，Docker 是好选择；而如果你经常使用 Node.js，则 NPM 或 pnpm 会更顺手。

在 Windows 上安装 OpenClaw

在 Windows 上，你可以通过多种方式安装 OpenClaw。其中，安装脚本提供了最快速、最稳定的方案，你可以借此充分访问本机硬件和桌面应用。对于高级用户，NPM 和 Docker 方法可以提供更高的可控性与灵活性。

使用安装脚本

安装脚本可以大幅简化整个过程，你无需担心手动配置或缺失依赖。按照以下步骤安装 OpenClaw：

打开终端或 Windows Subsystem for Linux（WSL2）。

运行以下命令开始安装：

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

如果你想在运行前先查看脚本内容，可以先下载脚本：
```
curl -O https://openclaw.ai/install.sh
```
检查无误后，执行脚本：
```
bash install.sh
```

🛠️ 提示：安装脚本会自动检查你的系统是否满足 Node.js 等依赖要求，你不需要提前手动安装它们。

整个安装过程通常只需几分钟。脚本会为你处理所有细节，你可以直接访问本地文件和桌面应用，这也有助于 OpenClaw 更顺畅地运行。

NPM 安装方式

如果你已经在使用 Node.js 和 npm，你可能更倾向于通过包管理器来安装 OpenClaw。这种方式让你对更新和依赖有更精细的控制。但你需要确保 Node.js 版本为 22 或更高。

打开终端或 WSL2。
运行以下命令：
```
npm install -g openclaw
```
安装完成后，通过以下命令启动 OpenClaw：
```
openclaw start
```

💡 注意：如果遇到 npm 权限错误，你可能需要调整 npm 的全局安装目录，将其设为个人用户目录，以避免权限问题。

NPM 方式非常适合想把 OpenClaw 作为其他 Node.js 项目一部分来管理的用户。你可以通过 npm 命令轻松更新或卸载 OpenClaw。

Docker 安装方式

Docker 为 OpenClaw 提供一个封装良好的运行环境，你无需担心系统层面的依赖冲突。开始前，确保你的 Windows 系统已经安装 Docker Desktop，并对 Docker Compose 有基本了解。

从官网安装 Docker Desktop。
打开终端。
拉取 OpenClaw Docker 镜像：
```
docker pull openclaw/openclaw:latest
```
创建一个包含所需配置的 docker-compose.yml 文件。
通过 Docker Compose 启动 OpenClaw：
```
docker-compose up -d
```

🧑‍💻 提示：Docker 会将 OpenClaw 与主系统隔离开来。如果你希望获得干净的运行环境，或计划在一台机器上运行多个服务，这是非常合适的选择。

当你希望把所有依赖打包在一起、减少与其他软件冲突并简化升级流程时，Docker 安装方式非常有价值。

安装方式	易用程度	硬件访问能力	最适合的人群
安装脚本	高	完全访问	新手用户、快速部署场景
NPM	中	完全访问	Node.js 用户
Docker	中	有限访问	高级用户、需隔离环境的场景

根据自身需求选择合适的方式。对于大多数人来说，安装脚本是最友好的方案，而 NPM 与 Docker 则为进阶玩法提供更多灵活性。

在 Mac 上安装 OpenClaw

你可以在几分钟内在 Mac 上完成 OpenClaw 的安装。步骤清晰且灵活：既可以选择最快的一行安装脚本，也可以使用 NPM 或 Docker 以获得更高可控性。

一行安装脚本

一行安装脚本是 Mac 上安装 OpenClaw 的最快方案。只需要在终端中执行一条命令。脚本会检查系统环境、发现缺失工具并为你完成安装，你无需自己手动处理依赖问题。

脚本通过自动处理安装任务，为你节省时间。
会自动检测并安装 Node.js 等必要工具。
你无需手动配置环境。
无论新手还是高级用户都适用。

使用安装脚本的步骤如下：

打开 Mac 上的 Terminal（终端）应用。

复制并粘贴以下命令，然后回车：

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

等待脚本执行完成，你会看到脚本在检查并安装相关工具的输出信息。
脚本执行完毕后，你就可以立即启动 OpenClaw。

💡 提示：如果你希望快速安装 OpenClaw 并尽量避免常见问题，一行安装脚本通常是最佳选择。

NPM 安装方式

如果你已经在其他项目中使用 Node.js，可以通过 NPM 安装 OpenClaw。这种方式让你对更新节奏和调试流程有更多掌控。需要确保 Mac 上的 Node.js 版本为 22 或更高。

使用 NPM 安装 OpenClaw 的步骤如下：

打开终端。
运行以下命令：
```
npm install -g openclaw
```
通过以下命令启动 OpenClaw：
```
openclaw start
```

下面的表格对比了 NPM 与 Docker 两种方式：

安装方式	优点	缺点	适用场景
Docker	容器隔离、环境统一、便于迁移	资源占用更高、配置相对复杂	VPS 服务器、NAS、Mac Mini
NPM	安装简单、资源占用低、便于调试	依赖宿主环境，可能发生版本冲突	个人电脑、开发环境

如果你偏向轻量级部署、并希望在开发流程中使用 OpenClaw，NPM 是非常合适的方式。你可以用简单的 NPM 命令更新或卸载 OpenClaw。

Docker 安装方式

Docker 允许你在容器中运行 OpenClaw，从而将其与主系统隔离，避免版本冲突和复杂依赖问题。你需要先在 Mac 上安装 Docker Desktop。

通过 Docker 安装 OpenClaw 的步骤如下：

从官网下载安装 Docker Desktop。
打开终端。
拉取最新 OpenClaw 镜像：
```
docker pull openclaw/openclaw:latest
```
创建一个配置正确的 docker-compose.yml 文件。
通过以下命令启动 OpenClaw：
```
docker-compose up -d
```

🛠️ 注意：如果你打算在服务器、NAS 或 Mac Mini 上长期运行 OpenClaw，Docker 是非常不错的方案。虽然资源开销更大，但可以获得稳定且隔离的运行环境。

你可以根据自身需求选择合适方式。一行安装脚本是最快速的安装方法，而 NPM 与 Docker 则适合需要自定义配置的用户。

OpenClaw 的配置与引导

运行引导向导（Onboarding Wizard）

安装完成后，你需要运行引导向导来完成基础配置。该向导会以分步方式帮助你设置 AI 助手，你只需回答几个简单问题即可开始使用。

通过以下命令运行引导向导：
openclaw onboard

向导会引导你完成以下步骤：

步骤	说明
1. 欢迎	介绍 OpenClaw
2. 网关设置	配置本地网关守护进程
3. 工作区	设置工作目录
4. API 密钥	配置 Anthropic / OpenAI 等 API 访问
5. 渠道	连接消息平台
6. 技能（Skills）	安装内置技能和额外技能

你将选择 AI 提供商，比如 Anthropic Claude、OpenAI GPT、Google Gemini 或本地的 Ollama 模型。然后输入对应的 API 密钥。接着，选择首个要连接的消息平台，例如 Telegram、WhatsApp 或 Slack。整个过程步骤清晰，易于跟随。

Telegram 机器人集成

你可以在引导过程中将 OpenClaw 连接到 Telegram。向导会提示你输入相应凭据，以完成 Telegram 账号的绑定。集成完成后，你就可以通过 Telegram 与 AI 助手对话。

你可以像与好友聊天一样，通过 Telegram 与 OpenClaw 互动。
配置过程简单快捷，让你可以几乎立刻开始使用。
当然，你也可以连接其他渠道，但 Telegram 是很多用户首选的方式。

这种多渠道接入方式，为你提供了灵活、自然的沟通体验。

验证安装是否成功

完成配置后，你应当检查 OpenClaw 是否正常运行。可以通过以下命令验证安装状态：

运行诊断工具：
```
openclaw doctor
```
此工具会检查 Node.js 是否为最新版本、配置文件是否有效、API 密钥是否可用，以及消息桥（messaging bridge）是否正常工作。如果存在问题，它会给出错误信息和修复建议。
检查版本号：
```
openclaw --version
```
如果你能看到版本号，说明安装已成功。

若遇到问题，请仔细阅读错误信息。常见问题包括 API 密钥无效或依赖项缺失。排查并修复这些问题可以确保 OpenClaw 稳定运行。

安装问题排查

即便安装流程已经相当完善，你在搭建 OpenClaw 时仍可能遇到一些问题。只要知道关键排查思路，大多数问题都能很快解决。本节将介绍最常见的错误及对应解决方法。

常见错误

在安装过程中，你可能会遇到如下常见错误：

在 Apple Silicon Mac 上，你需要使用原生 ARM 版本的 Node.js。可以通过以下命令检查架构：
```
node -p "process.arch"
```
损坏的 npm 缓存可能阻碍安装。可以通过以下命令清理缓存：
```
npm cache clean --force
```
在经历一次大型 macOS 升级后，原生模块可能失效。可以运行：
```
xcode-select --install
```
在 Windows 上，目前不建议原生安装，使用 WSL2 通常效果更好。
类似 “spawn npm ENOENT” 或脚本执行被策略阻止的错误在 Windows 上较常见。切换到 WSL2 通常可以解决这些问题。

🛠️ 提示：如果你在 Windows 上看到 “Gateway Connect Failed: Error: Pairing Required” 这样的错误信息，可以尝试编辑 .openclaw/devices 目录中的 pending.json 文件。社区中有相关图文指南可供参考。

依赖问题

许多安装失败都与 Node.js 或包依赖相关。按照以下步骤，可以解决大部分依赖问题：

检查 Node.js 版本：
```
node -v
```
需要确保版本为 22 或更高。
如果版本不符合要求，先安装 nvm（Node 版本管理器）。
使用 nvm 安装 Node.js 22，并将其设置为默认版本。

运行 OpenClaw 诊断与状态命令：

openclaw status
openclaw health
openclaw doctor

查看日志中的错误信息或堆栈追踪。
如果依旧无法解决，请在前往 GitHub 求助之前，先收集好日志和系统信息。

你也可以通过 Docker 来规避本地依赖冲突。只需拉取最新镜像并在容器中运行 OpenClaw：

docker pull openclaw/openclaw
docker run openclaw/openclaw

网络与权限问题

网络连接和权限设置也是导致安装失败的常见原因，可以参考以下建议：

若出现 “permission denied” 之类错误，可将 npm 全局目录设置到用户主目录，而非系统目录。
始终使用 Node.js 22 或更高版本，以避免兼容性问题。
如果引导向导找不到配置文件，可以重新运行引导，或者手动创建配置目录。

💡 注意：稳定的网络连接有助于避免依赖包下载失败或缺失。

按照这些步骤进行排查，大部分安装问题都可以被快速定位并解决，让 OpenClaw 顺利运行起来。

你可以在 Windows 或 Mac 上轻松安装 OpenClaw。安装脚本加上清晰的文档，使整个流程对所有类型用户都很友好。下表概括了灵活安装方式能为你带来的好处：

说明	好处
一条命令完成安装	各个技术水平的用户都能快速上手
分步引导文档	让非技术用户也能轻松完成部署
社区支持	获得快速帮助与问题修复

若想让 OpenClaw 保持安全、稳定和 7×24 小时运行，可以参考以下最佳实践：