2025-12-09 17:51:05 +00:00
|
|
|
|
---
|
2026-01-12 04:38:42 +00:00
|
|
|
|
summary: "Gateway lifecycle on macOS (launchd)"
|
2025-12-09 17:51:05 +00:00
|
|
|
|
read_when:
|
|
|
|
|
|
- Integrating the mac app with the gateway lifecycle
|
2026-01-31 16:04:03 -05:00
|
|
|
|
title: "Gateway Lifecycle"
|
2025-12-09 17:51:05 +00:00
|
|
|
|
---
|
2026-01-31 21:13:13 +09:00
|
|
|
|
|
2026-01-08 23:06:56 +01:00
|
|
|
|
# Gateway lifecycle on macOS
|
|
|
|
|
|
|
2026-01-18 16:29:33 +00:00
|
|
|
|
The macOS app **manages the Gateway via launchd** by default and does not spawn
|
|
|
|
|
|
the Gateway as a child process. It first tries to attach to an already‑running
|
|
|
|
|
|
Gateway on the configured port; if none is reachable, it enables the launchd
|
2026-01-30 03:15:10 +01:00
|
|
|
|
service via the external `openclaw` CLI (no embedded runtime). This gives you
|
2026-01-18 16:29:33 +00:00
|
|
|
|
reliable auto‑start at login and restart on crashes.
|
2026-01-08 23:06:56 +01:00
|
|
|
|
|
|
|
|
|
|
Child‑process mode (Gateway spawned directly by the app) is **not in use** today.
|
2026-01-12 04:38:42 +00:00
|
|
|
|
If you need tighter coupling to the UI, run the Gateway manually in a terminal.
|
2026-01-08 23:06:56 +01:00
|
|
|
|
|
|
|
|
|
|
## Default behavior (launchd)
|
|
|
|
|
|
|
2026-01-27 14:46:27 -06:00
|
|
|
|
- The app installs a per‑user LaunchAgent labeled `bot.molt.gateway`
|
2026-01-30 03:15:10 +01:00
|
|
|
|
(or `bot.molt.<profile>` when using `--profile`/`OPENCLAW_PROFILE`; legacy `com.openclaw.*` is supported).
|
2026-01-08 23:06:56 +01:00
|
|
|
|
- When Local mode is enabled, the app ensures the LaunchAgent is loaded and
|
|
|
|
|
|
starts the Gateway if needed.
|
|
|
|
|
|
- Logs are written to the launchd gateway log path (visible in Debug Settings).
|
|
|
|
|
|
|
|
|
|
|
|
Common commands:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-01-27 14:46:27 -06:00
|
|
|
|
launchctl kickstart -k gui/$UID/bot.molt.gateway
|
|
|
|
|
|
launchctl bootout gui/$UID/bot.molt.gateway
|
2026-01-08 23:06:56 +01:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-01-27 14:46:27 -06:00
|
|
|
|
Replace the label with `bot.molt.<profile>` when running a named profile.
|
2026-01-11 02:17:10 +01:00
|
|
|
|
|
2026-01-11 03:19:24 +01:00
|
|
|
|
## Unsigned dev builds
|
|
|
|
|
|
|
|
|
|
|
|
`scripts/restart-mac.sh --no-sign` is for fast local builds when you don’t have
|
|
|
|
|
|
signing keys. To prevent launchd from pointing at an unsigned relay binary, it:
|
|
|
|
|
|
|
2026-01-30 03:15:10 +01:00
|
|
|
|
- Writes `~/.openclaw/disable-launchagent`.
|
2026-01-11 03:19:24 +01:00
|
|
|
|
|
2026-01-12 04:38:42 +00:00
|
|
|
|
Signed runs of `scripts/restart-mac.sh` clear this override if the marker is
|
2026-01-11 03:19:24 +01:00
|
|
|
|
present. To reset manually:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-01-30 03:15:10 +01:00
|
|
|
|
rm ~/.openclaw/disable-launchagent
|
2026-01-11 03:19:24 +01:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-01-22 07:37:55 +00:00
|
|
|
|
## Attach-only mode
|
|
|
|
|
|
|
|
|
|
|
|
To force the macOS app to **never install or manage launchd**, launch it with
|
2026-01-30 03:15:10 +01:00
|
|
|
|
`--attach-only` (or `--no-launchd`). This sets `~/.openclaw/disable-launchagent`,
|
2026-01-22 07:37:55 +00:00
|
|
|
|
so the app only attaches to an already running Gateway. You can toggle the same
|
|
|
|
|
|
behavior in Debug Settings.
|
|
|
|
|
|
|
2026-01-08 23:06:56 +01:00
|
|
|
|
## Remote mode
|
|
|
|
|
|
|
|
|
|
|
|
Remote mode never starts a local Gateway. The app uses an SSH tunnel to the
|
|
|
|
|
|
remote host and connects over that tunnel.
|
|
|
|
|
|
|
|
|
|
|
|
## Why we prefer launchd
|
|
|
|
|
|
|
|
|
|
|
|
- Auto‑start at login.
|
|
|
|
|
|
- Built‑in restart/KeepAlive semantics.
|
|
|
|
|
|
- Predictable logs and supervision.
|
|
|
|
|
|
|
|
|
|
|
|
If a true child‑process mode is ever needed again, it should be documented as a
|
|
|
|
|
|
separate, explicit dev‑only mode.
|
