最近我终于把吃灰的 Ubuntu 机器重新翻了出来，认认真真把 OpenClaw 从头到尾装了一遍。OpenClaw 是一个开源的本地智能助理框架，最大的特点就是数据自持，对话记录、任务状态和配置全部落在你自己的机器上，而不是云端。安装过程本身谈不上难，但官方文档写得太简略，真正跑通靠的是反复试错。这篇文章就是我完整的安装记录，从环境准备到 systemd 托管，再到我踩过的所有坑和排查方法，给想在 Ubuntu 上部署 OpenClaw 的同学一份可以直接照着做的避坑指南。
1. 为什么选 OpenClaw 和 Ubuntu，装之前想清楚
1.1 OpenClaw 是什么：一句话说清楚
OpenClaw 是一个可以常驻在机器上的智能体框架，它解决的问题是"如何让一台机器按你的意图自动干活"。传统脚本是写死流程的，比如每天凌晨三点备份一下某个目录，而 OpenClaw 不一样，你把意图告诉它，它会自己拆解任务、调用对应工具、把结果整理回来。日程提醒、文件整理、网页信息抓取、定时触发脚本、语音交互这些都能接进去。
它本身不内置大模型，而是通过配置模型服务的 API 来获得理解和生成能力，也就是说模型能力可以换成任意兼容的服务商，也可以接本地跑的小模型。这个设计很灵活，但也意味着安装完成后还要花时间配置模型和插件，不是装上就万事大吉的。我建议把它理解成一个"大脑中枢"，插件是手脚，模型是知识储备，三者都到位了才好用。
1.2 为什么部署在 Ubuntu 上更合适
我用 Ubuntu 跑 OpenClaw，是认真对比过的。首先是常驻能力，Ubuntu 自带 systemd，服务崩溃了能自动拉起，开机自启只需要写一个 service 文件，这在 Windows 上要么装额外工具，要么配置计划任务，远没有 Linux 顺手。其次是无头运行，家里那台小主机没有屏幕，SSH 进去就能维护，图形界面完全不必要，资源也更省。
再就是插件隔离。OpenClaw 很多插件依赖容器运行时做隔离，Linux 下容器和 systemd 的结合非常顺畅，日志统一走 journald，排障时一条命令就能看到全部输出。综合下来，Ubuntu 是折腾这类自托管服务最省心的环境。
1.3 装之前要认清的三件事
第一，OpenClaw 的核心是框架，不是成品应用，你得自己配置模型密钥、装插件、调权限。第二，它要求一定的命令行基础，起码要会 cd、ls、systemctl、journalctl 这几个命令，不然排障会很痛苦。第三，硬件上有底线要求，实测 2GB 内存的机器跑起来很紧张，4GB 才比较从容。认清这三点再动手，能少一半的折腾。
2. 环境准备：先把这个坑踩平再装本体
2.1 系统版本和基础设置
推荐 Ubuntu 22.04 或 24.04 的 LTS 版本，不要用非 LTS，软件源和系统库的完整度都不一样，装依赖时差距很明显。到手先做两件事：
sudo apt update && sudo apt upgrade -y sudo timedatectl set-timezone Asia/Shanghai时区看起来无关紧要，但 OpenClaw 的任务调度、日志时间戳都依赖系统时间。我当时忽略了这一步，后来排查定时任务时发现日志时间和实际差了 8 个小时，白白浪费了大半天。先设好时区，后面所有时间相关问题都会顺畅很多。
内存方面，如果机器只有 2GB，建议先加 swap。不然编译原生依赖或者同时跑多个插件时，系统很容易 OOM，表现为进程突然消失，日志里只有一句 killed。加 swap 很简单，用系统自带的 swapfile 就行，2GB 内存配 4GB swap 是我实测比较舒服的组合。
2.2 Node.js 与 Python 环境：版本老坑最多
OpenClaw 的核心是 Node.js 写的，对运行时版本有要求。Ubuntu 软件源里自带的 nodejs 版本往往偏老，尤其是 20.04 默认才 10.x，跑 OpenClaw 直接报语法错误。正确做法是使用 NodeSource 提供的安装源装 LTS 版本：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v装完先打印版本号确认，再继续往下走。这一步慢一点没关系，后面省的事远大于这点时间。
Python 环境同样要处理。Ubuntu 24.04 默认 Python 3.12，够用，但直接往系统 Python 里装包会碰到 externallly-managed-environment 的报错，这是新版系统的保护机制，不是故障。正确做法是建一个独立虚拟环境：
sudo apt install -y python3-venv python3-pip python3 -m venv ~/openclaw-venv后面所有 Python 依赖都装到这个虚拟环境里，不要碰系统 Python，不然哪天系统升级把依赖搞崩了，想哭都找不到地方哭。
2.3 Docker 与基础工具：一个都不能少
OpenClaw 很多插件用容器隔离运行，Docker 属于刚需。安装直接用 apt 最省事：
sudo apt install -y docker.io sudo systemctl enable --now docker sudo usermod -aG docker $USER注意 usermod 之后要重新登录一次，docker 命令才能免 sudo 使用。如果不重登，会一直卡在 permission denied 上，这是高频坑。
除了 Docker，下面这些基础工具建议一次性装齐：
| 工具 | 用途 | 安装命令 |
|---|---|---|
| git | 拉取源码与后续升级 | sudo apt install -y git |
| build-essential | 编译部分原生依赖 | sudo apt install -y build-essential |
| ffmpeg | 音频转写与媒体处理插件 | sudo apt install -y ffmpeg |
| sqlite3 | 本地数据库操作与排障 | sudo apt install -y sqlite3 |
| curl | 接口调试与下载验证 | sudo apt install -y curl |
这些工具看着不起眼，缺哪个都不会立刻报错，但等你装某个插件启动失败时，日志里一串依赖缺失的提示才会让你回头补，浪费时间。
3. 正式安装：从源码到 systemd 常驻服务
3.1 获取源码与安装依赖
环境确认没问题后，开始装本体。我建议把代码放在 /opt/openclaw 目录，跟普通用户的家目录分开，权限结构更清晰：
sudo mkdir -p /opt/openclaw sudo chown $USER:$USER /opt/openclaw git clone <OpenClaw 仓库地址> /opt/openclaw cd /opt/openclaw npm ci注意这里用的是 npm ci 而不是 npm install。npm ci 会严格按照 package-lock.json 安装依赖，保证版本完全一致，最大程度避免"别人能跑你跑不了"的问题。第一次安装耗时取决于网络环境，耐心等，中途不要中断，否则 node_modules 状态会非常混乱。
3.2 配置文件与数据目录
依赖装完后，项目里一般有配置模板，复制一份再改：
cp config.example.yaml config.yaml配置文件里最关键的几项是模型服务密钥、监听端口、数据目录。我的配置大致长这样：
server: host: 0.0.0.0 port: 8080 data: directory: /var/lib/openclaw model: provider: openai-compatible api_key: 你的模型服务密钥 base_url: http://localhost:11434/v1端口默认 8080，如果机器上已经跑了其他服务占了 8080，改成 8787 之类的空闲端口，改完用 ss 验证一下。数据目录我建议指定到 /var/lib/openclaw 这类独立路径，而不是留在默认的家目录，这样备份时只同步一个目录就全搞定。
改完配置别急着启动，先把数据目录建好并确认属主，否则启动时会直接报权限错误：
sudo mkdir -p /var/lib/openclaw sudo chown -R $USER:$USER /var/lib/openclaw ls -ld /var/lib/openclaw3.3 首次启动与验证
我习惯先手动启动一次，确认日志正常再交给 systemd，这样报错容易看到：
cd /opt/openclaw npm run start看到日志里出现类似 server listening on 0.0.0.0:8080 的输出，说明服务已经起来了。再开一个终端验证接口：
curl http://localhost:8080/health返回 JSON 里带 ok 或者 status 字段就是正常的。验证通过后 Ctrl+C 停掉，进入下一步托管。
也可以在这里把模型密钥写进环境变量文件，比如在 /opt/openclaw/.env 里存一行，避免密钥直接出现在命令行历史或者 systemd 的进程信息里，干净也相对安全。
3.4 用 systemd 托管成常驻服务
手动运行会随终端退出而断开，所以一定要做成 systemd 服务。创建 /etc/systemd/system/openclaw.service：
[Unit] Description=OpenClaw Service After=network.target docker.service [Service] Type=simple User=你的用户名 WorkingDirectory=/opt/openclaw EnvironmentFile=/opt/openclaw/.env ExecStart=/usr/bin/npm run start Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target保存后依次执行：
sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclawstatus 显示 active (running) 就成了。这里有两个关键细节。第一，ExecStart 里我写的是 npm 的绝对路径，用 which npm 查一下填进去，因为 systemd 的环境和登录终端不一样，直接写 npm 可能找不到命令。第二，EnvironmentFile 指向的文件必须真实存在，哪怕只有一行注释也行，文件缺失会导致服务启动失败，这是个隐蔽坑。
4. 避坑实战：高频问题与排查思路
4.1 权限问题：最不起眼也最致命
我第一次装的时候图省事，用 root 跑了初始化，结果数据目录全部变成了 root 属主。后来换普通用户启动，想写数据目录直接 permission denied，数据库初始化失败，日志只给一句很笼统的 error，完全看不出来是哪里的问题。
排查方法很简单，启动前先确认目录属主：
ls -ld /opt/openclaw /var/lib/openclaw属主不对就 chown 回来。这里我强烈建议：这类常驻服务永远用普通用户跑，不要用 root。用 root 启动后创建的缓存、日志、状态文件全是 root 属主，后面换回普通用户就是一堆权限错乱，处理起来比重新安装还麻烦。
4.2 版本与依赖问题：报错要往版本上想
第二个高频坑是 Node 版本偏老，报错表现是启动时抛出一堆语法错误。如果你的机器以前装过旧版 Node，建议先清理干净再装新版：
sudo apt remove -y nodejs npm然后回到 2.2 节用 NodeSource 的方式重新装。
另一个常见问题是 npm 安装依赖时卡住或者超时。这个跟网络环境有很大关系，我实测官方源经常等到超时，后来在项目目录的 .npmrc 里配置了镜像源，下载速度明显改善。改完镜像之后如果还遇到奇怪的安装错误，先执行 npm cache clean --force 清理缓存再重试，很多时候是半截下载的缓存包在捣乱。
Python 依赖的问题前面提过，集中在 externallly-managed-environment 报错，解决办法是使用虚拟环境，不要试图往系统 Python 里强塞包。
4.3 端口、防火墙与 systemd 细节
服务起来了但外部访问不了，这是另一类高频问题。先查监听端口：
ss -lntp | grep 8080有监听但外部不通，大概率是防火墙拦截。Ubuntu 自带的 ufw 如果处于开启状态，需要放行对应端口：
sudo ufw allow 8080/tcpsystemd 这边还有一个隐蔽问题：修改了配置之后，需要 systemctl restart openclaw 而不是只 reload，否则服务跑的还是旧配置。另外 EnvironmentFile 指向的 .env 文件如果缺失，服务会启动失败，这个我在 3.4 节提过一次，这里再说一遍，因为真遇到了很容易一头雾水。
还有时区问题导致的定时任务偏差，以及缺 ffmpeg 等系统工具导致插件启动失败，这类问题报错信息往往不直观，需要结合日志和依赖清单逐一排除。
4.4 问题速查表
把高频问题和排查思路整理成一张表，出问题先对号入座：
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 启动报 Permission denied | 数据目录属主不对 | chown 给当前用户 |
| 启动直接抛语法错误 | Node 版本过旧 | 清理后用 NodeSource 装 LTS |
| npm 安装卡住或超时 | 源访问缓慢 | 配置镜像源并清理缓存 |
| 外部访问不了服务 | ufw 拦截 | ufw allow 对应端口 |
| systemd 启动失败 | .env 文件缺失 | 先创建 .env 文件 |
| 定时任务时间不对 | 时区未设置 | timedatectl 设置时区 |
| 插件启动报缺库 | 系统工具不齐 | 补装 ffmpeg、build-essential 等 |
我把这张表贴在服务器的目录备忘里，后来再排障基本都是先过一遍表，再往深里挖，效率高了很多。
5. 运行期维护：日志、备份、升级与调优
5.1 日志与运行状态查看
交给 systemd 托管之后，所有日志统一进 journald，查看命令：
journalctl -u openclaw -f-f 是实时跟踪，排查问题最常用。要看某段时间的日志，加 --since 参数：
journalctl -u openclaw --since "2025-01-01 00:00:00"日志量大的时候要防止把系统盘写满，在 /etc/systemd/journald.conf 里设置 SystemMaxUse=500M，然后重启 journald 生效。我自己的习惯是额外开启 OpenClaw 的日志文件输出，访问日志和错误日志分开，排查时直接对文件做 grep，比在 journald 里翻方便很多。
5.2 备份、升级与回滚
OpenClaw 的数据无非两块，配置文件和数据库目录。备份用 rsync 同步到另一块磁盘或者备份机：
rsync -av /opt/openclaw/config.yaml /var/lib/openclaw /backup/openclaw/升级流程我建议固定下来，每次照做：
cd /opt/openclaw git pull npm ci sudo systemctl restart openclaw先备份再升级，这是底线。如果新版本有问题，因为代码在 git 里，切回上一个 tag 再重启即可。我经历过一次升级后插件兼容性出问题，回滚到旧版本前后不到五分钟，前提就是升级前老老实实做了备份。
5.3 资源占用与调优心得
实测跑 OpenClaw 本体加三个常用插件，内存占用大约 1.5GB 到 2GB，多任务并发时能到 3GB 上下。CPU 平时非常低，但语音转写或者批量抓取时会明显拉高。机器内存紧张的话，建议开启 swap 并把数据目录放到 SSD 上，数据库的读写体验会明显不一样。
数据目录不要放在 /tmp 或者内存文件系统里，重启就清空，别贪图那点读写速度，可靠性才是自托管的第一原则。另外数据库体积增长之后，偶尔手动优化一下，把旧任务记录归档到别处，能保持日常操作不卡顿。
6. 卸载清理：不留半残状态
卸载这事看着简单，但很多人卸载不干净，导致以后想重装时各种奇怪残留。干净卸载的步骤是先停服务再禁用开机自启：
sudo systemctl stop openclaw sudo systemctl disable openclaw然后删除程序和配置：
sudo rm -rf /opt/openclaw /etc/systemd/system/openclaw.service rm -rf /var/lib/openclaw ~/.openclaw sudo systemctl daemon-reload如果还装过 Docker 插件镜像，用 docker system prune 一并清理。我的建议是：卸载前先把数据目录完整拷贝一份留底，万一以后想重新部署，配置和数据都还在，恢复成本几乎为零。
装完到现在已经跑了大半个月，最深的感受是 OpenClaw 本身安装真不难，难的是环境里那些"看不见的坑"。Node 版本、目录权限、时区、防火墙、systemd 环境变量，每一个单独看都是小事，串在一起就能消耗掉一整天。我个人实际操作中的体会是，先把环境理清楚再动官方教程，这个顺序不能反。最后分享一个小技巧，每完成一个步骤就停下来验证它的结果，装完 Node 就打印版本号，配完端口就用 curl 探一下，这样后面出了问题，你永远知道该从哪一步开始排查，而不是对着报错瞎猜。
