【OpenClaw 从入门到精通】第 2 篇：安装 OpenClaw — 全平台指南

本系列定位：零基础入门，从安装配置到高级架构全覆盖。无论你是开发者、运维工程师、还是技术爱好者，本系列带你彻底掌握 OpenClaw。

---

本篇你将学到

• 运行时要求（Node.js 版本）
• macOS / Linux 一键安装
• Windows 安装（PowerShell + Windows Hub）
• npm / pnpm / bun 包管理器安装
• Docker 安装方式
• 安装验证与健康检查

学完本篇，你的机器上将拥有一个可运行的 OpenClaw 环境。

---

下面是 OpenClaw 全平台安装的整体流程：

一、运行时要求

1.1 Node.js 版本

OpenClaw 基于 TypeScript 构建，需要 Node.js 运行时：

Node.js 版本	支持状态	说明
Node 24.15+	✅ 推荐	最新 LTS，性能最佳
Node 22.22.3+	✅ 支持	上一代 LTS
Node 25.9+	✅ 支持	Current 版本
< Node 22.22	❌ 不支持	版本太低

1.2 检查 Node.js

node --version
# 输出 v24.15.0 或更高即可

如果没有安装或版本太低：

# macOS（Homebrew）
brew install node@24

# Linux（nvm 方式，推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 24
nvm use 24

# Windows：从 nodejs.org 下载安装包

1.3 系统要求

要求	最低	推荐
操作系统	macOS 12 / Ubuntu 20.04 / Windows 10	macOS 14 / Ubuntu 22.04 / Windows 11
内存	2GB	4GB+
磁盘	300MB	500MB
网络	需要访问 AI 模型 API	—

---

二、macOS / Linux 安装

2.1 一键安装脚本（推荐）

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

脚本自动完成：

1. 检查 Node.js 版本
2. 全局安装 openclaw 包
3. 创建配置目录 ~/.openclaw/
4. 创建 Workspace 目录 ~/.openclaw/workspace/
5. 添加 openclaw 到 PATH

2.2 验证安装

openclaw --version

OpenClaw v2026.7.x

---

三、Windows 安装

3.1 方式一：PowerShell 一键安装

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

3.2 方式二：Windows Hub 伴侣应用

Windows 用户可以使用原生的 Windows Hub 伴侣应用：

1. 从 OpenClaw 官网下载 Windows Hub 安装包
2. 运行安装程序
3. Windows Hub 提供：
   • 图形化设置向导
   • 托盘状态图标
   • 内置聊天界面
   • Node Mode（节点模式）
   • Local MCP Mode

Windows Hub 适合不想用命令行的用户。开发者建议用命令行方式安装。

3.3 Windows 注意事项

注意	说明
确保 Node.js 在 PATH 中	安装后运行 node --version 验证
PowerShell 执行策略	如果脚本被阻止：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
防火墙	Gateway 需要 18789 端口（默认），确保未被占用

---

四、包管理器安装

4.1 npm

npm install -g openclaw@latest

4.2 pnpm

pnpm add -g openclaw@latest

4.3 bun

bun add -g openclaw@latest

三种包管理器效果相同。如果你不确定选哪个，用 npm。

---

五、Docker 安装

Docker 部署架构如下：

5.1 Docker Compose

version: "3.9"

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-gateway
    ports:
      - "18789:18789"
    volumes:
      - openclaw_data:/root/.openclaw
      - ./workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    restart: unless-stopped

volumes:
  openclaw_data:

5.2 启动

# 创建 .env 文件
echo "ANTHROPIC_API_KEY=your_key" > .env

# 启动
docker compose up -d

# 验证
docker exec openclaw-gateway openclaw doctor

5.3 Docker 优势

• 环境完全隔离
• 配置通过 Volume 持久化
• 方便服务器部署
• 多实例运行简单

---

六、安装后验证

6.1 健康检查

openclaw doctor

openclaw doctor 检查：

检查项	说明
Node.js 版本	是否满足要求
依赖完整性	核心包是否完整
配置文件	openclaw.json 是否存在
Workspace	工作目录是否可写
Gateway 端口	18789 是否可用
API Key	是否配置了至少一个 Provider
DM 安全策略	检查是否有风险配置

如果有问题，openclaw doctor 会给出修复建议。

6.2 目录结构

安装完成后，~/.openclaw/ 目录：

~/.openclaw/
├── openclaw.json           ← 主配置文件
├── workspace/              ← 工作空间
│   ├── AGENTS.md           ← 项目上下文
│   ├── SOUL.md             ← Agent 人格
│   └── skills/             ← 技能目录
├── gateway.db              ← Gateway 数据库（SQLite）
├── logs/                   ← 日志
└── state-snapshots/        ← 状态快照

---

目录结构关系图：

七、常见安装问题

Q1：openclaw: command not found

# 检查 npm 全局目录是否在 PATH 中
npm config get prefix

# 添加到 PATH
# macOS / Linux
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows：通常自动添加，重启终端

Q2：Node.js 版本太低

# 用 nvm 升级
nvm install 24
nvm use 24
nvm alias default 24

Q3：端口 18789 被占用

# 查看占用进程
lsof -i :18789       # macOS / Linux
netstat -ano | findstr :18789   # Windows

# 或者用其他端口启动
openclaw gateway --port 18790

Q4：权限不足

# macOS / Linux：修复 npm 全局目录权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 然后重新安装
npm install -g openclaw@latest

Q5：Docker 拉取镜像失败

# 配置镜像加速器
# 或使用代理
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=http://your-proxy:port
docker compose pull

---

本篇小结

知识点	核心内容
Node.js	需要 24.15+ / 22.22.3+ / 25.9+
macOS/Linux	curl -fsSL https://openclaw.ai/install.sh | bash
Windows	PowerShell 脚本 或 Windows Hub
包管理器	npm install -g openclaw@latest
Docker	docker-compose + Volume 持久化
验证	openclaw doctor
配置目录	~/.openclaw/（openclaw.json / workspace / logs）
默认端口	18789

---

下篇预告

第 3 篇：Onboarding 向导 — 五分钟完成初始配置

安装完了，用 openclaw onboard 五分钟完成 Gateway、Workspace、通道和技能的初始配置。

---

如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。