[OpenClaw 升级期间 npm 安装失败] - npm Install Failure During OpenClaw Upgrade on macOS

OpenClaw 安装程序在 npm 全局安装阶段报告静默失败。安装脚本成功完成环境检测，但无法安装软件包且未暴露底层错误。

观察到的行为：

  🦞 OpenClaw Installer
  The only crab in your contacts you actually want to hear from. 🦞

✓ Detected: macos

Install plan
OS: macos
Install method: npm
Requested version: latest

[1/3] Preparing environment
✓ Homebrew already installed
✓ Node.js v22.22.0 found
· Active Node.js: v22.22.0 (/usr/local/bin/node)
· Active npm: 10.9.4 (/usr/local/bin/npm)

[2/3] Installing OpenClaw
✓ Git already installed
· Installing OpenClaw v2026.2.26
! npm install failed for openclaw@latest
  Command: env SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm --loglevel error --silent --no-fund --no-audit install -g openclaw@latest
  Installer log: /var/folders/mm/rhtrkglj0cn_h1xhmkp21w540000gn/T/tmp.kWd5ANRq99
! npm install failed; showing last log lines
! npm install failed; retrying

关键指标：

• 环境检测通过（Node.js、npm、Git 均已检测到）
• 安装命令执行但返回非零退出码
• 日志文件存在但安装程序截断了输出
• 后续重试尝试也失败

安装失败后的次要症状：

# Verify installation state
$ openclaw --version
zsh: command not found: openclaw

# Check npm global packages
$ npm list -g --depth=0 | grep openclaw
# (empty output - package not installed)

安装失败源于预先存在的 clawbot 安装与新的 openclaw 软件包之间的冲突。npm 全局安装失败可能是由以下一个或多个根本原因导致的：

1. 过时缓存和冲突的元数据

从 clawbot 升级到 openclaw 时，npm 可能保留了该先前软件包的损坏或过时缓存条目。clawbot 的 npm 注册表元数据与新的软件包解析产生冲突，导致静默解析失败。

技术序列：

# Internal npm behavior during upgrade
npm install -g openclaw@latest
  → Check registry for "openclaw"
  → npm cache contains stale "clawbot" metadata
  → Version resolution returns incorrect package or 404
  → Exit code: 1 (silently truncated by --silent flag)

2. macOS 上的权限和所有权冲突

npm 全局前缀 /usr/local/lib/node_modules 需要提升的写入权限。在启用了系统完整性保护（SIP）的 macOS 上，结合 Homebrew 管理的 Node 安装，经常会发生所有权冲突。

问题配置：

# Typical macOS permission issue
$ ls -la /usr/local/lib/node_modules
drwxr-xr-x  root            admin  # Owned by root
drwxr-xr-x  user           staff  # Previous installation owned by user

# npm install cannot write to root-owned directories

3. Node.js 版本管理器冲突

用户已激活 /usr/local/bin/node，这超出了典型的 Node 版本管理器路径。如果安装了 nvm、fnm 或 volta，可能存在多个 Node.js 二进制文件，导致 npm 引用不正确或过时的安装。

4. 本机模块编译失败（libvips/sharp）

安装程序使用 SHARP_IGNORE_GLOBAL_LIBVIPS=1 来跳过 libvips，但如果之前的 clawbot 安装留下了编译的 sharp 模块产物，npm 的重建过程可能会尝试重新编译不兼容的本机代码。

阶段 1：清除 npm 缓存并移除之前的安装

# Step 1: Clear npm cache completely
npm cache clean --force

# Step 2: Remove previous clawbot installation
npm uninstall -g clawbot

# Step 3: Verify removal
npm list -g --depth=0 | grep -E "(clawbot|openclaw)" || echo "No previous installations found"

阶段 2：修复 npm 全局前缀权限

# Step 4: Create npm global directory with correct permissions
mkdir -p ~/.npm-global

# Step 5: Configure npm to use local prefix
npm config set prefix '~/.npm-global'

# Step 6: Add to PATH (add to ~/.zshrc for persistent effect)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
export PATH=~/.npm-global/bin:$PATH

# Step 7: Verify npm prefix configuration
npm config get prefix
# Expected output: /Users/[username]/.npm-global

阶段 3：重新安装 OpenClaw

# Step 8: Install OpenClaw with verbose logging for debugging
npm install -g openclaw@latest --loglevel verbose

# Alternative: If specific version required
npm install -g openclaw@v2026.2.26 --loglevel verbose

阶段 4：替代方法（Homebrew Node）

如果权限问题持续存在，请使用 Homebrew 的 Node.js，它会自动处理权限：

# Step 9: Install Node.js via Homebrew (if not already)
brew install node

# Step 10: Reinstall OpenClaw with Homebrew-managed Node
npm install -g openclaw@latest

# Step 11: Verify installation path
which openclaw
# Expected: /opt/homebrew/bin/openclaw (M1/M2) or /usr/local/bin/openclaw (Intel)

修复前 vs. 修复后配置

修复前（问题配置）：

# ~/.npmrc or global npm config
prefix=/usr/local  # Root-owned, requires sudo
cache=/var/root/.npm  # Inaccessible

# Environment
NODE_PATH=/usr/local/lib/node_modules
PATH=/usr/local/bin:$PATH

修复后（正确配置）：

# ~/.npmrc or global npm config
prefix=/Users/[username]/.npm-global
cache=/Users/[username]/.npm
node_options=--max-old-space-size=4096

# Environment (in ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH
export NPM_CONFIG_PREFIX=~/.npm-global

应用修复后，使用以下命令验证安装：

基本验证

# Test 1: Check OpenClaw binary is accessible
$ openclaw --version
v2026.2.26

# Test 2: Verify npm global package status
$ npm list -g --depth=0 | grep openclaw
├── openclaw@2026.2.26

# Test 3: Confirm installation location
$ npm list -g --depth=0 --parseable | grep openclaw
/Users/[username]/.npm-global/lib/node_modules/openclaw

# Test 4: Test OpenClaw initialization
$ openclaw init
# Should display setup wizard without errors

高级验证

# Test 5: Verify all dependencies are intact
$ openclaw doctor
✓ Node.js version: v22.22.0
✓ npm version: 10.9.4
✓ OpenClaw installation: valid
✓ Configuration directory: accessible
✓ Plugin directory: accessible

# Test 6: Check for conflicting installations
$ which -a openclaw
/Users/[username]/.npm-global/bin/openclaw
# Should show only one path

预期的成功输出：

✓ OpenClaw v2026.2.26 installed successfully
✓ Binary location: /Users/[username]/.npm-global/bin/openclaw
✓ All dependencies resolved
✓ Installation complete

退出码验证：

# Verify clean exit code
$ echo $?
0

1. 多个 Node.js 安装（M 系列 Mac）

问题： Apple Silicon Mac 可能通过 Homebrew (/opt/homebrew)、nvm (~/.nvm) 和直接下载 (/usr/local) 安装了 Node.js。

检测方法：

# Check for multiple Node installations
$ which -a node
/opt/homebrew/bin/node
/usr/local/bin/node

# Check actual symlink targets
$ ls -la /usr/local/bin/node
/usr/local/bin/node -> ../Cellar/node/.../bin/node  # Homebrew Intel
$ ls -la /opt/homebrew/bin/node
/opt/homebrew/bin/node -> ../opt/node/bin/node  # Homebrew ARM

解决方案： 合并为单个 Node.js 安装。从 ~/.zshrc 中移除重复路径。

2. macOS 上受 SIP 保护的目录

问题： 在系统完整性保护下，/usr/local 可能部分受保护，导致间歇性权限失败。

检测方法：

$ ls -la /usr/local/lib/node_modules
ls: cannot access '/usr/local/lib/node_modules': Operation not permitted

解决方案： 专门使用 ~/.npm-global 前缀。避免使用 sudo npm install -g，因为它会产生所有权冲突。

3. 过时的 npm 注册表缓存

问题： 之前 clawbot 安装的损坏缓存条目在缓存清除后仍然存在。

检测方法：

# Check cache integrity
$ npm cache verify
npm warn Failed to clean up old cache
npm error Unexpected end of JSON input while parsing near '...": "1.0.0", "dependencies": {'

解决方案：

# Force complete cache deletion
rm -rf ~/.npm
npm cache clean --force --cache ~/.npm

4. Intel 与 ARM 架构不匹配

问题： 在 Apple Silicon（或反之）上安装为 Intel 架构编译的软件包。

检测方法：

$ file $(which openclaw)
# Intel: Mach-O 64-bit executable x86_64
# ARM:   Mach-O 64-bit executable arm64

解决方案： 确保 npm 下载正确架构的本机二进制文件。如有需要，使用 npm rebuild。

5. .npmrc 配置冲突

问题： 项目级或全局 .npmrc 文件覆盖了预期行为。

检测方法：

# Check all .npmrc files
$ cat ~/.npmrc
prefix=~/.npm-global
$ cat ./.npmrc  # in current directory
prefix=/usr/local  # Conflicts!

解决方案： 移除或纠正冲突的 .npmrc 条目。优先使用 ~/.npmrc 而不是项目级配置。