OpenClaw macOS Gateway 宿主完全解析CLI 安装、LaunchAgent 服务生命周期与远程模式【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库中macos-gateway-host表面的完整性评估标准Completeness rubric见 macos-gateway-host.md为骨架系统讲解 macOS 作为 OpenClaw Gateway 宿主机时的完整技术版图从 CLI 安装与 Node 运行时要求、Local/Remote 两种 Gateway 模式、per-user LaunchAgent 服务生命周期到诊断命令、macOS TCC 权限与 Profile 隔离。读完后你能掌握如何在 Mac 上以 App 托管或纯 CLI 方式安装并管理 Gateway 服务、如何用launchctl与openclaw gateway命令做生命周期恢复以及远程模式下 SSH 隧道与 Tailscale 直连的取舍与配置项。一、这份 rubric 是什么macos-gateway-host 表面的六大评估维度OpenClaw 用一套成熟度记分卡maturity scorecard来度量各功能表面surface的能力完备度。其中macos-host表面的定义位于根目录 taxonomy.yamlid: macos-hostfamily: platform-applevel 标注为 stable/M4并指向本文档所在路径的完整性评估标准。该 rubric 将 macOS 宿主机能力划分为 6 个 CategoryCategory覆盖要点CLI Setup托管安装器、Node 版本要求、App 触发的 CLI 安装、Shell PATH 与版本管理器漂移Local Gateway IntegrationApp 的 local/remote 连接模式、App 托管的 LaunchAgent 安装/重启/卸载、CLI 安装检测、附加到已有本地 Gateway、gateway.modelocal配置、Loopback 绑定、本地端点解析、Bonjour 发现Remote Gateway ModeRemote over SSH 模式、SSH 隧道、Tailscale MagicDNS、远程端点 token/password/TLS 指纹、本地 node 主机启动Gateway Service Lifecycleper-user LaunchAgent 安装、launchctl bootstrap、LaunchAgent 标签、Gateway token/env 处理、openclaw update的 package/git 交接、陈旧 updater 作业检测、openclaw uninstall、遗留服务恢复Diagnostics and ObservabilityLaunchAgent 日志路径、openclaw gateway status --deep、Gateway 静默停摆排查、陈旧 updater 作业Permissions and Native CapabilitiesmacOS TCC 权限提示/状态、原生 node 能力暴露、system.run策略、权限驱动的支持Profile 与隔离Profile-specific LaunchAgent 标签、状态/配置/工作区根目录、派生端口、Rescue bot、重复 Gateway 进程检测构成第 6 个维度。理解这 6 个维度的意义在于它们恰好覆盖了安装 → 日常运行 → 状态检查 → 恢复 → 升级/卸载的完整运维闭环。下面按维度逐一展开并以仓库文档与源码为证。二、CLI Setup托管安装器、Node 运行时与 PATH 漂移macOS 上 Gateway 宿主的入口有两条OpenClaw.app 菜单栏应用触发的托管安装或手动 CLI 安装。2.1 App 托管安装无 Terminal、无 sudo根据 docs/platforms/mac/bundled-gateway.md全新 Mac 上在 onboarding 选择This Mac时App 会先运行其签名内嵌的安装脚本再进入 Gateway 向导在用户空间安装 Node 运行时和匹配的openclawCLI 到~/.openclaw目录下随后安装并启动 per-user launchd 服务全程无需 Terminal、Homebrew 或管理员权限但 Gateway 安装仍需联网下载独立的运行时和 OpenClaw 包。关键的架构事实是Gateway 始终是外部进程。App 内部捆绑的私有 Node runtime 只服务于 App 自有的node workerhelper从签名 bundle 内运行绝不用于启动 Gateway 本身——打包、重建或替换 App 只会替换该 worker不会安装、更新或重启 Gateway 服务。只有App 拥有本地 Gateway这一场景才需要独立 CLI 安装远程模式和附加到独立管理的本地 Gateway 都会跳过该安装。2.2 手动安装与 Node 版本要求自动安装失败时的手动恢复路径见 bundled-gateway.md# 需要 npm 12 或 npm 11.16npm 11.15 及更早版本请去掉 --allow-scriptsopenclaw npm install -g openclawversion --allow-scriptsopenclawNode 运行时要求当前文档推荐 Node 26也支持 Node 22.22.3、Node 24.15 或 Node 25.9taxonomy 中的 coverage IDmacos-host.node-24-recommendation即指Node 24.15 建议与 WAL-reset 安全的运行时下限。安装后在 App 中选择Check again让安装检测生效若 App 检测不到 CLI则 onboarding 会提示补装。2.3 Shell PATH 与版本管理器漂移rubric 单列了 Shell PATH and version-manager drift 一项因为非交互 shelllaunchd 服务、SSH 隧道里的远端命令看到的 PATH 与你的登录 shell 经常不同。远程模式排障表见 docs/platforms/mac/remote.md把这一症状固化为标准条目exit 127/ not found 意味着openclaw不在非登录 shell 的 PATH 中修复方式是把入口符号链接到/usr/local/bin或/opt/homebrew/bin或写入/etc/paths与 shell rc。同样的道理适用于本地宿主launchd 环境里 PATH 漂移是 Gateway 服务起不来的常见根因之一诊断时优先核对openclaw在非交互 shell 下是否可解析openclaw命令见 docs/cli/gateway.md。三、Local Gateway IntegrationLaunchAgent、Loopback 绑定与 Bonjour 发现3.1 LaunchAgent 标签与 plist 位置从 bundled-gateway.md 可以确认本地模式的落地形式标签默认 profile 为ai.openclaw.gateway命名 profile 为ai.openclaw.profile标签常量定义见 src/daemon/constants.tsplist 位置per-user~/Library/LaunchAgents/ai.openclaw.gateway.plist或ai.openclaw.profile.plistmacOS App 在 Local 模式下拥有默认 profile 的 LaunchAgent 安装/更新CLI 也可直接安装openclaw gateway install命名 profile 通过OPENCLAW_PROFILE环境变量选择。launchd 提供的行为保证登录时自启动、崩溃自动重启、单一可预测的日志位置且 Gateway 生命周期与 App 进程解耦——退出 App 不会停掉 Gatewaylaunchd 保活。若配置端口上已有 Gateway 在运行App 会附加attach到现有实例而不是再启动一个。3.2gateway.modelocal与 Loopback 绑定gateway.modelocal是 rubric 中 Local Gateway Integration 的核心配置项安装服务期间写入/缺省该模式声明本机 Gateway 由本机托管。Gateway 的配置与端点解析总览见 docs/gateway/index.mdgateway.mode的更多上下文见 docs/gateway/configuration.md。绑定策略遵循默认最小暴露Gateway 默认绑定 Loopback127.0.0.1只有显式host/bind覆盖才会暴露到非本机接口——一旦离开 Loopback就必须有有效认证token、密码或 identity-aware 反向代理gateway.auth.mode: trusted-proxy见 remote.md 安全注意事项。手动冒烟测试即可直观看到这一配置面openclaw --version OPENCLAW_SKIP_CHANNELS1 \ OPENCLAW_SKIP_CANVAS_HOST1 \ openclaw gateway --port 18999 --bind loopback验证健康openclaw gateway call health --port 18999 --timeout 30003.3 附加到已有 Gateway 与 Attach-only 开发模式当另一个进程已经拥有本地 Gateway 时开发版 App 可以用 attach-only 方式运行不安装、不改动任何 LaunchAgent见 bundled-gateway.mdscripts/restart-mac.sh --attach-only直接用--attach-only或--no-launchd启动 App 效果相同该覆盖会持久化到~/.openclaw/disable-launchagent删除该文件即可恢复 App 托管的 launchd 行为。所有权语义在 rubric 中也有对应attach-only 模式从不会提示安装 CLI 来运行 App 的 node暂停会保留 Gateway 的所有者身份——即无论谁停了服务谁管理这个 Gateway的记录不会丢失。3.4 Bonjour 发现本地发现走 Bonjour/mDNS局域网或 Tailnet 内通告了 Bonjour 的 Gateway 会出现在 Connection 窗口的发现列表中可直接选中自动填充 SSH target 或端点。协议细节见 docs/gateway/bonjour.md。源码侧可以对照 App 侧与 CLI 侧两套发现逻辑从源码 checkout 运行swift run openclaw-mac discover --timeout 3000 --json与openclaw gateway discover --json两者输出对比即可区分CLI 发现问题与App 连接问题该调试手法来自 bundled-gateway.md 的 Debug app connectivity 一节。四、Remote Gateway ModeSSH 隧道与 Tailscale 直连远程模式的完整文档在 docs/platforms/mac/remote.md总纲见 docs/gateway/remote.md三种模式Local (this Mac)全部在本机无 SSHRemote over SSH默认App 用-o BatchMode、你指定的 identity/key 建立 SSH 连接并做本地端口转发Remote direct (ws/wss)不走隧道直连 Gateway URLLAN、Tailscale、Tailscale Serve 或公网 HTTPS 反向代理。两种传输的差异SSH 隧道用ssh -N -L ...把远端 Gateway 端口转发到 localhostGateway 看到的节点 IP 是127.0.0.1Direct 模式则让 Gateway 看到真实客户端 IP。App 会为其自有 SSH 进程禁用连接复用ControlMaster与认证后后台化ForkAfterAuthentication确保它监控、重启的正是它自己拉起的那个进程。4.1configure-remote预配置命令无需欢迎向导即可通过命令行预配置 App# SSH 隧道模式 openclaw-mac configure-remote \ --ssh-target usergateway-host \ --local-port 18789 \ --remote-port 18789 \ --token $OPENCLAW_GATEWAY_TOKEN # Direct 模式LAN/Tailnet 已可达 openclaw-mac configure-remote \ --direct-url ws://192.168.0.202:18789 \ --token $OPENCLAW_GATEWAY_TOKEN配置解析顺序为OPENCLAW_CONFIG_PATH→$OPENCLAW_STATE_DIR/openclaw.json→~/.openclaw/openclaw.json两种形式都写入该活动文件并标记 onboarding 完成。--local-port/--remote-port默认18789其他标志包括--password、--identity path、--ssh-host-key-policy strict|openssh、--project-root、--cli-path、--json。几个容易被忽略的细节SSH 隧道模式下发现到的 LAN/tailnet 主机名会存为gateway.remote.sshTarget而gateway.remote.url保持为本地隧道端点如ws://127.0.0.1:18789使 CLI、Web Chat 与本地 node-host 服务共用同一 Loopback 传输本地隧道端口与远端 Gateway 端口不一致时用gateway.remote.remotePort指明远端端口发现结果同时含 Tailnet 原始 IP 与稳定主机名时App 优先 Tailscale MagicDNS 或 LAN 名称使连接在地址变化后更稳定。4.2 主机密钥策略与 TLS 指纹安全性是远程模式的重头戏SSH 主机密钥校验默认 strict因为 Gateway 凭证会经过这条隧道确要跟随托管 SSH 别名自身的信任策略用openclaw-mac configure-remote --ssh-host-key-policy openssh或直接设置gateway.remote.sshHostKeyPolicy: openssh更换 SSH 目标后策略会重置回strict除非再次显式选择Directwss://连接对 operator/control 流量和 Mac companion node 应用同一证书策略设置gateway.remote.tlsFingerprint做显式 pin不设置时App 只在 macOS 常规信任校验通过后才记录 first-use pin。Tailscale Serve 的wss://*.ts.net受信端点在证书轮换后会自动替换陈旧的存储 pin 并重试但配置过的 pin 永不自动轮换——证书更换后需手动更新gateway.remote.tlsFingerprintTailscale 的 MagicDNS、Serve 与 Funnel 的完整指引见 docs/gateway/tailscale.md。远端主机侧的前置条件安装 Node pnpm 并构建/安装 CLI确保openclaw在非交互 shell 的 PATH 上SSH 传输需先配置好密钥认证非局域网场景建议用 Tailscale IP 获得稳定可达性。五、Gateway Service Lifecyclelaunchctl 操作、更新交接与遗留服务恢复这是 rubric 中最硬核的维度对应 coverage IDslaunchctl-bootstrap、launchagent-labels、gateway-token-env-handling、openclaw-update-package-git-handoff、stale-updater-launchd-job-detection、openclaw-uninstall、stranded-service-recovery。5.1 launchctl 动词集与 KeepAlive 语义rubric 对launchctl bootstrap一项展开为bootstrap、bootout、enable、disable、kickstart、运行时状态解析、已安装但未加载的修复以及--disable语义。plist 侧的对应配置是KeepAlive崩溃/退出后拉起与RunAtLoad加载即运行再加上日志路径、工作目录与临时目录处理。App 的 OpenClaw Active 开关即对应 LaunchAgent 的 enable/disable。生命周期检查与恢复的日常命令openclaw gateway status --deep openclaw gateway restart更新场景下openclaw update区分 package 安装与 git checkout 两种交接路径openclaw-update-package-git-handoff更新后触发受管服务刷新与 LaunchAgent 重新 bootstrap相关文档为 docs/cli/update.md 与 docs/install/updating.md。update 命令在 launchd 下的重启辅助与系统级测试可参考 src/cli/update-cli/restart-helper.launchd-system.test.ts 等测试文件它们验证了 macOS 服务重启路径的行为边界。5.2 陈旧 updater 作业与遗留服务恢复两个专项维度值得单独强调Stale updater launchd job detection历史版本的自动更新机制可能留下废弃的 launchd 作业深检命令会识别并提示清理避免两个作业抢管同一 Gateway的混乱Stranded service recovery部分更新的 Mac 上可能出现服务记录在但进程起不来、或 plist 与运行时版本错位的情况。恢复手册见 docs/gateway/troubleshooting.md完整卸载含状态清理与手动 launchd 移除见 docs/install/uninstall.md。5.3 token/env 处理gateway-token-env-handling要求Gateway token 通过受管 env 文件/包装器承载且保持 owner-only 权限受管服务 env 键可审计status/doctor 输出能反映配置漂移。也就是说 token 不应当作明文长期留在 shell rc 或共享配置里而是由服务安装流程写入受权限保护的 env 载体。六、Diagnostics and Observability日志路径与静默停摆 Runbook6.1 固定日志位置launchd 服务的可观测性被设计成一个可预测的日志位置见 bundled-gateway.mdlaunchd stdout~/Library/Logs/openclaw/gateway.log命名 profile 为gateway-profile.loglaunchd stderr被抑制App 侧诊断日志见 docs/platforms/mac/logging.md。6.2 深检命令与静默停摆openclaw gateway status --deep是核心诊断入口配合 probe、openclaw doctor、health、logs 命令族见 docs/gateway/doctor.md 与 docs/cli/gateway.md。rubric 点名的典型故障场景包括Gateway 静默停止响应常见根因为睡眠/唤醒后的ENETDOWN、端口冲突、配置非法、内存压力supervisor loop主机反复出现EADDRINUSE或快速重启时检查是否存在重复的ai.openclaw.gateway/ai.openclaw.nodeLaunchAgent 及对应的 launchd-marker 处理方案troubleshooting 对应小节陈旧 updater 作业与配置漂移结合 5.2 的清理流程。七、Permissions and Native CapabilitiesTCC 与 system.run 策略macOS 宿主机同时是原生 node它通过 TCCTransparency, Consent, and Control体系暴露屏幕/画布/浏览器/系统操作能力。rubric 列出的权限域包括Accessibility、AppleScriptAutomation、Screen Recording、Microphone、Speech Recognition、Camera、Location、Notifications、Voice Wake。操作入口是Dashboard → Settings → This Mac → Permissions权限恢复与签名/TCC 问题排查见 docs/platforms/mac/permissions.md。与权限维度的配套机制节点通过node.list/node.describe广播自身权限状态让 agent 知道当前节点能做什么见 remote.md Permissions 一节system.run策略决定本地/远程节点执行语义——Mac 上经批准的 shell 命令在 App 上下文中执行保留 App 的 macOS 权限归属而共享 node 策略由 CLI runtime 持有见 docs/platforms/macos.md What the app owns 一节。八、Profiles and Isolation多 Gateway 隔离rubric 最后一个维度处理一台 Mac 上跑多个 Gateway的场景Profile-specific LaunchAgent 标签ai.openclaw.profile与独立的~/Library/LaunchAgents/ai.openclaw.profile.plist配合OPENCLAW_PROFILE环境变量选择命名 profileProfile 专属的状态/配置/工作区根目录每个 profile 有独立 state/config/workspace 根实现本地 Gateway 之间的数据隔离派生端口多 Gateway 通过派生端口避免冲突冲突规避策略见 docs/gateway/multiple-gateways.mdExtra Gateway 进程检测status --deep会检测多余的 Gateway 类服务与重复的本地进程Rescue bot 设置为隔离 profile 提供运维兜底入口。九、回到 rubric这套维度如何被用于评分macos-gateway-hostrubric 的实际用途在 claw-score 技能说明 中定义对某一表面打分时先读 taxonomy.yaml 中该表面的定义再读对应的完整性参考文件即本文展开的 6 个 Category然后从仓库公开证据docs、源码、测试、QA 场景元数据中寻找支撑最终把 Quality / Completeness / LTS 写入 qa/maturity-scores.yaml。评分语义上的两条关键纪律值得所有读者借鉴Completeness 度量的是面向操作者的预期工作流是否端到端存在setup → 正常使用 → 状态检查 → 恢复 → 升级/卸载以及重要平台/安全/生命周期分支不因为测试薄弱而扣分那是 Coverage也不因为实现质量脆弱而扣分那是 Quality分数带为Clawesome95-100/Stable80-95/Beta70-80/Alpha50-70/Experimental0-50。taxonomy 中macos-host表面的 level 目前是 stableM4rationale 明确写道LaunchAgent 服务路径、local/remote Gateway 模式、CLI 安装与 App 集成均有文档支撑。十、延伸阅读macOS App 总览与模式选择docs/platforms/macos.md本地 GatewayLaunchAgent详解docs/platforms/mac/bundled-gateway.md远程控制SSH/Direct/Tailscaledocs/platforms/mac/remote.mdGateway 通用运维手册docs/gateway/index.md、排障docs/gateway/troubleshooting.md、Doctordocs/gateway/doctor.md多 Gateway 隔离docs/gateway/multiple-gateways.mdCLI 参考docs/cli/gateway.md、更新docs/cli/update.md、卸载docs/install/uninstall.md成熟度记分卡数据qa/maturity-scores.yaml、分类法taxonomy.yamllaunchd 标签常量src/daemon/constants.ts需要提醒的适用前提本文所有版本要求、命令与配置项均取自当前仓库快照下的文档推荐 Node 26、最低 Node 22.22.3/24.15/25.9npm 11.16/12 的--allow-scripts语义等OpenClaw 迭代较快实际使用前请以你检出的仓库版本对应文档为准。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenClaw macOS Gateway 宿主完全解析：CLI 安装、LaunchAgent 服务生命周期与远程模式
OpenClaw macOS Gateway 宿主完全解析CLI 安装、LaunchAgent 服务生命周期与远程模式【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库中macos-gateway-host表面的完整性评估标准Completeness rubric见 macos-gateway-host.md为骨架系统讲解 macOS 作为 OpenClaw Gateway 宿主机时的完整技术版图从 CLI 安装与 Node 运行时要求、Local/Remote 两种 Gateway 模式、per-user LaunchAgent 服务生命周期到诊断命令、macOS TCC 权限与 Profile 隔离。读完后你能掌握如何在 Mac 上以 App 托管或纯 CLI 方式安装并管理 Gateway 服务、如何用launchctl与openclaw gateway命令做生命周期恢复以及远程模式下 SSH 隧道与 Tailscale 直连的取舍与配置项。一、这份 rubric 是什么macos-gateway-host 表面的六大评估维度OpenClaw 用一套成熟度记分卡maturity scorecard来度量各功能表面surface的能力完备度。其中macos-host表面的定义位于根目录 taxonomy.yamlid: macos-hostfamily: platform-applevel 标注为 stable/M4并指向本文档所在路径的完整性评估标准。该 rubric 将 macOS 宿主机能力划分为 6 个 CategoryCategory覆盖要点CLI Setup托管安装器、Node 版本要求、App 触发的 CLI 安装、Shell PATH 与版本管理器漂移Local Gateway IntegrationApp 的 local/remote 连接模式、App 托管的 LaunchAgent 安装/重启/卸载、CLI 安装检测、附加到已有本地 Gateway、gateway.modelocal配置、Loopback 绑定、本地端点解析、Bonjour 发现Remote Gateway ModeRemote over SSH 模式、SSH 隧道、Tailscale MagicDNS、远程端点 token/password/TLS 指纹、本地 node 主机启动Gateway Service Lifecycleper-user LaunchAgent 安装、launchctl bootstrap、LaunchAgent 标签、Gateway token/env 处理、openclaw update的 package/git 交接、陈旧 updater 作业检测、openclaw uninstall、遗留服务恢复Diagnostics and ObservabilityLaunchAgent 日志路径、openclaw gateway status --deep、Gateway 静默停摆排查、陈旧 updater 作业Permissions and Native CapabilitiesmacOS TCC 权限提示/状态、原生 node 能力暴露、system.run策略、权限驱动的支持Profile 与隔离Profile-specific LaunchAgent 标签、状态/配置/工作区根目录、派生端口、Rescue bot、重复 Gateway 进程检测构成第 6 个维度。理解这 6 个维度的意义在于它们恰好覆盖了安装 → 日常运行 → 状态检查 → 恢复 → 升级/卸载的完整运维闭环。下面按维度逐一展开并以仓库文档与源码为证。二、CLI Setup托管安装器、Node 运行时与 PATH 漂移macOS 上 Gateway 宿主的入口有两条OpenClaw.app 菜单栏应用触发的托管安装或手动 CLI 安装。2.1 App 托管安装无 Terminal、无 sudo根据 docs/platforms/mac/bundled-gateway.md全新 Mac 上在 onboarding 选择This Mac时App 会先运行其签名内嵌的安装脚本再进入 Gateway 向导在用户空间安装 Node 运行时和匹配的openclawCLI 到~/.openclaw目录下随后安装并启动 per-user launchd 服务全程无需 Terminal、Homebrew 或管理员权限但 Gateway 安装仍需联网下载独立的运行时和 OpenClaw 包。关键的架构事实是Gateway 始终是外部进程。App 内部捆绑的私有 Node runtime 只服务于 App 自有的node workerhelper从签名 bundle 内运行绝不用于启动 Gateway 本身——打包、重建或替换 App 只会替换该 worker不会安装、更新或重启 Gateway 服务。只有App 拥有本地 Gateway这一场景才需要独立 CLI 安装远程模式和附加到独立管理的本地 Gateway 都会跳过该安装。2.2 手动安装与 Node 版本要求自动安装失败时的手动恢复路径见 bundled-gateway.md# 需要 npm 12 或 npm 11.16npm 11.15 及更早版本请去掉 --allow-scriptsopenclaw npm install -g openclawversion --allow-scriptsopenclawNode 运行时要求当前文档推荐 Node 26也支持 Node 22.22.3、Node 24.15 或 Node 25.9taxonomy 中的 coverage IDmacos-host.node-24-recommendation即指Node 24.15 建议与 WAL-reset 安全的运行时下限。安装后在 App 中选择Check again让安装检测生效若 App 检测不到 CLI则 onboarding 会提示补装。2.3 Shell PATH 与版本管理器漂移rubric 单列了 Shell PATH and version-manager drift 一项因为非交互 shelllaunchd 服务、SSH 隧道里的远端命令看到的 PATH 与你的登录 shell 经常不同。远程模式排障表见 docs/platforms/mac/remote.md把这一症状固化为标准条目exit 127/ not found 意味着openclaw不在非登录 shell 的 PATH 中修复方式是把入口符号链接到/usr/local/bin或/opt/homebrew/bin或写入/etc/paths与 shell rc。同样的道理适用于本地宿主launchd 环境里 PATH 漂移是 Gateway 服务起不来的常见根因之一诊断时优先核对openclaw在非交互 shell 下是否可解析openclaw命令见 docs/cli/gateway.md。三、Local Gateway IntegrationLaunchAgent、Loopback 绑定与 Bonjour 发现3.1 LaunchAgent 标签与 plist 位置从 bundled-gateway.md 可以确认本地模式的落地形式标签默认 profile 为ai.openclaw.gateway命名 profile 为ai.openclaw.profile标签常量定义见 src/daemon/constants.tsplist 位置per-user~/Library/LaunchAgents/ai.openclaw.gateway.plist或ai.openclaw.profile.plistmacOS App 在 Local 模式下拥有默认 profile 的 LaunchAgent 安装/更新CLI 也可直接安装openclaw gateway install命名 profile 通过OPENCLAW_PROFILE环境变量选择。launchd 提供的行为保证登录时自启动、崩溃自动重启、单一可预测的日志位置且 Gateway 生命周期与 App 进程解耦——退出 App 不会停掉 Gatewaylaunchd 保活。若配置端口上已有 Gateway 在运行App 会附加attach到现有实例而不是再启动一个。3.2gateway.modelocal与 Loopback 绑定gateway.modelocal是 rubric 中 Local Gateway Integration 的核心配置项安装服务期间写入/缺省该模式声明本机 Gateway 由本机托管。Gateway 的配置与端点解析总览见 docs/gateway/index.mdgateway.mode的更多上下文见 docs/gateway/configuration.md。绑定策略遵循默认最小暴露Gateway 默认绑定 Loopback127.0.0.1只有显式host/bind覆盖才会暴露到非本机接口——一旦离开 Loopback就必须有有效认证token、密码或 identity-aware 反向代理gateway.auth.mode: trusted-proxy见 remote.md 安全注意事项。手动冒烟测试即可直观看到这一配置面openclaw --version OPENCLAW_SKIP_CHANNELS1 \ OPENCLAW_SKIP_CANVAS_HOST1 \ openclaw gateway --port 18999 --bind loopback验证健康openclaw gateway call health --port 18999 --timeout 30003.3 附加到已有 Gateway 与 Attach-only 开发模式当另一个进程已经拥有本地 Gateway 时开发版 App 可以用 attach-only 方式运行不安装、不改动任何 LaunchAgent见 bundled-gateway.mdscripts/restart-mac.sh --attach-only直接用--attach-only或--no-launchd启动 App 效果相同该覆盖会持久化到~/.openclaw/disable-launchagent删除该文件即可恢复 App 托管的 launchd 行为。所有权语义在 rubric 中也有对应attach-only 模式从不会提示安装 CLI 来运行 App 的 node暂停会保留 Gateway 的所有者身份——即无论谁停了服务谁管理这个 Gateway的记录不会丢失。3.4 Bonjour 发现本地发现走 Bonjour/mDNS局域网或 Tailnet 内通告了 Bonjour 的 Gateway 会出现在 Connection 窗口的发现列表中可直接选中自动填充 SSH target 或端点。协议细节见 docs/gateway/bonjour.md。源码侧可以对照 App 侧与 CLI 侧两套发现逻辑从源码 checkout 运行swift run openclaw-mac discover --timeout 3000 --json与openclaw gateway discover --json两者输出对比即可区分CLI 发现问题与App 连接问题该调试手法来自 bundled-gateway.md 的 Debug app connectivity 一节。四、Remote Gateway ModeSSH 隧道与 Tailscale 直连远程模式的完整文档在 docs/platforms/mac/remote.md总纲见 docs/gateway/remote.md三种模式Local (this Mac)全部在本机无 SSHRemote over SSH默认App 用-o BatchMode、你指定的 identity/key 建立 SSH 连接并做本地端口转发Remote direct (ws/wss)不走隧道直连 Gateway URLLAN、Tailscale、Tailscale Serve 或公网 HTTPS 反向代理。两种传输的差异SSH 隧道用ssh -N -L ...把远端 Gateway 端口转发到 localhostGateway 看到的节点 IP 是127.0.0.1Direct 模式则让 Gateway 看到真实客户端 IP。App 会为其自有 SSH 进程禁用连接复用ControlMaster与认证后后台化ForkAfterAuthentication确保它监控、重启的正是它自己拉起的那个进程。4.1configure-remote预配置命令无需欢迎向导即可通过命令行预配置 App# SSH 隧道模式 openclaw-mac configure-remote \ --ssh-target usergateway-host \ --local-port 18789 \ --remote-port 18789 \ --token $OPENCLAW_GATEWAY_TOKEN # Direct 模式LAN/Tailnet 已可达 openclaw-mac configure-remote \ --direct-url ws://192.168.0.202:18789 \ --token $OPENCLAW_GATEWAY_TOKEN配置解析顺序为OPENCLAW_CONFIG_PATH→$OPENCLAW_STATE_DIR/openclaw.json→~/.openclaw/openclaw.json两种形式都写入该活动文件并标记 onboarding 完成。--local-port/--remote-port默认18789其他标志包括--password、--identity path、--ssh-host-key-policy strict|openssh、--project-root、--cli-path、--json。几个容易被忽略的细节SSH 隧道模式下发现到的 LAN/tailnet 主机名会存为gateway.remote.sshTarget而gateway.remote.url保持为本地隧道端点如ws://127.0.0.1:18789使 CLI、Web Chat 与本地 node-host 服务共用同一 Loopback 传输本地隧道端口与远端 Gateway 端口不一致时用gateway.remote.remotePort指明远端端口发现结果同时含 Tailnet 原始 IP 与稳定主机名时App 优先 Tailscale MagicDNS 或 LAN 名称使连接在地址变化后更稳定。4.2 主机密钥策略与 TLS 指纹安全性是远程模式的重头戏SSH 主机密钥校验默认 strict因为 Gateway 凭证会经过这条隧道确要跟随托管 SSH 别名自身的信任策略用openclaw-mac configure-remote --ssh-host-key-policy openssh或直接设置gateway.remote.sshHostKeyPolicy: openssh更换 SSH 目标后策略会重置回strict除非再次显式选择Directwss://连接对 operator/control 流量和 Mac companion node 应用同一证书策略设置gateway.remote.tlsFingerprint做显式 pin不设置时App 只在 macOS 常规信任校验通过后才记录 first-use pin。Tailscale Serve 的wss://*.ts.net受信端点在证书轮换后会自动替换陈旧的存储 pin 并重试但配置过的 pin 永不自动轮换——证书更换后需手动更新gateway.remote.tlsFingerprintTailscale 的 MagicDNS、Serve 与 Funnel 的完整指引见 docs/gateway/tailscale.md。远端主机侧的前置条件安装 Node pnpm 并构建/安装 CLI确保openclaw在非交互 shell 的 PATH 上SSH 传输需先配置好密钥认证非局域网场景建议用 Tailscale IP 获得稳定可达性。五、Gateway Service Lifecyclelaunchctl 操作、更新交接与遗留服务恢复这是 rubric 中最硬核的维度对应 coverage IDslaunchctl-bootstrap、launchagent-labels、gateway-token-env-handling、openclaw-update-package-git-handoff、stale-updater-launchd-job-detection、openclaw-uninstall、stranded-service-recovery。5.1 launchctl 动词集与 KeepAlive 语义rubric 对launchctl bootstrap一项展开为bootstrap、bootout、enable、disable、kickstart、运行时状态解析、已安装但未加载的修复以及--disable语义。plist 侧的对应配置是KeepAlive崩溃/退出后拉起与RunAtLoad加载即运行再加上日志路径、工作目录与临时目录处理。App 的 OpenClaw Active 开关即对应 LaunchAgent 的 enable/disable。生命周期检查与恢复的日常命令openclaw gateway status --deep openclaw gateway restart更新场景下openclaw update区分 package 安装与 git checkout 两种交接路径openclaw-update-package-git-handoff更新后触发受管服务刷新与 LaunchAgent 重新 bootstrap相关文档为 docs/cli/update.md 与 docs/install/updating.md。update 命令在 launchd 下的重启辅助与系统级测试可参考 src/cli/update-cli/restart-helper.launchd-system.test.ts 等测试文件它们验证了 macOS 服务重启路径的行为边界。5.2 陈旧 updater 作业与遗留服务恢复两个专项维度值得单独强调Stale updater launchd job detection历史版本的自动更新机制可能留下废弃的 launchd 作业深检命令会识别并提示清理避免两个作业抢管同一 Gateway的混乱Stranded service recovery部分更新的 Mac 上可能出现服务记录在但进程起不来、或 plist 与运行时版本错位的情况。恢复手册见 docs/gateway/troubleshooting.md完整卸载含状态清理与手动 launchd 移除见 docs/install/uninstall.md。5.3 token/env 处理gateway-token-env-handling要求Gateway token 通过受管 env 文件/包装器承载且保持 owner-only 权限受管服务 env 键可审计status/doctor 输出能反映配置漂移。也就是说 token 不应当作明文长期留在 shell rc 或共享配置里而是由服务安装流程写入受权限保护的 env 载体。六、Diagnostics and Observability日志路径与静默停摆 Runbook6.1 固定日志位置launchd 服务的可观测性被设计成一个可预测的日志位置见 bundled-gateway.mdlaunchd stdout~/Library/Logs/openclaw/gateway.log命名 profile 为gateway-profile.loglaunchd stderr被抑制App 侧诊断日志见 docs/platforms/mac/logging.md。6.2 深检命令与静默停摆openclaw gateway status --deep是核心诊断入口配合 probe、openclaw doctor、health、logs 命令族见 docs/gateway/doctor.md 与 docs/cli/gateway.md。rubric 点名的典型故障场景包括Gateway 静默停止响应常见根因为睡眠/唤醒后的ENETDOWN、端口冲突、配置非法、内存压力supervisor loop主机反复出现EADDRINUSE或快速重启时检查是否存在重复的ai.openclaw.gateway/ai.openclaw.nodeLaunchAgent 及对应的 launchd-marker 处理方案troubleshooting 对应小节陈旧 updater 作业与配置漂移结合 5.2 的清理流程。七、Permissions and Native CapabilitiesTCC 与 system.run 策略macOS 宿主机同时是原生 node它通过 TCCTransparency, Consent, and Control体系暴露屏幕/画布/浏览器/系统操作能力。rubric 列出的权限域包括Accessibility、AppleScriptAutomation、Screen Recording、Microphone、Speech Recognition、Camera、Location、Notifications、Voice Wake。操作入口是Dashboard → Settings → This Mac → Permissions权限恢复与签名/TCC 问题排查见 docs/platforms/mac/permissions.md。与权限维度的配套机制节点通过node.list/node.describe广播自身权限状态让 agent 知道当前节点能做什么见 remote.md Permissions 一节system.run策略决定本地/远程节点执行语义——Mac 上经批准的 shell 命令在 App 上下文中执行保留 App 的 macOS 权限归属而共享 node 策略由 CLI runtime 持有见 docs/platforms/macos.md What the app owns 一节。八、Profiles and Isolation多 Gateway 隔离rubric 最后一个维度处理一台 Mac 上跑多个 Gateway的场景Profile-specific LaunchAgent 标签ai.openclaw.profile与独立的~/Library/LaunchAgents/ai.openclaw.profile.plist配合OPENCLAW_PROFILE环境变量选择命名 profileProfile 专属的状态/配置/工作区根目录每个 profile 有独立 state/config/workspace 根实现本地 Gateway 之间的数据隔离派生端口多 Gateway 通过派生端口避免冲突冲突规避策略见 docs/gateway/multiple-gateways.mdExtra Gateway 进程检测status --deep会检测多余的 Gateway 类服务与重复的本地进程Rescue bot 设置为隔离 profile 提供运维兜底入口。九、回到 rubric这套维度如何被用于评分macos-gateway-hostrubric 的实际用途在 claw-score 技能说明 中定义对某一表面打分时先读 taxonomy.yaml 中该表面的定义再读对应的完整性参考文件即本文展开的 6 个 Category然后从仓库公开证据docs、源码、测试、QA 场景元数据中寻找支撑最终把 Quality / Completeness / LTS 写入 qa/maturity-scores.yaml。评分语义上的两条关键纪律值得所有读者借鉴Completeness 度量的是面向操作者的预期工作流是否端到端存在setup → 正常使用 → 状态检查 → 恢复 → 升级/卸载以及重要平台/安全/生命周期分支不因为测试薄弱而扣分那是 Coverage也不因为实现质量脆弱而扣分那是 Quality分数带为Clawesome95-100/Stable80-95/Beta70-80/Alpha50-70/Experimental0-50。taxonomy 中macos-host表面的 level 目前是 stableM4rationale 明确写道LaunchAgent 服务路径、local/remote Gateway 模式、CLI 安装与 App 集成均有文档支撑。十、延伸阅读macOS App 总览与模式选择docs/platforms/macos.md本地 GatewayLaunchAgent详解docs/platforms/mac/bundled-gateway.md远程控制SSH/Direct/Tailscaledocs/platforms/mac/remote.mdGateway 通用运维手册docs/gateway/index.md、排障docs/gateway/troubleshooting.md、Doctordocs/gateway/doctor.md多 Gateway 隔离docs/gateway/multiple-gateways.mdCLI 参考docs/cli/gateway.md、更新docs/cli/update.md、卸载docs/install/uninstall.md成熟度记分卡数据qa/maturity-scores.yaml、分类法taxonomy.yamllaunchd 标签常量src/daemon/constants.ts需要提醒的适用前提本文所有版本要求、命令与配置项均取自当前仓库快照下的文档推荐 Node 26、最低 Node 22.22.3/24.15/25.9npm 11.16/12 的--allow-scripts语义等OpenClaw 迭代较快实际使用前请以你检出的仓库版本对应文档为准。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考