openclaw - 💡(How to fix) Fix macOS LaunchAgent gateway restart can leave valid gateway command unreachable

TL;DR

On macOS, openclaw gateway restart / the LaunchAgent path can leave the gateway service installed but not loaded or not reachable, while the exact same gateway command works when started in the foreground. This makes local plugin/runtime smoke checks falsely look like plugin failures even though the gateway binary and config are valid.

Why this matters

Plugin rollouts and local agent smoke tests depend on a reliable openclaw gateway status --deep result. In this case, EvaBrain/OpenClaw plugin validation passed on Linux/systemd customer VMs, but the local macOS LaunchAgent path failed independently of the plugin. That creates a confusing failure mode for any plugin, not only GBrain:

flowchart LR
  A[Plugin install/update] --> B[Restart OpenClaw gateway]
  B --> C{LaunchAgent loaded?}
  C -- no --> D[Status probe fails / port closed]
  C -- yes --> E[Runtime plugin smoke]
  D --> F[False plugin or package suspicion]

Reproduction observed

Environment:

• macOS local OpenClaw install
• CLI: openclaw 2026.5.19
• Gateway command from status output: /opt/homebrew/opt/node/bin/node /opt/homebrew/lib/node_modules/openclaw/dist/index.js gateway --port 18789
• Service file: ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Observed sequence:

1. openclaw gateway status --deep reported:
   • Service: LaunchAgent (not loaded)
   • LaunchAgent plist exists but launchd has no loaded job
   • Connectivity probe: failed
   • connect ECONNREFUSED 127.0.0.1:18789
2. The exact command from the status output was started through the same service env wrapper in the foreground/background:

   env -i ~/.openclaw/service-env/ai.openclaw.gateway-env-wrapper.sh \
     ~/.openclaw/service-env/ai.openclaw.gateway.env \
     /opt/homebrew/opt/node/bin/node \
     /opt/homebrew/lib/node_modules/openclaw/dist/index.js gateway --port 18789

3. Gateway then became reachable and plugin runtime inspection worked:

   {
     "name": "GBrain",
     "status": "loaded",
     "version": "0.41.18.6",
     "toolNames": ["gbrain_status", "gbrain_search", "gbrain_query"],
     "httpRoutes": 1
   }

Expected behavior

If the gateway command and config are valid, openclaw gateway restart should leave the LaunchAgent loaded and reachable on the configured port, or fail with a concrete actionable error from launchctl / service bootstrap.

Actual behavior

The service can end up with:

• plist present
• launchd job absent or not reachable
• port closed
• foreground command works

That means the service manager path is the failing layer.

Suggested fix direction

A robust fix should likely add a post-start verification loop to the macOS service manager path:

sequenceDiagram
  participant CLI as openclaw gateway restart
  participant LA as launchctl/LaunchAgent
  participant GW as Gateway process
  participant Probe as status probe

  CLI->>LA: bootstrap/load job
  LA->>GW: start command with service env
  CLI->>Probe: wait for ws://127.0.0.1:<port>
  alt reachable
    Probe-->>CLI: success
  else launchd missing or port closed
    CLI->>LA: collect print/blame/last exit status
    CLI-->>CLI: return actionable failure
  end

Recommended acceptance criteria:

• openclaw gateway restart fails nonzero if the LaunchAgent is not actually loaded or reachable after a bounded timeout.
• status --deep includes the launchctl print gui/$UID/ai.openclaw.gateway / last-exit information when the plist exists but the job is not loaded.
• The service-manager path and foreground path use the same resolved env/config inputs.
• Plugin smoke tests can distinguish gateway service-manager failure from plugin load failure.

Notes

This was found during an EvaBrain rollout, but the issue is host/runtime-level and applies to any OpenClaw plugin or local gateway smoke test.