Gateway 网络 / 崩溃问题

编号格式 #NNNNN 对应 GitHub issue，可直接搜索去重。

切换网络后 Gateway 崩溃（AssertionError，IPv4 变为 undefined）

来源：GitHub #38628（2026-03）

现象：笔记本切换 WiFi / 有线网络后，Gateway 进程崩溃，报 AssertionError，日志显示 IPv4 地址变为 undefined。

原因：网络切换瞬间系统 IPv4 短暂变为 undefined，Gateway 的断言检查未处理此中间状态，直接抛出错误。

解决方法：

立即恢复：

bash

openclaw gateway restart

长期方案——绑定到 0.0.0.0 而非具体 IP：

json5

{
  gateway: {
    host: "0.0.0.0"
  }
}

来源：GitHub #38682（2026-03）

现象：macOS 上使用 VPN 时，VPN 断线重连后 Gateway 不会自动恢复，需要手动重启。

原因：macOS LaunchAgent 无法检测 Gateway 进程的网络状态变化，不会在网络恢复后触发重启。

解决方法：

方案 1：在 LaunchAgent plist 中添加网络状态监测：

xml

<!-- ~/Library/LaunchAgents/ai.openclaw.gateway.plist -->
<key>KeepAlive</key>
<dict>
  <key>NetworkState</key>
  <true/>
</dict>

bash

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

方案 2：将 openclaw gateway restart 绑定到 VPN 客户端的重连事件（参考对应 VPN 软件文档）。

来源：GitHub #38721（2026-03）

现象：运行 openclaw stop 后一直超时，Gateway 进程不退出。重新运行 openclaw start 时报 "already running"。

原因：有活跃的子进程句柄（如未完成的 Agent Loop、进行中的工具调用）阻止 Gateway 正常关闭。

解决方法：

bash

# 查看 PID
openclaw gateway status

# 按 PID 强制终止
kill -9 <PID>

注意：使用 pkill -f openclaw 前确认只有 openclaw 进程匹配，避免误伤其他程序。