macOS 上的网关生命周期

macOS 应用默认通过 launchd 管理网关,不会将网关作为子进程启动。它首先尝试连接到已在配置端口上运行的网关;如果无法连接,则通过外部 openclaw CLI(无内嵌运行时)启用 launchd 服务。这为您提供了可靠的登录自动启动和崩溃重启功能。

子进程模式(网关由应用直接启动)目前未使用。如果您需要与 UI 更紧密的耦合,请在终端中手动运行网关。

默认行为(launchd)

• 应用会安装一个标记为 bot.molt.gateway 的每用户 LaunchAgent (使用 --profile/OPENCLAW_PROFILE 时为 bot.molt.<profile>;支持旧版 com.openclaw.*)。
• 启用本地模式时,应用会确保 LaunchAgent 已加载,并在需要时启动网关。
• 日志会写入 launchd 网关日志路径(在调试设置中可见)。

常用命令:

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,因此应用只会连接到已运行的网关。您也可以在调试设置中切换相同的行为。

远程模式

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

为什么我们偏好 launchd

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

如果将来确实需要真正的子进程模式,应该将其作为一个独立的、明确的仅开发模式进行文档化。