oliver
dbbe3add6a
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
2.3 KiB
| summary | read_when | title | |
|---|---|---|---|
| Gateway lifecycle on macOS (launchd) |
|
Gateway Lifecycle |
Gateway lifecycle on macOS
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
service via the external openclaw CLI (no embedded runtime). This gives you
reliable auto‑start at login and restart on crashes.
Child‑process mode (Gateway spawned directly by the app) is not in use today. If you need tighter coupling to the UI, run the Gateway manually in a terminal.
Default behavior (launchd)
- The app installs a per‑user LaunchAgent labeled
ai.openclaw.gateway(orai.openclaw.<profile>when using--profile/OPENCLAW_PROFILE; legacycom.openclaw.*is supported). - 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:
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway
Replace the label with ai.openclaw.<profile> when running a named profile.
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:
- Writes
~/.openclaw/disable-launchagent.
Signed runs of scripts/restart-mac.sh clear this override if the marker is
present. To reset manually:
rm ~/.openclaw/disable-launchagent
Attach-only mode
To force the macOS app to never install or manage launchd, launch it with
--attach-only (or --no-launchd). This sets ~/.openclaw/disable-launchagent,
so the app only attaches to an already running Gateway. You can toggle the same
behavior in Debug Settings.
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.