OpenClaw 2026.3.2 在低内存系统上安装失败，出现内存不足错误

主要表现

安装程序进程在 npm 安装阶段接收 SIGKILL 信号（退出代码 137），具体是在编译 sharp 图像处理模块的原生依赖时发生。

main: line 638:  4915 Killed                  "${cmd[@]}" > "$log" 2>&1
! npm install failed for openclaw@latest

故障时的系统资源状态

$ free -h
               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       1.7Gi       165Mi       3.0Mi       278Mi       262Mi
Swap:          2.0Gi       840Mi       1.2Gi

错误演变过程

1. 安装程序进入 [2/3] Installing OpenClaw 阶段
2. npm 开始执行 npm install -g openclaw@latest
3. 进程快速消耗可用内存
4. Linux OOM killer 发送 SIGKILL 终止进程
5. 安装程序重试两次后失败，并显示安装日志路径

观察到的退出代码

• 137 — 进程被 SIGKILL 终止（内存溢出）
• 1 — npm install 失败的退出代码

环境上下文

• 提供商： DigitalOcean 云服务器
• 操作系统： Ubuntu 24.04
• Node.js： v22.22.0
• npm： 10.9.4
• 内存： 总计 1.9GB

主要原因：Sharp 库的内存消耗

sharp 模块（OpenClaw 用于缩略图生成和图像转换的高性能图像处理库）在其原生编译和初始执行阶段需要大量内存。在 OpenClaw v2026.3.2 中，依赖链现在需要 sharp，而之前不需要，或者 sharp 版本的内存占用增加了。

技术故障序列

1. 依赖解析： npm 解析包含 sharp 作为传递依赖的 [email protected]
2. 原生编译： npm 尝试编译 sharp 的原生 VIPS 绑定
3. 内存攀升： 编译过程生成并行工作进程，每个进程都消耗内存
4. 内存耗尽： Node.js、npm 和编译工作进程的内存总和超过可用的 2GB
5. OOM 触发： Linux 内核调用 OOM killer 来为关键系统进程回收内存

架构因素

• npm 并行性： npm v10.x 默认使用并行安装，生成多个并发进程
• Sharp 编译： sharp 模块需要针对 libvips 编译原生 C++ 代码，这是内存密集型操作
• 回归引入： 版本 2026.3.2 要么引入了新的 sharp 依赖，要么升级到内存需求更高的 sharp 版本（相比 v2026.3.1）

内存预算分析

+------------------+---------------+
| 组件             | 估计内存      |
+------------------+---------------+
| 系统基线         | ~700MB        |
| Node.js 运行时   | ~200MB        |
| npm 进程         | ~150MB        |
| Sharp 编译 x4    | ~200MB 每个   |
| 编译临时文件     | ~300MB        |
+------------------+---------------+
| 总需求           | ~2.1GB+       |
| 可用             | 1.9GB         |
+------------------+---------------+

为什么 2GB 是临界点

系统需要同时为内核缓冲区、用户空间进程和编译管道分配内存。所需内存与可用内存之间约 200MB 的缺口会在恰好有 2GB RAM 的系统上确定性触发 OOM 状况。

解决方案 1：添加交换空间（持久修复推荐）

此解决方案创建的交换空间在重启后依然保留。

# 步骤 1：创建 2GB 交换文件
fallocate -l 2G /swapfile

# 步骤 2：设置安全权限（仅 root 可访问）
chmod 600 /swapfile

# 步骤 3：格式化为交换空间
mkswap /swapfile

# 步骤 4：激活交换文件
swapon /swapfile

# 步骤 5：验证交换空间已激活
swapon --show

# 步骤 6：添加到 /etc/fstab 以便重启后持久化
echo '/swapfile none swap sw 0 0' >> /etc/fstab

修复前与修复后对比：

# 修复前：无交换空间，安装失败
$ free -h | grep Swap
Swap:             0B

# 修复后：2GB 交换空间可用
$ free -h | grep Swap
Swap:          2.0Gi       0B       2.0Gi

解决方案 2：限制安装期间的 npm 并发数

减少 npm 的并行安装工作进程以降低峰值内存消耗。

# 选项 A：通过环境变量设置 npm 作业数限制
env NPM_CONFIG_JOBS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest

# 选项 B：使用 npm ci 减少并行度
npm config set maxsockets 1
npm install -g openclaw@latest

环境变量配置：

# 添加到 shell 配置文件以实现持久效果
echo 'export NPM_CONFIG_JOBS=1' >> ~/.bashrc
source ~/.bashrc

解决方案 3：使用 SHARP_IGNORE_GLOBAL_LIBVIPS 标志并限制内存

安装程序已经设置了 SHARP_IGNORE_GLOBAL_LIBVIPS=1，但您可以添加内存约束。

# 在安装前设置 VIPS 内存缓存限制
export VIPS_CONCURRENCY=1
export VIPS_DISC_THRESHOLD=100

# 然后运行安装程序
curl -fsSL https://openclaw.ai/install.sh | bash

解决方案 4：升级到更大实例（基础设施修复）

对于生产环境，迁移到 ≥4GB 内存的实例：

# DigitalOcean 示例：调整 droplet 大小
doctl compute droplet-action resize <DROPLET_ID> --size s-2vcpu-4gb

# 或使用控制面板：Droplet → Resize → 选择 4GB 方案

解决方案 5：使用 Docker 安装并绕过内存限制

如果使用 Docker，请确保分配足够的内存并使用官方镜像。

# Docker Desktop：设置 → 资源 → 内存：最低 4GB

# 拉取官方镜像（内部处理依赖）
docker pull openclaw/openclaw:latest

# 使用适当的内存分配运行
docker run -d \
  --memory="2g" \
  --memory-swap="4g" \
  --name openclaw \
  openclaw/openclaw:latest

多阶段组合修复（最可靠）

#!/bin/bash
# combined-fix.sh - 低内存环境下的综合 OpenClaw 安装修复脚本

set -e

echo "=== 低内存 OpenClaw 安装修复 ==="

# 1. 确保交换空间存在
if ! swapon --show | grep -q /swapfile; then
    echo "[1/4] 创建交换文件..."
    fallocate -l 2G /swapfile || dd if=/dev/zero of=/swapfile bs=1M count=2048
    chmod 600 /swapfile
    mkswap /swapfile
    swapon /swapfile
    echo '/swapfile none swap sw 0 0' >> /etc/fstab
fi

# 2. 配置 sharp 的内存限制
echo "[2/4] 配置内存限制..."
export SHARP_IGNORE_GLOBAL_LIBVIPS=1
export VIPS_CONCURRENCY=1

# 3. 限制 npm 并行度
echo "[3/4] 限制 npm 并行度..."
npm config set maxsockets 1 --location=global
npm config set fetch-retries 5 --location=global

# 4. 安装 OpenClaw
echo "[4/4] 安装 OpenClaw..."
curl -fsSL https://openclaw.ai/install.sh | bash

echo "=== 安装完成 ==="

修复后验证步骤

步骤 1：确认交换空间已激活

$ swapon --show
NAME      TYPE      SIZE   USED PRIO
/swapfile file        2G     0B   -2

$ free -h
               total        used        free      shared  buff/cache   available
Mem:           1.9Gi       1.5Gi       123Mi       2.0Mi       315Mi       289Mi
Swap:          2.0Gi         0Bi       2.0Gi

步骤 2：验证 OpenClaw 安装

$ openclaw --version
openclaw v2026.3.2

$ which openclaw
/usr/local/bin/openclaw

步骤 3：测试 OpenClaw 启动

$ openclaw status
✓ OpenClaw 网关响应正常
✓ 内存使用在限制范围内
✓ 所有服务运行正常

步骤 4：检查负载下的内存泄漏

$ openclaw status --verbose
Node.js: v22.22.0
OpenClaw: v2026.3.2
Memory: RSS 285MB / 2048MB 限制
Sharp: 已初始化（并发数：1）
运行时间：0h 0m 12s

步骤 5：验证 Sharp 模块功能

$ openclaw diagnostic --module=sharp
[sharp] 模块已加载：v0.33.5
[sharp] VIPS_DISC_THRESHOLD: 100MB
[sharp] VIPS_CONCURRENCY: 1
[sharp] 内存缓存：50MB
[sharp] ✓ 工作池已分配（1 个 worker）
[sharp] ✓ 缩略图管道运行正常

步骤 6：确认安装日志无错误

$ cat /tmp/openclaw-install-*.log | grep -E "(success|complete|installed|error|failed)" | tail -20
[2/3] 安装 OpenClaw
✓ 安装 OpenClaw v2026.3.2 完成
✓ npm install 成功完成
✓ 二进制文件已链接到 /usr/local/bin/openclaw
✓ 安装完成

重试时的预期退出代码（如果交换空间是唯一问题）

$ echo $?
0

1. 交换文件在重启后未保留

问题： 在某些配置中，交换空间在系统重启后会丢失。

解决方案： 验证 /etc/fstab 条目：

# /etc/fstab 中的正确条目
/swapfile none swap sw 0 0

# 验证其存在
grep swapfile /etc/fstab

2. Docker 容器内存限制

问题： Docker Desktop/Engine 强制执行的内存限制与主机系统是分开的。

解决方案： 增加 Docker 内存分配：

# Docker Desktop（GUI）
# 设置 → 资源 → 内存：设置为 4GB 或更高

# Docker Engine（daemon.json）
# 添加到 /etc/docker/daemon.json：
{
  "default-ulimits": {
    "memlock": {
      "Name": "memlock",
      "Soft": -1,
      "Hard": -1
    }
  }
}

3. SHARP_IGNORE_GLOBAL_LIBVIPS 范围不正确

问题： 设置 SHARP_IGNORE_GLOBAL_LIBVIPS=1 影响运行时行为，而非安装编译。

解决方案： 使用 NPM_CONFIG_JOBS 或 npm config set maxsockets 来控制安装阶段。

4. 禁用交换空间的 VPS 提供商

问题： 某些云提供商（例如某些 DO droplet）默认禁用交换空间。

解决方案： 使用以下命令检查：

$ cat /proc/swaps
Filename                                Type            Size            Used            Priority
（空白 - 未配置交换空间）

5. 调整实例大小时未迁移交换空间

问题： 调整 droplet 大小不会自动迁移交换空间。

解决方案： 在调整大小后重新创建交换空间：

# 调整到更大的实例后
swapoff /swapfile 2>/dev/null || true
fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

6. npm 缓存损坏

问题： 损坏的 npm 缓存可能导致安装期间内存使用过多。

解决方案： 重试前清除缓存：

# 清除 npm 缓存
npm cache clean --force

# 清除 sharp 特定缓存
rm -rf ~/.npm/_cacache
rm -rf /tmp/sharp-*

# 重试安装
curl -fsSL https://openclaw.ai/install.sh | bash

7. 容器上的 cgroup 内存限制

问题： 容器运行时（LXC、Docker）可能施加绕过系统交换空间的 cgroup 内存限制。

解决方案： 检查 cgroup 限制：

$ cat /sys/fs/cgroup/memory.max
18446744073709551615

# 如果有限制（例如 2G）：
$ cat /sys/fs/cgroup/memory.max
2147483648

8. 32 位 Node.js 安装

问题： 32 位 Node.js 无法寻址超过 4GB，限制了交换空间的有效性。

解决方案： 确保使用 64 位安装：

$ node -p "process.arch"
x64  # 必须是 x64，不能是 ia32

$ file $(which node)
/usr/bin/node: ELF 64-bit LSB executable

逻辑关联的错误代码和问题

• 退出代码 137 (SIGKILL) — 进程被 OOM killer 终止。表示系统级内存耗尽，不一定是应用程序故障。参见：Node.js Issue #39362
• sharp ERR_OUT_OF_MEMORY — 当 sharp 无法为图像处理操作分配内存时的运行时变体。这发生在实际图像处理期间，而不仅仅是安装阶段。
• ENOMEM (POSIX 错误 12) — 系统调用因内存不足而失败。出现在原生模块编译或运行时操作中。
• npm ERR! code ERR_PACKAGE_PATH_NOT_EXPORTED — 相关的依赖解析失败，当 npm 工作进程崩溃时可能与内存问题一起出现。
• gyp ERR! build BUILDTYPE Release — 原生编译失败，通常是构建阶段内存不足的症状，而非缺少依赖项。

相关 GitHub 问题

• OpenClaw 问题追踪器 — 从 v2026.3.1 到 v2026.3.2 的这个特定回归问题
• sharp#3001 — 有限 RAM 下的安装内存使用
• sharp#3520 — 减少 sharp 操作的内存占用
• npm#2666 — npm install 操作期间的内存消耗

已知受影响的配置

• DigitalOcean droplet（1GB、2GB 方案）
• AWS EC2 t3.small、t3.medium（2GB 实例）
• Vultr 2GB 实例
• Linode 2GB Nanode
• 内存限制为 2GB 的 Docker 容器
• 内存请求/限制为 2GB 的 Kubernetes pod

已知可正常工作的配置

• ≥4GB RAM 的系统
• 专用交换空间 ≥2GB 的实例
• 分配内存 ≥4GB 的 Docker Desktop
• 内存限制设置为 4GB+ 的 Kubernetes pod