# OpenClaw 安装教程

OpenClaw 是一个强大的 AI 助手框架，支持多平台消息集成、浏览器自动化、文件操作等功能。本教程将带你从零开始完成安装和配置。

# 系统要求

  • Node.js 22+（安装脚本会自动检测并安装）
  • 操作系统：macOS、Linux 或 Windows（推荐 WSL2）
  • pnpm：仅当从源码构建时需要

提示

Windows 用户强烈建议使用 WSL2 (opens new window) 运行 OpenClaw

# 快速安装（推荐）

# 方法一：安装脚本

这是最简单的安装方式，会自动处理 Node.js 检测和安装。

# macOS / Linux / WSL2

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

# Windows (PowerShell)

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

安装脚本会自动：

  • ✅ 检测并安装 Node.js
  • ✅ 安装 OpenClaw CLI
  • ✅ 启动配置向导

# 跳过配置向导

如果只想安装 CLI，稍后手动配置：

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

# Windows (PowerShell)
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

# 其他安装方法

# 方法二：npm 安装

如果已安装 Node.js 22+：

npm install -g openclaw@latest
openclaw onboard --install-daemon

注意

如果遇到 sharp 构建错误（macOS 常见），使用以下命令：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

# 方法三：pnpm 安装

pnpm add -g openclaw@latest
pnpm approve-builds -g  # 批准构建脚本
openclaw onboard --install-daemon

pnpm 说明

pnpm 需要明确批准有构建脚本的包。首次安装后会显示 "Ignored build scripts" 警告，运行 pnpm approve-builds -g 并选择列出的包即可。

# 方法四：从源码安装

适合贡献者或需要本地开发的用户：

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

# 2. 安装依赖并构建
pnpm install
pnpm ui:build
pnpm build

# 3. 全局链接 CLI
pnpm link --global

# 4. 运行配置向导
openclaw onboard --install-daemon

# 容器化部署

# Docker 安装

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

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v openclaw-data:/root/.openclaw \
  openclaw/openclaw:latest

# Podman 安装

# 首次运行设置脚本
./setup-podman.sh

# 启动脚本
./run-podman.sh

# 安装后验证

# 1. 检查 Gateway 状态

openclaw gateway status

# 2. 运行诊断

openclaw doctor  # 检查配置问题

# 3. 打开控制面板

openclaw dashboard
# 或直接访问 http://127.0.0.1:18789/

# 4. 发送测试消息

openclaw message send \
  --target +15555550123 \
  --message "Hello from OpenClaw"

# 常用命令

# Gateway 管理

# 查看状态
openclaw gateway status

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 前台运行（调试用）
openclaw gateway --port 18789

# 配置管理

# 运行配置向导
openclaw onboard

# 查看帮助
openclaw help

# 故障排除

# 问题：openclaw 命令找不到

诊断步骤：

node -v
npm -v
npm prefix -g
echo "$PATH"

解决方案：

如果 $(npm prefix -g)/bin 不在 $PATH 中，添加到 shell 配置文件：

# ~/.zshrc 或 ~/.bashrc
export PATH="$(npm prefix -g)/bin:$PATH"

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

# 问题：Node.js 版本过低

OpenClaw 需要 Node.js 22+。使用安装脚本会自动安装，或手动升级：

# 使用 nvm
nvm install 22
nvm use 22
nvm alias default 22

# 或使用官方安装包
# https://nodejs.org/

# 问题：权限错误

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

# 环境变量配置

如需自定义运行时路径：

变量名 说明
OPENCLAW_HOME 设置主目录路径
OPENCLAW_STATE_DIR 覆盖状态目录位置
OPENCLAW_CONFIG_PATH 覆盖配置文件路径

示例：

export OPENCLAW_HOME=/custom/path
export OPENCLAW_STATE_DIR=/custom/state

# 后续步骤

安装完成后，你可以：

下一步

安全提示

  • 生产环境避免使用第三方 "一键安装" 镜像
  • 建议使用干净的 Ubuntu LTS 基础镜像
  • 定期运行 openclaw doctor 检查配置