OpenClaw 完整安装教程

📖 目录

OpenClaw 简介
系统要求与准备工作
安装方式选择
Windows 系统安装教程
macOS 系统安装教程
Linux 系统安装教程
初始配置与向导
验证安装
常见问题解决
卸载与更新

OpenClaw 简介

OpenClaw（昵称"小龙虾"）是一款可本地部署、支持多平台接入的 AI 助手工具。它的核心突破在于：它不再是只能聊天的 AI，而是真正能"动手干活"的数字员工。

核心特性

多平台聚合：像网关一样连接你的 AI 模型（Claude、GPT-4、DeepSeek 等）和你常用的通讯软件（WhatsApp、Telegram、Discord、Slack 等）
持久化记忆：不会像 ChatGPT 那样关闭窗口就"失忆"，对话上下文和重要信息以 Markdown 格式存储在本地
主动性：支持 Cron 定时任务，可以主动给你发消息（例如：每天早上 8 点汇报服务器状态）
本地运行：代码运行在你自己的机器上，数据隐私掌握在自己手中
强大的技能系统：通过编写脚本，它可以执行终端命令、读写文件、控制浏览器

系统要求与准备工作

最低配置要求

项目	最低要求	推荐配置
系统	Windows 10+ / macOS 12+ / Ubuntu 20.04+	Windows 11 / macOS 14+ / Ubuntu 22.04+
运行环境	Node.js 22+	Node.js 22.x LTS 稳定版
内存	2GB	4GB 及以上
磁盘空间	500MB	1GB 及以上
网络	调用 AI API 需联网，本地模型可离线	稳定宽带 / WiFi

检查 Node.js 版本

在终端/命令提示符中执行：

node --version

如果版本低于 v22，需要先升级 Node.js。推荐使用 nvm（Node Version Manager）管理版本：

Windows 用户：

# 下载并安装 nvm-windows# https://github.com/coreybutler/nvm-windows/releasesnvm install 22nvm use 22

macOS/Linux 用户：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bashsource ~/.bashrcnvm install 22nvm use 22

安装方式选择

OpenClaw 支持四种主流安装方式，请根据你的需求选择：

安装方式	技术门槛	耗时	适用人群/场景	优点	缺点
一键脚本	低	10 分钟	新手、个人试用、本地办公自动化	全自动、零配置、快速上手	本地运行、外网访问需额外配置
npm 手动	中	5 分钟	开发者、已有 Node 环境、服务器批量部署	灵活、版本可控、批量部署	需自行安装 Node、处理依赖
源码编译	高	30 分钟+	二次开发、定制功能、本地调试	完全可控、可改源码	复杂、易出问题、维护成本高
Docker 部署	中	15 分钟	企业、7×24 运行、公网访问	环境隔离、易于迁移	产生云服务器费用

快速选型建议

个人/本地试用 → 选 一键脚本
已有 Node 环境、服务器批量部署 → 选 npm 手动
二次开发、定制功能 → 选 源码编译
企业生产、7×24、公网访问 → 选 Docker 部署

Windows 系统安装教程

方式一：使用官方一键脚本（推荐新手）

这是最简单快速的安装方式，适合大多数用户。

步骤 1：以管理员身份运行 PowerShell

按下 Win + X 键，选择 "Windows PowerShell (管理员)" 或 "终端 (管理员)"

如果出现用户账户控制（UAC）提示，点击 "是"

步骤 2：设置执行策略

首次运行 PowerShell 脚本需要修改执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

出现提示时输入 Y 并回车确认。

步骤 3：执行安装脚本

复制以下命令并粘贴到 PowerShell 中，按回车执行：

官方命令：

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

国内用户加速版（如果官方脚本速度慢）：

iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

步骤 4：等待安装完成

安装过程会自动完成以下操作：

✓ 检测并安装 Node.js（如果未安装）
✓ 安装 OpenClaw 核心程序
✓ 配置环境变量
✓ 安装必要的依赖

整个过程通常需要 3-8 分钟，请耐心等待。

步骤 5：验证安装

安装完成后，运行以下命令验证：

openclaw --version

如果输出了版本号（如 v2026.3.2），说明安装成功！

openclaw --help

查看帮助信息，了解可用命令。

方式二：WSL2 部署（官方推荐，更稳定）

Windows 官方推荐通过 WSL2 使用 OpenClaw，网络访问和文件系统性能更好。

步骤 1：安装 WSL2

在 PowerShell（管理员）中执行：

wsl --install

重启电脑，按照提示完成 Ubuntu 系统安装。

步骤 2：在 WSL2 中安装 OpenClaw

打开 Ubuntu 终端，执行 macOS/Linux 通用一键脚本：

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

方式三：手动安装（适合高级用户）

如果你已经熟悉 Node.js 环境，可以选择手动安装。

步骤 1：安装 Node.js

访问 Node.js 官网下载 LTS 版本（推荐 v22.x）

运行安装程序，按提示完成安装。

验证安装：

node -vnpm -v

步骤 2：安装 Git（可选但推荐）

访问 Git 官网下载 Windows 版本安装程序。

运行安装程序，使用默认设置即可。

步骤 3：全局安装 OpenClaw

打开 PowerShell（管理员权限），执行：

npm install -g openclaw

国内用户加速安装：

# 设置 npm 镜像源（使用淘宝镜像）npm config set registry https://registry.npmmirror.com# 安装 OpenClawnpm install -g openclaw# 恢复官方源（可选）npm config set registry https://registry.npmjs.org

步骤 4：验证安装

openclaw --version

macOS 系统安装教程

方式一：使用官方一键脚本（推荐）

步骤 1：打开终端

按下 Command + 空格 打开 Spotlight 搜索

输入"终端"或"Terminal"，按回车打开终端

步骤 2：执行安装脚本

复制以下命令并粘贴到终端中，按回车执行：

官方命令：

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

国内用户加速版：

curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

macOS 系统执行时，会提示输入电脑开机密码（输入时不显示字符，属于正常现象），输入完成后回车即可。

步骤 3：等待安装完成

脚本会自动检测系统环境并安装所需组件，包括：

✓ Homebrew（如果未安装）
✓ Node.js
✓ OpenClaw 核心程序

步骤 4：验证安装

openclaw --version

方式二：使用 Homebrew 手动安装

步骤 1：安装 Homebrew（如果未安装）

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

安装完成后，根据提示将 Homebrew 添加到 PATH：

echo 'eval"$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofileeval"$(/opt/homebrew/bin/brew shellenv)"

步骤 2：安装 Node.js

brew install node

验证安装：

node -vnpm -v

步骤 3：安装 Git（如果未安装）

brew install git

步骤 4：全局安装 OpenClaw

npm install -g openclaw

国内用户加速安装：

# 设置 npm 镜像源npm config set registry https://registry.npmmirror.com# 安装 OpenClawnpm install -g openclaw# 恢复官方源（可选）npm config set registry https://registry.npmjs.org

步骤 5：验证安装

openclaw --version

方式三：使用国内版 OpenClaw-cn

国内用户推荐使用 OpenClaw-cn，针对国内网络环境优化：

npm install -g openclaw-cn@latest

验证安装：

openclaw-cn --version

Linux 系统安装教程

方式一：使用官方一键脚本（推荐）

步骤 1：打开终端

根据你的 Linux 发行版，使用快捷键打开终端：

Ubuntu/Debian：Ctrl + Alt + T
Fedora：Ctrl + Alt + T
其他发行版：在应用菜单中搜索"终端"

步骤 2：更新系统包管理器

Ubuntu/Debian：

sudo apt updatesudo apt upgrade -y

Fedora：

sudo dnf update -y

步骤 3：安装必要的依赖

Ubuntu/Debian：

sudo apt install -y curl git build-essential

Fedora：

sudo dnf install -y curl git gcc-c++ make

Arch Linux：

sudo pacman -S --needed curl git base-devel

步骤 4：执行安装脚本

官方命令：

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

国内用户加速版：

curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

步骤 5：等待安装完成

脚本会自动安装：

✓ Node.js（通过 nvm 或包管理器）
✓ OpenClaw 核心程序
✓ 必要的系统依赖

步骤 6：验证安装

openclaw --version

方式二：使用包管理器手动安装

步骤 1：安装 Node.js

Ubuntu/Debian（使用 NodeSource）：

# 添加 NodeSource 仓库（以 Node.js 22.x 为例）curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -# 安装 Node.jssudo apt install -y nodejs# 验证安装node -vnpm -v

Fedora：

sudo dnf install -y nodejs npm

Arch Linux：

sudo pacman -S nodejs npm

步骤 2：安装 Git

Ubuntu/Debian：

sudo apt install -y git

Fedora：

sudo dnf install -y git

Arch Linux：

sudo pacman -S git

步骤 3：全局安装 OpenClaw

npm install -g openclaw

国内用户加速安装：

# 设置 npm 镜像源（使用淘宝镜像）npm config set registry https://registry.npmmirror.com# 安装 OpenClawnpm install -g openclaw# 恢复官方源（可选）npm config set registry https://registry.npmjs.org

步骤 4：配置环境变量（如果需要）

如果执行 openclaw --version 提示"command not found"，需要将 npm 全局目录添加到 PATH：

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc

步骤 5：验证安装

openclaw --version

方式三：使用 nvm 安装 Node.js（推荐开发者）

步骤 1：安装 nvm（Node Version Manager）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

步骤 2：重新加载配置文件

source ~/.bashrc

步骤 3：安装最新 LTS 版本的 Node.js

nvm install --ltsnvm use --lts

步骤 4：全局安装 OpenClaw

npm install -g openclaw

步骤 5：验证安装

openclaw --version

初始配置与向导

启动配置向导

安装完成后，执行以下命令启动交互式配置向导：

openclaw onboard --install-daemon

这个向导会引导你完成以下步骤：

选择 AI 供应商

Anthropic (Claude)
OpenAI (GPT)
Google (Gemini)
或通过 Ollama 跑本地模型
随时可以在配置里切换

添加 API Key

从供应商后台粘贴你的 API Key
Key 存在本地 .env 文件里——除了 AI 供应商，不会发到任何地方

连接聊天平台

接入 WhatsApp（扫二维码）
Telegram（粘贴 @BotFather 的 Bot Token）
Discord（粘贴 Bot Token）
或其他支持的平台

发条测试消息

通过已连接的聊天软件给 OpenClaw 发条消息
如果它回复了，就说明一切就绪
试试发："你能做什么？"

配置文件位置

所有配置存储在 ~/.openclaw/.env，你可以直接编辑这个文件来：

切换供应商
添加 API Key
调整设置

完整参考见 docs.openclaw.ai/configuration

验证安装

1. 检查版本

openclaw --version

应该输出已安装的版本号（如 v2026.3.2）

2. 健康检查

openclaw doctor

对你的环境做一次诊断检查：

Node.js 版本
依赖
配置文件
网络连接

3. 检查服务状态

openclaw status

查看综合状态，确认 Gateway 是否正在运行。

4. 打开 Web 控制台

openclaw dashboard

默认访问地址：http://127.0.0.1:18789/

常见问题解决

1. 权限不足报错

症状：安装时提示权限不足

解决方案：

Windows：必须以管理员身份运行 PowerShell（右键 → 以管理员身份运行）
macOS/Linux：在安装命令前加 sudo，或者用 nvm 等 Node 版本管理器免 root 安装

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

2. Node.js 版本太旧

症状：提示 Node.js 版本不满足要求

解决方案：

OpenClaw 需要 Node.js 22+。

检查版本：

node --version

用 nvm（macOS/Linux）或 nvm-windows 安装最新 LTS 版本：

# macOS/Linuxnvm install --ltsnvm use --lts# Windows (PowerShell)nvm install 22nvm use 22

3. 端口被占用

症状：提示端口 3000 或 18789 被占用

解决方案：

OpenClaw 的 Web UI 默认用 3000/18789 端口。如果被其他应用占了：

方法 1：在 .env 文件里设置自定义端口

# 编辑配置文件openclaw config edit

添加或修改：

PORT=3001

方法 2：关闭占用端口的程序

# 查找占用端口的进程lsof -i :3000  # macOS/Linuxnetstat -ano | findstr :3000  # Windows# 杀掉进程（将 <PID> 替换为实际进程号）kill -9 <PID>  # macOS/Linuxtaskkill /PID <PID> /F  # Windows

4. 网络超时（国内用户）

症状：下载缓慢或超时

解决方案：

方法 1：配置 npm 镜像源

npm config set registry https://registry.npmmirror.com

方法 2：使用国内镜像脚本

# Windowsiwr -useb https://open-claw.org.cn/install-cn.ps1 | iex# macOS/Linuxcurl -fsSL https://open-claw.org.cn/install-cn.sh | bash

5. WhatsApp 二维码不显示

症状：二维码显示不出来

解决方案：

换个终端模拟器试试
无头服务器上可以用 WebChat 界面扫码

6. 安装 OpenClaw 报错

症状：npm verbose reify failed optional dependency /usr/lib/node_modules/openclaw/node_modules/@discordjs/opus

解决方案：

@discordjs/opus 依赖系统级的音频编解码库（如 libopus）和编译环境。

Ubuntu/Debian 系统（推荐）：

sudo apt update && sudo apt install -y libopus-dev pkg-config build-essential

7. `openclaw: command not found`

症状：执行 openclaw 命令时提示找不到命令

解决方案：

可能原因：安装路径未加入系统 PATH

# 重新加载环境变量source ~/.bashrc  # Linux/macOS# 或手动添加路径（macOS/Linux）export PATH="$PATH:/usr/local/bin"# Windows 需要在系统环境变量中添加 npm 全局路径# 通常路径为：C:\Users\<用户名>\AppData\Roaming\npm

卸载与更新

更新版本

全系统通用

openclaw update

npm 手动更新

npm update -g openclaw@latest# 或 pnpm 更新pnpm update -g openclaw@latest

Docker 更新

docker pull openclaw/openclaw:latest && docker restart openclaw

在 github.com/openclaw/openclaw/releases 查看更新日志，了解每个版本的新内容。

卸载程序

npm uninstall -g openclaw

清理配置

rm -rf ~/.openclaw

注意：这会删除所有配置、记忆和技能设置，请谨慎操作。

Docker 容器化部署（进阶）

适合服务器 / 隔离环境使用。

前置要求

需提前安装 Docker Engine 20+ 或 Docker Desktop。

拉取镜像并启动容器

# 拉取最新镜像docker pull openclaw/openclaw:latest# 启动容器（配置端口映射与数据持久化）docker run -d \  --name openclaw \  -p 3000:3000 \  -v ~/.openclaw:/root/.openclaw \  --env-file ~/.openclaw/.env \  openclaw/openclaw:latest

使用 Docker Compose

创建 docker-compose.yml 文件：

version: '3.8'services:openclaw:image: openclaw/openclaw:latestports:- "3000:3000"volumes:- ~/.openclaw:/root/.openclawenv_file:- ~/.openclaw/.envrestart: unless-stopped

启动服务：

docker-compose up -d

验证状态

docker ps

显示 openclaw 容器状态为 Up 即部署成功。

源码编译安装（开发者专用）

适合想改代码、深度定制功能的用户。

前置要求

需提前安装 Git、pnpm 工具。

克隆源码并编译

# 克隆官方源码git clone https://github.com/openclaw/openclaw.git# 进入目录安装依赖并编译cd openclaw && \  pnpm install && \  pnpm run build# 启动配置向导pnpm run openclaw onboard

开发循环

自动重新加载 TypeScript 更改：

pnpm gateway:watch

附录：常用命令速查

安装与版本

npm install -g openclaw          # 安装openclaw --version               # 查看版本openclaw update                  # 更新到最新版

初始化与启动

openclaw onboard --install-daemon  # 交互式配置向导（推荐新手）openclaw init                     # 在当前目录初始化项目openclaw start                    # 启动 gatewayopenclaw stop                     # 停止 gatewayopenclaw restart                  # 重启 gatewayopenclaw status                   # 查看运行状态

调试与日志

openclaw logs                    # 查看日志openclaw logs --tail 100         # 查看最近 100 行日志openclaw doctor                  # 健康检查与自动修复openclaw doctor --repair          # 尝试自动修复问题

技能管理

openclaw skills list              # 列出已安装技能openclaw skills install           # 安装技能openclaw skills update --all      # 更新所有技能openclaw skills remove            # 删除技能

安全

openclaw security audit           # 安全扫描openclaw skills list --show-permissions  # 查看技能权限

记忆管理

openclaw memory validate          # 验证记忆文件格式openclaw memory flush            # 手动触发记忆刷新

渠道管理

openclaw channels list            # 查看已配置渠道openclaw channels add telegram     # 添加 telegram 渠道openclaw channels add whatsapp    # 添加 whatsapp 渠道

参考资源

官方 GitHub 仓库：github.com/openclaw/openclaw
官方文档中心：docs.openclaw.ai
技能市场：clawhub.ai

结语

OpenClaw 作为开源自托管 AI 助手，部署简单、功能强大，支持多平台联动与自定义模型接入。按照本文步骤，5 分钟即可完成部署，新手也能轻松玩转 AI 自动化！

如需云端部署、插件配置、多模型对接教程，欢迎查阅官方文档或私信讨论。

✅ 收藏本文，部署不迷路；转发分享，帮更多小白快速上手 OpenClaw！

文档最后更新时间：2026 年 3 月

OpenClaw 完整安装教程

📖 目录

OpenClaw 简介

核心特性

系统要求与准备工作

最低配置要求

检查 Node.js 版本

安装方式选择

快速选型建议

Windows 系统安装教程

方式一：使用官方一键脚本（推荐新手）

步骤 1：以管理员身份运行 PowerShell

步骤 2：设置执行策略

步骤 3：执行安装脚本

步骤 4：等待安装完成

步骤 5：验证安装

方式二：WSL2 部署（官方推荐，更稳定）

步骤 1：安装 WSL2

步骤 2：在 WSL2 中安装 OpenClaw

方式三：手动安装（适合高级用户）

步骤 1：安装 Node.js

步骤 2：安装 Git（可选但推荐）

步骤 3：全局安装 OpenClaw

步骤 4：验证安装

macOS 系统安装教程

方式一：使用官方一键脚本（推荐）

步骤 1：打开终端

步骤 2：执行安装脚本

步骤 3：等待安装完成

步骤 4：验证安装

方式二：使用 Homebrew 手动安装

步骤 1：安装 Homebrew（如果未安装）

步骤 2：安装 Node.js

步骤 3：安装 Git（如果未安装）

步骤 4：全局安装 OpenClaw

步骤 5：验证安装

方式三：使用国内版 OpenClaw-cn

Linux 系统安装教程

方式一：使用官方一键脚本（推荐）

步骤 1：打开终端

步骤 2：更新系统包管理器

步骤 3：安装必要的依赖

步骤 4：执行安装脚本

步骤 5：等待安装完成

步骤 6：验证安装

方式二：使用包管理器手动安装

步骤 1：安装 Node.js

步骤 2：安装 Git

步骤 3：全局安装 OpenClaw

步骤 4：配置环境变量（如果需要）

步骤 5：验证安装

方式三：使用 nvm 安装 Node.js（推荐开发者）

步骤 1：安装 nvm（Node Version Manager）

步骤 2：重新加载配置文件

步骤 3：安装最新 LTS 版本的 Node.js

步骤 4：全局安装 OpenClaw

步骤 5：验证安装

初始配置与向导

启动配置向导

配置文件位置

验证安装

1. 检查版本

2. 健康检查

3. 检查服务状态

4. 打开 Web 控制台

常见问题解决

1. 权限不足报错

2. Node.js 版本太旧

3. 端口被占用

4. 网络超时（国内用户）

5. WhatsApp 二维码不显示

6. 安装 OpenClaw 报错

7. openclaw: command not found

卸载与更新

更新版本

全系统通用

npm 手动更新

Docker 更新

卸载程序

清理配置

7. `openclaw: command not found`