OpenClaw 完整安装教程

📖 目录

1. OpenClaw 简介
2. 系统要求与准备工作
3. 安装方式选择
4. Windows 系统安装教程
5. macOS 系统安装教程
6. Linux 系统安装教程
7. 初始配置与向导
8. 验证安装
9. 常见问题解决
10. 卸载与更新

OpenClaw 简介

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

核心特性

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

系统要求与准备工作

最低配置要求

检查 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 支持四种主流安装方式，请根据你的需求选择：

快速选型建议

• 个人/本地试用 → 选 一键脚本
• 已有 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

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

1. 选择 AI 供应商

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

2. 添加 API Key

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

3. 连接聊天平台

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

4. 发条测试消息

• 通过已连接的聊天软件给 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 月