macOS 上的 Gateway 生命周期

macOS 应用默认通过 launchd 管理 Gateway，不会以子进程方式启动它。应用会先尝试连接到配置端口上已经运行的 Gateway；如果连不上，就通过外部 openclaw CLI 启用 launchd 服务（无内嵌运行时）。这样你就能获得可靠的登录自启和崩溃自重启。

子进程模式（由应用直接启动 Gateway）当前未使用。如果需要更紧密的 UI 耦合，可以在终端中手动运行 Gateway。

默认行为（launchd）

• 应用安装一个用户级 LaunchAgent，标签为 ai.openclaw.gateway （使用 --profile/OPENCLAW_PROFILE 时为 ai.openclaw.<profile>；旧版 com.openclaw.* 仍受支持）。
• Local 模式启用时，应用确保 LaunchAgent 已加载并在需要时启动 Gateway。
• 日志写入 launchd gateway 日志路径（可在 Debug Settings 中查看）。

常用命令：

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

使用命名 profile 时把标签换成 ai.openclaw.<profile>。

未签名的开发构建

scripts/restart-mac.sh --no-sign 用于没有签名密钥时的快速本地构建。为了防止 launchd 指向未签名的 relay 二进制文件，它会：

• 写入 ~/.openclaw/disable-launchagent。

签名后运行 scripts/restart-mac.sh 如果检测到该标记文件会自动清除。手动重置方法：

rm ~/.openclaw/disable-launchagent

仅连接模式

要让 macOS 应用绝不安装或管理 launchd，使用 --attach-only（或 --no-launchd）启动。这会设置 ~/.openclaw/disable-launchagent，应用只会连接已在运行的 Gateway。同样的行为也可以在 Debug Settings 中切换。

Remote 模式

Remote 模式不会启动本地 Gateway。应用通过 SSH 隧道连接到远程主机。

为什么选择 launchd

• 登录自动启动。
• 内置重启/KeepAlive 语义。
• 可预测的日志和进程管理。

如果将来确实需要子进程模式，应作为独立的、明确标注的开发专用模式来记录。