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.yaml（id: macos-host，family: platform-app，level 标注为 stable/M4），并指向本文档所在路径的完整性评估标准。该 rubric 将 macOS 宿主机能力划分为 6 个 Category：

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.16+；npm 11.15 及更早版本请去掉 --allow-scripts=openclaw npm install -g openclaw@<version> --allow-scripts=openclaw

Node 运行时要求：当前文档推荐 Node 26，也支持 Node 22.22.3+、Node 24.15+ 或 Node 25.9+（taxonomy 中的 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" 一项，因为非交互 shell（launchd 服务、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 Integration：LaunchAgent、Loopback 绑定与 Bonjour 发现

3.1 LaunchAgent 标签与 plist 位置

从 bundled-gateway.md 可以确认本地模式的落地形式：

• 标签：默认 profile 为ai.openclaw.gateway，命名 profile 为ai.openclaw.<profile>（标签常量定义见 src/daemon/constants.ts）；
• plist 位置（per-user）：~/Library/LaunchAgents/ai.openclaw.gateway.plist（或ai.openclaw.<profile>.plist）；
• macOS App 在 Local 模式下拥有默认 profile 的 LaunchAgent 安装/更新；CLI 也可直接安装：openclaw gateway install（命名 profile 通过OPENCLAW_PROFILE环境变量选择）。

launchd 提供的行为保证：登录时自启动、崩溃自动重启、单一可预测的日志位置，且 Gateway 生命周期与 App 进程解耦——退出 App 不会停掉 Gateway（launchd 保活）。若配置端口上已有 Gateway 在运行，App 会附加（attach）到现有实例而不是再启动一个。

3.2gateway.mode=local与 Loopback 绑定

gateway.mode=local是 rubric 中 "Local Gateway Integration" 的核心配置项：安装服务期间写入/缺省该模式，声明本机 Gateway 由本机托管。Gateway 的配置与端点解析总览见 docs/gateway/index.md，gateway.mode的更多上下文见 docs/gateway/configuration.md。

绑定策略遵循"默认最小暴露"：Gateway 默认绑定 Loopback（127.0.0.1），只有显式host/bind覆盖才会暴露到非本机接口——一旦离开 Loopback，就必须有有效认证（token、密码或 identity-aware 反向代理，gateway.auth.mode: "trusted-proxy"，见 remote.md 安全注意事项）。手动冒烟测试即可直观看到这一配置面：

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

3.3 附加到已有 Gateway 与 Attach-only 开发模式

当另一个进程已经拥有本地 Gateway 时，开发版 App 可以用 attach-only 方式运行，不安装、不改动任何 LaunchAgent（见 bundled-gateway.md）：

scripts/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 Mode：SSH 隧道与 Tailscale 直连

远程模式的完整文档在 docs/platforms/mac/remote.md（总纲见 docs/gateway/remote.md），三种模式：

• Local (this Mac)：全部在本机，无 SSH；
• Remote over SSH（默认）：App 用-o BatchMode、你指定的 identity/key 建立 SSH 连接并做本地端口转发；
• Remote direct (ws/wss)：不走隧道，直连 Gateway URL（LAN、Tailscale、Tailscale Serve 或公网 HTTPS 反向代理）。

两种传输的差异：SSH 隧道用ssh -N -L ...把远端 Gateway 端口转发到 localhost，Gateway 看到的节点 IP 是127.0.0.1；Direct 模式则让 Gateway 看到真实客户端 IP。App 会为其自有 SSH 进程禁用连接复用（ControlMaster）与认证后后台化（ForkAfterAuthentication），确保它监控、重启的正是它自己拉起的那个进程。

4.1configure-remote预配置命令

无需欢迎向导即可通过命令行预配置 App：

# SSH 隧道模式 openclaw-mac configure-remote \ --ssh-target user@gateway-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.tlsFingerprint；
• Tailscale 的 MagicDNS、Serve 与 Funnel 的完整指引见 docs/gateway/tailscale.md。

远端主机侧的前置条件：安装 Node + pnpm 并构建/安装 CLI；确保openclaw在非交互 shell 的 PATH 上；SSH 传输需先配置好密钥认证，非局域网场景建议用 Tailscale IP 获得稳定可达性。

五、Gateway Service Lifecycle：launchctl 操作、更新交接与遗留服务恢复

这是 rubric 中最"硬核"的维度，对应 coverage IDs：launchctl-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：日志路径与静默停摆 Runbook

6.1 固定日志位置

launchd 服务的可观测性被设计成"一个可预测的日志位置"（见 bundled-gateway.md）：

• launchd stdout：~/Library/Logs/openclaw/gateway.log（命名 profile 为gateway-<profile>.log）；
• launchd 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 Capabilities：TCC 与 system.run 策略

macOS 宿主机同时是"原生 node"：它通过 TCC（Transparency, Consent, and Control）体系暴露屏幕/画布/浏览器/系统操作能力。rubric 列出的权限域包括：Accessibility、AppleScript（Automation）、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环境变量选择命名 profile；
• Profile 专属的状态/配置/工作区根目录：每个 profile 有独立 state/config/workspace 根，实现本地 Gateway 之间的数据隔离；
• 派生端口：多 Gateway 通过派生端口避免冲突，冲突规避策略见 docs/gateway/multiple-gateways.md；
• Extra 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）；
• 分数带为Clawesome（95-100）/Stable（80-95）/Beta（70-80）/Alpha（50-70）/Experimental（0-50）。taxonomy 中macos-host表面的 level 目前是 stable（M4），rationale 明确写道："LaunchAgent 服务路径、local/remote Gateway 模式、CLI 安装与 App 集成均有文档支撑"。

十、延伸阅读

• macOS App 总览与模式选择：docs/platforms/macos.md
• 本地 Gateway（LaunchAgent）详解：docs/platforms/mac/bundled-gateway.md
• 远程控制（SSH/Direct/Tailscale）：docs/platforms/mac/remote.md
• Gateway 通用运维手册：docs/gateway/index.md、排障：docs/gateway/troubleshooting.md、Doctor：docs/gateway/doctor.md
• 多 Gateway 隔离：docs/gateway/multiple-gateways.md
• CLI 参考：docs/cli/gateway.md、更新：docs/cli/update.md、卸载：docs/install/uninstall.md
• 成熟度记分卡数据：qa/maturity-scores.yaml、分类法：taxonomy.yaml
• launchd 标签常量：src/daemon/constants.ts

需要提醒的适用前提：本文所有版本要求、命令与配置项均取自当前仓库快照下的文档（推荐 Node 26、最低 Node 22.22.3+/24.15+/25.9+，npm 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