OpenClaw Gateway 升级后启动失败排查手记

OpenClaw 从旧版本升级到新版（2026.7.x）后，Gateway 服务通过 launchd 管理，启动后反复崩溃、无法监听端口。launchd 显示状态正常但探活始终失败。排查过程历经 stderr 捕获、SQLite 状态冲突、migration lease 循环三个阶段，最终定位到双层状态存储不一致与 conda 环境初始化冲突叠加导致的"死亡组合"。

一、问题现象

升级 OpenClaw 后，执行服务状态检查：

openclaw gateway status --deep

Runtime: stopped (state active)
Connectivity probe: failed
  connect ECONNREFUSED 127.0.0.1:18789
Service is loaded but not running (likely exited immediately).

状态非常矛盾：launchd 注册了服务（active），但端口无响应。更让人困惑的是，升级前服务运行完全正常，升级过程中没有报任何错误，服务文件没有被修改，但重启后就是起不来。

升级相关的典型故障模式通常有两类：

• 数据迁移失败：新版改了 schema，但迁移脚本没有正确执行
• 环境依赖冲突：新版引入了新的依赖，与现有环境不兼容

这次遇到的情况比两者都更隐蔽——两个问题各自独立存在，叠加后才完全暴露。

二、第一层：打破 stderr 黑盒

2.1 launchd 的日志陷阱

macOS 上通过 launchd 管理的服务，默认将标准错误输出重定向到 /dev/null。进程崩溃了，但没有任何日志留下。这是 macOS 服务排查的第一个障碍。

找到服务的 plist 配置文件：

~/Library/LaunchAgents/ai.openclaw.gateway.plist

修改 StandardErrorPath，让 stderr 输出到可追踪的文件：

<!-- 改前 -->
<key>StandardErrorPath</key>
<string>/dev/null</string>

<!-- 改后 -->
<key>StandardErrorPath</key>
<string>/tmp/gateway-real-error.log</string>

重启服务后，日志文件终于有内容了。但随之出现了一个完全意料之外的信息。

2.2 conda 环境污染

日志中出现的内容如下：

sources/app/bin:/Applications/Visual Studio Code.app/Contents/Resources/app/bin
         PYTHONUNBUFFERED=1
     active environment : None
     user config file : /Users/xxx/.condarc
          conda version : 25.1.1
          python version : 3.10.16.final.0
An unexpected error has occurred. Conda has prepared the above report.

这是 conda 环境的初始化报告，与 Gateway 核心业务完全无关。Node.js 进程为什么会触发 conda？

仔细分析发现，launchd 服务在启动时加载了 shell 环境，而用户的 .zshenv 中配置了 conda 自动初始化。launchd 的 wrapper 脚本实际上通过 shell 执行 node 命令，conda 的初始化 hook 在这个过程中被激活。更关键的是，conda 初始化失败时报错退出，导致整个启动链以 exit code 1 终止。

关键发现：这个 conda 错误是在 stderr 中被首先看到的，但它不是根本原因——它是启动链路上的一个干扰项。真正导致启动失败的原因藏在后续排查中。

三、第二层：双层状态存储冲突

3.1 OpenClaw 的状态架构

OpenClaw 采用了双层状态存储机制来管理升级路径：

• SQLite 数据库（~/.openclaw/state/openclaw.sqlite）：权威结构化数据，存储 schema 版本、migration 记录、运行时租约等
• Legacy JSON 文件（~/.openclaw/update-check.json）：向前兼容层，记录"上次检查更新时间"等元数据

正常情况下两者保持同步。但在这次升级后，迁移脚本可能因为之前的 conda 错误而被中断，导致 JSON 文件被更新了（标记为 July 24），而 SQLite 中的记录未同步（仍停留在 July 23）。

3.2 migration guard 机制

OpenClaw 在启动时引入了 migration guard——一个在状态不一致时拒绝启动的保护机制。检查 SQLite 中的 schema 元数据表：

sqlite3 ~/.openclaw/state/openclaw.sqlite \
  "SELECT * FROM schema_meta WHERE meta_key LIKE '%migration%';"

# 输出
startup-migrations|global|1||2026.7.1-2|1784931850781|1784931850781

cat ~/.openclaw/update-check.json

# 输出
{"lastCheckedAt": "2026-07-24T00:37:04.964Z"}

可以看到，SQLite 中记录的版本是 2026.7.1-2，migration checkpoint 已存在。但 JSON 文件的时间戳（July 24）与 SQLite 中的时间戳（July 23）相差一天。migration guard 检测到了这个不一致，拒绝了启动请求。

实际日志中明确记载了这一点：

[state-migrations] Legacy state migration warnings:
- Left legacy update-check state in place because shared SQLite state
  already differs: /Users/xxx/.openclaw/update-check.json

[openclaw] Reason: OpenClaw startup migrations did not complete cleanly;
             refusing to report the gateway ready.

3.3 诊断表：状态分歧的识别

四、第三层：migration lease 循环陷阱

4.1 lease 机制的工作原理

OpenClaw 使用分布式 lease（租约）机制来防止并发启动。Gateway 启动流程如下：

1. CLI 进程向 SQLite 写入一条带 TTL（默认 5 分钟）的 lease 记录
2. fork 出真正的 Gateway 子进程
3. Gateway 进程就绪后，CLI 删除 lease 记录
4. 如果进程异常退出，lease 残留，直到 TTL 过期才自动释放

检查当前 lease 状态：

sqlite3 ~/.openclaw/state/openclaw.sqlite \
  "SELECT * FROM state_leases WHERE scope='startup-migrations';"

# 如果有残留记录，说明上一次启动异常退出了

4.2 为什么循环发生

lease 残留 + migration guard 不一致 + launchd 自动重启，三者形成了一个自我强化的死循环：

循环链路

① launchd 拉起服务 → ② 获取 lease（写入 SQLite） → ③ migration guard 检测状态不一致 → ④ 进程主动退出（lease 保留） → ⑤ launchd 感知退出 → ⑥ 重新拉起服务 → 回到 ①

每次循环都会创建新的 lease（owner UUID 不同，但 lease key 相同），说明每次都成功获取了锁，只是进程立即退出了。这让问题更难定位——锁机制本身工作正常，但后续启动步骤全部失败。

4.3 绕过 launchd 直接诊断

为了排除 launchd 和 shell wrapper 的干扰，直接用 node 二进制启动 Gateway：

/usr/local/bin/node /usr/local/lib/node_modules/openclaw/dist/index.js \
  gateway --port 18789 > /tmp/gw-direct.log 2>&1 &

sleep 12
kill -0 $! 2>/dev/null && echo "RUNNING" || echo "EXITED"

这次进程没有立即退出。验证端口：

curl -s --max-time 3 http://127.0.0.1:18789/ -o /dev/null -w "%{http_code}"
# 输出: 200

lsof -i :18789
# node  54292  ...  TCP localhost:18789 (LISTEN)

绕过 launchd 后服务正常！这说明问题不在 Gateway 进程本身，而在于 launchd 的启动方式带了额外的环境初始化逻辑。shell wrapper 加载了 conda 初始化，conda hook 拦截了 Node.js 子进程，进程以 exit code 1 退出。

五、根因完整还原

5.1 双重故障叠加模型

这不是一个单一 bug，而是两个独立故障叠加形成的"死亡组合"：

根因 A：状态迁移不一致

升级过程中，legacy JSON 文件被更新（July 24），但 SQLite 中的 migration 记录未同步（July 23）。migration guard 检测到不一致，拒绝启动服务。这是升级路径上的数据迁移缺陷。

根因 B：conda 环境初始化冲突

launchd 的 shell wrapper 加载了 conda 初始化脚本，Node.js 子进程被 conda hook 拦截，进程以 exit code 1 退出。conda 的错误输出掩盖了真正的 migration guard 拒绝信息，干扰了排查方向。

5.2 修复步骤

第一步：删除与 SQLite 冲突的 legacy JSON 文件。

rm ~/.openclaw/update-check.json

第二步：清理残留的 migration lease，打断重启循环。

sqlite3 ~/.openclaw/state/openclaw.sqlite \
  "DELETE FROM state_leases WHERE scope='startup-migrations';"

第三步：通过 launchd 重启服务。

launchctl bootout gui/$(id -u)/ai.openclaw.gateway
openclaw gateway start

sleep 8
curl -s --max-time 3 http://127.0.0.1:18789/ -o /dev/null -w "%{http_code}"
# 输出: 200

服务恢复正常，端口 18789 监听建立，HTTP 请求返回 200。

六、排查方法论沉淀

6.1 macOS 服务排查四步法

这次排查经历可以提炼为一个通用方法论，适用于任何 launchd 管理的服务：

6.2 升级类故障的识别模式

升级后服务异常，常见的故障指纹：

• 时间戳分歧：多个状态存储之间的时间戳或版本号不一致
• Lease 残留：带 TTL 的锁记录在异常退出后未被清理
• 版本跳跃：状态数据期望的版本与服务实际版本不匹配
• 环境依赖冲突：新版引入的依赖与现有 shell 环境不兼容

6.3 子进程问题的定位技巧

# 查看进程树，观察父子关系和重启频率
ps -o pid,ppid,command -p $(pgrep -d',' -f SERVICE_NAME)

# 直接跟踪进程系统调用（需要 sudo）
sudo dtruss -t read -t write -t exit -f -p PID

# 检查进程打开的文件描述符
lsof -p PID

# 查看 launchd 服务实时日志
tail -f /tmp/gateway-real-error.log

七、总结

这次排查经历了一个典型的"表象简单、根因隐藏"的升级故障。表面上只是"升级后服务起不来"，实际涉及了 macOS launchd 日志机制、多层状态存储的一致性保证、带租约的防并发机制，以及 shell 环境初始化冲突四个技术维度。

最重要的经验有三点：

• 先让日志可见：launchd 吞掉 stderr 是 macOS 服务排查的第一个障碍，任何服务问题都应从这里开始
• 不满足于第一个错误：conda 的报错信息只是启动链上的干扰项，真正的原因藏在 migration guard 的状态检查里
• 状态持久化是升级类故障的高发区：当服务启动时主动拒绝服务，优先检查 schema 版本、migration 记录、checkpoint 等持久化状态

· · ·

附：核心命令速查

# 1. 捕获 launchd 服务真实错误
# 修改 plist: StandardErrorPath → /tmp/gw-error.log
launchctl bootout gui/$(id -u)/ai.openclaw.gateway
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

# 2. 查看进程状态
ps aux | grep openclaw | grep -v grep
lsof -i :18789

# 3. 检查 SQLite 状态
sqlite3 ~/.openclaw/state/openclaw.sqlite "SELECT * FROM schema_meta;"
sqlite3 ~/.openclaw/state/openclaw.sqlite "SELECT * FROM state_leases;"

# 4. 清理冲突状态
rm ~/.openclaw/update-check.json
sqlite3 ~/.openclaw/state/openclaw.sqlite \
  "DELETE FROM state_leases WHERE scope='startup-migrations';"

# 5. 重启服务
openclaw gateway start

# 6. 验证
curl -s --max-time 3 http://127.0.0.1:18789/ -w "\n%{http_code}"