openclaw - 💡(How to fix) Fix v2026.5.12-beta.8 macOS update can leave gateway in launchd loop from stale updater job and service env wrapper

Summary

During a sanitized macOS npm update audit to 2026.5.12-beta.8 (097daf9) on 2026-05-14, one host was already down after an earlier beta 8 update attempt. The host was reachable by SSH, but openclaw gateway status --deep showed the LaunchAgent loaded while the gateway connectivity probe failed.

Running the beta 8 update completed the package/plugin portion, but the service refresh failed and the gateway would not stay online until a stale submitted launchd updater job was removed and the service plist was repaired.

Host/user/IP paths, account identifiers, tokens, and private workspace/prompt content are intentionally omitted.

Version / install context

• macOS npm/global install under Homebrew Node
• Before: 2026.5.12-beta.5
• After: 2026.5.12-beta.8 (097daf9)
• Command used:

openclaw update --channel beta --tag 2026.5.12-beta.8 --yes --timeout 1800

Observed behavior

The update's package/plugin phase completed, then service refresh failed:

Failed to refresh gateway service environment from updated install: Error: updated install refresh failed (...): Gateway install failed: Error: launchctl bootstrap failed: Bootstrap failed: 5: Input/output error

The gateway binary could be started manually in the foreground and reached readiness, but the managed LaunchAgent repeatedly terminated shortly after readiness:

[gateway] http server listening
[gateway] ready
[gateway] signal SIGTERM received

macOS launchd state showed a submitted updater job named like ai.openclaw.update.<tag> repeatedly running a temp update script, with a high run count and last exit code = 127. Logs showed launchd signaling the gateway after that updater job exited. Removing the stale submitted updater job and restarting the gateway restored stable service.

There was a second service-install/refresh problem at the same time: macOS logs showed policy/background-task-management friction around the generated service-env wrapper script under the user's OpenClaw state directory:

AppleSystemPolicy: security policy would not allow process .../.openclaw/service-env/ai.openclaw.gateway-env-wrapper.sh
BackgroundTaskManagement: exceeded max notifications for ai.openclaw.gateway-env-wrapper.sh

The gateway became stable after the stale updater job was removed and the LaunchAgent was temporarily rewritten to run Node directly with launchd EnvironmentVariables instead of the generated wrapper script. Token values are intentionally omitted; this was a local recovery workaround, not a recommended long-term fix.

Expected behavior

• The updater should not leave a keepalive submitted ai.openclaw.update.* job that can repeatedly terminate the gateway.
• If a stale submitted updater job exists, openclaw gateway status --deep or openclaw doctor should detect it and report a clear remediation.
• Gateway service install/refresh on macOS should avoid wrapper execution policy failures where possible, or surface them clearly when they happen.
• Service refresh/reinstall should preserve, migrate, or explicitly warn about local overlay gateway token state rather than leaving a listening-but-unauthorized gateway.

Actual recovery needed

1. Confirmed the gateway binary could start in the foreground.
2. Found launchd repeatedly running a stale submitted updater job that exited 127.
3. Removed that submitted updater job and deleted the temp update script.
4. Restarted OpenClaw gateway.
5. Repaired LaunchAgent service env handling locally so the gateway could remain stable.

After recovery:

• openclaw --version: OpenClaw 2026.5.12-beta.8 (097daf9)
• openclaw gateway status --deep: CLI/gateway beta 8, LaunchAgent loaded/running, connectivity OK, admin-capable
• Channels connected again: Discord, Telegram, and WhatsApp

One remaining operator task is unrelated to gateway service recovery: direct agent routing fell back because the Codex/OpenAI OAuth refresh returned 401 token_expired, so that host needs re-authentication.

Likely source areas

• src/cli/update-cli/update-command.ts
• launchd update/restart helper code
• src/daemon/launchd.ts
• src/daemon/launchd-plist.ts
• service env/local overlay token handling

Impact

This is high impact for usability because the host appears "down" after update even though the package update itself succeeded. The gateway can briefly reach ready, then gets killed again, and the visible symptoms point operators toward generic gateway restart/install commands rather than the stale submitted updater job and wrapper-policy interaction that actually kept the service offline.