保姆级教程：Windows/Mac/Linux三平台OpenClaw部署，90%的坑我帮你踩完了
做OpenClaw企业落地的这大半年，我被问得最多的问题就是：
为什么我跟着网上的教程部署，要么Docker启动失败，要么面板访问不了？
Windows部署WSL2报错怎么解决？Mac M芯片跑不起来是什么原因？Linux服务器部署完了外网访问不了？
毫不夸张地说，OpenClaw的部署本身极简，但90%的问题都不是OpenClaw本身的问题，而是环境配置、权限、端口、依赖兼容这些基础坑。我自己在三平台都反复部署过几十次，踩过的坑能凑成一本手册，小到中文路径导致的启动失败，大到企业内网环境的镜像拉取失败，几乎都遇见过。
这篇文章，我就把Windows/Mac/Linux三平台的部署流程，拆成保姆级的一步步操作，每一步都标注踩坑点，新手跟着走，99%能一次部署成功。同时把90%的人会遇到的问题，整理成「踩坑合集」，直接给原因+现成的解决方案，不用你再到处搜教程。
部署前必看：先搞懂这3点，少走90%的弯路
1. 硬件最低要求
很多人上来就部署，结果自己的电脑/服务器根本带不动，先看清楚硬件门槛：
| 配置类型 | 最低配置 | 推荐配置 | 说明 |
|---|---|---|---|
| CPU | 2核4线程 | 4核8线程 | 纯指令执行用最低配置即可，跑本地大模型建议8核以上 |
| 内存 | 4G | 8G+ | 跑本地开源大模型，至少16G起步（8B模型） |
| 硬盘 | 10G可用空间 | 50G+ SSD | 主要存储镜像、日志、技能包、大模型文件 |
| 系统 | Windows 10+/MacOS 12+/Linux内核3.10+ | 最新稳定版系统 | 不支持Windows 7、MacOS 11及以下 |
2. 两种部署方式怎么选？
我给三平台都准备了两种部署方案，对应不同的人群，新手直接选第一种：
| 部署方式 | 优势 | 劣势 | 适用人群 |
|---|---|---|---|
| Docker一键部署 | 1. 环境隔离，99%不踩依赖坑；2. 一行命令启动；3. 跨平台完全一致 | 二次开发需要改配置重新打包 | 新手、只想用OpenClaw功能、不想折腾环境的用户 |
| 原生源码部署 | 1. 可直接修改源码做二次开发；2. 性能更优；3. 可自定义编译配置 | 对环境依赖要求高，不同平台坑多 | 开发者、想做二次开发、自定义技能的用户 |
3. 核心避坑铁律（新手必背）
这几条是我踩了无数坑总结出来的，提前记住，能避开90%的基础问题：
- 绝对不要用中文路径、带空格/特殊字符的目录名，Windows最容易踩这个坑，直接导致启动失败；
- 部署前先关闭VPN/代理，否则会出现镜像拉取失败、大模型API连接超时的问题；
- 端口18789必须提前放行，防火墙、安全组都要开，不然面板访问不了；
- 不要用管理员/root权限直接运行Web面板，会出现权限溢出、文件读写失败的问题；
- Docker部署必须开启虚拟化，Windows要开WSL2，Mac要开Intel虚拟化/Apple Silicon虚拟化支持。
一、新手首选：Docker一键部署（三平台通用，一次成功）
Docker部署是我最推荐新手用的方式，不管你是Windows、Mac还是Linux，只要装好Docker，一行命令就能启动，完全不用管环境依赖、Python版本这些乱七八糟的问题。
第一步：三平台Docker安装（对应踩坑点已标注）
1. Windows平台Docker安装（最大的坑：WSL2）
Windows部署Docker，核心是必须开启WSL2，这是90%的Windows用户启动失败的原因。
下载安装Docker Desktop
去Docker官网下载Windows版Docker Desktop安装包，双击安装，安装时必须勾选「Use the WSL 2 based engine」，默认是勾选的，不要取消。
安装完成后启动Docker Desktop，看到左下角显示「Docker Desktop running」，就说明安装成功了。
🚨 踩坑提醒：如果Docker启动一直转圈，大概率是WSL2没正常启动，重新执行wsl --install，或者在PowerShell执行wsl --set-default-version 2，把WSL默认版本设为2。
开启WSL2和虚拟机平台
以管理员身份打开PowerShell，执行以下两条命令，执行完后必须重启电脑：
# 开启WSL功能 wsl --install # 开启虚拟机平台功能 dism.exe /online /enable-feature/featurename:VirtualMachinePlatform /all /norestart 🚨 踩坑提醒：重启电脑后，系统会自动安装Ubuntu子系统，按提示设置用户名和密码即可。如果提示WSL版本过低，去微软官网下载WSL2内核更新包安装即可。
2. Mac平台Docker安装（Intel/M芯片通用）
Mac的Docker安装比Windows简单很多，几乎没坑，唯一要注意的是芯片架构。
- 去Docker官网下载Mac版安装包，Intel芯片选x86_64版本，M1/M2/M3芯片选Apple Silicon版本，别下错了；
- 把下载的.dmg文件打开，把Docker拖到应用程序文件夹，完成安装；
启动Docker，看到顶部状态栏的Docker图标不转圈了，就是启动成功了。
🚨 踩坑提醒：MacOS提示「无法打开，因为来自身份不明的开发者」，去「系统设置→隐私与安全性」，拉到最下面，点击「允许打开」即可。
3. Linux平台Docker安装（CentOS/AlmaLinux/Ubuntu通用）
Linux服务器部署是企业最常用的，核心坑是防火墙、端口开放、Docker权限。
我以最常用的AlmaLinux/CentOS为例，Ubuntu的命令我会标注出来：
开放防火墙端口
# 开放OpenClaw默认端口18789sudo firewall-cmd --zone=public --add-port=18789/tcp --permanent# 重载防火墙sudo firewall-cmd --reload# 云服务器额外操作：去服务器控制台的安全组，放行18789端口🚨 踩坑提醒：云服务器（阿里云/腾讯云/华为云）必须在控制台的安全组里放行18789端口，不然外网永远访问不了面板，这是Linux服务器部署最常见的坑。
关键配置：免sudo执行Docker命令
这步必须做，不然每次执行docker命令都要加sudo，还会出现权限问题：
# 创建docker用户组sudogroupadddocker# 把当前用户加入docker组sudousermod-aGdocker$USER# 刷新用户组 newgrp docker# 验证免sudo是否生效dockerps启动Docker并设置开机自启
# 启动Dockersudo systemctl start docker# 设置开机自启sudo systemctl enabledocker# 验证安装sudodocker--version安装Docker核心组件
# AlmaLinux/CentOSsudo dnf install-y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin # Ubuntusudoapt-get update &&sudoapt-getinstall-y docker-ce docker-ce-cli containerd.io docker-compose-plugin 添加Docker官方源
# AlmaLinux/CentOSsudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # Ubuntucurl-fsSL https://download.docker.com/linux/ubuntu/gpg |sudo gpg --dearmor-o /usr/share/keyrings/docker-archive-keyring.gpg echo"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"|sudotee /etc/apt/sources.list.d/docker.list > /dev/null 安装Docker依赖
# AlmaLinux/CentOSsudo dnf install-y dnf-plugins-core # Ubuntusudoapt-getinstall-y ca-certificates curl gnupg lsb-release 卸载旧版本Docker（如果有）
# AlmaLinux/CentOSsudo dnf remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine # Ubuntusudoapt-get remove docker docker-engine docker.io containerd runc 第二步：Docker一键启动OpenClaw
三平台Docker安装完成后，启动命令完全通用，不管是Windows、Mac还是Linux，直接执行即可。
-d：后台运行容器；--name openclaw：给容器起个名字，方便管理；--restart=always：开机自启，容器崩溃自动重启，生产环境必加；-p 18789:18789：端口映射，宿主机18789端口映射到容器内的18789端口；-v 宿主机目录:/app/data：数据挂载，把容器内的数据目录映射到宿主机，实现数据持久化。
验证容器是否启动成功
执行以下命令，查看容器状态：
dockerps如果输出里有openclaw容器，状态是Up，就说明启动成功了。
🚨 踩坑提醒：如果容器状态是Exited，说明启动失败，执行docker logs openclaw查看日志，大概率是挂载目录权限不对，Windows给目录开读写权限，Linux执行sudo chmod 777 /opt/openclaw/data给目录权限。
执行启动命令
# Windows PowerShell执行docker run -d\--name openclaw \--restart=always \-p18789:18789 \-v C:/openclaw/data:/app/data \ openclaw/openclaw:latest # Mac/Linux执行docker run -d\--name openclaw \--restart=always \-p18789:18789 \-v /opt/openclaw/data:/app/data \ openclaw/openclaw:latest 命令参数详解（新手也能看懂）：
创建数据挂载目录
这步是为了数据持久化，就算容器删了，你的配置、技能、任务数据也不会丢：
# Windows PowerShell执行mkdir-p C:/openclaw/data # Mac/Linux执行mkdir-p /opt/openclaw/data 🚨 踩坑提醒：Windows不要把目录建在中文文件夹、桌面、我的文档里，建议直接建在C盘/D盘根目录，比如C:/openclaw/data，避免权限和路径问题。第三步：访问Web控制面板
容器启动成功后，打开浏览器，访问对应地址：
- 本地部署（Windows/Mac/本地Linux）：
http://localhost:18789 - 服务器部署：
http://你的服务器公网IP:18789
能看到OpenClaw的登录/初始化界面，就说明部署成功了！初始化设置管理员账号密码，就能进入控制面板了。
二、进阶玩家：三平台原生源码部署（二次开发必备）
如果你想基于OpenClaw做二次开发、自定义技能、修改源码，就需要用原生源码部署的方式，核心是Python环境和依赖包的安装，不同平台的坑主要集中在环境兼容上。
前置通用要求
所有平台都必须满足：
- Python 3.10 ~ 3.12 版本（不要用3.13+，很多依赖包不兼容，这是最大的坑）；
- Git 最新版；
- Node.js 18+ 版本（用于前端界面编译）。
1. Windows平台源码部署
- 去Python官网下载3.11版本（最稳定），安装时必须勾选「Add Python to PATH」，不然命令行找不到Python；
- 去Git官网下载Git安装包，默认安装即可；
- 去Node.js官网下载18LTS版本，默认安装即可。
安装完成后，打开PowerShell，执行以下命令验证是否安装成功：
启动OpenClaw服务
python main.py 看到终端输出「OpenClaw服务已启动，监听端口18789」，就说明启动成功了，浏览器访问http://localhost:18789即可。
🚨 踩坑提醒：Windows防火墙会弹出提示，一定要点击「允许访问」，不然其他设备访问不了面板。
编译前端界面
# 进入前端目录 cd web # 安装前端依赖 npm install # 编译前端 npm run build # 回到项目根目录 cd ..安装Python依赖包
# 升级pip到最新版 python -m pip install --upgrade pip # 安装依赖包 pip install -r requirements.txt 🚨 踩坑提醒：如果安装依赖报错，大概率是网络问题，加上国内镜像源：
拉取OpenClaw源码
找一个纯英文、无空格的目录，比如C:/code/openclaw，执行：
git clone https://github.com/openclaw/openclaw.git cd openclaw 安装前置依赖
python --version git --version node --version 都能输出版本号，就说明环境没问题。
2. Mac平台源码部署（Intel/M芯片通用）
启动服务
python3 main.py 🚨 踩坑提醒：MacOS提示「无法打开Python，因为来自身份不明的开发者」，去「系统设置→隐私与安全性」允许打开即可；M芯片用户如果安装依赖报错，执行arch -arm64 brew install [email protected]，用原生arm架构的Homebrew安装。拉取源码并安装依赖
# 拉取源码git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装Python依赖 pip3 install-r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 编译前端cd web npminstallnpm run build cd..安装前置依赖
Mac推荐用Homebrew安装依赖，一行命令搞定：
# 安装Homebrew（如果没装） /bin/bash -c"$(curl-fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"# 安装Python、Git、Node.js brew install [email protected] git node@18 验证安装：
python3 --versiongit--versionnode--version3. Linux平台源码部署
以AlmaLinux/CentOS为例，Ubuntu只需要把dnf换成apt-get即可。
后台运行服务（生产环境必备）
用systemd管理服务，实现开机自启、后台运行，避免终端关闭服务停止：
# 创建systemd服务文件sudotee /etc/systemd/system/openclaw.service <<EOF [Unit] Description=OpenClaw Service After=network.target [Service] Type=simple # 替换成你的项目根目录路径 WorkingDirectory=/root/openclaw # 替换成你的Python3路径 ExecStart=/usr/bin/python3.11 main.py Restart=always RestartSec=5 User=root [Install] WantedBy=multi-user.target EOF# 重载systemdsudo systemctl daemon-reload # 启动服务sudo systemctl start openclaw # 设置开机自启sudo systemctl enable openclaw # 查看服务状态sudo systemctl status openclaw 看到服务状态是active (running)，就说明启动成功了，记得开放防火墙和安全组的18789端口。
拉取源码并安装依赖
# 拉取源码git clone https://github.com/openclaw/openclaw.git cd openclaw # 安装Python依赖 pip3.11 install-r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple # 编译前端cd web npminstallnpm run build cd..安装前置依赖
# 安装系统依赖sudo dnf install-y python311 python311-pip git nodejs npm# 验证安装 python3.11 --versiongit--versionnode--version三、部署完成后：必做的3步验证（确保真的能用）
很多人部署完了，能打开面板就觉得成功了，结果后面用的时候各种问题，这里给大家3步验证流程，确保你的OpenClaw是真的部署成功了。
第一步：面板初始化与登录
访问http://你的IP:18789，完成管理员账号初始化，设置账号密码后登录，能正常进入控制面板的首页，没有报错，说明基础服务没问题。
第二步：大模型连接配置
OpenClaw的核心是AI能力，必须配置好大模型，才能正常执行任务。新手推荐先用第三方大模型API（比如DeepSeek、通义千问、GPT），配置最简单，几乎零坑。
- 进入控制面板→「模型配置」；
- 选择你要用的大模型，填入API Key、API地址；
点击「测试连接」，提示「连接成功」，就说明大模型配置好了。
📌 专栏预告：本地开源大模型（Llama3/Qwen/ChatGLM）的对接与优化，我会在专栏《OpenClaw实战指南》里详细讲解，包括完全断网的私有化部署方案。
第三步：跑通第一个任务
我们用最简单的「定时推送每日新闻摘要」任务，验证执行能力：
- 进入「技能市场」，启用「新闻采集」和「消息推送」技能；
- 进入「对话界面」，给AI发指令：“每天早上8点，采集科技行业最新动态，整理成3条核心摘要，推送到我的企业微信”；
- 看到AI回复「任务已创建」，进入「任务管理」，能看到创建的定时任务，就说明任务执行能力完全正常。
四、90%的人都会踩的坑合集（全是血泪经验）
这里我把部署过程中最常见的问题，全部整理出来，每个问题都给「原因+现成解决方案」，遇到问题直接查就行。
| 问题现象 | 核心原因 | 解决方案 |
|---|---|---|
| Docker镜像拉取失败，超时/报错 | 网络问题，国内访问Docker Hub慢 | 1. 关闭VPN/代理；2. 配置Docker国内镜像源（阿里云/中科大镜像）；3. 手动拉取镜像：docker pull registry.cn-hangzhou.aliyuncs.com/openclaw/openclaw:latest |
| 容器启动成功，但浏览器访问不了面板 | 端口没放行/被占用 | 1. 检查防火墙/安全组是否放行18789端口；2. 执行`netstat -ano |
| 源码部署安装Python依赖报错 | Python版本不对/网络问题 | 1. 确认Python版本是3.10~3.12，不要用3.13+；2. 加上清华镜像源安装；3. Windows用户以管理员身份运行PowerShell，Mac/Linux用户加sudo执行 |
| 大模型测试连接成功，但任务执行没反应 | 模型权限不够/提示词长度超限 | 1. 检查API Key是否有对话权限，不是只读权限；2. 降低模型的max-tokens参数，避免提示词超限；3. 查看系统日志，确认是否是模型返回内容为空 |
| Docker部署重启后，配置/任务全丢了 | 没做数据挂载 | 1. 必须加-v参数做目录挂载；2. 确认挂载的宿主机目录有读写权限，Linux给目录开777权限，Windows给目录开完全控制权限 |
| Windows部署WSL2启动失败 | 虚拟化没开 | 1. 重启电脑，进入BIOS，开启CPU虚拟化（Intel VT-x/AMD-V）；2. 重新执行wsl --install，更新WSL内核；3. 在「控制面板→程序→启用或关闭Windows功能」，勾选「Hyper-V」「虚拟机平台」「适用于Linux的Windows子系统」 |
| Mac M芯片源码部署，依赖安装报错「架构不兼容」 | 用了x86的Python版本 | 1. 用Homebrew安装arm64架构的Python；2. 执行arch -arm64 pip install -r requirements.txt，强制用arm架构安装依赖 |
结尾
这篇文章把OpenClaw三平台部署的全流程、所有坑都给大家讲透了，新手跟着走，10分钟就能部署成功。
但部署只是第一步，想要真正用OpenClaw解决工作中的实际问题，还有很多内容要讲：
- 自定义技能开发，从零给OpenClaw添加专属业务能力；
- 本地开源大模型的对接与优化，完全私有化部署；
- 企业微信/飞书/钉钉的深度对接，打造企业专属智能客服；
- 多智能体协同工作，搞定复杂项目流程；
- 企业级高可用部署、安全管控、权限体系搭建；
- 10+可直接复用的实战案例，从私人AI助理到企业级数字员工。
这些内容，我都会在我的ZEEKLOG专栏《OpenClaw实战指南》里，保姆级一步步讲解。
如果你也想摆脱重复的工作，用AI真正提升效率，或者给企业落地私有化的AI数字员工，欢迎订阅我的专栏，跟着我从零到一，吃透OpenClaw。
