OpenClaw 🦞

Gateway 生命周期

macOS 上的 Gateway 生命周期

macOS 应用默认通过 launchd 管理 Gateway，不会将 Gateway 作为子进程启动。它首先尝试附加到配置端口上已经运行的 Gateway；如果无法访问，则通过外部 openclaw CLI 启用 launchd 服务（没有嵌入式运行时）。这为你提供了登录时自动启动和崩溃后重启的可靠性。

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

默认行为（launchd）

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

常用命令：

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。你可以在调试设置中切换相同的行为。

远程模式

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

为什么我们首选 launchd

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

如果将来需要真正的子进程模式，应该将其记录为一个单独的、明确限定的仅开发模式。