小肉卷最近几乎每周都要回答一遍同样的问题：OpenClaw 在笔记本上、家里的 NAS 上跑得好好的，为什么搬上阿里云 ECS 就各种幺蛾子？有的装到一半报错退出，有的跑起来但网页控制台打不开，有的 Agent 一回复就提示模型连接失败。作为常年帮客户做阿里云落地部署的代理商，我把这一年多来经手过的 OpenClaw 部署问题做了一次复盘，高频故障其实高度集中在五个环节：基础环境、软件源、模型接线、Control UI、外部渠道接入。这篇文章不聊虚的，就把这 5 大常见问题的现象、原因、处理步骤一条一条列清楚。不管你是第一次碰 OpenClaw，还是已经在阿里云上跑过一版但不太稳，跟着这篇文章把部署链路过一遍，大部分坑都能提前避掉。
1. 动手前先搞懂：OpenClaw 部署链路的整体设计思路
1.1 OpenClaw 到底是个什么东西，能干什么
OpenClaw 是一款开源的个人 AI 代理框架，核心定位是“把大模型接到真实的工作流里”。它不同于普通的聊天机器人，更像一个带调度中枢的自动化管家：你可以让它定时帮你抓取网页信息、整理生成稿件甚至写小说、调用你编写的 Skill 去访问外部 API，再把结果推送到微信、飞书这些日常使用的聊天工具里。本质上它就干三件事：接模型、跑任务、联渠道。
我在帮客户规划部署方案时，经常打一个比方：OpenClaw 是一辆能自动驾驶的车，模型是发动机，渠道是轮子，Skill 是后备箱里的工具箱。很多人以为只要把发动机装上就能跑，结果轮子没装好、工具箱也没固定，自然一步都动不了。所以，部署之前先理解它的三层结构——模型层、执行层、渠道层，后面所有问题定位都会快很多。
1.2 阿里云上部署 OpenClaw 的链路组成
在阿里云上把 OpenClaw 跑起来，并不是“装个软件就行”那么简单，完整链路至少包含四层：
- 基础设施层：一台能长期开机的服务器（通常用 ECS），以及操作系统、公网带宽、安全组规则。
- 运行时层：Node.js 运行时（OpenClaw 主体通常依赖 Node 环境）、Docker（如果用容器化部署）、Python（部分 Skill 和依赖需要）。
- 服务层：OpenClaw 主程序、Control UI 管理界面、模型接口（云端 API 或本地模型服务）。
- 渠道层：微信、飞书这类消息渠道的接入配置，以及回调地址、Token 等。
每层都有可能出问题。很多时候用户说“OpenClaw 跑不起来”，真正的原因其实是在基础设施层或者运行时层，而不是 OpenClaw 本身。这也是做排障时要先建立全局视角的原因——别一上来就翻 Agent 日志，先看看进程在不在、端口通不通、安全组放行没放行，往往五分钟就能止血。
1.3 服务器与系统选型：预算怎么花在刀刃上
先给结论，再解释为什么：
- 个人体验、轻量自动化任务：2 核 4G 的 ECS 就够了，系统选 Ubuntu 22.04 LTS 64 位。
- 同时跑本地模型（比如 Qwen 7B、Llama 8B 这类量化模型）：建议 4 核 16G 起步，有条件上 8 核 32G，并且单独挂数据盘。
- 如果只是调用云端 API（OpenAI、通义千问、DeepSeek 等），显存和 CPU 压力主要不在服务器上，2 核 4G 依然够用。
这里有个常见的误解：很多人担心服务器配置不够，一上来就买 8 核 32G，结果用了不到 10% 的资源。OpenClaw 本身不是重资源应用，真正吃资源的是本地模型推理。用云端 API 的话，瓶颈通常在网络和模型服务端，而不是你的 ECS。所以买机器前先想清楚一个问题：你到底用云端模型还是本地模型？这个决策直接决定了你的服务器规格和预算。
系统版本我一般只推荐 Ubuntu 22.04 LTS 或 Debian 12，原因有三点：一是 OpenClaw 的文档和社区示例基本都以 Debian 系为主，包管理方式统一，apt 装依赖最省事；二是 CentOS 7 已经停止维护，CentOS Stream、Rocky 这类系统对 Node 项目的兼容性偶尔会出幺蛾子；三是阿里云的公共镜像里 Ubuntu 22.04 最稳定，开箱即用的坑最少。数据盘的问题也要提醒一句：模型文件、日志、数据库都建议放数据盘，系统盘只放程序和系统文件，这样即使系统盘出了问题需要重置，数据和 Agent 配置都不会丢。
注意：购买 ECS 时还有两个小细节容易被忽略。一个是公网带宽：如果你的 Agent 要被外部平台回调（比如飞书、企业微信回调到服务器），带宽至少要有 1Mbps，实际交互频繁的建议 5Mbps。另一个是安全组：默认情况下安全组只放行了 22 端口（SSH），后面装好 Control UI 或者要接 Webhook 回调，都需要去安全组里手动开端口。这个放到第 5 章详细说。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 问题一：Node.js 运行时找不到，装到一半就中断
2.1 现象与根因
这个报错在 Windows 和 Linux 上都会出现，常见的提示大概是 OpenClaw node runtime not found 或者 Cannot find module '/usr/local/lib/node_modules/...'。还有一个变种是，你执行启动命令以后，屏幕上闪过几行字就直接退出了，连个正经报错都不给，查日志才发现是 Node 版本不对。
根因有以下几种，按出现频率排：
- 系统自带的 Node 版本太老。Ubuntu 22.04 通过 apt 安装 Node，默认装到的是 12.x 或 16.x，而新版 OpenClaw 要求 Node 18 以上，部分版本甚至要求 Node 20+。
- 系统里同时有多个 Node 版本，PATH 环境变量指向了旧版本。
- Node 装好了，但 npm 全局包路径不对，导致 OpenClaw 的 CLI 找不到。
这里要特别说明：很多人习惯用 apt install nodejs 一把梭，这样装出来的版本大概率过旧。更稳妥的做法是通过 nvm（Node Version Manager）来管理运行时。另外，在 Windows 上看到 oneclaw node runtime not found 这类提示时，要先检查安装路径里是否包含空格或中文，有些版本对路径解析比较严格，放在纯英文路径下会更省心。
2.2 一键解法：用 nvm 管理 Node 版本
推荐在干净的 Ubuntu 22.04 上这样操作：
bash复制cd ~
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
nvm install 20
nvm alias default 20
node -v
npm -v
装完以后，确认 node -v 输出的是 v20.x。如果之前已经用 apt 装过 Node，建议先卸载干净再装 nvm，否则两个版本混在一起，PATH 解析会乱。
注意：nvm 脚本需要从 GitHub 的 raw 域名下载，国内服务器直连这个域名有时会超时。如果遇到这个情况，可以从阿里云镜像站或国内可访问的代码托管镜像获取 nvm 的安装脚本，或者多试几次避开高峰期。这一步是部署环境里最容易被卡住的地方之一，别硬等，换个获取方式通常就好了。
装好 Node 以后，再用 npm 安装 OpenClaw 的 CLI 或拉取项目依赖，就会顺畅很多。如果你用 Docker 方式部署，这个问题天然就避开了，因为 Docker 镜像内部已经封装好了运行时。所以我个人的建议是：新手第一次部署，优先选 Docker Compose 方案，省去环境问题；如果是二次开发、要频繁改代码，再用源码方式配合 nvm 管理 Node。
如何确认当前到底用的哪个 Node 版本？在执行启动命令前，先手动跑一下：
bash复制which node
node -v
npm root -g
如果 which node 输出的是 /usr/bin/node，说明用的是系统级 Node，不是 nvm 管理的版本。这里有个细节：nvm 安装的 Node 默认在 ~/.nvm/versions/node/v20.x.x/bin/node 下，软链接到 ~/.nvm/current。如果启动 OpenClaw 时用的是 systemd 服务或 pm2，需要注意环境变量是否继承，否则服务起来后用的可能是 PATH 里解析到的旧版本。这个问题在 systemd 服务里尤其坑，后面第 7 章会再次提到。
3. 问题二：依赖下载慢、超时，安装过程卡成 PPT
3.1 现象与根因
OpenClaw 安装过程中需要从 npm 拉取大量 JS 依赖包，如果还用到 Python 的 Skill，还要装 pip 包；用 Docker 部署则要拉镜像；部分安装脚本还可能会触发 apt 库更新。在阿里云 ECS 上，最常见的故障就是：npm install 跑到一半卡住，最终报 ETIMEDOUT、ECONNRESET 或 ELIFECYCLE 之类的错误；Docker 拉取镜像时进度条半天不动；pip install 下载第三方库超时。
根因很简单：这些包管理器默认从境外源拉取数据，国内服务器访问延迟高、链路不稳定。但注意，在阿里云环境里有一个天然优势：阿里云提供了内网加速能力，速度远快于公网访问。很多人在本地用习惯了默认源，上了云还是用老配置，自然被卡成 PPT。
3.2 解决方案：npm、pip、apt、Docker 镜像四件套
这里直接给一套比较完整的配置命令，按需执行：
- npm 源：
bash复制npm config set registry https://registry.npmmirror.com
建议在执行 npm install 之前就配好。验证命令：npm config get registry。
- pip 源（如果用 Python Skill）：
bash复制pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com
- apt 源（Ubuntu 22.04）：
把 /etc/apt/sources.list 里官方源替换成阿里云镜像源，一般是把 archive.ubuntu.com 和 security.ubuntu.com 批量换成 mirrors.aliyun.com，然后执行 apt update。新版 Ubuntu 使用 deb822 格式的 .sources 文件，也需要同步修改对应字段。
- Docker 镜像加速器：
在 /etc/docker/daemon.json 中配置：
json复制{
"registry-mirrors": ["https://your-id.mirror.aliyuncs.com"]
}
其中 your-id 是阿里云容器镜像服务控制台里分配的加速器地址。配置完执行 systemctl daemon-reload && systemctl restart docker。
这个四件套配置完，90% 的下载超时问题都能解决。我用在实际客户环境里的体感是：npm 依赖安装时间能从十几分钟压缩到两三分钟，Docker 拉镜像也从“基本靠等”变成秒级。
3.3 镜像站不是万能的：特殊版本要回退官方源
镜像站偶尔也会出现“没有某个版本”的情况。比如有人问“阿里云镜像站下载不了 Gradle 9.0”，其实是因为镜像站同步有滞后，或者对应平台还没发布完整版本。遇到这种特殊情况，处理方法有两种：一是把源临时切回官方源下载完再切回来；二是直接到官方 Releases 或中央仓库下载指定版本，放到本地目录用。Java 生态里的 Maven 仓库也是同理，settings.xml 里配置阿里云镜像后，大部分依赖都能加速，但个别冷门包或刚发布的快照版本，镜像站还没有，就需要单独走官方仓库。
这个经验同样适用于 OpenClaw 部署中的依赖问题：如果 npmmirror 短暂缺少某个包，临时执行：
bash复制npm install --registry=https://registry.npmjs.org
只针对当前命令生效，不会污染全局配置。这里要注意官方源在公网访问时可能较慢，但偶尔一个包缺了，用这种方式应急是可以的。关键原则是：全局配置优先走镜像，个别缺失走临时回退，不要因为一个小包把全局源都切回境外。
4. 问题三：模型配置导致 Agent 启动失败
4.1 现象：unknown model / agent failed before reply
部署成功后第一次和 OpenClaw 对话，可能是最容易“翻车”的环节。典型报错有：
agent failed before producing a replyunknown model: deepseeAuthenticationError / 401Connection error: Failed to connect to ...
这些报错看着吓人，但大部分原因集中在模型配置上。尤其是“zero token”部署（也就是不配置任何付费 API Key，打算用免费 Key、本地模型或第三方兼容接口），最容易踩到模型 ID 写错、Base URL 写错、模型服务地址不可达这三个坑。
举个例子，有用户反馈“我 OpenClaw zero token 安装后，Agent 回复报错：unknown model: deepsee”。排查发现，他在配置文件里把 deepseek-chat 写成了 deepsee，少了一个 k。这种错误在图形界面里不好发现，因为下拉框里没有对应模型，但配置文件里不会帮你校验模型名。模型名必须严格按服务商 API 文档来写，大小写、连字符都不能错。
4.2 模型配置的完整排查清单
我一般按下面的顺序排查，每一步都是独立的：
- 确认配置文件位置和加载逻辑：OpenClaw 的模型配置通常在 config 目录下的 YAML/JSON 文件或环境变量里，先拿到你正在用的那一个配置。
- 检查 Base URL：云端 API 模型，Base URL 要指向服务商的 API 地址；本地模型（如 Ollama）则指向
http://127.0.0.1:11434；如果 OpenClaw 跑在 Docker 容器里，访问宿主机上的 Ollama 要用host.docker.internal或宿主机内网 IP，不能用127.0.0.1。 - 检查模型 ID：对照服务商文档，确认 model 名完全一致。比如
gpt-4o、deepseek-chat、qwen-plus这类准确 ID。 - 检查 API Key 和额度：用 curl 直接调一下 API，排除 Key 失效、额度为 0、IP 白名单拦截等问题。
- 检查网络连通性：在服务器上 curl 一下 Base URL 对应的域名，确认能通、延迟正常。
其中第 4 步很多人会忽略。环境变量配置了 OPENAI_API_KEY，但 Key 已经过期或被额度限制，这时候 OpenClaw 的报错会是 agent failed before reply，非常不直观。一条 curl 命令就能定位问题：
bash复制curl https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'
如果返回 401，多半是 Key 问题；如果返回 200，问题就在 OpenClaw 的配置本身。这个习惯我强烈建议保留：任何模型接入后，先用 curl 验证一遍，再让 Agent 去连，能省掉大量无效调试。
4.3 零 token 方案：本地模型与第三方免费 Key 接入
“zero token”是 OpenClaw 社区里很流行的一种玩法：不买商业 API，改成接本地模型或者接第三方免费额度，实现零成本长期运行。常见组合是 Ollama 加 Qwen 系列模型，或者 Ollama 加 Llama 系列。
Ollama 接入的要点：
- 在服务器上先装 Ollama：`curl -fsSL https://