前两天帮同事在一台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这些版本之间一条命令切换重装依赖也很快。安装nvmcurl -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有个很多人忽略的细节如果系统之前装过其他版本的Nodenode -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: pnpm9.x这样的字段说明官方推荐用pnpm。安装pnpmnpm 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后面通常跟着node20或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过程中常见的几种报错我整理成一份速查表报错关键词原因处理办法ETIMEDOUT网络连接超时设置镜像源后重试ERR_PNPM_NO_MATCHING_VERSION版本锁定冲突清理lockfile后重装Integrity check failed下载包校验不一致删除缓存文件重新下载ENOENT依赖路径不存在确认当前目录是否为项目根目录实际经验是遇到网络类错误别急着反复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] DescriptionOpenClaw Service Afternetwork.target [Service] Userroot WorkingDirectory/opt/openclaw ExecStart/usr/bin/node /opt/openclaw/src/cli.js start Restartalways RestartSec5 EnvironmentNODE_ENVproduction [Install] WantedBymulti-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应用都能直接对接。安装Ollamacurl -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/v1api_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 NR2{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、构建机任务串起来。这次先记到这里希望你安装时能比我省下至少一半的时间。
