安装部署

本章将详细介绍 OpenClaw 的安装部署方法。安装过程大约需要 5 分钟，完成后你将拥有一个运行中的 Gateway、配置好的认证和一个可用的聊天会话。

安装前准备

你需要什么

项目	说明
Node.js	Node 24（推荐）或 Node 22.14+ LTS
API Key	来自模型提供商（Anthropic、OpenAI、Google 等）—— onboarding 会提示你输入
内存	建议 4GB 以上

平台支持

平台	支持情况	备注
macOS	原生支持	可使用菜单栏应用
Linux	原生支持	推荐用于服务器部署
Windows	原生 + WSL2	WSL2 更稳定，推荐使用
Docker	完全支持	适合服务器环境

Windows 用户建议

OpenClaw 支持原生 Windows 和 WSL2 两种方式。WSL2 提供了完整的 Linux 环境，体验更稳定，是更推荐的选择。OpenClaw 的许多功能（如文件系统监控、进程管理）在 Linux 环境下表现最佳。

如果你选择 WSL2，安装方法：

# 在 PowerShell（管理员）中执行
wsl --install

安装完成后重启电脑，然后进入 WSL2 Ubuntu 环境继续安装 OpenClaw。

一键安装（推荐）

官方安装脚本是最快的安装方式，它会自动检测你的操作系统、安装 Node.js（如果需要）、安装 OpenClaw 并启动 onboarding 向导。

macOS / Linux / WSL2

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

Windows PowerShell

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

安装脚本会依次执行：

检测操作系统类型
检查 Node.js 是否已安装，未安装则自动安装 Node 24
通过 npm 全局安装 OpenClaw
启动 onboarding 向导引导你完成配置

安装后验证

# 检查版本
openclaw --version

# 运行诊断
openclaw doctor

# 启动 Gateway
openclaw gateway

手动安装

如果你已经自己管理 Node.js 环境，可以手动安装。

使用 npm

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行 onboarding 向导
openclaw onboard

# 同时安装为系统服务
openclaw onboard --install-daemon

使用 pnpm

# 安装 OpenClaw
pnpm add -g openclaw@latest

# 运行 onboarding
openclaw onboard

安装后验证

# 检查版本
openclaw --version

# 运行诊断
openclaw doctor

# 初始化配置（如果尚未初始化）
openclaw setup

# 启动 Gateway
openclaw gateway

# 在另一个终端测试
openclaw agent --message "你好"

常见安装问题

sharp 构建错误

如果 npm 安装时 sharp 因为全局安装的 libvips 而失败：

# 方法一：使用 pnpm 代替
pnpm add -g openclaw@latest

# 方法二：设置 npm 忽略可选依赖
npm install -g openclaw@latest --ignore-scripts=false

openclaw 命令找不到

如果安装成功但终端找不到 openclaw 命令，说明 npm 全局 bin 目录不在 PATH 中：

# 查看npm全局bin目录
npm prefix -g

# 将其添加到shell启动文件（~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"

# 重新加载配置
source ~/.zshrc  # 或 source ~/.bashrc

详细安装步骤

macOS 安装

使用 Homebrew

# 安装 Node.js（推荐使用 nvm）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install 24
nvm use 24

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行 Onboard
openclaw onboard --install-daemon

验证安装

openclaw --version
openclaw gateway

Linux 安装

Ubuntu/Debian

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

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

# 运行 Onboard
openclaw onboard --install-daemon

CentOS/RHEL/Fedora

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

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

Windows 安装（WSL2）

强烈推荐使用 WSL2，这是在 Windows 上运行 OpenClaw 的最佳方式。

安装 WSL2

# 在 PowerShell（管理员）中执行
wsl --install

安装完成后重启电脑，然后进入 WSL2 Ubuntu 环境。

在 WSL2 中安装 OpenClaw

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

# 安装 OpenClaw
npm install -g openclaw@latest

# 运行 Onboard
openclaw onboard --install-daemon

访问 Windows 文件

WSL2 可以直接访问 Windows 文件系统：

# Windows 用户目录
cd /mnt/c/Users/你的用户名/

# 可以在 Windows 文件系统上创建工作空间
openclaw config set agents.defaults.workspace /mnt/c/Users/你的用户名/openclaw-workspace

Docker 部署

Docker 部署适合服务器环境或需要隔离的场景。

使用 Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/root/.openclaw
    environment:
      - TZ=Asia/Shanghai
    command: openclaw gateway

启动服务：

docker-compose up -d
docker-compose logs -f openclaw

使用 Docker 命令

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

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

Docker 注意事项

数据持久化：确保挂载 /root/.openclaw 目录
网络配置：如需外部访问，配置端口映射
资源限制：建议配置内存和 CPU 限制

配置文件

配置文件位置

文件	路径	说明
主配置	`~/.openclaw/openclaw.json`	全局配置文件
环境变量	`~/.openclaw/.env`	环境变量文件（可选）
工作空间	`~/.openclaw/workspace/`	Agent 工作目录
Agent 状态	`~/.openclaw/agents/`	各 Agent 的状态目录
记忆文件	`~/.openclaw/workspace/MEMORY.md`	Agent 记忆
人格定义	`~/.openclaw/workspace/SOUL.md`	Agent 人格

配置文件格式

配置文件使用 JSON5 格式，支持注释和尾随逗号：

{
  // 这是注释，方便理解配置项
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4",
      "workspace": "~/.openclaw/workspace",  // 尾随逗号是允许的
    },
  },
}

配置拆分（$include）

大型配置可以拆分为多个文件：

{
  "$include": "./channels.json",
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

$include 支持：

单个文件：替换包含对象
文件数组：按顺序深度合并（后面的覆盖前面的）
嵌套引用：最多支持 10 层嵌套
相对路径：相对于当前文件解析

环境变量

OpenClaw 从以下位置读取环境变量：

父进程环境
当前工作目录的 .env 文件
~/.openclaw/.env 文件（全局后备）

在配置中使用环境变量：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4",
        "apiKey": "${ANTHROPIC_API_KEY}"
      }
    }
  }
}

环境变量替换规则：

格式：${VAR_NAME}（只匹配大写名称）
变量不存在时会报错
转义：$${VAR} 输出字面量 ${VAR}

常用环境变量

变量	说明
`ANTHROPIC_API_KEY`	Claude API Key
`OPENAI_API_KEY`	OpenAI API Key
`GEMINI_API_KEY`	Google Gemini API Key
`VOYAGE_API_KEY`	Voyage API Key
`MISTRAL_API_KEY`	Mistral API Key
`OPENCLAW_GATEWAY_TOKEN`	Gateway 访问 Token
`OPENCLAW_CONFIG_PATH`	自定义配置文件路径
`OPENCLAW_STATE_DIR`	自定义状态目录

最小配置示例

~/.openclaw/openclaw.json 最小配置：

{
  "agent": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4-6"
    }
  }
}

推荐基础配置：

{
  "identity": {
    "name": "Clawd",
    "theme": "helpful assistant",
    "emoji": "🦞"
  },
  "agent": {
    "workspace": "~/.openclaw/workspace",
    "model": {
      "primary": "anthropic/claude-sonnet-4-6"
    }
  },
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15555550123"]
    }
  }
}

配置验证

# 验证配置文件格式
openclaw config validate

# 查看配置值
openclaw config get agents.defaults.model

# 设置配置值
openclaw config set agents.defaults.model.primary "anthropic/claude-sonnet-4"

# 查看配置文件路径
openclaw config file

# 查看配置 Schema
openclaw config schema

当配置验证失败时：

Gateway 无法启动
只有诊断命令可用：openclaw doctor、openclaw logs、openclaw health、openclaw status
运行 openclaw doctor --fix 可自动修复部分问题

启动服务

前台启动

openclaw gateway

后台运行（守护进程）

使用 Onboard 安装守护进程：

openclaw onboard --install-daemon

这会安装为系统服务（macOS 使用 launchd，Linux 使用 systemd）。

手动配置 systemd（Linux）

创建 /etc/systemd/system/openclaw.service：

[Unit]
Description=OpenClaw Gateway
After=network.target

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

[Install]
WantedBy=multi-user.target

启用服务：

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

验证安装

检查服务状态

# 检查 Gateway 是否运行
openclaw gateway status

# 或者直接访问
curl http://127.0.0.1:18789

访问 Control UI

打开浏览器访问：

http://127.0.0.1:18789

这是 OpenClaw 的控制界面，提供聊天、配置、会话管理等功能。

测试对话

openclaw agent --message "你好，请介绍一下你自己"

升级更新

# 更新到最新版本
npm update -g openclaw

# 检查版本
openclaw --version

# 运行诊断
openclaw doctor

切换版本通道

# 稳定版
openclaw update --channel stable

# Beta 版
openclaw update --channel beta

# 开发版
openclaw update --channel dev

常见问题

npm 安装失败

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

# 清除缓存重试
npm cache clean --force
npm install -g openclaw@latest

Node.js 版本过低

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

# 验证版本
node --version  # 应该显示 v24.x.x

端口被占用

# 查看端口占用
lsof -i :18789

# 更换端口
openclaw gateway --port 18790

权限问题

# Linux/macOS 修复权限
sudo chown -R $(whoami) ~/.openclaw

WSL2 连接问题

如果 WSL2 中启动后 Windows 浏览器无法访问：

# 检查 WSL2 网络
ip addr show eth0

# 使用 WSL2 IP 访问
# http://<WSL2-IP>:18789

配置验证失败

# 验证配置文件
openclaw config validate

# 自动修复
openclaw doctor --fix

卸载

# 卸载 npm 包
npm uninstall -g openclaw

# 删除配置和数据（可选）
rm -rf ~/.openclaw

下一步

快速开始 - 完成首次配置
核心概念 - 理解 OpenClaw 架构
渠道接入 - 连接消息平台

安装前准备​

你需要什么​

平台支持​

Windows 用户建议​

一键安装（推荐）​

macOS / Linux / WSL2​

Windows PowerShell​

安装后验证​

手动安装​

使用 npm​

使用 pnpm​

安装后验证​

常见安装问题​

sharp 构建错误​

openclaw 命令找不到​

详细安装步骤​

macOS 安装​

使用 Homebrew​

验证安装​

Linux 安装​

Ubuntu/Debian​

CentOS/RHEL/Fedora​

Windows 安装（WSL2）​

安装 WSL2​

在 WSL2 中安装 OpenClaw​

访问 Windows 文件​

Docker 部署​

使用 Docker Compose​

使用 Docker 命令​

Docker 注意事项​

配置文件​

配置文件位置​

配置文件格式​

配置拆分（$include）​

环境变量​

常用环境变量​

最小配置示例​

配置验证​

启动服务​

前台启动​

后台运行（守护进程）​

手动配置 systemd（Linux）​

验证安装​

检查服务状态​

访问 Control UI​

测试对话​

升级更新​

切换版本通道​

常见问题​

npm 安装失败​

Node.js 版本过低​

端口被占用​

权限问题​

WSL2 连接问题​

配置验证失败​

卸载​

下一步​

安装前准备

你需要什么

平台支持

Windows 用户建议

一键安装（推荐）

macOS / Linux / WSL2

Windows PowerShell

安装后验证

手动安装

使用 npm

使用 pnpm

安装后验证

常见安装问题

sharp 构建错误

openclaw 命令找不到

详细安装步骤

macOS 安装

使用 Homebrew

验证安装

Linux 安装

Ubuntu/Debian

CentOS/RHEL/Fedora

Windows 安装（WSL2）

安装 WSL2

在 WSL2 中安装 OpenClaw

访问 Windows 文件

Docker 部署

使用 Docker Compose

使用 Docker 命令

Docker 注意事项

配置文件

配置文件位置

配置文件格式

配置拆分（$include）

环境变量

常用环境变量

最小配置示例

配置验证

启动服务

前台启动

后台运行（守护进程）

手动配置 systemd（Linux）

验证安装

检查服务状态

访问 Control UI

测试对话

升级更新

切换版本通道

常见问题

npm 安装失败

Node.js 版本过低

端口被占用

权限问题

WSL2 连接问题

配置验证失败

卸载

下一步