# Gateway Lifecycle on macOS

## Overview

The macOS application manages the Gateway through launchd rather than spawning it as a child process. It attempts to connect to an existing Gateway on the configured port; if unavailable, it enables the launchd service via the `openclaw` CLI.

## Default Behavior

The system installs a per-user LaunchAgent labeled `bot.molt.gateway` (or `bot.molt.<profile>` for named profiles). When Local mode is active, the app ensures this agent is loaded and starts the Gateway as needed. Log files are directed to the launchd gateway log path, accessible through Debug Settings.

Key management commands include:

```bash
launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway
```

## Development Builds

Unsigned development builds use `scripts/restart-mac.sh --no-sign` for rapid iteration. This prevents launchd from referencing an unsigned binary by creating `~/.openclaw/disable-launchagent`. Signed builds automatically clear this override.

## Connection Modes

**Attach-only mode** forces the app to skip launchd management entirely using the `--attach-only` flag, connecting only to already-running Gateways.

**Remote mode** bypasses local Gateway startup, instead establishing an SSH tunnel to a remote host.

## Design Rationale

The launchd approach provides:

- Automatic login startup
- Built-in restart capabilities
- Consistent logging and supervision patterns
