跳转至

macOS 上的 Gateway

OpenClaw.app 捆绑了一个私有 Node 运行时和匹配的 OpenClaw 包，用于其应用拥有的 node worker 辅助组件以及固定的本地 Chrome 扩展设置入口点。私有包不暴露完整 CLI，也不启动 Gateway。重新构建或替换应用也会替换这些辅助组件，包括使用相同公开版本重新构建。它们从已签名的捆绑包中运行，因此移动应用或删除其构建检出不会改变它们所使用的运行时。

Gateway 仍为外部组件。该应用使用外部 openclaw CLI 来管理每个用户的 launchd 服务，或连接到已在运行的 Gateway。它不会在私有 worker 运行时内启动 Gateway。打包 worker 永远不会安装、更新或重启 Gateway 服务。

私有 worker 通过只读引导验证核心和 node 配置，没有整个 Gateway 的 Doctor 预检或通道架构验证。Node 插件在发布命令前仍会验证自己的设置，并且 node 运行时拥有其 MCP 客户端。Node 启动保留由 Doctor 拥有的设备认证、设备身份和执行审批迁移；这并不保证所有 worker 启动都是只读的。公开的 node run、Gateway 和 Doctor 保留其现有启动策略。

当原生应用在 worker 启动前创建身份、设备认证或审批表时，node 启动会在插件读取其状态之前，通过规范初始化器完成该已识别的零版本数据库。现有原生行会被保留。这不会迁移已版本化的共享 Gateway 数据库，也不会采用未知或已被占用的引导状态。

自动设置

在全新 Mac 上，在引导过程中选择 此 Mac。应用会在 Gateway 向导之前运行其已签名的捆绑安装脚本：它在 ~/.openclaw 下安装用户空间 Node 运行时和匹配的 openclaw CLI，然后安装并启动每个用户的 launchd 服务。此路径无需 Terminal、Homebrew 或管理员权限。

安装程序使用私有临时目录来存放下载内容和构建工具。如果应用继承的临时目录不可访问，设置会自动使用 /tmp 下的私有目录，并在安装程序退出时删除它。这也可以避免 macOS 临时目录权限错误，而无需以 root 身份安装 CLI。

Gateway 设置仍需要互联网连接以下载其独立运行时和匹配的 OpenClaw 包。捆绑安装程序负责该设置；私有 worker 不是 CLI 或 Gateway 安装的替代品。

远程连接以及连接到独立管理的本地 Gateway 会跳过此安装。仅连接模式永远不会提示使用 CLI 来运行应用的 node。暂停会保留 Gateway 的管理者，即使停止应用管理的服务会删除其 LaunchAgent 记录。如果重新连接时独立端点不再可用，本地设置会再次可用。无法读取的服务所有权记录会阻止自动安装，而不是被视为缺失的服务；请检查 LaunchAgent 并重试。

Chrome 扩展准备也会为默认应用配置文件自动运行，包括仅远程和仅连接的 Mac。它使用经过验证的私有运行时，在请求商店扩展之前注册原生辅助组件，并将 Chrome 的权限批准留给你。浏览器设置不会运行整个 Gateway 的 Doctor，也不会迁移 Gateway 状态。Dashboard 的 在此设备上设置 Chrome 操作会重试相同的序列化操作。参见 Chrome 扩展。

手动恢复

从应用读取要安装的版本：在菜单栏中选择 关于 OpenClaw，或运行 openclaw-mac status --json，它会报告应用版本和构建。

对于手动安装，请使用 Node 26（推荐）或其他受支持的版本：Node 24.16+ 或 Node 26.1+。全局安装 openclaw：

以下命令适用于 npm 12 或 npm 11.16+。在 npm 11.15 及更早版本中，省略 --allow-scripts=openclaw。

npm install -g openclaw@<version> --allow-scripts=openclaw

在自动设置失败后使用 重试设置。如果仍然失败，请使用上述命令手动安装 CLI，然后在引导过程中选择 再次检查。

Launchd（Gateway 作为 LaunchAgent）

标签：ai.openclaw.gateway（默认配置文件），或命名配置文件的 ai.openclaw.<profile>。

Plist 位置（每个用户）：~/Library/LaunchAgents/ai.openclaw.gateway.plist（或 ai.openclaw.<profile>.plist）。

macOS 应用在本地模式下拥有默认配置文件的 LaunchAgent 安装/更新。CLI 也可以直接安装它：openclaw gateway install（命名配置文件通过 OPENCLAW_PROFILE 环境变量选择）。从应用启用 Gateway 会保留已保存的运行时固定。如果固定无效，启用会因 CLI 错误而失败；请显式使用 --runtime 或 --runtime-path 重新安装以替换已保存的固定。禁用它会卸载 LaunchAgent，从而移除固定。

行为：

  • “OpenClaw 已激活” 启用/禁用 LaunchAgent。
  • 退出应用不会停止 Gateway（launchd 会保持其运行）。
  • 如果 Gateway 已在配置的端口上运行，应用会连接到它，而不是启动新的 Gateway。
  • 其他监听器保持运行。请通过拥有它们的进程或服务解决端口冲突；自动清理只会回收已记录的孤立 SSH 隧道。
  • 如果服务检查无法得出结论，应用会延迟安装并使用其现有就绪检查。已确认不存在的服务仍可以安装。

使用 CLI 进行生命周期检查和恢复：

openclaw gateway status --deep
openclaw gateway restart

当启用 也在此 Mac 上运行 Gateway 且主 Gateway 为远程时，受管理的 launch agent 会包含 --allow-unconfigured，以便在 gateway.mode 仍为 remote 时运行。将主 Gateway 切换到本地会移除该参数。参见 在远程主 Gateway 旁边进行本地托管。

Launchd 提供登录时自动启动、崩溃后重启，以及一个可预测的日志位置，而无需将 Gateway 的生命周期绑定到应用进程。

意外重复重启

如果 Gateway 在更新后反复重启，请运行以下命令：

openclaw gateway status
openclaw doctor

在 macOS 上，这两个命令都会报告 ai.openclaw.* 命名空间中的外部已加载任务，包括未通过 plist 提交的任务。报告会显示每个标签、程序、KeepAlive 标志，以及检测到的 openclaw gateway restart、start 或 stop 调用。纯文本状态会在至少一个任务具有 KeepAlive 或已验证的生命周期调用时，将该列表显示为警告。否则，该列表会作为信息性内容显示在“其他 OpenClaw launchd 任务（macOS）”下。状态 JSON 会在 service.foreignLaunchdJobs 下包含所有这些任务。对于警告，生命周期日志中最近的外部强制重启可提供可能的关联；仅凭数量无法确定是哪个任务导致了重启。 如果在十分钟内发生三次外部强制重启，受管理的 Gateway 会记录一条可操作的警告，并在可用时指出可能的 KeepAlive 任务。它不会抑制操作员的 restart 命令。

要移除已确认的多余 Gateway 生命周期任务并验证恢复：

openclaw doctor --fix
openclaw gateway status
openclaw health

Doctor 仅当外部任务的字面、直线脚本或直接参数调用带有 Gateway 生命周期子命令的绝对 OpenClaw 路径时，才会移除该外部任务。Shell 任务还必须没有任何会改变 shell 执行的 launchd 环境条目。所有不符合此约定的内容都会被报告并保持不变。这是命令元数据验证；它不会探测二进制可执行性、解释器可用性或隔离状态。

Doctor 会保留受管理的 LaunchAgent、无关标签以及无法确定用途的任务，即使在非交互式运行中也会明确说明每一项移除。对于隔离的安装身份、外部监督或正在进行的更新，服务修复仍保持禁用。

切勿使用 launchctl submit 或临时 KeepAlive 任务来执行更新或 Gateway 生命周期命令。此类任务可能会在其脚本每次退出时反复运行 openclaw gateway restart，如 #114967 中所述。请使用受管理的更新工作流及其挂起围栏，然后验证状态和健康状况。

仅附加开发

当另一个进程已经拥有本地 Gateway 时，在不安装或修改其 LaunchAgent 的情况下运行开发应用：

scripts/restart-mac.sh --attach-only

直接使用 --attach-only 或 --no-launchd 启动应用具有相同效果。该覆盖会持久保存在 ~/.openclaw/disable-launchagent 中；删除该文件可恢复应用管理的 launchd 行为。

命名配置文件仍要求监听器属于该配置文件的 Gateway 服务。仅附加模式不允许附加另一个进程或配置文件。如果发生端口所有权冲突，自动恢复会保留失败状态，而不是反复重新打开 Dashboard。请解决冲突，然后重新启动应用。

日志：

  • launchd stdout：~/Library/Logs/openclaw/gateway.log（配置文件使用 gateway-<profile>.log）
  • launchd stderr：合并到同一个 gateway.log 文件中，因此发生在日志记录器启动之前的启动失败仍会被记录
  • 如果主机因反复出现 EADDRINUSE 或快速重启而循环，请检查是否存在重复的 ai.openclaw.gateway / ai.openclaw.node LaunchAgent，以及 Gateway 故障排除 中的 launchd 标记变通方法。

版本兼容性

私有 worker 必须与应用的构建来源匹配，而不仅仅是其版本号。缺失或不兼容的 worker 负载会产生可见的 worker 错误；请重新构建或重新安装应用。更改 CLI 通道或更新全局 CLI 无法修复此私有负载。未捆绑的 Swift 开发构建可以改用检出中具备新鲜度感知能力的源码运行器。

如果 Gateway 更新将共享状态数据库架构推进到私有 worker 支持的版本之外，也请更新并重新启动 OpenClaw.app。重启外部 Gateway 不会替换应用拥有的 worker。来自该较旧读取器的架构版本错误并不意味着已升级 Gateway 的数据库已损坏。

对于应用拥有的本地 Gateway，macOS 应用会根据其安装策略检查外部 CLI。当该 CLI 缺失或不兼容时，引导设置会运行受管理的设置。已附加的 Gateway 使用连接和健康检查，而不是本地 CLI 安装诊断。在受管理安装失败后，使用 重试设置；或者从菜单栏打开 连接… → 连接，并在修复后选择 重新检查。当 Dashboard 无法连接到 Gateway 时，连接窗口仍可用。

macOS 上的状态目录

请将 OpenClaw 状态保存在本地、不同步的磁盘上。避免使用 iCloud Drive 和其他云同步文件夹；同步延迟和文件锁可能影响会话、凭据和 Gateway 状态。

仅在需要覆盖时，将 OPENCLAW_STATE_DIR 设置为本地路径。openclaw doctor 会警告常见的云同步状态路径，并建议移回本地存储。参见 环境变量 和 Doctor。

调试应用连接

使用捆绑的 macOS CLI 检查正在运行的应用：

openclaw-mac status --json
openclaw-mac primary show --json
openclaw-mac gateway list --json

应用的 CLI 安装程序会在其配置文件管理的 openclaw 命令旁边链接 openclaw-mac。你也可以直接运行 /Applications/OpenClaw.app/Contents/MacOS/openclaw-mac。有关 primary set、已保存 Gateway 命令、配置文件和凭据输入，请参阅 远程控制。

对于从源码检出进行的独立 Gateway WebSocket 握手和发现探测，现有的调试命令仍然可用：

cd apps/macos
swift run openclaw-mac connect --json
swift run openclaw-mac discover --timeout 3000 --json

connect 接受 --url、--token、--timeout、--probe 和 --json （以及客户端身份覆盖；运行 --help 查看完整列表）。 discover 接受 --timeout、--json 和 --include-local。当需要区分 CLI 发现与应用程序端连接问题时，请将发现输出与 openclaw gateway discover --json 进行比较。

冒烟检查

openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback

然后：

openclaw gateway call health --port 18999 --timeout 3000

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw