macOS 上的网关
OpenClaw.app 捆绑了一个由 OpenClaw Bun 分支构建的私有运行时、一个支持扩展加载的已签名 SQLite 库,以及完整的匹配 OpenClaw 包(CLI、Gateway 和 Control UI)。其应用拥有的 node worker 辅助程序和固定的本地 Chrome 扩展设置入口点运行在此 Bun 运行时上。应用包不包含 Node 可执行文件。
负载位于一个 Contents/Resources/runtime 目录中。通用应用在不同架构之间共享 JavaScript 包,并包含通用 Bun 和 SQLite 二进制文件以及每个架构的原生依赖项。重新构建或替换应用也会替换此运行时,包括使用相同公开版本的重建。应用在启动前验证包的版本、提交、构建时间和构建 ID。移动应用或删除其构建检出不会改变它使用的运行时。
在全新配置中,应用托管 Gateway,将其作为子进程运行,并使用其捆绑的 Bun 运行时。Gateway 随应用启动,并在应用退出时停止。配置端口上已有的 Gateway 会被附加,而不是重复创建。现有独立管理的安装保持其当前生命周期。符合条件的应用管理的 Node 服务会迁移到捆绑的 Bun,同时保留其常驻服务。
应用首先将其运行时复制到 <state>/runtime/<runtimeBuildId>/,其中 <state> 是 ~/.openclaw 或 ~/.openclaw-<profile>。复制在可用时使用 APFS 写时复制,并在来源和 Bun 检查成功后原子发布。子进程和应用管理的 Bun 服务使用具体构建目录,因此每个进程都保留其匹配的包和 SQLite 库。runtime/current 符号链接为终端 CLI 垫片选择运行时。应用保留当前和上一个构建;旧副本仅在 Gateway 健康检查成功且没有进程从它们运行时才会删除。
对于应用拥有的完整 Gateway 负载,打包会在 OpenClaw 包根目录写入 openclaw-install-owner.json,其中包含 schemaVersion: 1、owner: "macos-app"、displayName: "OpenClaw.app" 和 updateHint: "Update OpenClaw.app to update this Gateway."。此契约使负载和运行时更新随应用更新器(Sparkle)进行:核心报告所有者,跳过包注册表更新检查,并拒绝自更新和运行时迁移。启动宿主可以设置 OPENCLAW_GATEWAY_HOST_LIFELINE=stdin 并保留 stdin 管道写入端;EOF 或管道错误会请求 Gateway 优雅关闭。应用托管的 Gateway 使用此生命线,因此即使应用意外结束也会退出。
私有 worker 通过只读引导验证核心和 node 配置,而不执行 Gateway 范围的 Doctor 预检或通道模式验证。Node 插件在发布命令前仍会验证自己的设置,node 运行时拥有其 MCP 客户端。Node 启动保留由 Doctor 拥有的设备认证、设备身份和执行审批迁移;这不意味着所有 worker 启动都是只读的。公开的 node run、Gateway 和 Doctor 保留其现有启动策略。
当原生应用在 worker 启动前创建身份、设备认证或审批表时,node 启动会通过规范初始化器完成该被识别的零版本数据库,然后插件才读取其状态。现有原生行会被保留。这不会迁移已版本化的共享 Gateway 数据库,也不会采用未知或已占用的引导状态。
自动设置¶
在全新 Mac 上,引导期间选择 此 Mac。准备就绪 会准备内置运行时,启动 Gateway,并验证其已就绪。此设置无需下载运行时、安装 Node、Terminal、Homebrew 或管理员权限。连接 AI 提供商仍可能需要互联网访问。
应用创建 <state>/bin/openclaw,一个小型 shell 包装器,使用 Bun 和包含的 SQLite 库运行当前捆绑的 CLI。它还在旁边链接 openclaw-mac,并将该 bin 目录添加到常规 shell 配置文件。现有由操作员创建的 openclaw 文件会被保留;只有应用自己的包装器或受识别的 install-cli.sh 包装器会被替换。
未捆绑的 DEBUG 构建保留开发者安装程序和通道选择器。该安装程序使用私有临时目录用于下载和构建工具,当继承的临时目录不可访问时,回退到 /tmp 下的私有目录。
远程连接和附加到独立管理的本地 Gateway 会跳过此安装。仅附加模式从不提示用于运行应用 node 的 CLI。暂停会保留 Gateway 的管理者,即使停止应用管理的服务会删除其 LaunchAgent 记录。如果独立端点在重新附加时不再可用,本地设置会再次可用。无法读取的服务所有权记录会阻止自动安装,而不是被视为缺失服务;请检查 LaunchAgent 并重试。
Chrome 扩展准备也会为默认应用配置自动运行,包括仅远程和仅附加的 Mac。它使用经过验证的私有运行时,在请求商店扩展之前注册原生辅助程序,并将 Chrome 的权限批准留给你。浏览器设置不会运行 Gateway 范围的 Doctor,也不会迁移 Gateway 状态。仪表盘的 在此设备上设置 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。
捆绑设置失败后使用 重试设置。如果运行时负载缺失或不兼容,请重新安装 OpenClaw.app。安装全局 CLI 不会修复应用的捆绑负载。上述手动 Node 安装用于独立管理的 Gateway 或未捆绑的开发设置。
对于使用应用精确版本策略的现有应用管理 Gateway, 重试设置 会在启动前通过其已安装的 CLI 更新旧版本包。失败的更新仍可重试;通道策略和操作员运行时固定保留其现有更新路径。
Launchd(Gateway 作为 LaunchAgent)¶
标签:ai.openclaw.gateway(默认配置),或 ai.openclaw.<profile>(用于命名配置)。
Plist 位置(每用户):~/Library/LaunchAgents/ai.openclaw.gateway.plist(或 ai.openclaw.<profile>.plist)。
macOS 应用可以将 Gateway 作为后台服务管理,而不是作为子进程。请在 Dashboard 设备设置中,在 登录时启动 旁边打开 应用关闭时保持 OpenClaw 运行,或在捆绑的引导流程中打开。全新安装默认关闭。启用它会停止子进程并启动后台服务;禁用它会移除服务并启动由应用拥有的子进程。对于独立管理的 Gateway 以及不托管本地 Gateway 的连接,该控件不可用。当此偏好设置更改时,已暂停的 Gateway 保持暂停状态。
如果替换的 Gateway 启动失败,应用会恢复之前的托管模式,并在报告失败前验证其健康状态。操作员对服务的更改,或在切换期间暂停或退出,会停止自动恢复;应用会保留较新的选择,并报告未能完成的内容。
应用会保留来自 Gateway 生成的服务环境的设置,并在后续应用启动时重新读取该文件。如果服务存在在切换到应用托管后会丢失的设置,应用将保持服务不变,并要求你将所需设置移动到该配置的持久化配置或 .env 文件中。运行 openclaw gateway install --force,然后重试托管更改。这使用 Gateway CLI 对提供商凭据和所引用配置的现有持久化规则;任意环境变量的持久化不保证能通过新的服务安装保留。
CLI 也可以直接安装:openclaw gateway install(命名配置通过 OPENCLAW_PROFILE 环境变量选择)。从应用启用现有服务会保留其已保存的运行时固定。如果固定无效,启用会因 CLI 错误而失败;请显式使用 --runtime 或 --runtime-path 重新安装以替换已保存的固定。禁用它会卸载 LaunchAgent,从而移除固定。
新安装的应用管理 Bun 服务会固定到 <state>/runtime/<runtimeBuildId>/bin/bun,并带有匹配的包和 OPENCLAW_SQLITE_LIBRARY 环境。应用更新后,应用只会重新安装其拥有的、可执行文件位于 <state>/runtime/ 内的服务,将其安装到新的具体构建上。使用该目录外可执行文件的服务保持不变,包括未固定的可执行文件。更新窗口会报告:“Gateway 服务使用了操作员固定的运行时;请自行更新。”
行为:
- 在服务模式下,“OpenClaw 活动”启用/禁用 LaunchAgent。
- 在服务模式下,退出应用不会停止 Gateway(launchd 会保持其运行)。
- 如果 Gateway 已在配置的端口上运行,应用会附加到它,而不是启动新的 Gateway。
- 其他监听器保持运行。请通过拥有它们的进程或服务解决端口冲突;自动清理只会回收已记录的孤立 SSH 隧道。
- 如果服务检查无法得出结论,应用会延迟安装并使用其现有就绪检查。已确认不存在的服务仍可以安装。
使用 CLI 进行生命周期检查和恢复:
当启用 也在此 Mac 上运行 Gateway 且存在远程主节点时,受管理的 launch agent 会包含 --allow-unconfigured,以便在 gateway.mode 仍为 remote 时运行。将主节点切换为本地会移除该参数。参见 与远程主节点并行的本地托管。
Launchd 提供登录时自动启动、崩溃重启和一个可预测的日志位置,而无需将 Gateway 生命周期绑定到应用进程。
意外重复重启¶
如果 Gateway 在更新后反复重启,请运行以下命令:
在 macOS 上,这两个命令都会报告 ai.openclaw.* 命名空间中的外部已加载作业,包括未使用 plist 提交的作业。报告会显示每个标签、程序、KeepAlive 标志,以及检测到的 openclaw gateway restart、start 或 stop 调用。当至少一个作业具有 KeepAlive 或已验证的生命周期调用时,纯文本状态会将该列表显示为警告。否则,该列表会以信息形式显示在“其他 OpenClaw launchd 作业(macOS)”下。状态 JSON 会在 service.foreignLaunchdJobs 下包含所有这些作业。对于警告,生命周期日志中最近的外部强制重启可提供可能的关联;仅凭计数无法确定是哪个作业导致了重启。在十分钟内发生三次外部强制重启后,受管理的 Gateway 会记录一条可操作的警告,并在可用时列出可能的 KeepAlive 作业。它不会抑制操作员的重启命令。
要移除已确认的多余 Gateway 生命周期作业并验证恢复:
Doctor 仅当外部作业的字面、直接脚本或直接参数以 Gateway 生命周期子命令调用绝对 OpenClaw 路径时,才会移除该外部作业。Shell 作业还必须没有会改变 shell 执行的 launchd 环境条目。该约定之外的一切都会被报告并保持不变。这是命令元数据验证;它不会检查二进制可执行性、解释器可用性或隔离状态。
Doctor 会保留受管理的 LaunchAgent、无关标签以及无法确定用途的作业,即使在非交互式运行中也会列出每个移除项。对于隔离的安装身份、外部监督或正在进行的更新,服务修复仍保持禁用。
切勿使用 launchctl submit 或临时 KeepAlive 任务来执行更新或 Gateway 生命周期命令。此类任务可以在其脚本退出时反复运行 openclaw gateway restart,如 #114967 中所述。请使用受管更新工作流及其挂起围栏,然后验证状态和健康。
仅附加开发¶
当另一个进程已经拥有本地 Gateway 时,在不安装或修改其 LaunchAgent 的情况下运行开发版应用:
直接使用 --attach-only 或 --no-launchd 启动应用具有相同效果。该覆盖会持久化到 ~/.openclaw/disable-launchagent;删除该文件以恢复应用托管的 launchd 行为。
命名配置文件仍要求监听器属于该配置文件的 Gateway 服务。仅附加模式不允许附加其他进程或配置文件。如果发生端口所有权冲突,自动恢复会保留失败状态,而不是反复重新打开仪表盘。解决冲突后,重新启动应用。
日志:
- Gateway 标准输出:
~/Library/Logs/openclaw/gateway.log(配置文件使用gateway-<profile>.log) - Gateway 标准错误:合并到同一个
gateway.log文件中,因此发生在日志记录器启动之前的启动失败仍会被记录 - 如果主机因反复出现
EADDRINUSE或快速重启而循环,请检查重复的ai.openclaw.gateway/ai.openclaw.nodeLaunchAgent 以及 Gateway 故障排查 中的 launchd 标记变通方法。
应用托管生命周期与更新¶
应用会以递增延迟重启崩溃的子进程,延迟从 1 秒翻倍到 30 秒,并在健康运行 60 秒后重置。连续 5 次快速失败会停止重启循环,并显示失败以及 Gateway 日志尾部。暂停或退出会关闭宿主生命周期,并等待优雅关闭,然后强制无响应的进程组退出。
应用更新后(包括以相同公开版本重新构建),应用会播种新运行时,并以所选托管模式重启其 Gateway。它会先验证健康状态,再删除旧构建。已暂停的 Gateway 保持暂停。已播种的安装永远不会运行 npm 自更新;请更新 OpenClaw.app 以更新其 Gateway。已暂停的旧版应用托管 Node 安装即使旧应用已删除其 LaunchAgent,也会保持后台服务托管。暂停期间,应用会记录该偏好,而不检查或更改运行时。恢复时,它会在更新前恢复受管 Node CLI;这也适用于命名配置文件。现有应用托管的 Node 服务会继续通过其已安装 CLI 的更新和修复流程运行,包括健康验证,并保持其运行时固定。留在磁盘上的播种不会采用已附加的 Node 服务。如果无法验证该旧版运行时,更新窗口会保留可重试的失败状态,而不是用全新的捆绑安装替换它。缺失的 runtime/current 链接会通过播种修复;旧构建会保留,直到后续成功更新重新建立上一构建记录。无效的现有元数据仍为可重试失败。外部服务和通道策略保持其现有所有权规则。在远程主 Gateway 情况下,已安装的旧版 Mac 节点服务会通过其自身捕获的 CLI 进行更新和验证。应用拥有的本地伴随 Gateway 随后会单独更新;更新回执会保持待定,直到两个必需运行时都健康。捆绑的私有工作器不是 Node LaunchAgent,且缺失的节点服务或命名配置文件不会触发旧版节点生命周期工作。
要在发布应用上安装本地重新构建,请使用发布身份对其进行打包。默认调试包会保持独立的权限、默认配置文件偏好和已保存的 Gateway 配置文件,并针对发布应用的 Keychain 项触发登录钥匙串提示。参见 替换已安装的发布应用。
现有应用托管的 Node 服务¶
对于引导完成后的默认配置文件,应用会分两次独立尝试迁移其精确版本的 Node 安装。如果已安装版本与捆绑版本不同,现有受管更新器会先将 Node 安装更新到应用版本。核心更新器负责备份、回滚和数据库迁移。更新失败会使运行时保留在 Node 上,并显示现有更新失败和重试窗口。
在下次启动或重试时,一旦核心更新或修复完成且版本匹配,应用会播种其捆绑运行时,并使用匹配的特定 Bun、包和 SQLite 路径重新安装服务。它会在完成迁移前验证健康状态。如果该步骤失败,它会重新安装并验证保留的同版本 Node 命令,然后显示失败并提供重试。应用会保留旧 Node 工具和 npm 包用于恢复。在迁移完成前暂停并重新启动会保留 Node 恢复路径;它不会跳过版本更新,也不会提前启用托管切换。
在通过捆绑 CLI 进行应用拥有的安装之前,应用会使用相同的 CLI、运行时和环境,通过 gateway status --deep --json 读取运行时意图。在最终本地托管检查之后,它会将观察到的修订版本和服务定义传递给安装器。检查失败或未知会停止安装。如果操作员在安装开始前更改服务或运行时固定,CLI 会保留该选择,应用会报告它,而不重试或回滚。
Node 回滚和先前构建恢复会使用此应用的捆绑 CLI,并采用相同的运行时意图观察。安装器会恢复保留包的运行时和入口点,以及其用于 Bun 的 SQLite 库,而不是它自己的。恢复不要求失败的替换服务正在运行。操作员更改会被保留并报告,而不重试。如果应用的捆绑运行时缺失或不兼容,恢复会停止;请重新安装 OpenClaw.app。核心更新器步骤仍会运行已安装的 CLI,并且不受此安装围栏覆盖。
Channel-policy installs, independently managed services, and services with saved operator runtime pins are not migrated. This includes a saved pin pointing at the app's Node tools. This registered-service migration does not run automatically in named profiles.
旧版应用在暂停时会移除 LaunchAgent。在本地模式完成入门后,仍存留的应用管理的 Node 安装即使没有 LaunchAgent 也会保留服务托管。这适用于使用精确或未设置安装策略的默认和命名配置文件。暂停期间,应用仅记录托管偏好;它不会更新、初始化或安装 Gateway。
恢复时,应用使用该 Node 安装的核心更新器达到应用版本,而无需重启服务。然后它会初始化 Bun、安装服务,并在同一次启动尝试中验证健康状态。如果运行时切换失败,应用会重新安装并验证相同版本的 Node 服务,并显示带有“重试”的更新失败。全新配置文件保留应用托管;通道策略、仅附加配置文件和独立管理的安装不会被采用。
版本兼容性¶
私有 worker 必须匹配应用的构建来源,而不仅仅是其版本号。缺失或不兼容的 worker 负载会产生可见的 worker 错误;请重新构建或重新安装应用。更改 CLI 通道或更新全局 CLI 无法修复此私有负载。未捆绑的 Swift 开发构建可以改用检出的感知新鲜度的源码运行器。
如果 Gateway 更新将共享状态数据库架构推进到私有 worker 支持的版本之外,也请更新并重新启动 OpenClaw.app。重启外部 Gateway 不会替换应用拥有的 worker。来自该旧读取器的架构版本错误并不意味着升级后的 Gateway 数据库已损坏。
对于捆绑的本地 Gateway,应用会将其自身构建来源与已初始化的运行时进行验证;Node 版本要求不会阻止设置。未捆绑的开发构建会根据其安装策略检查外部 CLI。已附加的 Gateway 使用连接和健康检查,而不是本地 CLI 安装诊断。设置失败后请使用 重试设置,或从菜单栏打开 连接… → 连接,并在修复后选择 重新检查。当仪表板无法连接到 Gateway 时,连接窗口仍可用。
macOS 上的状态目录¶
将 OpenClaw 状态保留在本地、非同步磁盘上。避免使用 iCloud Drive 和其他云同步文件夹;同步延迟和文件锁可能影响会话、凭据和 Gateway 状态。
仅在需要覆盖时,将 OPENCLAW_STATE_DIR 设置为本地路径。
openclaw doctor 会警告常见的云同步状态路径,并建议移回本地存储。参见
环境变量 和
Doctor。
调试应用连接¶
使用捆绑的 macOS CLI 检查正在运行的应用:
应用的 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
然后:
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw