OpenClaw 官方完整版安装文档（全平台适配·新手零基础）

适配系统：Windows 10/11、macOS、Linux（Ubuntu/Debian/CentOS）

文档定位：零基础一站式安装、环境配置、故障排查，全程可直接复制执行

简介：OpenClaw 是一款开源轻量化 AI 智能编排、自动化任务处理工具，支持可视化配置、脚本自动化、多场景智能调度，广泛用于个人效率提升、小型项目自动化、AI 辅助开发等场景。本文档提供一键安装、包管理器安装、源码编译三种主流安装方式，覆盖新手快速部署与开发者深度部署需求。

一、环境前置要求（必看）

1.1 硬件要求

  • 内存：≥4GB 可用内存

  • 磁盘：≥5GB 空闲存储空间

  • 网络：安装&首次启动需联网（拉取依赖&初始化资源），部署完成后支持离线运行

1.2 软件依赖（核心必备）

所有系统安装前，必须提前安装 Git + Node.js 20.x 及以上稳定版，低版本会导致安装失败、依赖报错。

Windows 系统前置配置

推荐使用 WSL2 Ubuntu 环境（兼容性最佳，规避原生终端权限、脚本拦截问题），原生 CMD/PowerShell 需放开执行权限。

macOS 系统前置配置

需安装命令行工具，终端执行：xcode-select --install

Linux 系统前置配置

推荐系统：Ubuntu 20.04+、Debian 11+、CentOS 8+

二、全平台依赖安装（统一标准）

2.1 安装 Git

用于拉取源码、版本更新，所有系统通用：

  • Windows/Mac/Linux：前往 Git 官网 下载对应版本，默认下一步安装即可

  • 安装验证：终端输入 git --version，输出版本号即为成功

2.2 安装 Node.js 20+

OpenClaw 核心运行环境，禁止使用 16.x 及以下旧版本

  • 下载地址：Node.js 官网（选择 LTS 长期稳定版）

  • Mac 快速安装：brew install node@20

  • Linux 快速安装：通过 nvm 安装 Node20 稳定版

安装验证：终端执行以下命令，均输出版本号即为环境就绪

node -v
npm -v

2.3 配置国内镜像（关键！解决下载慢/超时）

官方源国内访问极易超时、卡顿，安装前必须切换淘宝镜像源：

# npm 镜像配置
npm config set registry https://registry.npmmirror.com/

# pnpm 镜像配置（推荐，速度更快）
pnpm config set registry https://registry.npmmirror.com/

三、三种安装方式（按需选择）

优先级推荐：新手选 一键安装 > 日常使用选 包管理器安装 > 二次开发选 源码编译安装

方式一：一键脚本安装（推荐新手｜最快5分钟部署）

适配 macOS / Linux / WSL2 Windows，官方封装脚本，自动配置环境、安装依赖、初始化服务

终端直接执行一键安装命令：

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

安装流程说明：

  1. 自动检测系统环境、依赖完整性

  2. 自动下载最新稳定版 OpenClaw

  3. 自动配置全局环境变量

  4. 全程无需手动干预，等待终端提示 Install Success 即可

方式二：包管理器安装（推荐日常使用｜版本可控）

支持 npm / pnpm 全局安装，方便版本升级、卸载、管理

1、npm 安装

# 全局安装最新稳定版
npm install -g openclaw@latest

# 补充安装核心依赖（必执行）
openclaw install

2、pnpm 安装（速度更快、占用更小）

# 全局安装
pnpm install -g openclaw@latest

# 初始化依赖环境
openclaw install

方式三：源码编译安装（推荐开发者｜可二次开发）

适合需要自定义修改源码、参与开源迭代的用户，全程开源透明

# 克隆官方源码仓库
git clone https://github.com/openclaw/openclaw.git

# 进入项目目录
cd openclaw

# 安装项目依赖
pnpm install

# 编译构建项目
pnpm build

# 全局链接本地版本
pnpm link -g

四、安装验证（必做，确认部署成功）

任意终端执行版本查询命令，输出版本号即代表安装完成：

openclaw --version
# 或简写
claw -v

✅ 成功示例：输出 openclaw vx.x.x 稳定版版本号

五、启动与基础使用

5.1 启动服务

# 默认启动服务
openclaw start

# 后台常驻启动（推荐服务器使用）
openclaw start -d

5.2 访问控制台

启动成功后，浏览器打开默认地址：http://localhost:8090，即可进入 OpenClaw 可视化管理后台，开始配置自动化任务、AI 调度等功能。

5.3 常用基础命令

# 查看运行状态
openclaw status

# 停止服务
openclaw stop

# 重启服务
openclaw restart

# 升级最新版本
openclaw upgrade

# 卸载程序
openclaw uninstall

六、Windows 专属适配方案（解决兼容问题）

Windows 原生终端易出现脚本拦截、权限报错，推荐以下配置：

6.1 PowerShell 放行执行权限

以管理员身份打开 PowerShell，执行命令，输入 Y 确认：

set-executionpolicy remotesigned

6.2 最优方案：WSL2 部署

Windows 用户优先使用 WSL2 Ubuntu 子系统，完美兼容所有命令，无权限、脚本报错问题，体验与 Linux 一致。

七、常见报错与故障排查

问题1：下载依赖超时、卡住不动

✅ 解决方案：重新执行本文 2.3 国内镜像配置，切换镜像后重新安装即可

问题2：node 版本过低报错

✅ 解决方案：升级 Node.js 至 20.x 及以上 LTS 稳定版，重启终端重试

问题3：openclaw 命令未找到

✅ 解决方案：重启终端，或配置系统环境变量；源码安装需执行 pnpm link -g 全局链接

问题4：启动端口被占用

✅ 解决方案：修改默认端口，或关闭占用 8090 端口的程序后重启服务

问题5：安全软件拦截安装

✅ 解决方案：临时关闭电脑管家、360 等安全软件，安装完成后重新开启

八、更新与卸载

8.1 版本更新

openclaw upgrade

8.2 完全卸载

# 停止服务
openclaw stop

# 卸载程序
openclaw uninstall

# 全局卸载包
npm uninstall -g openclaw