最近社区里关于 Openclaw 的讨论明显多了起来很多人把它当成一套“拿下来就能跑”的工具结果真上手的时候才发现文档散、配置项多、依赖版本还容易互掐。我在三台不同的机器上完整部署过 Openclaw踩了不少坑也把流程理顺了。这篇是第一篇核心就一件事用最短的时间把 Openclaw 从零部署到能正常访问后台、能跑通第一个任务。文章会尽量贴近实际操作的顺序来讲适合刚接触 Openclaw 的开发者也适合那些想把部署流程固化到脚本里、反复重装机器的人。这篇不会讲太多源码层面的设计而是聚焦部署链路本身。我会先聊部署前的准备工作再逐个过环境依赖、源码获取、配置、初始化、启动、验证最后把我踩过的几个坑和完整的排查过程摊开讲。你可以照着做也可以把它当成一份检查清单在遇到问题的时候翻出来对照。1. 部署前的准备先把硬件、系统和网络这三道门槛摸清楚1.1 硬件底线别让内存和磁盘成为第一批瓶颈我实际部署 Openclaw 时第一个教训是别轻信“轻量级”这个词。Openclaw 安装包确实不大但它一旦跑起来会同时拉起主服务、任务队列、数据库连接池某些任务执行还会创建独立的临时运行环境。这一套下来4GB 内存的机器会非常吃紧我用过的参考配置如下项目最低配置推荐配置备注内存4GB8GB 及以上并发任务多时内存是主要瓶颈CPU2 核4 核及以上任务类型偏计算时建议更高磁盘20GB40GB 以上SSD 优先日志和任务产物非常占空间网络能正常访问代码和依赖仓库稳定带宽即可下载依赖和镜像时明显感知差距为什么内存这么敏感因为任务执行过程中要保存中间结果涉及数据处理的任务还会额外占用大量内存。我见过最典型的情况是机器表面上还剩 3GB 空闲内存任务一启动进程直接消失dmesg 里全是 OOMOut Of Memory的记录。这不是 Openclaw 的 bug是真实内存不够了。磁盘这里得多说一句。很多人只盯着安装目录忽略了日志和任务产物。Openclaw 默认会把任务输出、运行日志写到工作目录下时间一长非常能吃空间。建议至少留出 20GB 给安装目录和数据目录有条件直接上 SSD。机械硬盘在任务并发稍高的时候I/O 等待会拖慢整个平台哪怕 CPU 和内存看起来都富余。1.2 操作系统选型为什么我建议先用 LinuxOpenclaw 的设计明显偏向 Linux 生态安装脚本、依赖管理、进程托管这些环节在 Linux 上最顺。我自己也在 Windows 的 WSL2 里跑通过能跑但有两个问题一是跨文件系统读写性能差得明显二是和容器运行时配合时容易遇到网络模式冲突排查起来相当费时。所以我的建议很简单第一次部署直接用一台 Ubuntu 22.04 LTS 的机器不管是云服务器还是本地虚拟机都可以。等流程彻底跑通、弄明白哪些配置影响哪些行为之后再考虑 Windows 或 macOS 上的适配。这个顺序能帮你省掉大量跟 Openclaw 本身无关的环境排查时间。1.3 网络环境与依赖拉取策略Openclaw 的安装过程会从代码托管平台拉仓库从包索引和 npm 源下载依赖还可能需要拉容器镜像。这一步对网络质量的要求其实挺高的尤其是在依赖文件比较大的时候中断一次就要重来。这里分享一个我的习惯不要直接执行网上看到的“一键安装”脚本先把脚本内容完整翻一遍看清楚它到底做了哪些事再执行。有些脚本会默认安装到 /root有些会覆盖系统级配置文件等发现问题再回溯就很麻烦。如果拉取依赖失败优先尝试常规的镜像源替换手段。Python 依赖可以通过 pip 指定镜像源npm 依赖可以切换 registry 地址容器镜像也可以配置加速器。这些都是常规操作刚开始别嫌麻烦。依赖下载反复中断的情况下重试几次往往就是浪费时间不如一开始就配置好。2. 环境依赖安装运行时版本对齐是第一个大坑2.1 三个运行时Python、Node.js、容器运行时Openclaw 最核心的运行时依赖有三个Python、Node.js 和容器运行时Docker 或兼容实现。注意我说的是“版本对齐”因为这三个组件不是互相独立的它们会协作完成任务调度和执行。Python 负责运行主服务和后台逻辑Node.js 负责构建管理后台的前端资源容器运行时负责创建隔离的任务执行环境。我在当前版本下实测比较稳的组合是Python 3.11、Node.js 20 LTS、Docker Engine 24 及以上。为什么 Python 不用 3.12我实际试过某些涉及 C 扩展的依赖在 3.12 下编译会报错需要手动装额外的构建工具折腾成本高。Node.js 倒是 18 和 20 都可以但 17、19 这类中间版本最好不要用依赖解析时比较容易出问题。2.2 安装依赖时的常见信号我把三个最容易踩的信号列在这里方便你对号入座现象可能原因处理方式Python 包安装报 Failed building wheel缺编译工具链或 Python 头文件安装系统级 build-essential、python3-dev前端依赖安装报 ERR! code ETARGET请求的版本不存在或源不同步检查版本号或把 registry 切回默认源再试容器命令显示客户端/服务器版本不匹配容器运行时升级或配置异常重启容器服务或检查 socket 权限提示安装运行时之前先用对应命令查看现有版本。很多机器上已经自带了旧版本不要盲目覆盖安装优先用虚拟环境或版本管理工具做隔离。2.3 为什么强烈建议用虚拟环境我的建议是不管你是不是第一次部署都先把 Python 虚拟环境建好。原因是 Openclaw 的依赖清单很长直接装进系统环境很容易和机器上已有项目发生版本冲突。举例来说你系统里可能有一个依赖 requests 2.x 的项目Openclaw 恰好锁定了 3.x这时候要么全局升级影响其他项目要么就得手动解决依赖冲突非常痛苦。虚拟环境一步就能解决这个问题python3.11 -m venv openclaw-env source openclaw-env/bin/activate后面的安装和启动操作都在这个环境里执行。Node.js 侧同理用版本管理工具管理 Node 版本需要切换时不会影响系统全局。这个习惯能让你在部署多个服务时保持环境干净出了问题时也能快速重建。3. 获取源码与理解项目结构先看清再动手3.1 拉取代码的正确姿势Openclaw 的代码仓库通常分多个分支main 分支是开发主线更新频繁但偶尔会有未修完的功能提交上去。我建议拉取稳定的 release 分支或最新的 release tag而不是直接 clone main。git clone -b stable 项目仓库地址 cd openclaw具体仓库地址以项目官方文档为准。这一步不要急拉下来之后先看一眼目录结构比直接执行安装脚本要稳妥得多。3.2 目录结构速览Openclaw 的代码目录结构大概是这样的openclaw/ ├── app/ # 主程序逻辑 ├── cli/ # 命令行入口和相关工具 ├── web/ # 管理后台前端源码 ├── config/ # 配置文件目录 ├── scripts/ # 安装、初始化、启动脚本 ├── tests/ # 自动化测试 ├── requirements.txt # Python 依赖清单 ├── package.json # Node.js 前端依赖清单 └── docker-compose.yml # 容器编排配置理解目录结构的意义在于部署时你需要改动的文件其实非常集中。日常运维主要关心 config 目录下的配置文件、scripts 里的控制脚本以及 docker-compose.yml如果用容器模式。app 目录和 web 目录通常不需要手动改动除非你要二次开发。3.3 配置、初始化、启动三件套Openclaw 的部署流程可以压缩成三件事复制配置、初始化数据库、启动服务。理解这三件事后面所有细节都能串起来。第一件把 config 目录下的示例配置复制一份改成自己的配置。第二件执行初始化脚本让数据库把基础表建好。第三件启动主服务。就这么简单剩下的都是这三件事在不同场景下的变体。4. 配置文件逐项解读与首次启动从命令行到浏览器4.1 先改好你的配置文件打开 config 目录下面的示例配置文件复制一份出来命名成自己的配置文件。在 Openclaw 里配置文件决定了服务监听地址、数据库连接方式、认证密钥、日志级别等核心行为我建议重点关注这几个配置项作用我的建议server.host服务监听地址本机调试用 127.0.0.1远程访问用 0.0.0.0server.port服务监听端口默认 8080注意不要和已有服务冲突database.type数据库类型单机体验用 sqlite生产建议切 PostgreSQLauth.secret_key认证密钥必须改成随机生成的长字符串log.level日志级别首次部署用 info排障时临时改 debug认证密钥这一步千万不能省。如果留着默认值管理后台的安全校验就是形同虚设。生成随机密钥可以直接在命令行完成openssl rand -hex 32把输出结果粘贴到配置文件的 auth.secret_key 字段里。这个密钥一旦部署完成就不要频繁更换否则已签发的登录态会全部失效。4.2 初始化数据库数据库初始化这一步Openclaw 提供了一个命令行脚本类似这样./scripts/ctl.sh db init它会在指定位置创建数据库文件并写入基础表结构包括用户表、任务表、执行记录表。执行成功后会有明显的成功提示。如果这一步报错多半是配置文件里的数据库路径或连接信息写错了。PostgreSQL 场景下初始化命令会先尝试连接数据库实例连接失败会直接报错。所以用 PostgreSQL 时要先把数据库实例本身准备好并为 Openclaw 创建独立的账号和库不建议直接用超级管理员账号。4.3 首次启动前台跑通再谈托管我第一次部署时图省事直接用了后台启动参数结果日志全丢进了黑洞出了问题只能干瞪眼。所以强烈建议第一次启动用前台模式source openclaw-env/bin/activate uvicorn app.main:app --host 0.0.0.0 --port 8080看到类似 Application startup complete 的日志说明服务已经正常起来了。此时打开浏览器访问 http://服务器IP:8080应该能看到管理后台的登录页。如果看不到登录页先检查启动参数里的 host 是不是 0.0.0.0再检查防火墙放行。4.4 用 systemd 把进程稳定托住前台跑通只是第一步你不可能一直开着终端窗。接下来用 systemd 把 Openclaw 托管成系统服务这样开机自启、崩溃重启都可以自动完成。先创建一个独立的运行用户然后写一个 service 文件[Unit] DescriptionOpenclaw Service Afternetwork.target [Service] Useropenclaw ExecStart/home/openclaw/openclaw-env/bin/uvicorn app.main:app --host 0.0.0.0 --port 8080 WorkingDirectory/home/openclaw/openclaw Restarton-failure RestartSec5 [Install] WantedBymulti-user.target注意 ExecStart 里必须使用虚拟环境下的二进制路径不要用系统环境否则依赖会乱。文件写好后sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw这个阶段结束后你的 Openclaw 已经能稳定运行可以随时重启机器而不需要手动拉起服务。5. 功能验证用一个真实的小任务走通全流程5.1 登录管理后台部署完成不等于部署成功能登录后台就算成功了一半。首次访问管理后台时用默认账号登录初始密码一般会在初始化日志中打印或者写在部署文档对应位置。第一次登录后系统会强制要求修改密码这一步不要跳过。登录后可以先在用户设置里把密钥、通知配置看一眼不用动它但至少知道这些设置在哪里。5.2 创建一个最简单的测试任务进入任务管理页面新建一个任务。我用来验证部署效果的任务写得很简单每 5 分钟采集一次当前主机的 CPU 和内存使用率并把结果写入一个日志文件。创建任务时需要关注几个字段任务名称、触发方式、执行命令或脚本、超时时间。首次测试时把超时时间设得宽松一些比如 300 秒避免任务还没跑完就被判定超时。触发方式可以先用手动触发等手动跑通了再切到定时触发。5.3 观察执行结果保存任务后手动触发一次。在任务详情页可以看到执行状态、开始时间、结束时间、日志输出。如果状态是 success说明整条链路已经通了主服务在运行、任务队列在工作、结果能正常落盘。这一步极其重要。很多人部署完看到登录页就以为万事大吉结果过了几天发现任务从来没执行过。真正能“跑通一个任务”才叫部署完成。别小看这个验证动作它能帮你把部署问题从业务问题里剥离出来。6. 从部署到稳定运行我踩过的三个坑6.1 浏览器打不开管理后台宿主地址别写死有次我在一台服务器上部署配置里明明写了 host0.0.0.0客户端却始终访问不了后台。当时我的排查链路是这样的先看端口监听状态确认服务进程确实在监听 8080。然后检查防火墙发现 8080 端口根本没放行。放行之后仍然不行再用本机 curl 测试本机能通说明问题不在服务本身。最后查了半天发现是 systemd 服务文件里启动参数又写了一遍 --host 127.0.0.1把配置文件里的设置覆盖了。这个坑的教训是配置文件里的 host 是一回事启动参数里的 host 是另一回事后者优先级更高。排查时两处都要看不能只盯着配置文件。6.2 容器任务一直重启环境变量拼写错了Openclaw 某些任务会以容器方式执行容器任务依赖数据库连接。有次我配置好一个任务后容器一直处于重启状态日志刷屏。我先用容器日志命令查看日志里面明确写着无法连接数据库。然后检查主服务的数据库连接配置没问题。再检查容器任务的环境变量发现我在某处配置里把数据库连接地址的环境变量名写错了——多了一个后缀。就是这个拼写错误导致整个容器启动即退出。这种错误最气人因为肉眼很难发现。我把这个教训总结成一句话容器任务的环境变量要从主配置文件里复制字段名不要凭记忆手打。6.3 任务运行到一半进程消失被系统杀了这是我的第二台部署机器上遇到的问题。任务一旦处理数据量较大的场景进程就会消失重启后又能跑一阵。先用系统日志过滤 OOM 关键字确认进程确实是被系统 OOM Killer 杀掉的。再用内存查看命令观察资源使用情况发现可用内存一直偏低。临时方案是加 swap 分区让系统有缓冲空间。长期方案是给容器任务设置内存上限让每个任务最多只能使用固定内存而不是挤占整机内存。比如在编排配置里给执行环境加上内存限制参数同时把任务并发数调到 1。4GB 内存的机器上压并发任务不如直接把并发数调小来得实在。7. 从“能跑”到“用好”部署完成后的几件事7.1 日志要会转储Openclaw 运行时间一长日志文件会膨胀到好几个 GB磁盘空间很容易被吃光。可以配置 logrotate 按天切分日志并保留最近若干天配置文件大致长这样/path/to/openclaw/logs/*.log { daily rotate 30 compress missingok notifempty }这个配置放在 /etc/logrotate.d/ 下系统会自动按天执行。日志转储这件事最好在部署当天就做不要等磁盘满了再想起来。7.2 配置和数据库要纳入备份Openclaw 最有价值的数据是配置文件、数据库和任务定义。数据库备份用最简单的定时导出即可建议每天全量备份一次每周再做一次归档备份文件放到独立目录。备份时注意配置文件和数据库的连接信息都带有敏感内容备份文件要做好权限控制避免被非授权用户读取。最好能加密存档至少也要设置严格的文件权限。7.3 下一篇想写什么这篇把部署讲完了但 Openclaw 真正的深度不在部署而在于怎么编排任务。我打算在下一篇里写任务编排的核心机制触发方式怎么选、变量怎么传递、执行结果怎么回调以及如何把外部系统的 API 接进来。如果你也在折腾 Openclaw欢迎在评论区聊聊你的机器配置和踩过的坑我先整理一下再说。