Summary

openclaw update fails during npm package update when node-llama-cpp tries to install cmake via xpm, blocking all updates.

Environment

• OS: macOS 15.x (Sequoia) Apple Silicon
• OpenClaw Version: 2026.2.26
• Node.js: v25.6.0
• npm: v11.9.0
• Installation: Homebrew global npm (/opt/homebrew/lib/node_modules/openclaw)
• cmake: Not installed initially

Error Message

npm error SpawnError: Command npm exec --yes -- xpm@^0.16.3 install @xpack-dev-tools/cmake@latest --no-save exited with code 254

Full Error Log

Updating OpenClaw...
│ ◇ ✗ Updating via package manager (98.49s)
npm error at createError (file:///opt/homebrew/lib/node_modules/openclaw/node_modules/node-llama-cpp/dist/utils/spawnCommand.js:34:20)
npm error at ChildProcess.<anonymous> (file:///opt/homebrew/lib/node_modules/openclaw/node_modules/node-llama-cpp/dist/utils/spawnCommand.js:47:24)
npm error at ChildProcess.emit (node:events:508:20)
npm error at ChildProcess._handle.onexit (node:internal/child_process:293:12)

Update Result: ERROR
Root: /opt/homebrew/lib/node_modules/openclaw
Reason: global update
Before: 2026.2.26
After: 2026.2.26
Total time: 98.67s

Detailed npm Log

From ~/.npm/_logs/2026-03-02T17_53_07_757Z-debug-0.log:

[node-llama-cpp] ◷ Downloading cmake
[node-llama-cpp] ✖ Failed to download cmake
[node-llama-cpp] To install "cmake", you can run "brew install cmake"
[node-llama-cpp] A prebuilt binary was not found, falling back to building from source

npm error code ENOENT
npm error syscall open
npm error path /Users/yuki/.npm/_npx/3f6d3ce19cc8f028/package.json
npm error errno -2
npm error enoent Could not read package.json: Error: ENOENT: no such file or directory
npm error enoent This is related to npm not being able to find a file.

[node-llama-cpp] Failed to build llama.cpp with Metal support. 
Error: SpawnError: Command npm exec --yes -- xpm@^0.16.3 install @xpack-dev-tools/cmake@latest --no-save exited with code 254

Problem Description

1. openclaw update triggers npm update
2. node-llama-cpp postinstall script runs
3. It tries to download cmake via xpm (xPack Package Manager)
4. xpm cmake installation fails with exit code 254
5. The entire update process fails and rolls back
6. User is stuck on old version (2026.2.26)

Root Cause

• System doesn't have cmake installed
• node-llama-cpp tries to auto-download cmake but fails
• xpm has issues (possibly network, permissions, or Node.js 25 compatibility)
• The error message suggests: To install "cmake", you can run "brew install cmake"

Impact

• Users cannot update OpenClaw to newer versions
• Security updates and bug fixes cannot be applied
• Workaround requires manual cmake installation (not documented)

Solution

Installing cmake via Homebrew before updating resolves the issue:

brew install cmake
openclaw update  # Now succeeds

Suggested Fixes

Option 1: Document cmake requirement

Add to installation/update docs:

### Prerequisites for macOS
- cmake (install via `brew install cmake`)

Option 2: Make node-llama-cpp optional

Related to #17988 - make node-llama-cpp an optional dependency so updates don't fail if it can't build.

Option 3: Use system cmake if available

Modify node-llama-cpp postinstall to check for system cmake before trying xpm:

if command -v cmake &>/dev/null; then
  echo "Using system cmake"
else
  # Try xpm download
fi

Option 4: Provide --skip-optional flag

Allow users to update without optional dependencies:

openclaw update --skip-optional

Workaround

Until fixed:

# Install cmake first
brew install cmake

# Then update
openclaw update

Related Issues

• Make node-llama-cpp an optional dependency to reduce install size by ~670MB #17988 - Make node-llama-cpp an optional dependency
• node-llama-cpp silently fails to install on Apple Silicon + Node.js 22 #29548 - node-llama-cpp silently fails to install on Apple Silicon
• memory_search crashes gateway: node-llama-cpp FileHandle GC error on Node.js 25 #18839 - memory_search crashes gateway: node-llama-cpp FileHandle GC error

Additional Context

This issue blocks users from updating OpenClaw and is not immediately obvious since the error message is buried in npm logs. The suggestion to install cmake via Homebrew is shown in the logs but easy to miss.