1. 安装前要摸清的底细
如果你搜到这个标题，大概率已经有两个预判：一是觉得“Ubuntu 20 装个开源工具能有多难”，二是卡在某个报错里出不来。我先后在物理机、虚拟机、WSL2 里完整跑过 OpenClaw，也被 npm 权限、Node 版本、WSL 报错按在地上摩擦过。这篇就以 Ubuntu 20.04 为基准，把一套能落地的 OpenClaw 安装流程讲透，顺带把那些折磨人的经典报错一起收拾掉。适合读这篇文章的人很明确：想在 Linux 服务器或虚拟机里部署 OpenClaw、想把 Qwen2.5 这类模型接进 OpenClaw、或者已经试过安装但卡在环境报错上。
1.1 先搞清楚你要跑的是哪种 OpenClaw
这一点看起来多余，但我见过太多人把“安装 OpenClaw”理解得太单一，导致照着错误教程折腾半天。OpenClaw 这类工具通常有三种跑法。第一种是命令行交互模式，装完就能在终端里对话调试，适合第一次试水，资源占用也最小。第二种是常驻服务模式，把 OpenClaw 作为后台进程跑在服务器上，通过配置文件对接各种消息平台，比如 Microsoft Teams、Telegram 这一类，这也是“部署”两个字最常指的场景。第三种是作为依赖库嵌进自己的 Node.js 项目里，把 OpenClaw 的能力当模块调，适合二次开发。
这三种跑法的安装前置几乎一样，差别主要在启动参数和配置项。我的建议是：先按第一种跑通，再加消息平台，最后才考虑嵌进项目。上来就搞全家桶，报错时你会分不清是环境问题还是自己配置问题。
1.2 Ubuntu 20.04 这个版本的特殊性
选择 Ubuntu 20.04 的理由通常很现实：现有服务器是它、虚拟机模板是它、或者你只是不想升级系统。但它有个绕不开的问题——默认 apt 源里的 Node.js 老到没法看，通常是 v10 出头，而 OpenClaw 这类基于现代 Node 的工具一般要求 16 或 18 以上。所以“装不上”“一启动就崩”很多时候不是工具本身的问题，是运行时太旧。
另外，20.04 的 glibc、OpenSSL 版本都偏保守。如果你编译本地依赖或者跑某些需要新版加密库的模块，可能碰到 GLIBCXX_3.4.30 not found 或 OpenSSL 1.1 相关的兼容性警告。这并不致命，但要有心理准备。相比之下，22.04 会温和不少，但生产环境更新系统不是拍脑袋就能决定的，所以 20.04 上怎么把 OpenClaw 跑顺，确实值得单独写一篇。
1.3 部署前的自检清单
开工前先花五分钟确认四件事，能省掉后面一整晚。第一，硬件。纯命令行交互加远程 API 模型，2 核 2G 内存都够；如果要在本机跑 Qwen2.5-3b 这类小模型，建议至少 4G 可用内存，量化后的 3B 模型也要占好几个 G。第二，操作系统版本，确认是 20.04.x，不是 18.04 也不是 22.04，因为后两者的源、内核和依赖库都不一样。第三，Node.js 版本，目标 18.x 或 20.x LTS。第四，网络与模型密钥。如果你打算接在线模型 API，把 Key 和接口地址准备好；如果走 Ollama 本地模型，先确认显卡或 CPU 跑 3B 模型的可行性。把这几项写在一张纸上，对着打勾。工具部署这件事，九成失败案例都出在自检环节，而不是安装环节本身。
2. 基础环境三板斧：源、运行库、Node.js
这一节做的所有事，都是为了给 OpenClaw 一个“能正常吃饭”的宿主环境。宿主环境不对，后面每一步都可能冒出新错误。
2.1 先把软件源换成国内镜像
Ubuntu 20.04 默认源在国外，apt 更新慢会导致两个恶心结果：一是apt update经常超时，二是装依赖时因为拉包太慢莫名中断。我习惯先备份sources.list，然后换成阿里云或者清华镜像。注意不同镜像站对 Ubuntu 20.04 的代号是 focal，不要在换源时把版本代号写错，否则下载包时会报 404。
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list sudo apt update && sudo apt upgrade -y换完源之后顺手把编译工具链装齐，OpenClaw 的一些原生依赖安装时可能需要现场编译：
sudo apt install -y build-essential git curl ca-certificatesca-certificates经常被忽略，但 HTTPS 证书链校验出问题、下载时报“证书验证失败”时，它往往是第一嫌疑人。装完后顺手跑一句sudo update-ca-certificates。
2.2 Node.js 请用 NodeSource 源，别碰 apt 默认版
Ubuntu 20.04 默认仓库里的 Node 是 10.x，这个版本跑现代 CLI 工具基本是告别。更麻烦的是，如果你先装了这个旧 Node，后面再装新版，可能会出现/usr/bin/node和/usr/local/bin/node两个版本并存的混乱，which node的结果全凭缘分。我推荐的方案是用 NodeSource 的源安装 Node 18 LTS。在 20.04 上执行：
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v用-E保留当前环境变量，是因为 NodeSource 脚本要拿到代理或镜像配置。如果公司网络限制，也可以先下载 setup 脚本看内容再执行，至少知道自己对机器做了什么。装完确认node -v是 v18.x，npm -v是 9.x 左右，就可以继续。
也有人喜欢用 nvm 管理 Node 版本，这本身没问题。但 nvm 是按用户安装的，每次新开 shell 需要.bashrc里生效，如果你用sudo切换身份，或者写 systemd 服务时用的用户不对，就会出现“刚才明明装好了，换个终端又找不到 node”的灵异事件。所以我前面说，能用系统级 NodeSource 就先别上 nvm，等以后需要在多个 Node 版本间切换时再上也不迟。
2.3 PATH 与环境变量：翻车重灾区
环境变量问题在热门搜索里出现频率高得离谱，比如“ubuntu环境变量配置错误”。典型的场景是：命令装好了，openclaw却提示 command not found。原因基本都出在 PATH 没有包含 npm 的全局安装目录。
先用三个命令定位问题：
which node npm config get prefix echo $PATHnpm 全局安装目录一般在/usr/local/bin，但如果配置过 prefix，可能会跑到别的路径。检查/usr/local/bin是否在 PATH 里，如果没有，就补进去。改配置文件的正确方式是编辑~/.bashrc或者/etc/profile.d/node.sh：
export PATH="/usr/local/bin:$PATH"改完之后source ~/.bashrc再验证。注意：把export PATH=/usr/local/bin:$PATH写错成export PATH=/usr/local/bin这种，等于砍掉其他所有路径，后果是 ls、cat 这些基础命令全部失效，终端直接“瘫痪”。这种情况不用重装系统，先把 PATH 手动恢复成系统默认值，再回去改配置文件：
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin提示：改 PATH 之前先备份配置文件，哪怕只是复制一份
.bashrc .bashrc.bak。别问我怎么知道的。
3. 安装 OpenClaw 主程序与模型配置
基础环境就绪后，核心步骤就简单多了。但简单不代表不会出幺蛾子，尤其 npm 权限和模型接口这两块。
3.1 安装方式：npm 全局包或官方安装脚本
OpenClaw 的发布渠道不同，安装命令也不同。我从搜索热词里看到大量人卡在“node.js官网下载openclaw”这类关键字上，其实 OpenClaw 并不是 Node.js 官方出的工具，它只是运行在 Node 生态里。所以别去 nodejs.org 找它，要去项目官方仓库的 README 里找安装命令。
大多数 Node 生态的 CLI 工具会发布到 npm，安装方式类似：
npm install -g openclaw-cli或者带 scope 的包名：
npm install -g @openclaw/cli具体包名以官方文档为准。如果你不确定，npm search openclaw看一下哪个是活跃维护且下载量正常的，再对照官方仓库名确认。部分项目也会提供curl | bash形式的安装脚本，脚本本质是帮你把二进制或 npm 包装到/usr/local，省去手动配置。无论哪种方式，装完先跑openclaw --version验证可用。
如果 npm 全局装包时报 EACCES，说明 npm 目录权限不够。很多人第一反应就是sudo npm，但这会带来“root 装的全局包，普通用户调用时找不到”的隐患。比较干净的处理是：用npm config set prefix把全局目录指到用户目录下，再在 PATH 里补上这个目录。一劳永逸。
3.2 初始化项目目录与配置骨架
OpenClaw 安装完不会自动生成业务配置。一般需要在某个工作目录里初始化：
mkdir -p ~/openclaw && cd ~/openclaw openclaw initinit 命令会帮你生成.env、配置文件、默认模板。如果版本不同没有 init 命令，就用openclaw --help看当前版本提供了什么动作，常见的有 init、config、start、logs、status 这类。
初始化完成后，重点看.env。这个文件里通常要填模型服务商、API Key、Base URL、模型名字，以及可选的消息平台凭证。注意.env里不要出现多余空格和引号，很多“密钥不对”的错误其实只是.env的格式问题。我吃过这个亏，老老实实填API_KEY=sk-abc就好，别加引号别加分号。
3.3 模型接入：Qwen2.5-3b 怎么关联进来
搜索热词里有一句“qwen2.5-3b 关联到 openclaw”，这是很多人的真实需求。Qwen2.5-3b 接入 OpenClaw 有两条路，先分清你是想在线调 API 还是本地跑模型。
在线方式用 DashScope 兼容接口。在 OpenClaw 配置文件里把 provider 指向 DashScope，模型名填qwen2.5-3b-instruct这类官方标记，Base URL 按 DashScope 的 OpenAI 兼容地址填，再把 API Key 填进去。优点是零部署门槛，缺点是按量计费。
本地方式用 Ollama。先在 Ubuntu 20.04 上装 Ollama：
curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:3b ollama serve然后 Ollama 会监听localhost:11434，并提供 OpenAI 兼容接口/v1。OpenClaw 这边就不需要填什么特殊密钥，Base URL 改成http://localhost:11434/v1，模型名填qwen2.5:3b就行。这样 OpenClaw 和本地模型就关联上了。需要提醒的是，3B 模型用 CPU 硬跑也能跑，但速度感人；有 NVIDIA 显卡的话要提前确认 Ollama 能识别到 GPU，ollama ps能看到显存占用，如果显示 CPU/GPU 分支，说明环境没完全配好。
3.4 启动服务与验证链路
配置完别急着接消息平台，先本地启动验证。常见启动命令是openclaw start，前台模式能看到完整日志，适合第一次跑。启动后观察三类信息：是否读取到.env、模型接口是否握手成功、有没有报端口占用。如果日志里看到模型连接失败，先别怀疑 OpenClaw，直接 curl 一下模型接口：
curl http://localhost:11434/v1/models这样能快速把问题隔离在“模型服务”还是“OpenClaw 配置”上。确认本地交互没问题后，再按需让它后台常驻，后面我会给 systemd 的写法。
4. WSL2 里的 Ubuntu 20：安装报错与验证问题
这一节写给在 Windows 下用 WSL2 跑 Ubuntu 的用户。热门搜索词里“分发名称: 'ubuntu' 错误代码: 0x80070424”“openclaw无法安全验证”“sl2环境。请在powershell中运行wsl --status”全扎堆在这，显然这里坑很多。
4.1 0x80070424：先分清是 WSL 服务问题还是发行版问题
错误信息“分发名称: 'ubuntu' 错误代码: 0x80070424”常在执行wsl --install -d Ubuntu或从商店装 Ubuntu 时出现。这个错误码的意思是“服务无法启用或资源未被找到”，常见原因有三个：WSL 可选组件没真正启用、LxssManager 服务停着不动、安全软件把 WSL 相关服务注册给拦了。排查流程建议固定为“先 status 再 update”：
wsl --status wsl --update wsl --shutdown wsl --install -d Ubuntuwsl --status能看到 WSL 版本和默认发行版信息，这是热词里反复出现的原因——官方排查第一件事就是让你先看状态。如果 status 报 WSL 没安装完整，管理员 PowerShell 执行：
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart然后重启 Windows，再执行wsl --update把内核更新到最新，基本能解决大半 0x80070424。如果仍然不行，检查 LxssManager 服务状态，管理员 PowerShell 里执行net start LxssManager或sc query LxssManager查看。安全软件拦截的情况比较阴间，表现是每次安装到一半就回滚，这类只能进安全软件的白名单或临时退出再装。
4.2“无法安全验证”这个提示卡在哪一层
“openclaw无法安全验证”这个描述，需要拆成两种场景来理解。第一种是下载安装包时，系统提示无法验证开发者签名。这种情况在 Windows 和 macOS 上更常见，对策很简单：只从官方仓库的 Release 页面下载包，别从第三方站拿；如果本机时间不对，证书有效期校验会失败，同步一下系统时间再试。
第二种场景是在 WSL 的 Ubuntu 里通过 npm 或脚本安装时，遇到ERR! certificate has expired或者 TLS 握手失败。这通常是根证书问题，Ubuntu 侧处理：
sudo apt install --reinstall ca-certificates sudo update-ca-certificates --fresh同时检查系统时间和时区，时间漂移会让证书链校验以为“证书未生效”：sudo timedatectl set-ntp true。这类问题的共同点是：OpenClaw 本身没问题，是你机器的时间或证书链坏了。
4.3 WSL 里的文件与网络细节
WSL2 里跑 OpenClaw，我强烈建议不要把项目放在/mnt/c/下面。原因有两个：一是 Windows 文件系统的 I/O 在 WSL2 里走 9P 协议，速度慢，尤其 node_modules 这种动辄几万文件的目录，装依赖能磨到怀疑人生；二是文件权限映射经常出问题，chmod 不生效，OpenClaw 的配置文件读取会异常。项目放 Linux 侧的~/openclaw，要用 Windows 侧工具打开，就通过\\wsl$\Ubuntu\home\你的用户名\openclaw访问。
网络方面，WSL2 默认通过 NAT 让 Linux 侧访问外网，Windows 侧访问 Linux 侧的服务用 localhost 就能通。所以 OpenClaw 监听某个端口，浏览器在 Windows 侧访问http://localhost:端口一般直接可用。如果你改了 WSL 的网络模式，或者用了镜像网络之外的自定义配置，端口映射可能断，到时候先在 WSL 里确认服务真的监听在 0.0.0.0 上，再看 Windows 侧能不能通。
5. 高频问题排查速查表
下面这些是从各大社区、搜索热词里整理出来的高频症状，基本是 OpenClaw 在 Ubuntu 20 上安装时的代表性报错。与其说这些是 OpenClaw 的错，不如说大部分是环境问题在特定工具上的投影。
5.1 按症状快速定位
| 症状 | 最可能原因 | 先做的排查 |
|---|---|---|
command not found: openclaw | PATH 缺 npm 全局目录 | 检查npm config get prefix并确认目录在 PATH |
npm error EACCES | 全局目录无写权限 | 重新配置 npm prefix 到用户目录或修目录权限 |
Cannot find module 'xxx' | Node 版本过旧导致依赖不兼容 | 确认node -v，低于 16 就切 18/20 |
| 模型接口 connection refused | Ollama 没启动或端口不对 | curl http://localhost:11434/v1/models |
| API 返回 401 | .env密钥有多余字符或不对 | 重新复制 Key，检查.env格式 |
| 下载依赖极慢或超时 | 网络到默认源不稳定 | 换 npm 镜像 registry 后重装 |
| 安装过程提示证书错误 | ca-certificates 缺失或时间错误 | 重装 ca-certificates 并开启时间同步 |
这些症状不是 OpenClaw 专属，我帮人排查时发现至少有三分之一的问题在装之前就埋下了。速查表的意义是让你别顺着报错往上找，先退一步看环境。
5.2 PATH 改坏之后，大约三分钟能救回来
前面提过 PATH 写错会让终端陷入半瘫痪，这里展开讲抢救流程。首先，如果当前终端还能运行命令，哪怕只有 export、echo，就直接用默认 PATH 恢复：
export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin然后马上编辑~/.bashrc，把错误行删掉或注释。如果终端连 ls 都打不出，说明 PATH 被写进环境变量的优先级极高，别慌，用绝对路径调用命令：
/bin/ls /home/你的用户名/.bashrc或者绕开 profile 直接开一个新外壳：bash --noprofile --norc。这个模式不加载配置，PATH 会回到系统默认，然后就能正常编辑修复文件。修复后执行source ~/.bashrc，再开个新终端确认没问题。记住：改动环境变量的文件是/etc/profile、/etc/environment、~/.bashrc、~/.profile，排查优先级也按这个顺序来。
5.3 本地模型起不来时的三层检查法
接入 Qwen2.5-3b 这类本地模型时，模型服务起不来是高频故障。我总结为三层检查。第一层看进程。ollama serve有没有在跑，终端里执行pgrep -f ollama。没有就前台启动一次，看有没有显存不足、端口占用这类直接报错。第二层看模型。ollama list看模型是否下载完整，如果显示 pending 或体积不正确，重新ollama pull qwen2.5:3b。第三层看接口。curl -s http://localhost:11434/v1/models | head -c 200，用这个最朴素的 HTTP 探测，判断 Ollama 的兼容接口是否真的能用。三层都通过，再回头看 OpenClaw 的配置里 Base URL 是不是写成了localhost而不是127.0.0.1，或反过来——这种“看似同一个地址”的问题最容易忽略。
6. 部署之后的体验优化与平台扩展
安装只是开始，真正决定你愿不愿意长期用 OpenClaw 的，其实是跑起来之后的稳定性和接入体验。
6.1 用 systemd 把 OpenClaw 跑成常驻服务
如果只在前台跑，SSH 一断进程就没了。Linux 上常规做法是用 systemd。在/etc/systemd/system/openclaw.service里写一个最小 unit：
[Unit] Description=OpenClaw Service After=network-online.target [Service] WorkingDirectory=/home/你的用户名/openclaw ExecStart=/usr/bin/openclaw start Restart=always RestartSec=5 EnvironmentFile=/home/你的用户名/openclaw/.env [Install] WantedBy=multi-user.target写完后：
sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw注意 ExecStart 里的路径要与你which openclaw的结果一致，如果用的是 nvm 装的 Node，路径往往在~/.nvm/...下，systemd 默认环境可能找不到，要在 unit 里写绝对路径或补 PATH。环境变量也别只依赖 EnvironmentFile，如果某些变量是运行时注册的，在 ExecStart 前通过Environment=显式补上。这个细节是很多人从“终端能跑”到“服务起不来”的分水岭。
6.2 接入 Microsoft Teams 的通用路径
热门搜索里有“openclaw 如何接入 microsoft teams”，说明不少人部署 OpenClaw 不只是自己调试，而是要把它当成一个团队机器人来用。Teams 接入的基本流程类似其他 Bot：先有一个应用注册，把 Bot 身份拿到手，再把凭证填进 OpenClaw 配置。
具体来说，你需要用到 Teams 开发者平台或 Azure Bot 服务，创建一个 Bot 应用，拿到 App ID、App Password（有的地方叫 Client Secret）。如果只是团队内部测试，注意关闭“仅限组织内”的严格权限，或者在 Teams 管理后台把应用策略允许范围调大。然后在 OpenClaw 的配置里找到 teams 相关段落，填入：
TEAMS_APP_ID=你的应用ID TEAMS_APP_PASSWORD=你的客户端密钥 TEAMS_TENANT_ID=你的租户ID不同版本的 OpenClaw 对配置项命名有差异，填之前先看官方集成文档，或者对着配置模板把 teams 字段过一遍。启动后观察日志里有没有 teams 连接成功的记录，没有的话用openclaw logs -f看实时日志，重点找“failed to connect”“unauthorized”这类关键词。
6.3 关于扩展与资源占用的实在建议
搜索词里的“openclaw obsidian”让我多说一句：这类把知识库工具和 Agent 框架结合的功能，通常依赖特定插件或适配器，不是 OpenClaw 装完就自带的能力。如果你在博客里搜到一篇教程，建议看清楚它的 OpenClaw 版本和你是否一致，版本不对的教程参考价值会大打折扣。
资源占用方面，OpenClaw 本身是个 Node 进程，常驻内存一般不高，真正吃内存的是本地模型。Qwen2.5-3b 量化后在 CPU 推理也要 3G 往上，如果你只有 4G 内存的空闲，别指望它跑得多快。我的建议是：交互调试用本地 3B 模型，真正要稳定服务或者多人使用，还是接在线 API。等 GPU 环境成熟了再折腾本地推理也不迟。
7. 如果再装一次，我会提前做的几件事
把流程重新过了一遍之后，我想多说几句实在体会。第一个建议：安装任何 Node 生态工具前，先把 npm 前缀目录和 PATH 问题一次配置到位。我在 20.04 上耗时最多的一晚，就是在“sudo 装包”和“换用户找不到命令”之间反复横跳。与其事后补救，不如一开始就配置好用户级 npm 全局目录，后面装什么 CLI 都省心。
第二个建议：先在最小配置上跑通，再扩展。很多人拿到 OpenClaw 就想着一步到位接 Teams、接知识库、接本地模型，结果全平台都报错，反而不知道问题在哪一条链路上。正确顺序是：命令行跑通、接一个模型服务、再考虑消息平台，每一步都验证完再往前走。最后一个技巧：配置模型和平台之后，把.env里的密钥和账号信息单独整理到安全位置，别直接泡在公开代码仓库里。OpenClaw 这类 AI 工具本来就是连接器和执行器，密钥一旦泄露，成本账单可能让你怀疑人生。我说的这些，希望你能比我少踩几个坑。
