★ FEATURED ARTICLE OpenClaw这阵子在AI圈子里讨论度确实高。简单说它就是一个开源的AI个人助理框架能接大模型API能调用各种工具能调度定时任务也能把它挂到聊天软件上当机器人用。我3月份帮几个朋友部署完一轮之后整理出来这么一套从云端到本地全平台的新手教程目标是让一个没接触过的人在8分钟内跑起来。这篇文章针对三类人一是想租个云服务器挂自动化任务的二是用Mac或Linux当主力机想本地跑的三是Windows 11用户尤其是被原生环境坑过、想用最省心方式跑的。三条路我都在不同机器上实踩过下面按顺序逐个讲清楚。每个命令、每个配置背后的原因我也会说方便你以后自己变通。1. 部署思路与方案选择1.1 先搞清楚OpenClaw部署的本质很多人第一次看到OpenClaw以为它是一个需要编译的大项目其实不是。它的核心是一个Node.js写的命令行工具加一个常驻服务部署的本质就三件事装好Node环境、把OpenClaw装进去、配置好各种API密钥。搞懂这个本质你就不慌了。后面的所谓“云端部署”“Mac部署”“Win11部署”差别只在于怎么装Node、怎么让服务常驻后台OpenClaw本身的安装流程几乎一模一样。那8分钟是怎么算出来的我实测下来云端买服务器到跑起来算上SSH连接和等待系统更新5分钟左右Mac和Linux本地跑3分钟左右Windows 11走WSL2路线因为要初始化子系统会慢一些但真正花在OpenClaw上的操作也就4分钟。整体控制在8分钟前提是你照着下面的流程走别去折腾多余的配置。1.2 三类环境的取舍先说结论如果你是打算7x24小时挂任务直接上云服务器如果只是自己电脑上偶尔跑跑Mac和Linux都很舒服Windows 11用户别犹豫走WSL2不要试图在原生Windows环境里折腾。我为什么这么建议因为OpenClaw这类服务有个特点它依赖Node的进程模型和文件目录权限在类Unix环境下运行非常顺畅进程管理、日志查看、开机自启都有一套成熟的工具链。Windows原生环境虽然能装Node但路径分隔符、权限模型、服务守护这些地方总有各种小问题新手很容易卡在莫名奇妙的地方。WSL2本质是给Windows装了一个完整的Linux内核等于你在Windows上跑了一个UbuntuOpenClaw的所有坑都变成Linux的常见问题网上资料一搜一大堆。云端和本地的取舍也有讲究。云端的优势是稳定、随时能连、不占本机资源缺点是花钱、数据在别人机器上。本地的优势是免费、数据完全在自己手里缺点是机器不能随便关机。我自己是本地Mac跑一个日常用的实例云服务器专门跑定时任务分工明确。1.3 版本与前置依赖2026年3月这个时间点OpenClaw的安装方式已经比早期版本稳定很多了。但有一点必须提醒这个项目迭代非常快命令参数、配置文件格式都可能变化。所以下面所有命令我都按“当前主流版本”来写但你实际安装时一定要以官方文档最新说明为准。前置依赖就三样Node.js 18以上、npm、git。Node版本很重要太老跑不起来太新有时会有兼容问题。我实测最稳的是Node 20和22的LTS版本尽量别用最新版尝鲜稳是第一位的。另外OpenClaw启动时会读取一个配置文件里面放模型API的密钥、机器人token、各种工具开关。这个文件的路径在Unix系统通常是用户主目录下的一个隐藏目录比如.openclaw里面有个config.json之类。部署时一定要先把密钥准备好否则启动后报认证错误会让人摸不着头脑。2. 云服务器部署挂机最稳的一条路2.1 服务器选型和系统初始化云端部署我推荐选一个2核4G的轻量服务器硬盘40G起步。为什么是4G内存因为OpenClaw本身吃内存不多但如果你让它跑一些需要加载模型的工具或者同时跑多个定时任务2G内存会捉襟见肘。我最初用1G内存的机器试过开个系统加OpenClaw就快满了Swap一触发响应变得非常慢。系统选Ubuntu 22.04 LTS这是目前兼容性和稳定性最好的选择。买完服务器之后先在控制台里完成两件事设置root密码或密钥对、放行端口。端口这里要注意SSH默认22端口要放行OpenClaw如果开了Web面板或API服务默认端口一般是3000或者你自己配置的其他端口也要在防火墙和安全组里放行。很多新手以为装好了连不上其实就是安全组端口没开。2.2 远程连接与环境准备用终端软件SSH登录服务器登录后第一件事是更新系统包sudo apt update sudo apt upgrade -y这一步建议做因为新服务器上的软件源索引可能是旧的直接装东西容易遇到版本不匹配。更新过程可能要一两分钟正好可以把下面的命令提前复制好。接着装Node.js。我不推荐直接用Ubuntu自带的apt装Node因为版本太旧。推荐用nvm方式装方便以后切换版本curl -o- 官方nvm安装脚本地址 | bash source ~/.bashrc nvm install 22 nvm alias default 22nvm之所以比apt好在于它把Node安装在用户目录而不是系统目录权限问题少而且随时可以切换版本。如果你不想用nvm用NodeSource源装也行但过程更繁琐新手没必要折腾。2.3 安装与初始化OpenClawNode装好后全局安装OpenClaw的命令行工具包npm install -g 官方包名安装完成后执行初始化命令创建配置目录openclaw init这个命令会引导你选择预设模板、填写模型API密钥、设置服务端口。需要说明的是不同版本交互方式略有差别核心就是一路按提示走该填密钥的地方填密钥。初始化完成后建议手动编辑配置文件把模型API地址、密钥、默认参数确认一遍。这一步别看简单我遇到过好几次问题都是密钥里带了多余空格或者换行符导致认证失败。配置文件在~/.openclaw/目录下用nano打开修改即可。改完先用openclaw doctor之类的自检命令看看配置有没有问题然后再启动。2.4 让服务常驻后台启动OpenClaw直接前台跑没问题但如果SSH断开进程就没了。所以必须用进程守护工具我推荐pm2npm install -g pm2 pm2 start openclaw --name openclaw pm2 save pm2 startuppm2的startup命令会生成一个开机自启脚本服务器重启后OpenClaw自动恢复运行这对云端挂机是刚需。日常看日志用pm2 logs openclaw重启服务用pm2 restart openclaw。还有一种方式是写systemd服务更系统化但对新手偏复杂pm2完全够用。3. Mac本地部署跟着Homebrew走完3.1 检查Homebrew和NodeMac本地部署比云端简单因为不用处理远程连接和服务器安全组。前提是你装了Homebrew这是Mac上最主流的包管理器。没装的话去官网复制安装命令到终端执行这个过程通常要几分钟因为要下载Command Line Tools。Homebrew就绪后安装Node和gitbrew install node git这里有个坑如果你的Mac是Apple Silicon芯片Homebrew默认装在/opt/homebrew目录如果是Intel芯片装在/usr/local目录。如果之后出现command not found多半是路径没进环境变量把对应的bin目录加到~/.zshrc的PATH里就行。装完验证一下node -v npm -v能正常输出版本号就说明Node环境OK了。这里我多说一句Mac自带的终端就够用不需要装iTerm2之类的高级终端少一个变量少一个坑。3.2 全局安装与权限问题OpenClaw的安装和云端一样全局安装官方包名npm install -g 官方包名如果遇到EACCES权限报错别急着用sudo npm install -g。用sudo装全局npm包会带来权限混乱以后每次升级、清理缓存都可能出问题。正确的做法是用nvm安装Node把全局安装路径放在用户目录下避开/usr/local的系统目录权限限制。初始化流程和云端一致不再重复。Mac本地特别需要注意的是文件目录权限OpenClaw运行时会在工作目录下创建日志、缓存、临时文件如果你把项目目录放在需要授权才能写入的地方比如某个iCloud同步文件夹服务可能启动成功但写日志报错表现很诡异。我建议直接放在用户目录下比如~/openclaw-workspace干净省事。Mac上还有一个好处可以直接用openclaw start前台跑配合CtrlC停止适合调试。调试没问题之后再用pm2托管。4. Linux本地部署桌面机还是工控机都适用4.1 用nvm而不是apt装NodeLinux本地部署和云端服务器的步骤高度相似但有一个关键差别本地Linux可能是桌面版也可能是工控机的小内存环境软件源里的包可能很旧。所以安装Node我强烈建议用nvm。为什么非要nvm不用apt我拿一个常见场景说明很多Linux发行版自带或源里的Node版本是12到16而OpenClaw要求Node 18以上。用apt装完才发现版本不够再升级就得换源或者从源码编译非常麻烦。nvm装完直接就是最新LTS一条命令切换版本干净利落。# 安装nvm后执行 nvm install 22 nvm use 22装好之后把nvm的初始化脚本加到shell配置里否则每次开新终端都找不到node。这个细节很基础但极其重要我就是曾经开新终端忘了执行一度以为安装失败了。4.2 配置自启动服务本地Linux不像Mac那样开着就行Ubuntu桌面版默认开机不会自动执行你的自定义脚本所以要让OpenClaw开机自启还得配systemd服务文件。这里我给出一个模板你改一下路径和用户就能直接用。sudo nano /etc/systemd/system/openclaw.service写入[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/openclaw-workspace ExecStart/home/你的用户名/.nvm/versions/node/v22.x.x/bin/openclaw start Restarton-failure RestartSec5s [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这里有个细节ExecStart里写的是nvm安装的具体Node路径不能用笼统的openclaw因为systemd的环境变量路径不一定包含nvm。获取完整路径执行which openclaw就行。另外WorkingDirectory一定要指向你的工作目录否则OpenClaw可能在错误的目录下创建配置文件到时候数据乱放找都找不到。5. Win11部署WSL2是标准答案5.1 一步到位启用WSL2Windows 11原生跑OpenClaw理论上可行但实际体验一言难尽。最省心的方式是开WSL2在Windows里跑一个Ubuntu子系统。操作很简单管理员身份打开PowerShell执行wsl --install -d Ubuntu这个命令会自动启用WSL2所需的Windows功能、装好WSL内核、再拉取Ubuntu镜像。执行完重启电脑第一次启动Ubuntu会让你设置用户名和密码之后就进入一个完整的Linux终端环境。有人看到要重启就嫌麻烦但这一步值得。我印象很深的是曾经试图在Windows原生环境直接装结果遇到Node路径带空格、npm脚本权限错乱、防火墙弹窗拦截等一系列问题折腾两小时还不如一开始就用WSL2。5.2 在Ubuntu里跑通OpenClaw进入WSL的Ubuntu终端后后面的步骤就完全是Linux路线安装nvm、安装Node、安装OpenClaw。你完全可以把前面的Linux章节拿出来照抄唯一区别是WSL里的文件目录在Windows资源管理器里能直接看到在资源管理器地址栏输入\\wsl$\Ubuntu\home\你的用户名就能访问。这一点我强烈建议新手好好利用OpenClaw的配置文件和日志都可以在Windows图形界面里直接查看编辑比在终端里用nano改要直观很多。我用的是VS Code安装WSL扩展后直接在Windows侧打开WSL目录编辑配置、看日志、调试代码都特别流畅。5.3 文件互访和给Windows的备用方案WSL2和Windows之间的文件互访是个容易迷惑的点。原则是OpenClaw相关的一切包括配置文件、工作目录、数据文件都尽量放在WSL的Linux文件系统里也就是/home/下面不要放在/mnt/c/Windows的C盘挂载目录。为什么因为/mnt/c/是跨文件系统访问性能和权限处理都不好。我之前把工作目录放在/mnt/c/openclaw结果跑定时任务时大量小文件读写特别慢源是PyCharm项目么我说慢就慢在跨文件系统IO上。后来把目录挪回Linux原生文件系统立竿见影。如果你实在不想用WSL非要Windows原生部署那至少用系统包管理器装Node.js LTS版然后全程在PowerShell里操作遇到问题多半要在社区搜索Windows专属解决方案。这条路我不推荐但对某些只能装Windows的办公电脑也算备用方案。能用WSL尽量用WSL省心程度不是一个量级。6. 实战中踩过的坑和排查清单6.1 启动阶段的常见报错部署OpenClaw过程中几乎每个人都会遇到报错。最常见的几类我列一下。第一类command not found: openclaw。这代表安装步骤没成功或者环境变量没配对。先检查npm全局安装路径是否在PATH里Mac和Linux用echo $PATH看Win11走WSL的话在Linux环境里看。如果路径里没有npm全局目录手动加进去。第二类启动后进程存在但端口访问不了。这种情况云端最常见因为安全组没放行。也有可能是OpenClaw绑定在127.0.0.1只允许本机访问。如果你要远程访问Web面板或API就要在配置里把监听地址改成0.0.0.0。改完记得重启。第三类启动时提示Node版本过低。这就是我说为什么一定要用nvm的原因直接nvm install 22切版本不要试图在老版本上凑合。6.2 API密钥和配置问题密钥问题是排查花费时间最多的地方。常见的表现是启动成功了但一调用模型就报401认证失败或者返回“invalid api key”。我踩过很多次后发现大概率不是密钥本身错了而是配置文件格式问题。比如从文档复制密钥时带上了换行符或者填错了模型服务商的地址甚至填的是旧项目的废弃密钥。排查方法是先直接在配置文件里输出密钥的前几位和后几位确认无误再试。注意别在日志里暴露完整密钥。另外一个很隐蔽的问题是多个模型服务组合时默认模型和服务商不匹配。比如配置里默认模型填了一个国内厂商不支持的型号结果所有请求都报错但服务本身看着是正常的。这时候要把配置里所有模型名和服务商逐一核对别只看着“默认模型”一栏。6.3 性能与稳定性调整OpenClaw跑久了内存占用会缓慢上涨这是Node服务常见现象。我一般给pm2设置一个内存阈值自动重启pm2 start openclaw --name openclaw --max-memory-restart 300M这样内存超过300M就自动重开长期挂机不用管它。另外如果定时任务比较多建议给每个任务配上独立的日志文件方便排查是哪个任务出了问题否则所有输出混在一起上万行日志看得人头疼。云端部署还有一个容易被忽略的点服务器时区。定时任务都是按本地时间触发的如果服务器默认UTC时区你的“每天8点执行”就会变成“北京时间16点执行”。执行timedatectl set-timezone Asia/Shanghai之类的命令把时区改过来。6.4 快速排查速查表我把典型问题整理成一个速查表建议收藏备查。现象可能原因解决办法找不到openclaw命令环境变量未配置检查并添加npm全局路径到PATH启动后立刻退出配置文件的语法错误运行自检命令检查JSON格式调用模型报401密钥错误或格式有换行核对密钥清理不可见字符端口访问不了防火墙或安全组未放行控制台放行对应端口定时任务不触发时区不对设置正确的服务器时区系统卡顿内存不足换4G内存机器或调低并发数服务掉线后不恢复没有使用守护进程pm2或systemd托管这份清单是我根据多次部署和帮朋友解决问题的实际经历总结出来的覆盖了绝大部分新人会遇到的问题。最后再分享两个我自己的习惯。一是配置文件一定定期备份尤其升级前先复制一份这项目迭代快升级出问题能秒回滚。二是时刻盯官方更新日志因为新版常常会调整配置字段的命名旧配置直接套新版本可能启动就是黑屏日志里的“unknown field”。部署本身不难难的是保持稳定运行的好习惯。希望这篇东西能让你少折腾两小时。
阅读完成 · 觉得有帮助？
