简介：这是一份针对 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 denied | npm 全局目录权限不足 | 用 nvm 管理 Node.js；不要用 root 直接跑 |
ERR! code ERESOLVE | 依赖树冲突 | 删除node_modules和package-lock.json后重新npm install |
node-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 start
OpenClaw 自带一个网页控制界面（Control UI），方便你管理 agent、查看日志、配置 skill。但这个 UI 偶尔会起不来，日志里报Control UI did not start。
我遇到这个问题的原因比较简单：启动时依赖的一个本地服务端口被占用了，UI 进程起不来。排查方法：
# 查看日志 npm run dev 2>&1 | 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] Description=OpenClaw Service After=network.target [Service] Type=simple User=你的用户名 WorkingDirectory=/home/你的用户名/apps/OpenClaw ExecStart=/home/你的用户名/.nvm/versions/node/v20.x.x/bin/node /home/你的用户名/apps/OpenClaw/入口文件.js Restart=on-failure RestartSec=10 Environment=NODE_ENV=production [Install] WantedBy=multi-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 的 engines |
| npm 网络超时 | ERESOLVE、ETIMEDOUT | 换 npm 源，删 node_modules 重装 |
| 模型 ID 不匹配 | agent failed: unknown model: xxx | 核对 API 文档里的真实模型 ID |
| 端口占用 | Control UI 起不来 | 先查端口，再改配置 |
| 渠道登录态失效 | 消息发出去没回复 | 重新扫码，区分消息到达和 agent 处理 |
| 系统重启后服务没了 | 手动启动太麻烦 | 用 systemd 托管进程 |
我个人建议，如果你打算长时间跑 OpenClaw，前端可以配一个 Nginx 反代到 Control UI，加一层访问控制，避免管理界面直接裸奔在公网上。这个不是必须的，但既然都做了源码部署，安全和稳定性顺手一起搞定是值得的。
回头再看这几天踩的坑，其实大部分问题都不是 OpenClaw 本身的问题，而是 Linux 环境下的常规摩擦。只要环境干净、版本匹配、配置仔细，这套源码跑起来之后是真的稳。希望这篇记录能让你少走几步弯路，尤其是那些卡在"装好了但起不来"状态的朋友，按上面的清单一步步排查，基本都能找到出口。
本文还有配套的精品资源，点击获取
