Skip to content

Bug: gateway restart fails after unload due to incorrect launchctl command sequence on macOS #20030

@applre

Description

@applre

Bug Description

openclaw gateway restart fails to restart the gateway on macOS. The service is stopped but never restarted.

Error Log

[tools] exec failed: Stopped LaunchAgent: gui/501/ai.openclaw.gateway
Gateway start failed: Error: launchctl kickstart failed:
Command exited with code 1

Root Cause

The restart logic uses an incorrect launchctl command sequence:

  1. launchctl bootout (unload) — ✅ succeeds, service is stopped
  2. launchctl kickstart — ❌ fails, service not found

After bootout/unload, the service is removed from launchd's registry. kickstart can only start services that are already registered in launchd, so it fails with "Could not find service".

Expected Fix

Replace kickstart with load/bootstrap after unloading:

# Current (broken)
launchctl bootout gui/501/ai.openclaw.gateway
launchctl kickstart gui/501/ai.openclaw.gateway  # fails - service not registered

# Correct
launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist  # re-registers and starts

Steps to Reproduce

  1. Run openclaw gateway restart on macOS
  2. Gateway stops but does not restart
  3. launchctl list | grep openclaw shows no service

Environment

  • macOS Darwin 24.6.0
  • openclaw version: 2026.2.14
  • LaunchAgent: gui/501/ai.openclaw.gateway

Workaround

Manually restart with:

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    staleMarked as stale due to inactivity

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions