{
  "title": "Gateway lifecycle on macOS",
  "content": "The macOS app **manages the Gateway via launchd** by default and does not spawn\nthe Gateway as a child process. It first tries to attach to an already‑running\nGateway on the configured port; if none is reachable, it enables the launchd\nservice via the external `openclaw` CLI (no embedded runtime). This gives you\nreliable auto‑start at login and restart on crashes.\n\nChild‑process mode (Gateway spawned directly by the app) is **not in use** today.\nIf you need tighter coupling to the UI, run the Gateway manually in a terminal.\n\n## Default behavior (launchd)\n\n* The app installs a per‑user LaunchAgent labeled `bot.molt.gateway`\n  (or `bot.molt.<profile>` when using `--profile`/`OPENCLAW_PROFILE`; legacy `com.openclaw.*` is supported).\n* When Local mode is enabled, the app ensures the LaunchAgent is loaded and\n  starts the Gateway if needed.\n* Logs are written to the launchd gateway log path (visible in Debug Settings).\n\nReplace the label with `bot.molt.<profile>` when running a named profile.\n\n## Unsigned dev builds\n\n`scripts/restart-mac.sh --no-sign` is for fast local builds when you don’t have\nsigning keys. To prevent launchd from pointing at an unsigned relay binary, it:\n\n* Writes `~/.openclaw/disable-launchagent`.\n\nSigned runs of `scripts/restart-mac.sh` clear this override if the marker is\npresent. To reset manually:\n\nTo force the macOS app to **never install or manage launchd**, launch it with\n`--attach-only` (or `--no-launchd`). This sets `~/.openclaw/disable-launchagent`,\nso the app only attaches to an already running Gateway. You can toggle the same\nbehavior in Debug Settings.\n\nRemote mode never starts a local Gateway. The app uses an SSH tunnel to the\nremote host and connects over that tunnel.\n\n## Why we prefer launchd\n\n* Auto‑start at login.\n* Built‑in restart/KeepAlive semantics.\n* Predictable logs and supervision.\n\nIf a true child‑process mode is ever needed again, it should be documented as a\nseparate, explicit dev‑only mode.",
  "code_samples": [
    {
      "code": "Replace the label with `bot.molt.<profile>` when running a named profile.\n\n## Unsigned dev builds\n\n`scripts/restart-mac.sh --no-sign` is for fast local builds when you don’t have\nsigning keys. To prevent launchd from pointing at an unsigned relay binary, it:\n\n* Writes `~/.openclaw/disable-launchagent`.\n\nSigned runs of `scripts/restart-mac.sh` clear this override if the marker is\npresent. To reset manually:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Default behavior (launchd)",
      "id": "default-behavior-(launchd)"
    },
    {
      "level": "h2",
      "text": "Unsigned dev builds",
      "id": "unsigned-dev-builds"
    },
    {
      "level": "h2",
      "text": "Attach-only mode",
      "id": "attach-only-mode"
    },
    {
      "level": "h2",
      "text": "Remote mode",
      "id": "remote-mode"
    },
    {
      "level": "h2",
      "text": "Why we prefer launchd",
      "id": "why-we-prefer-launchd"
    }
  ],
  "url": "llms-txt#gateway-lifecycle-on-macos",
  "links": []
}