openclaw - 💡(How to fix) Fix Bug: OpenClaw breaks after Homebrew updates due to mixed Homebrew Node/runtime/plugin cache drift [1 comments, 2 participants]

Summary

OpenClaw repeatedly becomes unavailable after brew upgrade / OpenClaw updates on macOS when the installed service/CLI is backed by Homebrew-managed Node and globally installed OpenClaw packages.

This happened multiple update cycles in a row on my machine. The failures are not a single bad update; they appear to come from a fragile mixed runtime layout:

• Gateway LaunchAgent runs Homebrew node@24
• CLI runs via #!/usr/bin/env node, resolving to Homebrew node
• OpenClaw package is loaded from global Homebrew npm path
• plugin runtime deps are cached separately under ~/.openclaw/plugin-runtime-deps
• older bundled runtime artifacts also exist but are not the active service runtime

When Homebrew or OpenClaw updates only part of that stack, the host, plugins, SDK files, and native library ABI can drift out of sync.

Environment

• macOS: 26.3 arm64
• OpenClaw: 2026.4.27
• Active CLI package: /opt/homebrew/lib/node_modules/openclaw
• CLI shebang: /opt/homebrew/bin/openclaw -> #!/usr/bin/env node
• CLI Node after repair: /opt/homebrew/bin/node -> v25.9.0
• Gateway service Node: /opt/homebrew/opt/node@24/bin/node -> v24.15.0
• Gateway package path: /opt/homebrew/lib/node_modules/openclaw/dist/index.js
• Relevant Homebrew packages after repair:
  • node 25.9.0_2
  • node@24 24.15.0
  • simdjson 4.6.3

Gateway LaunchAgent currently contains:

ProgramArguments:
  /Users/.../.openclaw/service-env/ai.openclaw.gateway-env-wrapper.sh
  /Users/.../.openclaw/service-env/ai.openclaw.gateway.env
  /opt/homebrew/opt/node@24/bin/node
  /opt/homebrew/lib/node_modules/openclaw/dist/index.js
  gateway
  --port
  18789

There is also an older inactive/stale-looking LaunchAgent backup using bundled Node:

~/.openclaw/tools/node-v22.22.0/bin/node
~/.openclaw/lib/node_modules/openclaw/dist/entry.js

Observed failures

1. Native library ABI break after Homebrew update

openclaw status failed before the CLI could start:

dyld: Library not loaded: /opt/homebrew/opt/simdjson/lib/libsimdjson.29.dylib
  Referenced from: /opt/homebrew/Cellar/node/25.6.1/bin/node
  Reason: tried: '/opt/homebrew/opt/simdjson/lib/libsimdjson.29.dylib' ... no such file

At that point Homebrew had:

/opt/homebrew/opt/simdjson/lib/libsimdjson.33.dylib

So Homebrew node 25.6.1 was still linked against libsimdjson.29, while the installed simdjson provided ABI 33.

Repair used:

brew reinstall node

Then openclaw status worked again with node v25.9.0.

2. Host/plugin version skew after update

Gateway logs show plugin compatibility failures where plugins require a newer host than the active OpenClaw host:

Invalid config at ~/.openclaw/openclaw.json:
- plugins.entries.feishu: plugin feishu: plugin requires OpenClaw >=2026.4.24, but this host is 2026.4.22; skipping load
- plugins.entries.whatsapp: plugin whatsapp: plugin requires OpenClaw >=2026.4.24, but this host is 2026.4.22; skipping load

Later, after another update cycle:

Invalid config at ~/.openclaw/openclaw.json:
- plugins.entries.feishu: plugin feishu: plugin requires OpenClaw >=2026.4.25, but this host is 2026.4.24; skipping load
- plugins.entries.whatsapp: plugin whatsapp: plugin requires OpenClaw >=2026.4.25, but this host is 2026.4.24; skipping load

3. Plugin runtime cache / SDK file mismatch

Gateway logs also show a Telegram plugin registration failure after update:

[plugins] telegram failed during register from /opt/homebrew/lib/node_modules/openclaw/dist/extensions/telegram/index.js:
Error: Cannot find module '/opt/homebrew/lib/node_modules/openclaw/dist/plugin-sdk/root-alias.cjs/model-session-runtime'
Require stack:
- ~/.openclaw/plugin-runtime-deps/openclaw-unknown-d811d4fcd03f/dist/extensions/telegram/probe-*.js

~/.openclaw/plugin-runtime-deps contained multiple cache dirs, including versioned and unknown entries:

openclaw-2026.4.24-da6bdffc3d96
openclaw-2026.4.27-da6bdffc3d96
openclaw-unknown-983b8cea1a8e
openclaw-unknown-d811d4fcd03f

This suggests stale runtime deps/probe files can survive across host updates and reference SDK paths that are not present in the currently active global package.

Expected behavior

After brew upgrade or OpenClaw update, the service and CLI should keep working, or the installer/service manager should atomically update the full runtime stack so these do not drift:

• Node runtime
• OpenClaw host package
• plugin SDK
• plugin runtime deps cache
• LaunchAgent runtime path

Actual behavior

The service/CLI can become unavailable after update due to one or more of:

1. Homebrew native dependency ABI mismatch (node linked against missing libsimdjson.*.dylib)
2. Gateway host version older than configured plugin requirements
3. cached plugin runtime deps referencing missing SDK files

Workaround used locally

brew reinstall node
brew pin node node@24 simdjson

This restored the immediate CLI/service availability, but it is a workaround. It still leaves OpenClaw coupled to Homebrew's rolling Node/runtime libraries.

Suggested fix direction

A more robust setup would be one of:

1. Prefer a bundled/pinned OpenClaw-managed Node runtime for the Gateway service instead of Homebrew Node.
2. Make the LaunchAgent use the same runtime/package layout that OpenClaw controls atomically.
3. On update, clear or validate ~/.openclaw/plugin-runtime-deps against the active host version/build hash.
4. Detect host/plugin version skew before service start and either auto-repair or produce a clear actionable error.
5. Avoid #!/usr/bin/env node for critical service paths if Homebrew Node ABI churn can break the CLI before OpenClaw can self-repair.

Why this matters

This has reproduced across several consecutive update cycles locally. The current layout makes OpenClaw fragile after normal Homebrew updates, especially on macOS where Homebrew frequently updates shared libraries and replaces ABI versions.