跳到主要内容

安装部署

本章将详细介绍 OpenClaw 在 Windows、macOS、Linux 三大平台的安装部署方法，以及 Docker 容器化部署方案。

系统要求​

最低配置​

项目要求
CPU2 核以上
内存4GB 以上（推荐 8GB）
存储至少 5GB 可用空间
Node.js18.x 或更高版本
npm9.x 或更高版本

推荐配置​

项目要求
CPU4 核以上
内存8GB 以上
存储20GB 以上 SSD
Node.js20.x LTS 版本

Windows 安装​

方法一：一键安装（推荐）​

打开 PowerShell（以管理员身份运行），执行：

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

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

  1. 检测系统环境
  2. 安装 Node.js（如果未安装）
  3. 安装 OpenClaw
  4. 配置环境变量
  5. 创建默认配置文件

方法二：手动安装​

1. 安装 Node.js​

访问 Node.js 官网 下载 LTS 版本安装包，或使用包管理器：

# 使用 Chocolatey
choco install nodejs-lts

# 使用 Scoop
scoop install nodejs-lts

2. 验证 Node.js 安装​

node --version
npm --version

确保 Node.js 版本 >= 18，npm 版本 >= 9。

3. 安装 OpenClaw​

npm install -g openclaw@latest

4. 验证安装​

openclaw --version

方法三：使用安装包​

  1. 访问 OpenClaw Releases 页面
  2. 下载 Windows 安装包（.exe 或 .msi）
  3. 双击安装包，按提示完成安装

Windows 防火墙配置​

首次启动时，Windows 可能弹出防火墙提示，请选择"允许访问"。

如果需要手动配置防火墙规则：

# 允许 OpenClaw 通过防火墙
New-NetFirewallRule -DisplayName "OpenClaw" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 18789

macOS 安装​

方法一：一键安装​

打开终端，执行：

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

方法二：使用 Homebrew​

# 添加 OpenClaw 仓库
brew tap openclaw/tap

# 安装 OpenClaw
brew install openclaw

方法三：手动安装​

1. 安装 Node.js​

# 使用 Homebrew
brew install node@20

# 或使用 nvm（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.zshrc
nvm install 20
nvm use 20

2. 安装 OpenClaw​

npm install -g openclaw@latest

3. 验证安装​

openclaw --version

macOS 权限配置​

首次运行时，macOS 可能提示"无法验证开发者"，解决方法：

# 方法一：在系统偏好设置中允许
# 系统偏好设置 → 安全性与隐私 → 通用 → 仍要打开

# 方法二：使用命令行
xattr -cr /usr/local/bin/openclaw

Linux 安装​

方法一：一键安装​

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

方法二：包管理器安装​

Ubuntu/Debian​

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
sudo npm install -g openclaw@latest

CentOS/RHEL/Fedora​

# 安装 Node.js
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# 安装 OpenClaw
sudo npm install -g openclaw@latest

Arch Linux​

# 安装 Node.js
sudo pacman -S nodejs npm

# 安装 OpenClaw
sudo npm install -g openclaw@latest

方法三：从源码安装​

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 构建
npm run build

# 全局安装
npm link

Linux 系统配置​

创建专用用户（推荐）​

# 创建 openclaw 用户
sudo useradd -r -s /bin/bash -m -d /opt/openclaw openclaw

# 切换到 openclaw 用户
sudo su - openclaw

# 安装 OpenClaw
npm install -g openclaw@latest

配置文件描述符限制​

# 编辑 limits.conf
sudo tee -a /etc/security/limits.conf << EOF
openclaw soft nofile 65535
openclaw hard nofile 65535
EOF

Docker 部署​

使用 Docker Compose（推荐）​

1. 创建配置文件​

创建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
      - "18792:18792"
    volumes:
      - ./data:/root/.openclaw
      - ./logs:/var/log/openclaw
    environment:
      - TZ=Asia/Shanghai
      - OPENCLAW_LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

2. 启动服务​

docker-compose up -d

3. 查看日志​

docker-compose logs -f openclaw

使用 Docker 命令​

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -p 18792:18792 \
  -v $(pwd)/data:/root/.openclaw \
  -e TZ=Asia/Shanghai \
  openclaw/openclaw:latest

Docker 网络配置​

如果需要让 OpenClaw 访问宿主机服务：

services:
  openclaw:
    extra_hosts:
      - "host.docker.internal:host-gateway"

树莓派 / ARM 设备部署​

OpenClaw 支持 ARM 架构，可在树莓派等设备上运行。

安装步骤​

# 安装 Node.js（ARM 版本）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
npm install -g openclaw@latest

性能优化建议​

对于资源受限的 ARM 设备：

# 降低并发限制
openclaw config set concurrency.max 2

# 减少内存使用
openclaw config set memory.max_history 50

# 使用轻量级模型
openclaw config set model.provider ollama

初始化配置​

安装完成后，需要进行初始化配置：

交互式配置​

openclaw config

按照提示依次配置：

  1. 选择运行模式（local/cloud）
  2. 配置模型提供商
  3. 配置渠道（可选）
  4. 设置管理员密码

命令行配置​

# 配置模型
openclaw config set model.provider claude
openclaw config set model.api_key sk-xxx

# 配置 Gateway 端口
openclaw config set gateway.port 18789

# 配置时区
openclaw config set timezone Asia/Shanghai

配置文件位置​

平台配置文件路径
WindowsC:\Users\<用户名>\.openclaw\
macOS~/.openclaw/
Linux~/.openclaw/
Docker容器内 /root/.openclaw/

启动服务​

前台启动​

openclaw gateway start

后台启动（守护进程）​

# 安装为系统服务
openclaw service install

# 启动服务
openclaw service start

# 查看状态
openclaw service status

systemd 服务配置（Linux）​

创建服务文件 /etc/systemd/system/openclaw.service：

[Unit]
Description=OpenClaw AI Agent
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/opt/openclaw
ExecStart=/usr/bin/openclaw gateway start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启用服务：

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

验证安装​

检查服务状态​

openclaw gateway status

访问 Web UI​

打开浏览器访问：

http://127.0.0.1:18789

首次访问需要输入 Token，获取方式：

openclaw config --show-token

测试对话​

openclaw chat "你好，请介绍一下你自己"

常见安装问题​

npm 安装失败​

原因：网络问题或权限不足。

解决：

# 使用国内镜像
npm config set registry https://registry.npmmirror.com

# 使用 sudo（Linux/macOS）
sudo npm install -g openclaw@latest

# Windows 使用管理员权限运行 PowerShell

Node.js 版本过低​

原因：Node.js 版本低于 18。

解决：

# 使用 nvm 升级
nvm install 20
nvm use 20

# 或直接安装新版本
# Windows: 下载最新安装包
# macOS: brew upgrade node
# Linux: 参考上面的安装步骤

端口被占用​

原因：默认端口 18789 已被其他程序占用。

解决：

# 查看端口占用
# Windows
netstat -ano | findstr 18789

# Linux/macOS
lsof -i :18789

# 更换端口
openclaw config set gateway.port 18790

权限问题​

原因：文件或目录权限不足。

解决：

# Linux/macOS
sudo chown -R $(whoami) ~/.openclaw

# Windows：以管理员身份运行

Docker 容器无法访问​

原因：网络配置问题。

解决：

# 检查容器状态
docker ps -a

# 查看容器日志
docker logs openclaw

# 检查端口映射
docker port openclaw

升级更新​

npm 方式升级​

npm update -g openclaw

Homebrew 方式升级​

brew upgrade openclaw

Docker 方式升级​

docker-compose pull
docker-compose up -d

检查版本​

openclaw --version

卸载​

npm 方式卸载​

npm uninstall -g openclaw

# 删除配置文件（可选）
rm -rf ~/.openclaw

Homebrew 方式卸载​

brew uninstall openclaw
brew untap openclaw/tap

Docker 方式卸载​

docker-compose down
docker rmi openclaw/openclaw:latest

下一步​