Ubuntu源码部署OpenClaw实战：从环境配置到踩坑排查全记录

简介这是一份针对 Ubuntu 24.04 安装 OpenClaw 3.2 时典型故障整理的源码与排错方案包面向开发者、运维人员及 AI 应用搭建者压缩包仅 8KB包含 HTML 说明页、InsCode 配置和 Git 忽略规则等 3 个文件结构精简而紧扣部署场景。目前已有 116 人学习使用。内容围绕两个高频问题展开选择千问大模型后登录页面卡住以及 systemctl 命令执行时报“找不到介质”对应包含关闭浏览器重开 qwen 地址、创建服务文件、补装 nvm、升级 Node.js 并重跑安装脚本等处理办法步骤清晰可复现。同时附带 Ubuntu、OpenClaw、npm 与 Node.js 的环境版本信息以及安装教程和官方文档链接能帮助读者快速复现环境、定位根因并完成修复适合部署 OpenClaw 遇到同类问题时直接对照使用。 在我连着折腾了三天 Ubuntu 上的 OpenClaw 之后最想说的第一句话是这玩意儿本身不复杂复杂的是它默认假设你已经把环境准备好了偏偏这个假设在 Linux 上基本不成立。我这次是从源码方式部署的最后拿到了一套可以稳定跑的源码目录也把过程中遇到的那些报错一个个按死。这篇文章就是把我的实操记录整理出来包括安装思路、源码部署的完整步骤、遇到的典型报错和排查方法以及让源码真正可运行的配置细节。如果你正在 Ubuntu 上装 OpenClaw或者装完了但跑不起来这篇文章应该能帮你省掉不少时间。需要说明的是OpenClaw 这个项目迭代很快不同版本之间的配置字段、目录结构可能有差异。我下面写的内容基于我实际使用的版本你在操作时如果遇到字段名对不上优先以你拉下来的源码里的示例配置为准排查思路是通用的。1. 部署前要想清楚的几件事1.1 OpenClaw 到底是什么简单说OpenClaw 是一个开源的个人 AI 智能体框架核心思路是给你一个可以自己掌控的 AI 助手底座。它跟那种网页上聊两句的 AI 不一样OpenClaw 是一个跑在你自己的机器上的服务你可以给它接入不同的消息渠道比如微信、飞书这类 IM也可以配置不同的模型后端云端 API 或者本地模型还可以通过 skill 机制让它调用工具、执行任务。选择在 Ubuntu 上部署好处很明显Ubuntu 作为服务器系统很干净没有桌面环境的资源占用跑这种常驻服务比 Windows 省心得多而且 systemd 做守护进程、日志管理都很方便。坏处也很明显——官方文档里很多步骤默认你在 macOS 或者 Docker 环境直接照搬到 Ubuntu 源码部署时各种环境问题就冒出来了。1.2 为什么我坚持用源码方式部署官方其实提供了一键脚本和容器化部署的路子但我这次还是选了源码部署原因有三第一可控性强。一键脚本封装得太好出了问题你根本不知道它装了什么、改了什么。源码部署每一步都看得见排查问题时能直接看到依赖树和日志。第二便于二次开发。OpenClaw 本来就是开源项目源码部署可以随时改 skill、改配置、甚至改核心逻辑。你拿到的是一个可以继续改的工程不是一个黑盒。第三资源占用小。容器化部署虽然隔离性好但多了一层虚拟化开销。在一台配置不高的机器上源码部署的启动速度和内存占用都更友好。当然源码部署也有代价就是环境问题全得自己扛。接下来我会把环境和依赖逐个说清楚。2. 环境准备Ubuntu 下的依赖安装2.1 Node.js 版本是第一个坑OpenClaw 的服务端是 Node.js 写的所以第一个前置条件就是 Node.js。这里我踩了一个非常典型的坑Ubuntu 自带的 apt 源里 Node.js 版本普遍偏老而 OpenClaw 对 Node.js 版本有要求版本太老会直接装不上依赖或者装上了启动就报语法错误。我建议用 nvm 安装 Node.js而不是用 apt。nvm 的好处是可以随意切换版本之后 OpenClaw 升级要求新版本时不用重新折腾系统。具体操作curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20Node.js 20 是 LTS 版本我当时用的就是 20.x稳定跑了一段时间。如果你拉到的源码版本比较新建议看一眼项目里的package.json的engines字段那里写了要求的 Node.js 版本范围。另外顺手把 npm 源换一下不然依赖下载那一步能卡到你怀疑人生npm config set registry https://registry.npmmirror.com注意nvm 安装脚本走的是 GitHub如果网络不稳导致下载失败多试几次或者直接用系统包管理器安装 NodeSource 维护的二进制包效果一样。2.2 克隆源码与安装依赖源码获取这块直接从项目的官方仓库拉就行。我习惯把这类服务放在/opt或~/apps下面避免跟用户目录混在一起mkdir -p ~/apps cd ~/apps git clone https://github.com/OpenClaw/OpenClaw.git cd OpenClaw拉下来之后先别急着npm install我建议先看一眼目录结构确认入口文件和配置样例在哪里。我当时拉下来的版本里根目录有package.json配置样例是config.example.json之类的文件。先了解结构再动手后面排错会轻松很多。然后是安装依赖。这一步是问题高发区常见问题有权限报错、网络超时、版本冲突等npm install如果你执行时遇到EACCES权限错误多半是 npm 的全局目录权限问题不要在 root 下硬跑用 nvm 安装的 Node.js 一般不会出现这个问题。如果遇到网络超时换个 npm 源基本能解决。2.3 配置文件准备依赖装完之后最重要的就是配置。OpenClaw 默认不会帮你生成配置你需要把示例配置复制一份然后按自己的情况改cp config.example.json config.json打开config.json核心要配置两块模型配置和渠道配置。模型配置决定 OpenClaw 的大脑用什么。如果你有云端模型的 API Key直接填进去就行如果没有可以用 Ollama 跑本地模型。这两条路我都试过后文会细说。渠道配置决定你从哪里跟 OpenClaw 对话。微信、飞书、Telegram 之类的渠道需要额外的 token 或者扫码登录配置项也都在这个文件里。注意config.json里如果有密钥信息千万别提交到 Git 仓库。我习惯在.gitignore里把config.json加进去或者干脆用环境变量引用敏感信息。3. 安装报错与排查实录3.1 依赖安装失败与缓存问题npm install报错是最常见的我把几种典型情况列一下报错特征可能原因解决方案ETIMEDOUT或ECONNRESET网络问题导致 npm 下载超时换 npm 源重试检查网络连通性EACCES: permission deniednpm 全局目录权限不足用 nvm 管理 Node.js不要用 root 直接跑ERR! code ERESOLVE依赖树冲突删除node_modules和package-lock.json后重新npm installnode-gyp编译失败缺少编译工具链sudo apt install build-essential python3后重试特别是node-gyp报错很多原生模块需要编译Ubuntu 上缺编译工具链很常见。提前装好build-essential能省不少事sudo apt update sudo apt install -y build-essential python3另外如果npm install中途失败再次运行前建议把node_modules删掉重来。残留的半截依赖会带来各种奇怪问题最直接的办法就是rm -rf node_modules package-lock.json npm install3.2 agent failed before reply: unknown model 这类模型配置错误启动的时候我遇到过最典型的报错是agent failed before reply: unknown model: deepseek这个报错乍一看很懵模型名字明明填对了怎么就 unknown后来排查发现问题出在配置文件里模型名称和 provider 的对应关系上。OpenClaw 的配置里模型名称需要跟 provider 列表里实际支持的模型 ID 对应。比如 DeepSeek 的 API模型 ID 一般是deepseek-chat但如果你在配置里随手写了deepseek服务端就认不出来。这其实是一个很常见的名字对不上问题。排查思路很简单先打开 provider 的官方 API 文档确认你要用的模型的确切 ID然后检查config.json里的model字段是否一致。另外如果你的 provider 配的是 OpenAI 兼容接口注意 base URL 要填对/v1后缀经常被人漏掉。3.3 Control UI did not startOpenClaw 自带一个网页控制界面Control UI方便你管理 agent、查看日志、配置 skill。但这个 UI 偶尔会起不来日志里报Control UI did not start。我遇到这个问题的原因比较简单启动时依赖的一个本地服务端口被占用了UI 进程起不来。排查方法# 查看日志 npm run dev 21 | tail -100 # 或者直接查看相关端口占用 netstat -tlnp | grep 端口号如果是端口被占把占用进程处理掉或者改配置里的端口号即可。还有一次是 Node.js 版本太老导致 UI 依赖的某个模块崩了换了 Node.js 20 之后问题消失。这个报错的关键就是看完整日志别只盯着最后一行的结论往前翻几十行通常有真正的异常堆栈。3.4 消息渠道连接问题接入微信这类 IM 渠道时问题也不少。OpenClaw 的微信接入走的是 Web 协议启动后需要扫码登录有几次我卡在二维码过期上——终端里显示的二维码有时候因为字符宽度问题扫不出来后来我把终端窗口拉大、换用更简洁的扫码方案才解决。还有一次是接入后 agent 不回复后来发现是渠道侧的登录态失效了重新扫码就好了。我的经验是渠道问题首先要分清是消息没进来还是进来了但 agent 没处理。前者多半是接入/登录问题后者要去看 agent 的日志通常是模型配置或 prompt 配置的问题。4. 让源码真正可运行的细节4.1 本地模型 vs 云端模型的模型配置如果你没有云端 API Key又想让 OpenClaw 真正跑起来本地模型是必由之路。我用的是 Ollama安装很简单curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7b然后在 OpenClaw 的配置里把模型 provider 指向 Ollama 的本地地址默认http://localhost:11434模型名填你在 Ollama 里拉取的名字比如qwen2.5:7b。这里有几个实操要点第一本地模型对内存和 CPU 有要求。7B 模型量化版跑起来大概需要 8GB 以上内存如果机器配置一般建议从 3B 或 4B 的小模型开始试。第二本地模型首次加载模型会比较慢启动 OpenClaw 之后第一次对话可能要等十几秒甚至更久这是正常的不是卡死了。第三本地模型和云端模型可以共存。我在配置里把默认模型设成云端 API同时保留本地模型作为备选这样可以兼顾响应速度和离线可用性。4.2 Skill 与二次开发入口如果你想让 OpenClaw 做更多事就得理解 skill 机制。简单说skill 就是一组预设的提示词和工具调用逻辑告诉 agent 在什么场景下怎么干活。源码模式下skill 一般在项目里的skills/目录下每个 skill 是一个独立目录里面有描述文件和处理逻辑。你自己写一个新 skill就是新建一个目录把逻辑写好然后在配置里注册。这个机制对开发者特别友好等于你随时可以给 agent 加新能力不需要改核心代码。我实际测试过自己写一个 skill 的流程复制一个现有 skill 目录重命名为你的 skill 名称。编辑其中的描述文件说清楚这个 skill 什么时候触发、做什么事。在里面实现具体的处理逻辑Node.js 代码。在配置里注册这个 skill重启服务。整个过程不需要改框架源码这就是源码部署最大的红利——你有了完全的控制权。4.3 开机自启与守护进程OpenClaw 是长驻服务不可能每次开机都手动npm start。我建议用 systemd 把它做成系统服务这样开机自启、崩溃自动重启、日志统一管理全都有了。在/etc/systemd/system/openclaw.service里写[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple User你的用户名 WorkingDirectory/home/你的用户名/apps/OpenClaw ExecStart/home/你的用户名/.nvm/versions/node/v20.x.x/bin/node /home/你的用户名/apps/OpenClaw/入口文件.js Restarton-failure RestartSec10 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw注意ExecStart里的 node 路径要用绝对路径不能用node这种简写因为 systemd 环境里不一定能拿到 nvm 的 PATH。你可以用which node查到自己的 Node.js 路径填进去。之后查看日志就用journalctl -u openclaw -f这个方式比在终端里跑着省心太多了SSH 断开也不影响服务运行。5. 如果再装一次我会怎么做5.1 从源码运行的关键时间节点总结一下整个流程的关键节点Node.js 版本要够新npm 源要提前换编译工具链要装好配置文件要仔细核对模型 ID渠道登录态会过期。这几个点只要抓好源码部署其实很快。我再给一个快速上手清单用 nvm 安装 Node.js 20 LTS。安装build-essential和python3。克隆源码执行npm install遇到网络问题换 npm 源重试。复制示例配置为config.json填入模型配置云端 API 或本地 Ollama。启动服务通过 Control UI 或消息渠道测试对话。稳定后配置 systemd 守护进程实现开机自启。5.2 避坑清单坑表现提前预防Node.js 版本过老依赖安装失败、启动报语法错用 nvm 装 20看 package.json 的 enginesnpm 网络超时ERESOLVE、ETIMEDOUT换 npm 源删 node_modules 重装模型 ID 不匹配agent failed: unknown model: xxx核对 API 文档里的真实模型 ID端口占用Control UI 起不来先查端口再改配置渠道登录态失效消息发出去没回复重新扫码区分消息到达和 agent 处理系统重启后服务没了手动启动太麻烦用 systemd 托管进程我个人建议如果你打算长时间跑 OpenClaw前端可以配一个 Nginx 反代到 Control UI加一层访问控制避免管理界面直接裸奔在公网上。这个不是必须的但既然都做了源码部署安全和稳定性顺手一起搞定是值得的。回头再看这几天踩的坑其实大部分问题都不是 OpenClaw 本身的问题而是 Linux 环境下的常规摩擦。只要环境干净、版本匹配、配置仔细这套源码跑起来之后是真的稳。希望这篇记录能让你少走几步弯路尤其是那些卡在装好了但起不来状态的朋友按上面的清单一步步排查基本都能找到出口。本文还有配套的精品资源点击获取