macOS 上的 Gateway 生命周期

macOS 应用默认通过 launchd 管理 Gateway，不会将 Gateway 作为子进程启动。它会先尝试连接到配置端口上已经运行的 Gateway；如果连不上，就通过外部的 openclaw CLI 启用 launchd 服务（没有内嵌运行时）。这样可以让你在登录时自动启动，崩溃后自动重启。

子进程模式（应用直接启动 Gateway）目前已不再使用。如果你需要与 UI 更紧密的耦合，可以在终端手动运行 Gateway。

默认行为（launchd）

• 应用会安装一个用户级的 LaunchAgent，标签为 bot.molt.gateway （使用 --profile/OPENCLAW_PROFILE 时为 bot.molt.<profile>；也支持旧版的 com.openclaw.*）。
• 启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway。
• 日志会写入 launchd gateway 日志路径（在调试设置中可见）。

常用命令：

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

运行命名配置文件时，把标签替换成 bot.molt.<profile>。

未签名的开发构建

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

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

签名运行 scripts/restart-mac.sh 时，如果标记文件存在会清除这个覆盖。手动重置的方法：

rm ~/.openclaw/disable-launchagent

仅连接模式

要强制 macOS 应用永不安装或管理 launchd，用 --attach-only（或 --no-launchd）启动。这会设置 ~/.openclaw/disable-launchagent，让应用只连接到已经运行的 Gateway。你也可以在调试设置中切换这个行为。

远程模式

远程模式永远不会启动本地 Gateway。应用会使用 SSH 隧道连接到远程主机，并通过隧道进行通信。

为什么我们更喜欢 launchd

• 登录时自动启动。
• 内置重启/KeepAlive 机制。
• 可预测的日志和监控。

如果以后真的需要子进程模式，应该把它作为一个独立的、明确的仅开发模式来记录。