OpenClaw 在 macOS 突然“全挂”排障实录：一次 Homebrew 动态库 ABI 漂移

现象：前一晚 20:00 还能正常使用，第二天早上 OpenClaw 完全起不来。

TL;DR（一句话结论）

这次不是 OpenClaw 业务逻辑崩溃，而是 Node 运行时依赖链被 Homebrew 升级打断：node@22 仍链接 libsimdjson.29.dylib，但系统里的 simdjson 已升级到只提供 .30，导致 Node 启动即崩，OpenClaw 所有命令随之失效。

1）故障现场

先做最小化探活：

which openclaw
openclaw --version
openclaw status

关键信号：

• openclaw 二进制路径存在
• 但执行时报错：
• Library not loaded: /opt/homebrew/opt/simdjson/lib/libsimdjson.29.dylib
• Referenced from: ... /opt/homebrew/Cellar/node@22/22.22.0/bin/node

再看进程：

ps aux | grep -i openclaw | grep -v grep

结果为空：说明不是“卡死未退出”，而是根本拉不起来。

2）为什么昨晚还好，今天突然挂？

继续验证依赖现状：

ls /opt/homebrew/opt/simdjson/lib/libsimdjson*.dylib
brew info simdjson | head -5
brew info node@22 | head -5

得到事实：

• 当前 simdjson 是 4.3.0，仅提供 libsimdjson.30*
• node@22 仍在找 libsimdjson.29.dylib
• Cellar 里还残留旧版本 4.2.4（包含 .29）

这就是典型的 ABI 版本漂移：

从时间上看，这类故障通常出现在一次 brew upgrade（或安装新包触发联动升级）之后。

3）修复过程（最短恢复路径）

目标：先恢复 .29 运行时，让 OpenClaw 活过来。

Step A：切回可用的 simdjson 版本

brew unlink simdjson
ln -sfn /opt/homebrew/Cellar/simdjson/4.2.4 /opt/homebrew/opt/simdjson

Step B：确认 .29 已恢复

ls /opt/homebrew/opt/simdjson/lib/libsimdjson.29.dylib

Step C：验证 Node / OpenClaw

node --version
openclaw --version
openclaw status

验证通过后，服务恢复。

4）根因复盘

根因

• OpenClaw 依赖 Node 运行
• Node 依赖 simdjson 动态库
• Homebrew 升级后，动态库主版本从 .29 变为 .30
• Node 未同步重建，导致运行时找不到旧 ABI

影响范围

• openclaw --version、openclaw status 直接失败
• 相关 cron/巡检链路会出现连带异常

5）防复发建议（可直接落地）

1）锁定关键依赖

brew pin simdjson

在 node@22 重新适配前，不让 simdjson 被自动升级。

2）升级前做“依赖对齐检查”

在 brew upgrade 前后自动跑：

node --version && openclaw --version && openclaw status >/dev/null

任一失败立即告警。

3）把关键版本写进运维基线

建议维护一份“可运行组合”清单，例如：

• [email protected]
• simdjson 4.2.4（或后续已验证可用版本）
• openclaw 2026.2.x

4）将故障从“人工发现”改为“主动发现”

把上述探活命令纳入定时巡检（每 30 分钟或每小时），出现 dyld 缺库错误时即时推送。

6）这次事件给我的启发

在 macOS + Homebrew 环境里，很多“应用突然挂掉”本质上是底层运行时依赖链断裂，不是应用本身代码问题。排障时先看“能不能启动”、再看“缺了哪个库”，比直接怀疑业务逻辑更快。

如果你也遇到「昨晚还好，今天全挂」这种情况，第一反应建议是：

1. 看 dyld 报错缺哪个 .dylib
2. 对齐 Homebrew 当前库版本与可执行文件链接版本
3. 先恢复可运行状态，再做长期升级策略

这套流程基本能在几分钟内定位同类故障。