## 系统要求
在安装 OpenClaw 之前，请确认你的系统满足以下基本要求：
- **Node.js**：推荐 Node 24（最新 LTS），最低支持 Node 22.14+
- **操作系统**：macOS、Linux、Windows 均支持
- **磁盘空间**：至少 500MB 可用空间
- **网络**：安装过程需要联网下载依赖
检查 Node.js 版本：
```bash
node --version
```
如果尚未安装 Node.js，推荐使用 [nvm](https://github.com/nvm-sh/nvm)（macOS/Linux）或 [nvm-windows](https://github.com/coreybutler/nvm-windows)（Windows）来管理 Node 版本：
```bash
# macOS / Linux
nvm install 24
nvm use 24
# Windows（使用 nvm-windows）
nvm install 24
nvm use 24
```
## Windows 安装
Windows 用户有两种安装方式，推荐使用 WSL2 以获得更稳定的体验。
### 方式一：WSL2 安装（推荐）
WSL2（Windows Subsystem for Linux）让你在 Windows 上运行完整的 Linux 环境，兼容性最好，社区技能和工具支持最完善。
**第一步：安装 WSL2**
打开 PowerShell（管理员模式），运行：
```powershell
wsl --install
```
安装完成后重启电脑，系统会自动配置 Ubuntu 发行版。
**第二步：在 WSL2 中安装 OpenClaw**
打开 WSL2 终端（在开始菜单搜索 "Ubuntu"），运行安装脚本：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
安装完成后，OpenClaw 的所有命令都在 WSL2 环境中使用。
**第三步：服务管理**
在 WSL2 中，你可以使用 systemd 管理 OpenClaw 服务（与 Linux 方式相同）：
```bash
openclaw gateway install
openclaw gateway start
```
### 方式二：原生 Windows 安装
如果你不想使用 WSL2，也可以直接在 Windows 上安装。
打开 PowerShell，运行：
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
**服务管理**
原生 Windows 使用计划任务（Scheduled Task）来管理 OpenClaw 服务：
```powershell
# 安装为系统服务（计划任务）
openclaw gateway install
# 查看服务状态
openclaw gateway status
# 启动 / 停止 / 重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
```
### Windows 注意事项
- WSL2 方式下，文件系统性能在 Linux 分区（`/home/`）比 Windows 挂载目录（`/mnt/c/`）快很多，建议把工作区放在 Linux 分区
- 原生 Windows 安装时，部分依赖 Unix 工具的技能可能无法正常工作
- 防火墙可能阻止 Gateway 端口，需要手动放行 18789 端口
- 如果遇到 npm 权限问题，尝试以管理员身份运行 PowerShell
## macOS 安装
macOS 安装最为简单，一行命令搞定。
### 安装脚本
打开终端，运行：
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
脚本会自动检测系统架构（Intel / Apple Silicon），下载对应版本并配置环境变量。
### 服务管理
macOS 使用 launchd 管理后台服务，OpenClaw 提供了便捷的安装命令：
```bash
# 安装为 launchd 服务（开机自启）
openclaw gateway install
# 查看服务状态
openclaw gateway status
# 启动 / 停止 / 重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
```
安装为 launchd 服务后，OpenClaw Gateway 会在系统启动时自动运行，无需手动启动。
### macOS 注意事项
- 首次运行时，macOS 可能弹出安全提示，在"系统设置 → 隐私与安全性"中允许即可
- Apple Silicon（M1/M2/M3/M4）原生支持，无需 Rosetta
- 如果使用 Homebrew 管理 Node.js，确保 `node` 命令在 PATH 中
## Linux 安装
Linux 是 OpenClaw 的主力平台，支持所有主流发行版。
### 安装脚本
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
### 服务管理
Linux 使用 systemd 用户服务管理 OpenClaw：
```bash
# 安装为 systemd 用户服务
openclaw gateway install
# 查看服务状态
openclaw gateway status
# 启动 / 停止 / 重启
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
```
### 持久运行
默认情况下，systemd 用户服务在用户注销后会停止。如果你希望 OpenClaw 在服务器上 7×24 小时运行，需要启用 linger：
```bash
sudo loginctl enable-linger <你的用户名>
```
启用后，即使你断开 SSH 连接，OpenClaw Gateway 也会继续运行。
### Linux 注意事项
- Ubuntu/Debian 用户如果没有 `curl`，先安装：`sudo apt install curl`
- CentOS/RHEL 用户确保 Node.js 版本足够新，系统自带的版本通常过旧
- 服务器环境建议使用 systemd 管理，不要用 `nohup` 或 `screen`
- SELinux 开启时可能需要额外配置端口策略
## Docker 安装
如果你熟悉 Docker，可以用容器方式运行 OpenClaw，隔离性好，部署方便。
### 快速启动
```bash
docker run -d \
--name openclaw \
-p 18789:18789 \
-v openclaw-data:/root/.openclaw \
openclawai/openclaw:latest
```
### docker-compose 方式
创建 `docker-compose.yml` 文件：
```yaml
version: '3.8'
services:
openclaw:
image: openclawai/openclaw:latest
container_name: openclaw
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- openclaw-data:/root/.openclaw
environment:
- TZ=Asia/Shanghai
volumes:
openclaw-data:
```
启动服务：
```bash
docker-compose up -d
```
### Docker 注意事项
- 使用 `-v` 挂载数据卷，确保配置和会话数据持久化
- 国内拉取镜像可能较慢，可以配置 Docker 镜像加速器
- 容器内安装技能和插件的数据也存储在挂载卷中
- 更新版本时，先 `docker pull` 新镜像，再重建容器
## 各平台服务管理对比
| 平台 | 服务管理方式 | 安装命令 | 开机自启 | 后台持久运行 |
|------|-------------|---------|---------|-------------|
| macOS | launchd | `openclaw gateway install` | ✅ 自动 | ✅ 自动 |
| Linux | systemd 用户服务 | `openclaw gateway install` | ✅ 需 enable-linger | ⚠️ 需 enable-linger |
| Windows (WSL2) | systemd | `openclaw gateway install` | ✅ 需配置 | ⚠️ 需 WSL2 自启 |
| Windows (原生) | 计划任务 | `openclaw gateway install` | ✅ 自动 | ✅ 自动 |
| Docker | docker restart policy | `restart: unless-stopped` | ✅ 自动 | ✅ 自动 |
## 验证安装
无论使用哪种安装方式，安装完成后都可以用以下命令验证：
```bash
# 查看版本号
openclaw --version
# 运行诊断检查
openclaw doctor
# 查看 Gateway 状态
openclaw gateway status
```
`openclaw doctor` 会检查 Node.js 版本、依赖完整性、配置文件等，如果有问题会给出修复建议。
## 各平台常见问题
### Windows
- **PowerShell 执行策略限制**：运行 `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` 解除
- **端口被占用**：检查 18789 端口是否被其他程序占用，用 `netstat -ano | findstr 18789` 排查
- **WSL2 网络问题**：WSL2 默认使用 NAT 网络，从 Windows 访问 WSL2 中的 Gateway 使用 `localhost`
### macOS
- **权限不足**：安装脚本需要写入 `/usr/local/bin`，可能需要输入密码
- **端口冲突**：用 `lsof -i :18789` 检查端口占用
### Linux
- **curl 未安装**：`sudo apt install curl`（Debian/Ubuntu）或 `sudo yum install curl`（CentOS）
- **Node.js 版本过旧**：使用 nvm 安装最新版本，不要依赖系统包管理器自带的 Node.js
- **systemd 不可用**：部分精简版 Linux（如 Alpine）没有 systemd，可以用 PM2 替代
### Docker
- **镜像拉取超时**：配置国内 Docker 镜像加速器（如阿里云、腾讯云镜像源）
- **容器内无法联网**：检查 Docker 网络配置和 DNS 设置
#Windows安装 #macOS安装 #Linux安装 #Docker部署 #龙虾技能库