一、安装前准备

1.1 系统环境要求

1.2 必备依赖

OpenClaw 基于 Node.js 构建，必须先安装以下核心依赖：

（1）Node.js

版本要求：Node.js 20.x LTS 或 22.x 最新版（不支持 18.x 及以下版本）

验证方式（安装后执行）：

# Windows/macOS/Linux 通用
node -v  # 输出示例：v22.2.0
npm -v   # 输出示例：10.5.0

（2）Git

用途：拉取插件依赖、克隆开源仓库

验证方式：

git --version  # 输出示例：git version 2.43.0

二、全平台安装步骤

2.1 步骤1：安装基础依赖

Windows 系统

1. 下载 Node.js：访问 Node.js 官网，选择「LTS 版」或「Current 22.x 版」的 Windows 64位安装包；

2. 安装 Node.js：

• 运行安装包，勾选「Add to PATH」（默认已勾选）；

• 勾选「Automatically install the necessary tools」（自动安装 Python/Git 等依赖）；

• 点击「Next」完成安装，重启终端使环境变量生效；

3. 验证安装（以管理员身份打开 PowerShell）：

node -v
npm -v
git --version

macOS 系统

1. 安装 Homebrew（若已安装可跳过）：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装 Node.js 和 Git：

brew install node@22 git
# Intel 芯片配置环境变量
echo 'export PATH="/usr/local/opt/node@22/bin:$PATH"' >> ~/.zshrc
# M1/M2/M3 芯片配置环境变量
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
# 生效配置
source ~/.zshrc

3. 验证安装：

node -v
npm -v
git --version

Linux 系统（以 Ubuntu 为例）

1. 安装 Node.js 22.x：

# 添加 NodeSource 源
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装 Node.js 和 Git
sudo apt update && sudo apt install -y nodejs git

2. 验证安装：

node -v
npm -v
git --version

2.2 步骤2：安装 OpenClaw 核心包

推荐方式：使用官方一键安装脚本，自动处理环境兼容问题。

方式1：官方一键安装（推荐）

# Windows PowerShell（管理员身份）
iwr -useb https://openclaw.cc/install.ps1 | iex

# macOS/Linux
curl -fsSL https://openclaw.cc/install.sh | sh

方式2：手动 npm 安装（备用）

# 全局安装 OpenClaw
npm install -g openclaw@latest

# 验证安装
openclaw -v  # 输出示例：OpenClaw 2026.3.7 (42a1394)

2.3 步骤3：初始化 OpenClaw 配置

安装完成后，执行初始化命令生成默认配置文件：

openclaw init

执行后会在用户目录生成 .openclaw 核心配置目录：

• Windows：C:\Users\<你的用户名>\.openclaw

• macOS/Linux：~/.openclaw

2.4 步骤4：验证核心功能

执行以下命令检查 OpenClaw 基础功能是否正常：

# 查看版本
openclaw -v

# 查看帮助
openclaw help

# 检查系统环境（关键）
openclaw doctor

正常输出：openclaw doctor 会显示「All checks passed!」，无红色错误提示。

三、插件安装（以飞书插件为例）

3.1 下载插件包

从 OpenClaw 插件市场下载对应插件包（如 openclaw-feishu-2026.3.7.tgz）。

3.2 安装插件

# 全局安装插件（推荐）
openclaw plugins install <插件包路径>/openclaw-feishu-2026.3.7.tgz

# Windows 示例
openclaw plugins install C:\Users\admin\Downloads\openclaw-feishu-2026.3.7.tgz

# macOS/Linux 示例
openclaw plugins install ~/Downloads/openclaw-feishu-2026.3.7.tgz

3.3 安装插件依赖

部分插件需手动安装第三方依赖，未安装会导致插件加载失败！

以飞书插件为例，需安装 @larksuiteoapi/node-sdk：

# 进入插件安装目录（Windows 示例）
cd C:\Users\\AppData\Roaming\npm\node_modules\openclaw\extensions\feishu

# 国内用户先切换镜像（避免安装失败）
npm config set registry https://registry.npmmirror.com
# 安装依赖
npm install @larksuiteoapi/node-sdk --save

3.4 配置插件信任（安全要求）

编辑 OpenClaw 配置文件，显式信任插件，避免安全警告：

# Windows 打开配置文件
notepad C:\Users\\.openclaw\config.json

# macOS/Linux 打开配置文件
vim ~/.openclaw/config.json

写入以下配置（替换实际路径）：

{
  "plugins": {
    "allow": ["feishu"],
    "scan": false,
    "entries": {
      "feishu": "C:\\Users\\admin\\AppData\\Roaming\\npm\\node_modules\\openclaw\\extensions\\feishu\\index.ts"
    }
  },
  "logLevel": "info"
}

注意：路径中的反斜杠需用 \\ 转义，确保和插件实际路径一致。

3.5 验证插件安装

openclaw plugins list

正常输出：
           🦞 Installed plugins:
             - feishu (2026.3.7) [trusted]

四、常见安装问题解决

4.1 npm error code 128

原因：Git SSH 访问权限问题，无法拉取依赖。

解决方案：强制 Git 使用 HTTPS 协议：

git config --global url."https://github.com/".insteadOf ssh://git@github.com/

4.2 找不到模块（如 @larksuiteoapi/node-sdk）

原因：插件依赖未安装或安装失败。

解决方案：

1. 切换国内 npm 镜像：npm config set registry https://registry.npmmirror.com

2. 强制安装依赖：npm install <模块名> --save --force

3. 手动下载依赖包放入插件 node_modules 目录

4.3 重复插件 ID 警告

原因：多目录扫描到同名插件，导致冲突。

解决方案：

1. 删除重复插件目录：rm -Recurse -Force <重复插件路径>（Windows）或 rm -rf <重复插件路径>（macOS/Linux）

2. 配置 scan: false 禁用自动扫描（见 3.4 节）

4.4 Windows 权限不足

解决方案：以「管理员身份」运行终端/命令提示符。

五、卸载 OpenClaw

5.1 卸载核心包

npm uninstall -g openclaw

5.2 删除配置文件

# Windows
rm -Recurse -Force C:\Users\\.openclaw

# macOS/Linux
rm -rf ~/.openclaw