OpenClaw macOS Gateway 运行时管理指南LaunchAgent 服务、自动安装与故障恢复实战【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclawOpenClaw 在 macOS 上采用App 捆绑私有 Node 运行时 外部独立 Gateway的双层架构桌面 App 自带经过签名的 node worker 助手但 Gateway 始终作为外部进程运行由 per-user 的 launchd LaunchAgent 守护。本文围绕 docs/platforms/mac/bundled-gateway.md 系统讲解这套运行时模型的安装、生命周期、日志、版本兼容与故障排查读完你将掌握在 macOS 上部署、接管、调试和恢复 Gateway 服务的完整实战方案。架构定位捆绑 worker 与外部 Gateway 的职责边界OpenClaw.app 捆绑了一个私有 Node 运行时和与之配套的 OpenClaw 软件包专供 App 自有的node worker助手使用。这个助手具有三个关键特性随 App 一起重建/替换重新构建或替换 App 会同步替换该助手即使是相同公共版本的重新构建也不例外从签名包内运行助手从已签名的 bundle 中启动因此移动 App 或删除其构建检出目录都不会改变它实际使用的 worker不承担 Gateway 职责打包 worker 的过程永远不会安装、更新或重启 Gateway 服务App 也不会在自己的私有 worker 运行时内部启动 Gateway。与之相对Gateway 始终保持外部。App 通过外部的openclawCLI 管理一个 per-user 的 launchd 服务或者直接挂接attach到一个已在运行的 Gateway 上。从源码结构看这一职责边界在 apps/macos/Sources/OpenClaw/GatewayLaunchAgentManager.swift 中得到落实App 侧对 Gateway 的一切守护操作都归结为调用外部openclaw gateway子命令install --force --port ... --runtime node、uninstall、restart并由CommandResolver.resolveLocalCLI解析本机 CLI 后执行而非在 App 进程内自起 Gateway。私有 worker 的启动策略私有 worker 通过只读的 bootstrap校验 core 与 node 配置它不执行 Gateway 级的 Doctor 预检preflight也不做 channel-schema 校验。但需要注意Node 插件在发布命令前仍会自行校验自身设置node 运行时拥有自己的 MCP 客户端node 启动保留了 Doctor 负责的 device-auth、device-identity 和 exec-approval 迁移——这并不承诺 worker 的全部启动过程都是只读的公开的node run、Gateway 和 Doctor 则维持各自原有的启动策略。当原生 App 在 worker 启动前就创建了 identity、device-auth 或 approval 数据表时node 启动会通过规范初始化器canonical initializer补齐这个被识别为 version-zero 的数据库之后插件才能读取其状态且已存在的原生行会被保留。该流程不会迁移一个已有版本的共享 Gateway 数据库也不会接管未知或被占用的 bootstrap 状态。自动安装This Mac 引导流程在一台全新的 Mac 上于引导onboarding过程中选择This Mac即可触发全自动安装。App 会在 Gateway 向导之前运行其已签名的捆绑安装脚本整个过程无需 Terminal、Homebrew 或管理员权限在~/.openclaw下安装用户空间user-space的 Node 运行时与配套的openclawCLI安装并启动 per-user 的 launchd 服务。安装器使用一个私有临时目录存放下载物与构建工具。如果 App 继承的临时目录不可访问安装器会自动改用/tmp下的私有目录并在安装器退出时将其移除。这一机制规避了 macOS 临时目录的权限错误同时避免以 root 身份安装 CLI。需要强调的是Gateway 的安装仍需要联网——安装器要下载独立的运行时和配套的 OpenClaw 包捆绑的私有 worker 并不能替代 CLI 或 Gateway 的安装。跳过安装的场景以下情况会跳过这套安装流程远程连接连接到远程 Gateway 时挂接已有本地 Gateway挂接attach到独立管理的本地 Gateway 时纯挂接模式attach-only该模式永远不会提示你运行 CLI 来驱动 App 的 node。另外有两个值得注意的守护语义暂停Pause保留管理权暂停会保留谁在管理 Gateway这一事实即使停止 App 管理的服务会移除其 LaunchAgent 记录不可读的所有权记录会阻止安装如果服务所有权记录无法读取App 会阻止自动安装而不是当作服务缺失此时应检查 LaunchAgent 后重试。手动恢复版本读取与 CLI 安装读取目标版本从 App 中读取要安装的版本菜单栏选择About OpenClaw或运行openclaw-mac status --json其输出包含 App 版本与构建信息。手动安装 CLI手动安装要求 Node 26推荐或其他受支持的版本Node 24.16 或 Node 26.1。然后全局安装openclawnpm install -g openclawversion --allow-scriptsopenclaw版本前提上述命令适用于 npm 12 或 npm 11.16。在 npm 11.15 及更早版本上请省略--allow-scriptsopenclaw。恢复路径自动安装失败后使用Retry setup重试设置若重试仍失败先用上面的命令手动安装 CLI然后在引导中重新选择Check again再次检查。LaunchdGateway 作为 LaunchAgentmacOS 上的 Gateway 以 per-user LaunchAgent 形式常驻由 launchd 负责开机自启与崩溃重启。标识与位置项默认 profile命名 profileLabelai.openclaw.gatewayai.openclaw.profilePlist 位置~/Library/LaunchAgents/ai.openclaw.gateway.plist~/Library/LaunchAgents/ai.openclaw.profile.plistApp 在 Local 模式下负责默认 profile 的 LaunchAgent 安装/更新CLI 也可以直接安装openclaw gateway install命名 profile 通过OPENCLAW_PROFILE环境变量选择。在源码中GatewayLaunchAgentManager.swift 的set(enabled:...)正是把启用/停用翻译为openclaw gateway install --force --port port --runtime node与openclaw gateway uninstall并附加--json标志解析返回结果而plistURL(homeDirectory:profile:)也印证了~/Library/LaunchAgents/label.plist的落盘路径。行为语义OpenClaw ActiveApp 内开关启用/停用 LaunchAgent退出 App 不会停止 Gatewaylaunchd 会继续保持其存活端口已占用则挂接如果配置端口上已有 Gateway 在运行App 挂接到它而不是再启动一个新实例服务检查不确定时推迟安装若服务检查service inspection结果不确定App 会推迟安装并使用现有的就绪检查只有确认服务缺失时才允许安装。生命周期检查与恢复命令openclaw gateway status --deep openclaw gateway restart本地托管 远程主 Gateway当启用了Also run a Gateway on this Mac且存在远程主remote primary时受管理的 launch agent 会包含--allow-unconfigured参数使其可以在gateway.mode仍为remote的情况下运行。将主连接切换回本地后该参数会被移除。详见 本地托管与远程主并行。launchd 方案带来的收益是登录自启、崩溃重启、以及一个可预测的日志位置同时 Gateway 的生命周期不再绑定 App 进程。意外重复重启foreign launchd jobs 的识别与修复如果 Gateway 在更新后反复重启先运行诊断命令openclaw gateway status openclaw doctor在 macOS 上这两个命令都会报告ai.openclaw.*命名空间中的外来已加载任务foreign loaded jobs包括那些没有 plist 就提交的任务。报告会展示每个任务的label标签program程序路径KeepAlive 标志检测到的openclaw gateway restart/start/stop调用展示规则纯文本状态当至少一个任务带有 KeepAlive 或经过验证的生命周期调用时列表以警告形式显示否则以Other OpenClaw launchd jobs (macOS)信息项展示JSON 状态所有这些任务都位于service.foreignLaunchdJobs字段下。对于警告场景生命周期日志中最近的外部强制重启记录可以作为可能的相关线索——但仅凭计数无法确定是哪个任务导致的重启。当 10 分钟内发生 3 次外部强制重启后受管理的 Gateway 会记录一条可操作的警告在可用时点名可疑的 KeepAlive 任务它不会压制操作员自己发起的重启命令。Doctor 清理与验证openclaw doctor --fix openclaw gateway status openclaw healthDoctor 的移除遵循严格的命令元数据验证契约仅当任务的字面量、直线脚本straight-line script或直接参数调用的是绝对路径的 OpenClaw并带有 Gateway 生命周期子命令时才会移除外来任务对 shell 任务还必须确保其没有修改 shell 执行方式的 launchd 环境条目契约之外的一切都会被报告并保持原样。需要理解的是这是命令元数据验证不会探测二进制可执行性、解释器可用性或隔离quarantine状态。Doctor 会保留受管理的 LaunchAgents、无关 label 以及无法确定用途的任务并且在非交互运行中也会逐一具名每个移除动作。对于隔离安装身份、外部监督或更新进行中的场景服务修复保持禁用。重要警告永远不要使用launchctl submit或临时 KeepAlive 任务来执行更新或 Gateway 生命周期命令——这类任务会在其脚本退出时反复触发openclaw gateway restart。应使用受管理的更新工作流及其暂停围栏suspension fence然后验证 status 与 health。重复 LaunchAgent 导致的监督循环当ai.openclaw.gateway与ai.openclaw.node两个 LaunchAgent 同时激活、各自注入OPENCLAW_LAUNCHD_LABEL时OpenClaw 会误判 launchd 监督状态把重启交还给 launchd从而陷入快速EADDRINUSE/respawn 循环详见 Gateway 服务与进程排障。其现象是Gateway 每隔几秒重启、health 检查在健康与不可用之间抖动、通道投递停滞。诊断要点for i in 1 2 3 4; do ps aux | grep openclaw.*index.js | grep -v grep | awk {print $2} sleep 10 done openclaw gateway status --deep openclaw node status launchctl print gui/$UID/ai.openclaw.gateway | grep -E state|last exit|runs tail -n 80 ~/Library/Logs/openclaw/gateway.log处置步骤按需若本机只应运行 Gateway 服务通过 OpenClaw 卸载受管理的 node 服务openclaw node uninstall若确实依赖 node 服务的远程节点能力请跳过此步否则会停用相关功能安装一个在启动 OpenClaw 前清除继承 launchd 标记的持久 Gateway wrapper使用受支持的--wrapper选项不要直接编辑~/.openclaw/service-env/下生成的文件——服务重装、更新和 doctor 修复都会重新生成该文件mkdir -p ~/.local/bin cat ~/.local/bin/openclaw-launchd-workaround EOF #!/bin/sh set -eu unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true exec openclaw $ EOF chmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \ --wrapper ~/.local/bin/openclaw-launchd-workaround \ --forceAttach-only 开发模式当另一个进程已经拥有本地 Gateway 时可以以挂接模式运行开发版 App而不安装也不改动其 LaunchAgentscripts/restart-mac.sh --attach-only直接以--attach-only或--no-launchd启动 App 效果相同。该覆盖会持久化在~/.openclaw/disable-launchagent标记文件中——删除该文件即可恢复 App 管理的 launchd 行为。这与源码中 GatewayLaunchAgentManager.swift 的disableLaunchAgentMarker常量disable-launchagent及isLaunchAgentWriteDisabled()检查一一对应标记存在时set(enabled:)与kickstart()都会记录skip (disable marker set)并直接返回。限制与行为命名 profile 仍要求监听者属于该 profile 的 Gateway 服务挂接模式不允许挂接其他进程或其他 profile若发生端口所有权冲突自动恢复会保留失败现场而不是反复重开仪表盘——解决冲突后重新启动 App 即可。日志位置launchd stdout~/Library/Logs/openclaw/gateway.log命名 profile 使用gateway-profile.loglaunchd stderr合并进同一个gateway.log因此日志器启动之前的启动失败也会被记录如果主机陷入重复的EADDRINUSE或快速重启循环请检查是否存在重复的ai.openclaw.gateway/ai.openclaw.nodeLaunchAgent并参考上面的 launchd-marker 变通方案。日志路径在源码侧也有兜底逻辑GatewayLaunchAgentManager.launchdGatewayLogPath()会优先从 LaunchAgent plist 快照的StandardOutPath/StandardErrorPath读取读不到时回退到LogLocator.launchdGatewayLogPath。版本兼容性私有 worker 必须匹配 App 的构建出处build provenance而不只是版本号worker 载荷缺失或不兼容会产生可见的 worker 错误此时应重建或重装 App更换 CLI channel 或更新全局 CLI 都无法修复这个私有载荷未捆绑的 Swift 开发构建可以使用 checkout 中具备新鲜度感知的源码运行器source runner。对于 App 自有的本地 GatewaymacOS App 会按其安装策略检查外部 CLI当该 CLI 缺失或不兼容时引导onboarding会运行受管理的安装流程挂接attached的 Gateway 改用连接与健康检查而不使用本地 CLI 安装诊断受管理安装失败后使用Retry setup修复后从菜单栏打开Connection… → Connection并选择Recheck。即使仪表盘无法连接 GatewayConnection 窗口依然可用。macOS 上的状态目录将 OpenClaw 状态放在本地的、非同步的磁盘上避免 iCloud Drive 及其他云同步文件夹——同步延迟与文件锁可能影响会话、凭据与 Gateway 状态仅在确实需要覆盖时才设置OPENCLAW_STATE_DIR为本地路径openclaw doctor会警告常见的云同步状态路径并建议移回本地存储。相关参考见 环境变量文档 与 Doctor 文档。调试 App 连通性使用 App 捆绑的 macOS CLI 检查运行中的 Appopenclaw-mac status --json openclaw-mac primary show --json openclaw-mac gateway list --jsonApp 的 CLI 安装器会在其 profile 管理的openclaw命令旁链接openclaw-mac也可以直接运行/Applications/OpenClaw.app/Contents/MacOS/openclaw-mac更多primary set、已保存 Gateway 命令、profile 与凭据输入参见 远程控制。源码检出下的独立探针从源码检出对独立 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 发现与 App 侧连接问题时可将发现输出与openclaw gateway discover --json对比。Smoke Check端到端健康验证openclaw --version OPENCLAW_SKIP_CHANNELS1 \ OPENCLAW_SKIP_CANVAS_HOST1 \ openclaw gateway --port 18999 --bind loopback然后调用健康 RPCopenclaw gateway call health --port 18999 --timeout 3000OPENCLAW_SKIP_CHANNELS与OPENCLAW_SKIP_CANVAS_HOST用于跳过通道与 Canvas 宿主启动使 Gateway 以最小依赖在回环端口 18999 上快速起服适合验证安装链路与协议握手是否正常。小结与延伸阅读macOS 上 OpenClaw 的 Gateway 运维核心可以概括为三句话App 只管自己的私有 node workerGateway 永远由外部 CLI launchd 管理生命周期操作统一走openclaw gateway子命令异常重启优先用openclaw doctor --fix清理外来 launchd 任务。相关主题可继续阅读macOS App 平台文档Gateway 运维手册Gateway 服务与进程排障macOS 远程控制与多 Gateway【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考