OpenClaw 安装保姆级教程 | 含原版 + 国产衍生版,附全场景踩坑解决方案

本文所有安装步骤均来自官方文档与厂商公开合规指引，更新至 2026 年 3 月，覆盖 Windows、macOS、Linux、国产操作系统全平台，同时包含新手零门槛国产衍生版一键安装方案，全程可落地，无玄学操作。

一、安装前必看基础说明

（一）最低配置要求

OpenClaw 对硬件要求极低，普通办公电脑即可流畅运行，核心配置门槛如下：

表格

配置项	最低要求	推荐配置
操作系统	Windows 10 22H2+、macOS 12+、Ubuntu 20.04+、统信 UOS / 麒麟 V10	Windows 11、macOS 13+、Ubuntu 22.04 LTS
运行内存	2GB	4GB 及以上
存储空间	1GB 可用空间	10GB 及以上（避免缓存占满）
网络	可正常访问互联网	稳定国内网络，无需特殊环境
核心依赖	Node.js 22.x LTS 及以上版本（原版必需，国产衍生版无需手动安装）	Node.js 22.x LTS 最新版

（二）合规前置提醒

请仅通过官方渠道下载安装包与执行安装脚本，严禁使用非官方破解版、修改版客户端，避免个人信息泄露、财产损失与知识产权侵权风险。
所有产品的安装与使用，需严格遵守《生成式人工智能服务管理暂行办法》、对应平台用户协议及相关法律法规，严禁用于违规违法场景。
原版 OpenClaw 遵循 MIT 开源协议，支持合规二次开发与个人非商用使用，商用请遵守开源协议规范。

二、原版OpenClaw 全平台官方安装教程

原版为开源社区官方发布版本，无生态绑定，自定义程度最高，适合有一定终端操作能力的用户、开发者与深度定制需求人群。

（一）Windows 平台安装教程

Windows 提供两种安装方案，新手优先选择PowerShell 一键脚本，追求稳定性优先选择WSL2 方案（官方推荐）。

方案1：PowerShell 一键脚本安装（3 分钟完成）

右键点击桌面左下角 Windows 开始图标，选择Windows PowerShell (管理员) / 终端 (管理员)，必须以管理员身份运行，否则会出现权限报错。
（可选）解锁脚本执行策略，避免系统拦截：在终端中执行以下命令，输入Y回车确认

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

1.执行官方一键安装命令，国内网络环境可使用国内镜像脚本，避免下载超时

powershell

官方原版脚本iwr -useb https://openclaw.ai/install.ps1 | iex

国内镜像加速脚本（网络不佳优先使用）iwr -useb https://gitee.com/openclaw/install/raw/main/install.ps1 | iex

1.等待脚本自动执行：脚本会自动检测、安装Node.js环境与OpenClaw核心程序，全程无需手动操作，等待进度完成即可。

2.安装验证：脚本执行完成后，在终端输入openclaw -v，回车后显示版本号，即安装成功。

3.初始化配置：执行openclaw onboard，按终端提示填入API Key、配置基础参数，完成后浏览器访问http://localhost:18789即可进入Web管理界面。

Windows 专属高频踩坑点 & 解决方案

表格

报错现象	核心原因	一键解决方案
提示“禁止运行脚本”/“无法加载文件，因为在此系统上禁止运行脚本”	PowerShell 默认执行策略拦截了脚本运行	重新以管理员身份打开终端，执行步骤 2 的解锁命令，确认后重新执行安装脚本
提示“Node.js not found”/“npm: 不是内部或外部命令”	脚本自动安装 Node.js 失败，系统环境变量未配置	手动前往 Node.js 官网下载 22.x LTS 版本，默认路径一路下一步安装，安装完成后重启终端，重新执行安装脚本
提示“EACCES: permission denied” 权限拒绝	非管理员身份运行，或文件夹只读权限	必须以管理员身份运行终端；右键 C 盘用户目录下的.openclaw文件夹，取消“只读” 属性，确认后重试
安装完成后无法访问 18789 端口	端口被占用 / 防火墙拦截	1. 执行 `netstat -ano	findstr "18789"` 找到占用进程 PID，在任务管理器结束进程；2. 关闭 Windows Defender 防火墙 / 第三方杀毒软件，或放行 18789 端口
提示“DLL 文件缺失”/“VC++ 运行库缺失”	系统缺少 C++ 构建工具链	下载安装 Microsoft C++ Build Tools，勾选 “使用 C++ 的桌面开发” 工作负载，安装完成后重启电脑重试

方案2：WSL2 安装方案（官方推荐，稳定性最佳）

1.以管理员身份打开PowerShell，执行WSL安装命令，安装完成后重启电脑

powershell

wsl --install -d Ubuntu-22.04

1.重启后系统会自动完成Ubuntu配置，设置用户名与密码，进入WSL2终端环境。

2.在WSL2终端中执行Linux一键安装脚本，国内网络使用加速镜像

bash

运行

官方脚本curl -fsSL https://openclaw.ai/install.sh | bash

国内加速镜像curl -fsSL https://gitee.com/openclaw/install/raw/main/install.sh | bash

1.安装验证：执行openclaw -v显示版本号即安装成功，执行openclaw onboard完成初始化，浏览器访问http://localhost:18789即可使用。

（二）macOS 平台安装教程（Intel/Apple Silicon 芯片通用）

macOS 提供终端一键脚本和桌面应用安装两种方案，新手优先选择桌面应用方案，无需接触命令行。

方案1：终端一键脚本安装（推荐开发者使用）

打开 macOS 自带的「终端」应用（启动台 - 其他 - 终端）。
执行官方一键安装命令，国内网络可使用加速镜像

bash

运行

官方原版脚本curl -fsSL https://openclaw.ai/install.sh | bash

国内加速镜像脚本curl -fsSL https://gitee.com/openclaw/install/raw/main/install.sh | bash

1.若提示权限不足，在命令前添加sudo，输入电脑开机密码回车即可

bash

运行

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

1.脚本自动完成环境检测、Node.js安装与OpenClaw部署，等待完成即可。

2.安装验证：终端输入openclaw -v显示版本号即成功，执行openclaw onboard完成初始化，浏览器访问http://localhost:18789进入管理界面。

方案2：桌面应用安装（新手零门槛首选）

打开 OpenClaw 官方网站，下载 macOS 对应版本的.dmg安装包。
双击打开下载的 DMG 文件，将左侧的 OpenClaw 图标拖拽到右侧「应用程序」文件夹，完成安装。
打开启动台，点击 OpenClaw 图标启动应用，首次启动会弹出权限申请，按提示授予辅助功能权限、通知权限（核心必需权限，否则无法执行自动化操作）。
验证安装：应用启动后，macOS 菜单栏出现 OpenClaw 图标，状态显示「运行中」，即安装成功，可直接通过图形化界面完成配置与使用。

macOS 专属高频踩坑点 & 解决方案

表格

报错现象	核心原因	一键解决方案
提示“无法打开，因为苹果无法检查其是否包含恶意软件”	系统安全策略拦截第三方应用	打开「系统设置 - 隐私与安全性」，下滑找到 “已阻止使用” 的提示，点击「仍要打开」，输入开机密码确认后，重新启动应用
提示“xcode-select: error”	缺少 Xcode 命令行工具，依赖编译失败	终端执行xcode-select --install，按提示完成安装，重启终端后重试
终端执行命令提示“permission denied”	权限不足	命令前添加sudo，输入开机密码执行；或执行sudo chown -R $(whoami) /usr/local/lib/node_modules获取目录权限
启动后端口访问失败	端口被占用 / 防火墙拦截	1. 终端执行lsof -i :18789找到 PID，执行kill -9 [PID]结束进程；2. 打开「系统设置 - 网络 - 防火墙」，放行 OpenClaw 应用的网络权限
Apple Silicon 芯片安装后闪退	架构不兼容，安装了 Intel 版本	重新下载对应 Apple Silicon（M 系列芯片）的安装包，Rosetta2 模式运行可解决大部分兼容问题

（三）Linux 平台安装教程（Ubuntu/Debian/CentOS 通用）

Linux 平台支持一键脚本安装和Docker 容器化部署两种方案，个人使用优先一键脚本，服务器/ 云主机部署优先 Docker 方案。

方案1：一键脚本安装（本地 / 服务器通用）

打开 SSH 终端或系统终端，切换至 root 用户，或使用 sudo 权限执行命令。
执行官方一键安装脚本，国内网络使用加速镜像

bash

运行

官方脚本curl -fsSL https://openclaw.ai/install.sh | bash

国内加速镜像curl -fsSL https://gitee.com/openclaw/install/raw/main/install.sh | bash

1.权限不足时，添加sudo执行

bash

运行

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

1.等待脚本自动完成环境配置与安装，执行openclaw -v显示版本号即安装成功。

2.云服务器部署额外步骤：进入服务器控制台安全组/防火墙，放行18789端口TCP协议，即可通过http://服务器公网IP:18789远程访问。

方案2：Docker 容器化部署（服务器 / 自托管首选）

1.确保服务器已安装Docker与Docker Compose环境，未安装可执行以下命令一键安装

bash

运行

Ubuntu/Debiancurl -fsSL https://get.docker.com | bash && sudo systemctl enable docker && sudo systemctl start docker

CentOS

yum install -y docker && systemctl enable docker && systemctl start docker

1.执行Docker命令，一键拉取镜像并启动容器

bash

运行

docker run -d \--name openclaw \-p 18789:18789 \-v ~/openclaw-data:/root/.openclaw \--restart always \

openclaw/openclaw:latest

1.命令说明：-v参数将数据目录挂载到本地，避免容器重启数据丢失；--restart always设置开机自启。

2.验证安装：执行docker ps查看容器状态为Up即启动成功，浏览器访问对应地址即可进入管理界面。

Linux 专属高频踩坑点 & 解决方案

表格

报错现象	核心原因	一键解决方案
提示“curl: 未找到命令”	系统未安装 curl 工具	Ubuntu/Debian 执行sudo apt install curl -y；CentOS 执行yum install curl -y，安装完成后重试
提示“EACCES: permission denied”	非 root 用户无目录写入权限	切换 root 用户执行，或命令前添加sudo；执行sudo chmod -R 755 /usr/local/lib/node_modules修改目录权限
Docker 启动后无法访问	端口未放行 / 容器启动失败	1. 执行docker logs openclaw查看容器日志排查报错；2. 服务器安全组 / 防火墙放行 18789 端口；3. 关闭 SELinux（CentOS）执行setenforce 0
安装后提示“Node.js 版本过低”	系统自带 Node.js 版本低于 22.x	使用 nvm 管理 Node.js 版本，执行 `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh	bash，重启终端后执行nvm install 22 && nvm use 22`，切换版本后重新安装
云服务器访问超时	运营商封禁端口 / 公网 IP 不通	更换端口启动，执行openclaw gateway --port 18790，同时在防火墙放行对应新端口，使用新端口访问

（四）国产Linux 系统（统信 UOS / 银河麒麟）专属安装教程

打开系统自带终端，切换至 root 权限，执行sudo su输入开机密码确认。
先安装系统依赖，执行对应命令

bash

运行

统信UOS/麒麟Debian系sudo apt update && sudo apt install curl git python3 build-essential -y

麒麟RPM系sudo yum install curl git python3 gcc gcc-c++ make -y

1.执行国内加速一键安装脚本，避免官方源访问失败

bash

运行

curl -fsSL https://gitee.com/openclaw/install/raw/main/install.sh | bash

1.安装完成后，执行openclaw -v验证版本，执行openclaw onboard完成初始化，浏览器访问http://localhost:18789即可使用。

2.常见问题：若系统安全中心拦截，需在安全中心放行终端的网络权限与文件读写权限，关闭应用管控拦截。

三、主流国产OpenClaw 衍生产品一键安装教程（零代码，新手首选）

以下产品均为厂商官方合规发布，完成了环境封装与图形化优化，全程无需接触命令行、无需手动配置环境，新手 1 分钟即可完成安装。

（一）智谱AutoClaw（澳龙）安装教程

打开智谱 AutoClaw 官方网站，系统会自动识别你的操作系统（Windows/macOS），点击「下载体验」获取对应安装包。
安装步骤：

Windows 用户：双击下载的.exe文件，按安装向导一路下一步，默认路径安装即可，无需修改任何配置。
macOS 用户：打开下载的.dmg文件，将 AutoClaw 图标拖拽到「应用程序」文件夹，完成安装。

3.启动应用：双击打开AutoClaw，首次启动会自动完成环境配置与依赖安装，无需手动操作。

4.登录配置：使用手机号注册登录，可选择「一键接入飞书/企业微信」，扫码授权后即可直接使用，无需手动配置API Key。

5.常见问题：macOS若提示无法打开，参考前文macOS安全拦截解决方案，在系统设置中允许应用运行；Windows若被杀毒软件拦截，添加信任即可。

（二）腾讯QClaw 安装教程

打开腾讯 QClaw 官方网站，下载对应系统的安装包，支持 Windows/macOS 双平台。
双击安装包，按向导完成默认安装，全程无需修改配置，10 秒即可完成。
打开应用，使用微信 / QQ 扫码登录，无需额外注册，应用会自动完成环境初始化。
核心优势：微信 / QQ 生态零配置绑定，可直接通过微信远程控制设备执行合规自动化任务，全程零代码操作。
常见问题：若远程控制功能失效，需在系统设置中授予应用「辅助功能权限 / 屏幕控制权限」，同时确保设备网络正常。

（三）网易有道LobsterAI 安装教程

打开网易有道 LobsterAI 官方网站，免费下载对应系统的客户端安装包。
双击安装包，按提示完成默认安装，支持 Windows/macOS 双平台。
打开应用后，使用手机号注册登录，应用内置了免费模型适配，无需手动配置 API Key，开箱即用。
核心优势：针对文献翻译、学术处理场景做了专项优化，全中文界面，新手友好度极高，完全免费无隐藏收费。
常见问题：若文献解析功能失效，需检查 PDF 文件是否为可复制文本格式，图片版 PDF 需先完成 OCR 识别。

（四）火山引擎ArkClaw 云端部署教程（无需本地安装，打开网页即用）

打开火山引擎官网，注册并完成实名认证，进入 ArkClaw 产品页面。
点击「一键开通」，选择对应订阅档位，新用户可享受首月优惠，开通后无需部署，直接进入 Web 管理界面。
飞书用户可直接扫码授权，完成飞书生态深度绑定，无需任何本地配置，浏览器即可全功能使用。
核心优势：云端 7×24 小时在线，不占用本地设备资源，飞书办公场景优化拉满，稳定性强，适合职场办公用户。
常见问题：若飞书联动功能失效，需检查授权是否过期，重新扫码授权即可；功能权限与订阅档位绑定，可查看官方档位说明确认对应权限。

四、全平台通用安装失败终极排查手册

如果遇到本文未提及的报错，可按以下顺序排查，解决 99% 的安装问题：

网络问题排查：所有安装失败的首要原因，优先切换国内镜像脚本，关闭 VPN / 代理，确保网络能正常访问对应域名，企业网络需联系网管放行对应域名的访问权限。
权限问题排查：Windows 必须以管理员身份运行终端，macOS/Linux 必须使用 sudo/root 权限执行命令，同时关闭系统安全软件、防火墙的拦截。
依赖问题排查：确保 Node.js 版本≥22.x LTS，手动安装后需重启终端，确保环境变量生效；Windows 需安装 VC++ 运行库，macOS 需安装 Xcode 命令行工具，Linux 需安装 build-essential 基础构建工具。
端口冲突排查：OpenClaw 默认使用 18789 端口，若端口被占用，可更换端口启动，或结束占用进程，同时放行防火墙对应端口。
重装终极解决方案：若以上步骤均无效，执行npm uninstall -g openclaw卸载旧版本，删除用户目录下的.openclaw文件夹，重启设备后，重新执行官方安装脚本，可解决大部分残留文件导致的安装失败。

五、合规使用避坑指南

免费 API 额度仅适用于学习、测试与轻量化使用，生产环境、企业级场景请选择官方付费服务，保障服务可用性与合规性。
妥善保管个人 API 密钥，严禁将密钥转借、售卖、公开传播，避免额度被盗用、产生额外费用，建议通过环境变量、密钥管理服务规范管理。
本文所有安装步骤与规则均来自官方公示，厂商可能会调整安装流程与产品规则，安装前请务必前往官方渠道核实最新信息。
严禁使用安装后的工具执行窃取他人信息、批量发送垃圾信息、入侵系统等违规违法行为，所有操作需遵守国家法律法规与平台用户协议。