本地部署openclaw这件事我前前后后折腾了两天。第一天照着网上一些零散的教程去试结果不是权限报错就是端口冲突折腾到半夜服务都没起来。第二天干脆推倒重来从裸系统开始一步步捋把每个环节都记下来总算是稳定跑起来了。这篇教程就是基于那次完整实操整理出来的从零开始到服务常驻后台、开机自启、数据备份全都有适合手里有一台Ubuntu服务器虚拟机、物理机、云主机都行并且想把openclaw这类自托管服务真正用起来的朋友。我会把每一步的完整命令、预期输出、坑点和判断逻辑都写清楚。整个流程看着长但其实大部分时间花在等下载和等编译上真正需要动脑子的地方没几处。跟着走一遍你的Ubuntu服务器上就能跑起来一个干净的openclaw服务。1. 部署前的整体思路与准备1.1 先想清楚部署一个开源服务到底在做什么很多人拿到一个开源项目第一反应就是git clone然后按README里的命令一把梭。这么干在运气好的时候确实能跑起来但一旦出问题排查的难度会成倍增加。我自己的习惯是先把三件事想明白这个服务是干什么的、它依赖什么运行时、它对外要开哪些端口。openclaw本质上一个长期运行的后台服务这类服务有几个共性需要稳定运行、需要持久化数据、需要可被其他机器访问、需要能在重启后自动恢复。所以部署工作不只是“把代码拉下来跑起来”而是要把运行环境、数据目录、端口规划、进程守护、日志管理这几件事一次性做对。另外要明确部署形态。如果你只是本机自己访问监听地址用127.0.0.1就够了如果是局域网里多台设备要用就得监听0.0.0.0并注意防火墙规则。我这次按“局域网内多设备访问”来部署这也是大多数人实际使用场景。1.2 硬件配置和系统版本怎么选先说系统和硬件这一块决定了后面会不会莫名其妙出问题。系统方面我用的是Ubuntu 22.04 LTS这个版本稳定、软件源干净、遇到问题能找到大量社区经验。当然20.04、24.04也都可以命令基本通用。我不建议在非LTS版本上部署长期服务除非你特别清楚自己在做什么。硬件配置我的建议是配置项最低要求推荐配置说明CPU1核2核及以上编译安装时单核会明显变慢内存2GB4GB及以上内存不够最容易被OOM killer杀掉进程磁盘10GB30GB以上数据会持续增长日志也需要空间网络局域网即可千兆有线多设备并发访问时网络瓶颈更明显内存是这里面最容易踩坑的。服务刚启动时看内存占用可能只有几百MB但跑一段时间后缓存和连接堆上来2GB内存很容易被打满然后系统会把服务进程杀掉。检查内存用free -h看Swap那一行如果经常是满的就得考虑加内存或者限制服务本身的资源占用。1.3 端口规划和目录约定端口这块是我第一次部署失败的主要原因。服务器上已经有了其他服务占用了默认端口openclaw一启动就报“address already in use”我当时还没反应过来以为是代码没拉全白白排查了很久。建议在部署之前就确定好端口和目录后面所有配置都围绕这个约定来。这次我用的是8443端口原因很简单避开22SSH、80HTTP、443HTTPS这些几乎必然被占用的常用端口同时8443在HTTPS替代端口里比较常见不容易和其他软件冲突。目录规划我按下面这个结构来/app/openclaw # 代码目录 /var/lib/openclaw # 数据目录重点备份对象 /etc/openclaw # 配置文件 /var/log/openclaw # 日志目录注意代码、数据、配置、日志分开存放。这样做的直接好处是升级代码不会动到数据备份数据不会带上代码日志爆掉也不影响主程序。很多教程把数据直接放在代码目录下当时用着方便后面升级或者迁移的时候就是灾难。2. 基础环境配置与依赖安装2.1 系统更新与基础工具链拿到一台裸Ubuntu服务器第一件事永远是更新软件源。虽然这一步看起来没什么技术含量但它能避免后面大量“依赖版本太旧”的问题。sudo apt update sudo apt upgrade -y升级完后安装基础工具链。我用的是sudo apt install -y curl wget git vim build-essential ca-certificates gnupg lsb-release这里build-essential很多人觉得用不上其实不然。有些依赖在安装时需要编译原生模块缺少这个工具链会直接报错而且报错信息很长新手很容易被吓到。vim用来改配置文件虽然你用nano也可以但vim几乎是服务器标配装上没坏处。2.2 安装运行时环境openclaw这种项目的运行环境一般离不开Node.js或Python。我建议两个都装好。先说Node.js我不推荐用apt直接安装因为Ubuntu软件源里的Node版本通常比较旧而这类项目对Node版本有明确要求版本不对会出现各种奇怪的兼容性问题。推荐用nvm安装指定版本的Nodecurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新登录终端或者source一下配置文件让nvm生效然后安装Node。以Node 20 LTS为例nvm install 20 nvm alias default 20 node -v这里的核心原因是nvm支持在同一个服务器上维护多个Node版本方便以后切换。很多时候项目升级会要求新的Node版本如果你是用apt装的全局版本升级系统Node会影响到所有项目用nvm则可以做到互不干扰。Python这边我建议装Python 3.10以上版本并且用venv创建虚拟环境不要让项目依赖去污染系统Pythonsudo apt install -y python3-pip python3-venv python3-dev依赖安装是另一个容易出问题的环节。如果pip下载速度很慢可以把pip源切换到国内镜像源操作方式是在用户目录下创建pip.confmkdir -p ~/.pip vim ~/.pip/pip.conf写入如下内容[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple trusted-host pypi.tuna.tsinghua.edu.cn这里我只放了清华源的例子其他镜像源同理。不管用哪个源关键是保证安装过程稳定别在装了一半的时候超时中断。2.3 创建专用账户和服务目录部署长期服务的一个重要原则是不要用root直接跑。原因主要有三个第一root权限太大一旦程序有漏洞被利用攻击者直接拿到整台服务器的控制权第二用root跑服务产生的日志和文件都属于root后续普通用户操作起来非常别扭第三隔离的账户更容易管理备份权限。创建专用账户sudo adduser openclaw按提示设置密码其他的信息可以直接回车跳过。然后把刚才规划的目录建好并修改属主sudo mkdir -p /app/openclaw /var/lib/openclaw /etc/openclaw /var/log/openclaw sudo chown -R openclaw:openclaw /app/openclaw /var/lib/openclaw /etc/openclaw /var/log/openclawchown这一行非常重要。我见过很多次服务启动失败最后发现就是数据目录属主不对服务进程没有写权限。用openclaw用户跑服务那服务要读写的目录就必须归openclaw所有这是Linux权限模型的基础逻辑。3. 获取项目代码与配置修改3.1 拉取代码与版本选择切到openclaw用户再拉代码sudo -u openclaw bash -c cd /app/openclaw git clone 项目仓库地址 .为什么要用sudo -u而不是先su过去sudo -u更干净不会要求你切换到那个用户的交互式shell。当然你直接su - openclaw再执行git clone也可以效果一样。这里有个容易忽略的细节clone之后要看一下当前处于哪个分支。很多项目默认分支是dev或main但dev分支往往是开发中状态不适合直接部署。我会切到最新的稳定版本标签上cd /app/openclaw git tag # 查看有哪些稳定版本 git checkout 稳定版本号在正式环境里跑稳定版而不是追最新代码这个习惯能帮你省掉很多“昨天还能用今天更新完就崩了”的麻烦。3.2 配置文件里的关键参数配置文件一般在项目根目录或者/etc/openclaw目录下。先看看项目里有没有示例配置文件通常叫config.example.yaml、.env.example之类的然后复制一份出来改成实际配置cp config.example.yaml /etc/openclaw/config.yaml下面是我这次部署中实际需要改的几项你可以根据自己情况调整参数示例值说明bind_address0.0.0.0监听所有网卡地址局域网设备才能访问port8443对外服务端口data_path/var/lib/openclaw持久化数据存放位置log_path/var/log/openclaw日志存放位置log_levelinfo日常运行建议不用debug日志太多secret_key随机长字符串加密相关生成一个足够随机的值bind_address这个参数特别容易理解错。默认情况下很多服务只监听127.0.0.1意思是只能本机访问其他设备连不上。如果你按教程装完之后发现自己电脑打不开服务器上的服务90%是这个参数没改。修改配置文件的命令就是vimsudo -u openclaw vim /etc/openclaw/config.yaml3.3 初始化数据目录配置改完之后先手动创建数据目录里的基础结构。大部分项目会在首次启动时自动创建目录但为了避免权限问题提前暴露我建议手动创建一层sudo -u openclaw mkdir -p /var/lib/openclaw/data接下来安装项目依赖。这一步是新手最容易卡住的环节。以Node项目为例一般执行npm installPython项目执行pip install。但这里有个重要前提先看项目文档确认用哪个包管理器。有些项目用npm有些用yarn有些用pnpm用错了虽然不一定报错但会产生不同的lock文件后续升级容易出问题。cd /app/openclaw sudo -u openclaw npm install等待安装完成时不要干等着我习惯同时把防火墙规则检查一遍。Ubuntu默认可能没有启用ufw但如果启用了就要放行8443端口sudo ufw allow 8443/tcp sudo ufw status4. 启动、验证与守护进程4.1 首次启动与验证依赖装完、配置改好就可以开始启动验证了。先用前台模式启动这样你能直接看到日志输出有没有报错一目了然cd /app/openclaw sudo -u openclaw ./bin/openclaw start --foreground如果你看到类似“Server listening on 0.0.0.0:8443”的日志说明服务起来了。这时候在浏览器里访问http://你的服务器IP:8443应该能看到界面。第一次访问一般会让你初始化管理员账号。这个过程不要跳过也不要设太简单的密码。openclaw的管理员相当于整个系统的总开关密码设得简单后面再加强就麻烦了。确认能访问之后按CtrlC停掉前台进程进入下一步的常驻配置。4.2 用systemd把服务变成常驻进程前台模式有个致命问题终端一关服务就停了。要让服务在后台稳定运行、开机自动启动、崩溃自动拉起标准做法是写一个systemd服务单元。创建服务单元文件sudo vim /etc/systemd/system/openclaw.service内容如下[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple Useropenclaw WorkingDirectory/app/openclaw ExecStart/app/openclaw/bin/openclaw start --foreground Restartalways RestartSec5 EnvironmentFile/etc/openclaw/config.env [Install] WantedBymulti-user.target这里有几个关键点要解释环境隔离。EnvironmentFile指定了配置文件路径这样进程能从固定的位置读取配置。加上WorkingDirectory指向代码目录可以避免进程的工作目录不对导致找不到文件的错误。Restartalways这个参数是“服务挂了自动重启”的核心。配合RestartSec5能让服务崩溃后等5秒再拉起。但注意区分如果是配置错误导致启动即崩systemd会进入不断重启的循环这时候要看日志来定位问题不能只依赖自动重启。Typesimple告诉systemd这个进程就是主进程本身不会fork。很多程序用Typesimple就够了但如果程序文档特别说明要配合Typenotify或者forking要以文档为准。保存后重载systemd配置并启动服务sudo systemctl daemon-reload sudo systemctl enable --now openclawenable --now这个组合很实用enable设置开机自启now立即启动一个命令同时完成两件事。4.3 服务状态检查与常用管理命令启动之后检查一下状态sudo systemctl status openclaw正常会看到active (running)字样。再确认端口确实在监听ss -lntp | grep 8443日常管理用的命令我整理成一张表收藏着用场景命令查看服务状态sudo systemctl status openclaw实时查看日志sudo journalctl -u openclaw -f重启服务sudo systemctl restart openclaw停止服务sudo systemctl stop openclaw开机自启开关sudo systemctl disable openclaw尤其要养成自觉用journalctl看日志的习惯。报错信息基本都能在里面找到比到处猜强多了。5. 常见问题与排查方案5.1 端口被占用导致启动失败这个问题我踩过一次之后印象极深。如果你启动时看到“Error: listen EADDRINUSE”或者“address already in use”说明端口被别人占了。先确认端口占用情况sudo ss -lntp | grep 8443你会看到占用进程的PID和名字。解决方式两种要么停掉占用进程要么改openclaw的端口。端口规划这东西真得提前做。你可以在服务器上维护一个简单的端口登记表时间久了端口冲突的问题一定会遇到。尤其是我这种一台服务器跑了好几个服务的情况哪个服务用哪个端口提前登记好至少能少踩一半的坑。5.2 依赖安装过程失败npm install或者pip install失败的原因很多最常见的有网络超时、Node/Python版本不对、缺编译工具链。排查顺序是先看错误信息的前五行。如果看到“network”或者“ETIMEDOUT”大概率是网络原因考虑换镜像源如果看到“node-gyp”“make”“g”相关的报错说明缺编译工具链装build-essential如果看到“engine”字样说明Node版本不符合要求用nvm切换Node版本。这里我强烈建议大家养成“先读报错第一行”的习惯。很多人一看报错信息很长就直接复制到搜索引擎里搜结果搜出来的答案五花八门更不知道怎么选。实际上错误信息最关键的部分就在前几行。5.3 数据目录权限导致的启动失败启动报错里出现“EACCES: permission denied”或者“cannot write to /var/lib/openclaw”时基本都是权限问题。检查目录属主ls -ld /var/lib/openclaw看到输出前几位是drwxr-xr-x且属主是root那openclaw用户肯定写不进去。修复方式sudo chown -R openclaw:openclaw /var/lib/openclaw这种问题在第一次部署时很常见因为创建目录的往往是root但配置里写的是让openclaw用户去写。权限模型就是这样目录创建者和目录使用者不一致中间就容易出问题。养成创建完目录就顺手chown的习惯能省很多事。5.4 升级版本导致配置丢失开源项目迭代快升级是经常要做的事。但一些朋友升级的方式有问题直接把整个目录删掉重新clone。代码是被更新了但数据目录、配置文件和上传的文件如果放在同一个目录下就会一起被删掉。我自己用的升级方式是三步第一步备份把/etc/openclaw、/var/lib/openclaw打包第二步拉新代码在代码目录里git pull或者重新clone到新目录再切换软链第三步校验配置看看新版有没有新增必填配置项对照项目文档修正后再重启服务sudo systemctl restart openclaw这种升级方式最核心的逻辑是代码是随时可以重新生成的数据不是。升级过程中优先保护数据代码坏了大不了重装数据没了就真的没了。6. 后续扩展安全加固、备份与资源配置6.1 给局域网访问加一层HTTPS保护如果只是局域网里自己用HTTP访问其实也能接受。但如果你打算让服务长期运行并且会输入一些敏感数据还是建议加一层加密传输。在局域网环境下可以用自签名证书浏览器会提示不受信任点击继续访问就行。操作上生成证书、配置到服务里。生成的命令我会附在后面这段操作里sudo mkdir -p /etc/openclaw/certs sudo openssl req -x509 -nodes -newkey rsa:2048 -days 365 \ -keyout /etc/openclaw/certs/server.key \ -out /etc/openclaw/certs/server.crt \ -subj /CCN/STLocal/LLocal/OLocalOrg/CNopenclaw.local然后在配置文件里开启HTTPS指定证书路径。对于局域网环境这一步能防止同一网络里的其他人通过抓包看到你传输的明文数据。如果是单机自己用这一步可以跳过。另外再说一点如果你的路由器支持端口转发可以把服务器的8443端口映射到路由器上这样在外面的设备也能通过路由器IP访问。但这一步涉及端口映射不是必须而且一旦暴露到外部网络安全责任就大了很多。我建议没有经验的朋友不要一开始就做公网暴露先在内网里跑熟再说。6.2 备份策略部署完成后最容易被忽略的就是备份。很多服务是跑了几个月之后某天数据出问题才想起备份这件事。把备份融入日常其实只需要一个cron任务。我采用的备份方案是每天凌晨3点打包数据目录保留最近7天的备份副本。写一个简单的备份脚本#!/bin/bash BACKUP_DIR/var/backups/openclaw DATA_DIR/var/lib/openclaw DATE$(date %Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR tar -czf $BACKUP_DIR/openclaw_data_$DATE.tar.gz -C $DATA_DIR . find $BACKUP_DIR -name openclaw_data_*.tar.gz -mtime 7 -delete脚本放到/usr/local/bin/backup_openclaw.sh赋予执行权限然后加入cronsudo chmod x /usr/local/bin/backup_openclaw.sh sudo crontab -e在打开的文件里加一行0 3 * * * /usr/local/bin/backup_openclaw.sh备份这件事最大的痛点是“平时想不起来出事了才想起来”。设置好自动备份之后虽然平时看不到它工作但真遇到问题的时候这个脚本能救命。我在实际部署里还养成了一个习惯每逢大版本升级前手动打一次备份这样一旦升级出问题可以随时回滚。6.3 限制资源占用与日志轮转openclaw这类服务长时间运行日志文件会越来越大。看日志的时候用ls检查一下ls -lh /var/log/openclaw/如果发现单个日志文件好几个GB先看是不是日志级别设置的debug。光是这一个调整就能大幅降低日志增长速度。同时在systemd的unit文件里追加日志轮转的配置也是可行的编辑openclaw.service在[Service]段下加一行RuntimeMaxSec86400这行表示进程最多运行24小时就自动重启一次适合日志积累特别快的场景。不过这个方式比较粗暴适合对重启容忍度高的服务。更优雅的方式是用logrotatesudo vim /etc/logrotate.d/openclaw写入/var/log/openclaw/*.log { weekly rotate 4 compress delaycompress missingok notifempty copytruncate }这段配置的意思是每周轮转一次保留4份压缩历史如果文件非空就截断。尤其是copytruncate这个参数它能保证程序持续往同一个文件里写也不会因为日志被移动而出问题。另外内存限制也可以加。在systemd服务文件里追加MemoryMax2G这样即使服务有内存泄漏也不会把整个服务器拖垮。我在一台内存不大的服务器上部署这类服务后几乎一定会加这个参数。限制资源不是为了限制服务能力而是为了服务器整体稳定。写在最后部署过程里我踩的最深的一个坑是端口冲突第二个深坑是目录权限。这两个问题出现的频率超高但只要你按照本文提前规划、用专用用户运行、目录各司其职基本可以绕开。我自己后来在其他服务器上再部署同类的服务都会先花五分钟把端口表、目录结构、备份脚本这三个东西一次性准备好部署效率明显高一截。最后再分享一个小技巧部署完成之后可以往浏览器收藏夹里同时存下服务地址和服务器登录方式。很多时候服务出了异常第一反应不是看日志而是翻收藏夹、回忆服务器密码这种时间浪费特别不值得。把运维信息和访问入口一起管理好整个项目才算真正交接到自己手里。