零踩坑!OpenClaw 全平台安装教程(新手也能10分钟搞定)

2026年AI圈最火的个人智能体工具，非 OpenClaw 莫属✨

GitHub星标21.5万+，日增星标3800+，能通过聊天软件发指令、自动整理文件、处理邮件、运行脚本、同步日程，堪称效率控的“万能AI助手”。

但很多新手刚上手就栽在了第一步——安装部署。Node.js版本不对、Docker配置报错、路径含中文、权限不足……各种坑让人还没开始就想放弃。

这篇教程专为新手定制，覆盖 Windows、Mac、Linux 全平台，提供3种安装方式（新手首选一键脚本，进阶可选Docker/手动安装），每一步都标注易错点和解决方案，跟着做，10分钟就能成功部署

一、安装前必看：环境准备与检查

在开始安装前，先确认你的设备满足以下条件，避免中途报错，节省时间👇

1.1 系统与硬件要求

1.2 核心依赖：Node.js（必装！）

⚠️ 易错点1：Node.js版本过低是90%安装失败的根源！

OpenClaw 强制要求 Node.js ≥ 22版本，很多用户的系统还停留在16或18版本，必须先升级。

✅ 检查当前Node.js版本（打开终端/命令行，输入以下命令）：

node -v

如果显示 v16.x.x 或 v18.x.x ，必须先升级，推荐用 nvm 管理Node版本（更灵活，避免后续冲突）。

📌 不同系统升级/安装方法：

• Windows用户：下载安装 nvm-windows（下载地址），安装完成后，在PowerShell输入：nvm install 22nvm use 22

• macOS/Linux用户：在终端输入以下命令，安装nvm并升级Node.js：curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bashsource ~/.bashrcnvm install 22nvm use 22

✅ 验证安装：输入 node -v 显示 v22.x.x ，输入 npm -v 显示 10.x.x 及以上，即为成功。

1.3 其他可选依赖

如果需要使用OpenClaw的视频处理、代码仓库相关功能，可额外安装：

• Git：用于手动克隆源码（下文手动安装方式需用到）

• Python 3.9+ + FFmpeg：用于视频帧提取等特殊技能

二、3种安装方式（按需选择，新手首选第一种）

方式一：一键脚本安装（新手首选，10分钟搞定）

这是最简单、最推荐的安装方式，自动检测系统环境、安装全量依赖，跳过所有繁琐配置，全平台通用。

步骤1：打开对应终端（重点！权限要够）

• Windows用户：必须用PowerShell（管理员身份）！右键点击PowerShell图标，选择“以管理员身份运行”（否则权限不足，安装必失败）。

• macOS/Linux用户：直接打开终端即可（无需管理员权限，脚本会自动处理）。

步骤2：执行一键安装脚本

• macOS/Linux用户：在终端输入以下命令，回车等待即可：curl -fsSL https://openclaw.ai/install.sh | bash

• Windows用户（PowerShell管理员）：输入以下命令，回车等待：iwr -useb https://openclaw.ai/install.ps1 | iex

⚠️ 易错点2：安装过程中不要关闭终端，不要中断网络，等待脚本自动完成（约3-5分钟，取决于网络速度）。

步骤3：验证安装是否成功

安装完成后，在终端输入以下命令：

openclaw --version

如果显示版本号（如 openclaw v2.1.0 ），说明安装成功！

步骤4：初始化配置（关键一步）

输入以下命令，启动配置向导，按提示一步步操作即可：

openclaw init

配置要点（新手可直接按默认，后续可修改）：

• 选择模型提供方：OpenAI、Gemini、Claude、国内大模型等（按需选择）。

• 输入API Key：从对应模型平台获取（⚠️ 易错点3：API Key不要泄露，建议保存在环境变量中）。

• 选择连接渠道：微信、钉钉、飞书等（可选，后续可添加）。

• 设置数据存储路径：建议使用默认路径，避免中文路径。

步骤5：启动OpenClaw

输入以下命令，启动服务：

openclaw start

如果想后台运行（不占用终端），输入：

openclaw start --daemon

服务启动后，打开浏览器，访问 http://localhost:3000 ，即可看到OpenClaw的Web管理界面，安装完成！

方式二：Docker部署（进阶用户首选，环境隔离无残留）

适合有一定终端基础、想实现环境隔离（不污染本地依赖）、需要服务器部署的用户，优势是便于迁移、卸载便捷。

步骤1：安装Docker

• Windows用户：先安装WSL2（输入wsl --install ，重启电脑），再安装Docker Desktop（下载地址）。

• macOS用户：在终端输入 brew install --cask docker ，等待安装完成。

• Linux用户（Ubuntu/Debian）：输入 curl -fsSL https://get.docker.com | bash ，安装完成后启动Docker服务：sudo systemctl start dockersudo systemctl enable docker

⚠️ 易错点4：Windows用户注意，所有文件路径不能包含中文或空格（如 D:\openclaw 可行，D:\我的文档\openclaw 不可行）。

步骤2：创建Docker配置文件

1. 创建项目目录（终端输入）：mkdir -p ~/openclaw && cd ~/openclaw

2. 创建 docker-compose.yml 文件，复制以下内容粘贴（可直接用终端命令创建）：version: '3.8' services:   openclaw:     image: openclaw/openclaw:latest  container_name: openclaw     ports:       - "3000:3000"     volumes:       - ./data:/app/data       - ./config:/app/config    environment:       - NODE_ENV=production       - OPENAI_API_KEY=${OPENAI_API_KEY}       - MODEL_PROVIDER=openai       - MODEL_NAME=gpt-4     restart: unless-stopped

3. 创建 .env 文件（存储API Key，避免泄露）：echo "OPENAI_API_KEY=your-api-key-here" > .env（将 your-api-key-here 替换为你的实际API Key）。

步骤3：启动Docker容器

在终端输入以下命令，拉取镜像并启动容器：

docker-compose up -d

✅ 验证启动状态：docker ps（显示 openclaw 容器正在运行即为成功）docker-compose logs -f（查看运行日志，排查报错）

步骤4：访问服务

打开浏览器，访问 http://localhost:3000 ，即可进入OpenClaw Web管理界面，Docker部署完成！

方式三：手动安装（适合开发者，可深度定制）

适合有终端和代码基础、想深度定制OpenClaw功能、进行二次开发的用户，步骤稍繁琐，但灵活性最高。

步骤1：安装依赖（已安装Node.js和Git）

先确认已安装Git（Windows用户可从Git官网 下载，安装时勾选“Add to PATH”）。

配置国内npm镜像（加速依赖下载）：npm config set registry https://registry.npmmirror.com

步骤2：克隆官方仓库

在终端输入以下命令，克隆源码到本地：git clone https://github.com/openclaw/openclaw.git

进入项目目录：cd openclaw

步骤3：安装依赖并编译

输入以下命令，安装项目依赖并编译：pnpm installpnpm ui:buildpnpm build

⚠️ 若没有pnpm，先安装：npm install -g pnpm

步骤4：初始化与启动

1. 执行初始化配置：openclaw onboard --install-daemon

2. 启动服务（指定端口，可选）：node openclaw.mjs gateway --port 18789 --verbose

启动后，访问 http://localhost:18789 ，即可进入Web控制台，手动安装完成！

三、高频报错+解决方案（避坑必看）

整理了新手安装时最常遇到的4个报错，对应解决方案直接用，不用再查资料👇

1. 报错：command not found（命令找不到）

原因：npm全局bin目录未添加至系统PATH，终端无法识别openclaw命令。

解决方案：将npm全局目录添加到系统环境变量，重启终端即可（具体路径可百度“npm全局目录设置”，对应自己的系统操作）。

2. 报错：sharp安装失败

原因：依赖包sharp安装时缺少环境依赖。

解决方案：执行命令 SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest ，重新安装即可。

3. 服务无法访问（localhost:3000打不开）

原因：端口被占用、防火墙拦截，或服务未启动成功。

解决方案：① 检查服务是否启动（openclaw status），未启动则执行openclaw start；② 关闭防火墙，或放行3000端口；③ 更换端口启动（如 openclaw start --port 3001）。

4. AI功能不可用（提示API Key错误）

原因：API Key输入错误、过期，或模型提供方选择错误。

解决方案：① 重新获取API Key，确保输入正确；② 检查模型提供方是否与API Key匹配（如用OpenAI的API Key，需选择OpenAI作为模型提供方）；③ 检查API Key额度是否充足。

四、实用运维指令（后续常用）

收藏这部分，后续操作不用再翻教程：

• 检查系统环境是否达标：openclaw doctor

• 查看服务健康状态：openclaw health

• 更新OpenClaw至最新版本：npm install -g openclaw@latest

• 停止OpenClaw服务：openclaw stop

• 卸载OpenClaw：openclaw uninstall

最后总结

✅ 新手首选「一键脚本安装」，零配置、省时间，10分钟就能上手；

✅ 进阶用户选「Docker部署」，环境隔离，适合服务器长期运行；

✅ 开发者选「手动安装」，可深度定制，适配二次开发需求。

按照教程操作，基本能避开90%的安装坑。欢迎评论区留言讨论。

安装完成后，就可以解锁OpenClaw的全部功能，让AI帮你处理繁琐工作，提升效率啦！