Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix gateway restart on macOS fails to re-bootstrap LaunchAgent [2 pull requests, 4 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#63128•Fetched 2026-04-09 07:58:07
View on GitHub
Comments
4
Participants
3
Timeline
7
Reactions
0
Author
zwaydotzwaydot
Participants
jbalaterojbalateroniiglelogniiglelogzwaydotzwaydot
Timeline (top)
commented ×4cross-referenced ×1referenced ×1subscribed ×1

openclaw gateway restart on macOS bootouts the LaunchAgent but does not re-bootstrap it, leaving the gateway dead after the process exits.

Error Message

$ openclaw gateway restart
Restarted LaunchAgent: gui/502/ai.openclaw.gateway

Root Cause

After shutdown, launchd does not restart the process because the service was bootout'd.

Fix Action

Workaround

openclaw gateway install && openclaw gateway start

Or manually re-bootstrap:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

PR fix notes

PR #63164: fix(daemon): re-bootstrap LaunchAgent after bootout in gateway restart

Description (problem / solution / changelog)

Summary

  • openclaw gateway restart on macOS called launchctl bootout which fully deregistered the LaunchAgent, leaving the gateway dead with no auto-restart
  • Fix: after bootout, re-bootstrap the plist so the service stays registered but dormant; on restart, enable before kickstart to clear any persisted disabled state

Closes #63128

Changes

  • src/daemon/launchd.ts — stopLaunchAgent: add disable + bootstrap after bootout; restartLaunchAgent: add enable before kickstart -k
  • src/daemon/launchd.test.ts — update assertions for new enable-before-kickstart behavior

Test plan

  • launchd.test.ts (all pass)
  • launchd-recovery.test.ts (all pass)
  • lifecycle.test.ts + lifecycle-core.test.ts (all pass, 61 total)
  • Manual: openclaw gateway restart on macOS, verify service stays in launchctl list
  • Manual: openclaw gateway stop then openclaw gateway start, verify KeepAlive works

🤖 Generated with Claude Code

Changed files

  • src/daemon/launchd.test.ts (modified, +181/-2)
  • src/daemon/launchd.ts (modified, +55/-3)

PR #64447: fix(daemon): keep launchd stop persistent without reinstall

Description (problem / solution / changelog)

Summary

  • make openclaw gateway stop persistently stop macOS LaunchAgents without requiring reinstall before a later start or restart
  • disable the LaunchAgent before stopping so KeepAlive does not immediately relaunch it, then fall back to bootout if stop cannot be made authoritative
  • treat explicit start, restart, and repair flows as operator intent to bring the LaunchAgent back by re-enabling it before bootstrap or kickstart
  • validate LaunchAgent labels before constructing plist paths or launchctl targets

Changes

  • src/daemon/launchd.ts
    • validate the resolved LaunchAgent label before using it in plist paths or launchctl commands
    • change stopLaunchAgent from unconditional bootout to disable + stop, with a bootout fallback when disable fails, stop fails, or launchctl print cannot confirm the service is down
    • sanitize launchctl output before surfacing warning or error details
    • enable the LaunchAgent before bootstrap in install/repair flows and before kickstart -k in restartLaunchAgent
  • src/daemon/launchd-restart-handoff.ts
    • validate the resolved LaunchAgent label in the detached restart helper
    • enable before kickstart/start in the detached restart helper
    • pass the plain label explicitly for launchctl start instead of deriving it with basename
  • tests
    • update unit coverage for persistent stop, degraded fallback paths, explicit re-enable on repair/restart, detached handoff label passing, and label validation
    • add an integration test covering stop -> restart without reinstall

Test plan

  • pnpm test src/daemon/launchd.test.ts src/daemon/launchd-restart-handoff.test.ts src/commands/doctor-gateway-daemon-flow.test.ts src/cli/daemon-cli/launchd-recovery.test.ts
  • pnpm test src/daemon/launchd.integration.e2e.test.ts src/cli/daemon-cli/lifecycle-core.test.ts src/daemon/service.test.ts src/cli/daemon-cli/lifecycle.test.ts
  • manual macOS CLI e2e with temp HOME + OPENCLAW_PROFILE: install -> health check -> openclaw gateway stop -> verify down -> openclaw gateway restart -> verify healthy -> openclaw gateway status --deep
  • pre-commit pnpm check

Changed files

  • CHANGELOG.md (modified, +1/-0)
  • extensions/telegram/src/bot-handlers.runtime.ts (modified, +1/-1)
  • src/daemon/launchd-restart-handoff.test.ts (modified, +35/-1)
  • src/daemon/launchd-restart-handoff.ts (modified, +19/-6)
  • src/daemon/launchd.integration.e2e.test.ts (modified, +92/-0)
  • src/daemon/launchd.test.ts (modified, +264/-10)
  • src/daemon/launchd.ts (modified, +127/-9)

Code Example

$ openclaw gateway restart
Restarted LaunchAgent: gui/502/ai.openclaw.gateway

$ sleep 5 && launchctl list | grep ai.openclaw.gateway
(no output — service gone)

$ openclaw logs --follow
Gateway not reachable. Is it running and accessible?

---

[gateway] signal SIGTERM received
[gateway] received SIGTERM; shutting down

---

openclaw gateway install && openclaw gateway start

---

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist
RAW_BUFFERClick to expand / collapse

Summary

openclaw gateway restart on macOS bootouts the LaunchAgent but does not re-bootstrap it, leaving the gateway dead after the process exits.

Environment

  • OpenClaw: 2026.4.8 (9ece252)
  • macOS: 26.3.1 (arm64)
  • Node: 22.16.0
  • Install method: npm global

Steps to reproduce

  1. openclaw gateway install — LaunchAgent installed, running, KeepAlive: true
  2. openclaw gateway restart — prints "Restarted LaunchAgent"
  3. Gateway starts briefly, but after any SIGTERM (or sometimes immediately), the service disappears from launchctl list
  4. Gateway does not auto-restart despite KeepAlive: true in the plist

Observed behavior

$ openclaw gateway restart
Restarted LaunchAgent: gui/502/ai.openclaw.gateway

$ sleep 5 && launchctl list | grep ai.openclaw.gateway
(no output — service gone)

$ openclaw logs --follow
Gateway not reachable. Is it running and accessible?

Gateway logs show:

[gateway] signal SIGTERM received
[gateway] received SIGTERM; shutting down

After shutdown, launchd does not restart the process because the service was bootout'd.

Expected behavior

openclaw gateway restart should reliably stop and restart the gateway, keeping the LaunchAgent registered so KeepAlive: true works.

Workaround

openclaw gateway install && openclaw gateway start

Or manually re-bootstrap:

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Additional context

  • openclaw gateway stop also bootouts the LaunchAgent (may be intentional for stop, but restart should re-register)
  • The plist at ~/Library/LaunchAgents/ai.openclaw.gateway.plist is correct with KeepAlive: true and RunAtLoad: true
  • This was observed after upgrading from 2026.4.5 to 2026.4.8, but may not be version-specific

extent analysis

TL;DR

The openclaw gateway restart command fails to re-bootstrap the LaunchAgent after stopping it, causing the gateway to not restart automatically.

Guidance

  • Verify that the ai.openclaw.gateway.plist file has the correct settings, including KeepAlive: true and RunAtLoad: true, to ensure the LaunchAgent is configured to restart the gateway.
  • Use the provided workaround openclaw gateway install && openclaw gateway start to manually restart the gateway and re-register the LaunchAgent.
  • Check the gateway logs for any errors or issues that may be causing the LaunchAgent to be bootout'd after restarting.
  • Consider manually re-bootstrapping the LaunchAgent using launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist if the workaround does not work.

Example

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist

This command manually re-bootstraps the LaunchAgent, which may help resolve the issue.

Notes

The issue may not be specific to version 2026.4.8, as it was observed after upgrading from 2026.4.5. Further investigation is needed to determine the root cause.

Recommendation

Apply the workaround openclaw gateway install && openclaw gateway start to manually restart the gateway and re-register the LaunchAgent, as it provides a reliable way to restart the gateway and keep the LaunchAgent registered.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

openclaw gateway restart should reliably stop and restart the gateway, keeping the LaunchAgent registered so KeepAlive: true works.

#response parsing#generation error#database connection#vector store#embedding generation

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING