Ubuntu部署OpenClaw：从零安装到Ollama本地模型对接全攻略

前两天帮同事在一台Ubuntu 24.04的机器上部署OpenClaw，从拉代码到服务跑起来，零零散散踩了七八个坑。网上关于OpenClaw的教程不算少，但要么是官方README的复读，要么只讲Windows环境怎么装，真正卡人的地方——比如依赖装到一半报错、配置文件写了不生效、本地模型接不上——基本没人系统讲。这篇就把我在Ubuntu上从零安装OpenClaw的全过程记录下来，包括环境准备、安装命令、报错定位、Ollama本地模型对接、Skill扩展实践。如果你也打算在自己的Linux机器上搭一个既能接云端API、也能跑本地模型、还能通过Skill扩展能力的AI智能体助手，这篇能帮你省下好几个晚上的试错时间。

1. 安装前先理清环境：为什么Ubuntu和Node.js是主战场

1.1 我为什么把OpenClaw放在Ubuntu上跑

先说选系统。OpenClaw本身是跨平台的开源AI智能体框架，Windows、macOS、Linux都能跑，但如果真想把它当常驻服务用——比如跑定时任务、监听文件目录、对接开发机或NAS——我强烈建议放在Linux上，原因有三点。

第一，Ubuntu的权限体系和systemd配合得很好，服务开机自启、崩溃自动重启、日志集中管理都很顺手。Windows上虽然也能通过任务计划程序实现类似效果，但体验真不在一个级别，尤其你还要处理登录会话、锁屏状态对后台进程的影响。第二，OpenClaw依赖链里有很多需要原生编译的组件，Linux下的gcc、python3、pkg-config一套装齐，基本不会遇到Windows上那种"缺少VC++ Build Tools"或者"找不到gcc"的尴尬报错。第三，服务器环境常年没有图形界面，SSH进去就能管理，内存和CPU占用也能压得很低，把资源留给模型推理。

当然，用桌面版Ubuntu也一样跑，不影响安装逻辑。只是部署完成后不建议把OpenClaw挂在前台终端里，后面会专门讲怎么用systemd或pm2把它变成"系统服务"。

1.2 四样前置工具装齐：NVM、Git、Python、包管理器

OpenClaw本质上是Node.js生态的项目，所以第一优先级是保证Node版本符合要求。这里强烈建议不要直接去官网下deb包，而是用nvm管理Node版本。原因很现实：OpenClaw对Node的major版本有明确要求，报错里经常出现ERR! engine这类提示。nvm可以让你在node 20、node 22这些版本之间一条命令切换，重装依赖也很快。

安装nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22

装完Node，还要装git和Python环境。Python不一定每次都用上，但OpenClaw的某些Skill或编译依赖会调用python3，提前装好能防止中途卡住。

sudo apt update sudo apt install -y git curl wget python3 python3-pip pkg-config build-essential

有个很多人忽略的细节：如果系统之前装过其他版本的Node，node -v输出正常但npm -v报错，八成是PATH里残留了旧npm链接。处理办法是清理掉which npm指向的残留路径，再重开一个终端。我这次就遇到了，一开始还以为是nvm没装好。

提示：以上命令是一个最基础的环境基线，不是所有场景都要全部执行，但装了不亏。如果是精简版Ubuntu服务器，建议先把apt源更新完再继续。

2. OpenClaw安装流程全拆解：从拉取代码到首次启动

2.1 获取源码：版本选择和目录规划一起说

环境准备好之后，第一步是拿OpenClaw源码。OpenClaw是开源项目，GitHub官方仓库里能找到release和源码。有过线上经验的朋友应该懂，我不建议直接clone默认分支，因为main分支经常是正在开发的版本，依赖变动频繁。建议先看仓库的Tags列表，选一个带v前缀的稳定发行版，如果拿不准，也可以走官方Release包或npm全局安装的发布版本，省去一部分编译环节。

目录规划上，建议单独建一个OpenClaw数据目录，比如/opt/openclaw，把程序文件和数据分开。为什么不用用户目录？因为后面如果用systemd托管，服务进程会以指定用户运行，数据目录放/opt下更好控制权限，也不会因为普通用户目录里的异常文件干扰运行。如果只是在个人电脑上折腾，放在~/openclaw也可以，但至少别把配置文件和日志文件混在源码目录里，否则升级代码时容易误删配置。

2.2 依赖安装：npm和pnpm怎么选，装到一半失败怎么办

OpenClaw的依赖体量不小。拉完代码进目录，我建议用pnpm而不是npm。pnpm的硬链接机制对这类依赖很多的Node项目效果明显：安装更快，磁盘占用更低，node_modules结构更干净。而且很多开源项目的package.json里本身就带packageManager: "pnpm@9.x"这样的字段，说明官方推荐用pnpm。

安装pnpm：

npm install -g pnpm

然后在项目目录执行：

pnpm install

这一步大概率会遇到问题。最常见的是网络原因导致某些包下载失败，解决办法是设置镜像源：

pnpm config set registry https://registry.npmmirror.com

再重新安装。如果卡在某个包重试几次都不行，不要反复执行install，先把pnpm缓存清理一下，再单独装那个失败的包，基本都能定位出来。

还有个容易忽略的点：部分原生依赖需要获取预编译二进制，失败时报错通常带node-gyp、python或gcc字样。这就是前面让提前装build-essential的原因，装完再执行pnpm install，一般就过去了。

2.3 初始化配置：第一次启动前需要准备哪些参数

依赖装完，项目目录下会有可执行入口，大部分情况可以用npx openclaw来操作。第一次启动前，最好先把配置初始化好。OpenClaw提供openclaw init这样的交互式初始化命令，会在用户目录或项目目录生成一个配置文件，我这次生成的是openclaw.config.json，交互流程会依次问几个关键问题。

• 模型接入方式：接云端API还是本地模型
• API Key：对应服务商的密钥
• 模型名称：比如GPT系列、Claude系列或本地Qwen
• 存储位置和日志目录

有几个参数强烈建议手动改，尤其是state_dir和log_dir。很多人一路回车用默认值，结果日志散落在临时目录，等出问题想排查时日志早没了。这两个路径必须固定到稳定目录，比如/var/lib/openclaw和/var/log/openclaw，或者统一放用户目录下的.openclaw文件夹。

初始化完成后，用openclaw start启动，看到类似"OpenClaw is running"的输出，基础安装就算成功了。

3. 安装和启动阶段最常踩的五个坑：报错原文与修复步骤

3.1 Node版本不符：ERR! engine这种报错怎么定位

这类报错最容易劝退新手。报错里出现ERR! engine，后面通常跟着node@>=20或Unsupported engine字样，原因就是OpenClaw新版本要求Node 20以上，而系统默认还是Node 16或18。不要试图改package.json的engines字段，改了也跑不起来，因为代码里可能真的用了高版本特性；更不要用--ignore-engines强跳，那会在运行时出现各种离奇错误。

正确解法就是之前说的nvm。先看当前版本：

node -v

如果版本太低就切换：

nvm install 22 nvm use 22 node -v

如果切换后npm -v还是老的，记得执行hash -r清命令缓存，或者重开终端。这个问题的核心不是版本本身，而是PATH里真正生效的Node不是你以为的那个。

3.2 依赖下载超时或校验失败：换镜像源和重试策略

pnpm install过程中常见的几种报错，我整理成一份速查表：

实际经验是，遇到网络类错误别急着反复install，先把pnpm缓存清理干净：

pnpm store prune

再重新装。这种"重试三次都不行、清理缓存后一把过"的场景我遇到太多次了。

3.3 配置文件语法错误导致服务起不来

初始化生成的配置文件是JSON格式。JSON语法很死，多一个逗号、少一个括号，解析器直接罢工。我在改配置时经常想用注释，但JSON本身不支持注释，保存后一旦被程序读取就容易报Unexpected token /之类的错误。

我的建议是：如果只是临时调整，看下当前版本是否支持YAML格式；如果确定用JSON，不要手写，用工具生成或修完用jq验证：

jq . openclaw.config.json

能正常输出格式化结果，说明语法没问题。启动失败时优先看日志，日志目录通常在初始化时指定的log_dir，用tail -f观察实时输出，比把服务挂在前台瞎猜高效得多。

3.4 环境变量加载顺序问题：.env文件没生效

OpenClaw支持用.env文件存放敏感配置，比如API Key。这里有个非常容易踩的点：它的配置优先级一般是"系统环境变量 > .env文件 > 配置文件默认值"。如果你已经在shell里export过某个变量，后面改.env会发现改了半天没反应，其实是被环境变量覆盖了。

排查方法很简单：

env | grep -i openclaw

看有没有残留变量。如果确定要用.env，就让启动服务的方式统一。比如systemd启动时通过EnvironmentFile指定加载某个env文件，就不会和shell环境冲突。我自己的习惯是所有密钥放.env，但不在shell里export同名变量，两套机制分开，避免互相覆盖。

3.5 端口被占用和进程管理：用systemd和pm2哪种更省心

OpenClaw默认会在本地开一个HTTP端口，启动时报EADDRINUSE说明端口被占了。用：

lsof -i :端口号

查一下占用者，停掉或者给OpenClaw换端口。

服务跑起来之后，千万别用nohup裸奔。我推荐用systemd注册成服务，Ubuntu自带，开机自启，崩溃自动拉起。写一个unit文件放在/etc/systemd/system/openclaw.service：

[Unit] Description=OpenClaw Service After=network.target [Service] User=root WorkingDirectory=/opt/openclaw ExecStart=/usr/bin/node /opt/openclaw/src/cli.js start Restart=always RestartSec=5 Environment=NODE_ENV=production [Install] WantedBy=multi-user.target

然后：

sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw

如果用pm2，命令更简单：

pm2 start src/cli.js --name openclaw pm2 save

两种都用过之后，我的倾向是：生产机用systemd，个人调试机用pm2。pm2的好处是日志聚合方便、命令行友好，坏处是多一层Node进程依赖；systemd更原生，但日志要用journalctl看，一开始不太习惯。

4. 把OpenClaw接到本地模型：Ollama与Qwen2.5的实战对接

4.1 先装Ollama再拉模型：为什么本地小模型适合日常调试

前面反复提到OpenClaw能接本地模型，最省心的本地模型供给方式就是Ollama。Ollama是一个本地大模型运行时，一条命令装好，一条命令拉模型，对外提供一个兼容OpenAI格式的API端点，很多AI应用都能直接对接。

安装Ollama：

curl -fsSL https://ollama.com/install.sh | sh

拉一个Qwen2.5的3B模型：

ollama pull qwen2.5:3b

为什么选3B这个档位？因为它只有几个GB大小，普通CPU或入门显卡就能跑，日常调试OpenClaw链路已经够用。有时候改了一行配置，想快速验证Skill逻辑通不通，用云端模型既等接口又花费用，本地小模型就是完美的调试后端。真要跑复杂生产任务，再切回云端API不迟。

4.2 修改OpenClaw配置对接本地API端点

OpenClaw配置里接模型的核心参数有四个：provider、base_url、api_key、model。接Ollama时，provider填ollama或openai兼容模式，base_url填http://127.0.0.1:11434/v1，api_key可以随便填一个，因为本地服务不做校验，model填qwen2.5:3b。

一个常见的配置片段长这样：

{ "model": { "provider": "ollama", "base_url": "http://127.0.0.1:11434/v1", "api_key": "ollama", "model": "qwen2.5:3b" } }

改完重启服务。如果还连不上，先自己curl测试：

curl http://127.0.0.1:11434/v1/models

能列出模型列表，说明服务正常，问题在OpenClaw配置；返回连接拒绝，说明Ollama没起来或端口不对。

4.3 Skill扩展：让OpenClaw能调用工具和处理文件

OpenClaw比较吸引人的是Skill机制。简单理解，Skill就是一组可以被AI智能体调用的函数，让OpenClaw不只是聊天，还能执行命令、读写文件、调用外部API。Skill目录通常在~/.openclaw/skills下，每个Skill是一个独立子目录，里面包含skill.yaml描述文件和一段可执行脚本。

我这次写了一个"查询系统资源"的Skill。skill.yaml里指定名称、描述和入口：

name: sysinfo description: 查询CPU和内存使用情况 entrypoint: sysinfo.sh

然后在同级目录放一个sysinfo.sh：

#!/bin/bash echo "CPU使用率: $(top -bn1 | grep 'Cpu(s)' | awk '{print $2}')%" echo "内存使用: $(free -h | awk 'NR==2{print $3"/"$2}')"

Skill被加载后，启动OpenClaw时日志里会看到Skill loaded: sysinfo这样的提示。之后对话里只要提到类似"看看系统负载"，模型会结合Skill描述自动选择合适的工具去调用。这个机制调试起来特别直观，能感受到智能体在真正干活，而不是聊天机器人。

5. 跨设备部署的几个补充思路：Windows Companion和手机端

5.1 OpenClaw Windows Companion解决什么问题

如果你主力机是Windows，又希望OpenClaw能操作Windows上的资源——比如读取本地文件、控制浏览器、调用Windows应用程序——可以单独运行一个Companion组件。Windows Companion本质上是一个位于Windows端的轻量服务，它与Linux上的OpenClaw主进程通过本地网络或配置关联，把Windows的系统能力暴露给主程序调用。典型场景是：Ubuntu服务器上跑OpenClaw做自动化编排，Windows主机上做文件浏览和浏览器自动化。

配置方式不算复杂，先在Windows上下载Companion安装包，启动后它会给出一个访问地址或内网端口，然后在Linux端的OpenClaw配置里填上这个地址作为连接端点。需要注意防火墙放行对应端口。

5.2 Android上用Termux部署的可行性

手机上通过Termux装OpenClaw确实也有人在做。Termux是Android上的Linux终端模拟器，可以借助它安装nodejs-lts，然后走类似流程装OpenClaw。不过我的实际建议是：手机部署适合演示或轻量使用，真不适合当生产环境。手机CPU和内存有限，系统后台限制严格，长时间常驻进程发热又耗电，Ollama这种大模型在手机上跑体验也一般。真要折腾，把手机当作OpenClaw的远程入口更现实——用终端或客户端连到服务器上的OpenClaw服务，逻辑都在服务器端跑，手机只是个输入输出设备。

6. 最后想说的几点经验和建议

整趟装下来，最大的感受是：OpenClaw的安装本身不算复杂，真正耗时间的是环境不一致导致的隐性坑。反复刷屏的报错大部分集中在Node版本、依赖下载、配置文件这三处，这三个点提前处理好，后面就很顺。

几个我自己的习惯，供参考。第一，生产环境不要追新，稳定版本能用就别频繁换main分支，我见过好几个朋友升级后依赖全坏。第二，配置文件和日志路径一定要显式指定，别依赖默认值，不然换环境或重装系统，以前的配置和数据很容易找不回来。第三，接本地模型调试、接云端模型干活，把Ollama当调试后端，既能省钱，逻辑链路验证也更快。

如果后面继续折腾，我会优先研究Skill编排能力，把OpenClaw和NAS、构建机任务串起来。这次先记到这里，希望你安装时能比我省下至少一半的时间。