macOS 应用

macOS 应用是 OpenClaw 的 菜单栏伴侣。它负责权限管理，管理/连接本机 Gateway（launchd 或手动），并以节点的形式向 Agent 暴露 macOS 能力。

- 在菜单栏显示原生通知与状态。

- 负责 TCC 授权弹窗（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。

- 运行或连接 Gateway（本机或远程）。

- 暴露 macOS 专有工具（Canvas、Camera、Screen Recording、''system.run''）。

- 在 远程 模式下启动本机节点宿主服务（launchd），在 本机 模式下停止它。

- 可选托管 PeekabooBridge 用于 UI 自动化。

- 需要时通过 npm/pnpm 安装全局 CLI（''openclaw''）（不建议用 bun 作为 Gateway 运行时）。

- ''本机（默认）''：如果检测到正在运行的本机 Gateway，就直接连接；否则通过 ''openclaw gateway install'' 启用 launchd 服务。

- 远程：应用通过 SSH/Tailscale 连接远端 Gateway，且不会在本机启动 gateway 进程。

该模式下应用会启动本机的 节点宿主服务，让远端 Gateway 能连接到这台 Mac。

应用不会以子进程方式拉起 Gateway。

应用管理一个按用户的 LaunchAgent，label 为 ''bot.molt.gateway''

(''bot.molt.<profile>'' when using ''--profile''/''OPENCLAW_PROFILE''; legacy ''com.openclaw.*'' will be uninstalled).

如果使用命名配置文件，请将标签替换为 ''bot.molt.<profile>''。

如果 LaunchAgent 未安装，可以在应用内启用，或运行 ''openclaw gateway install''。

launchctl kickstart -k gui/$UID/bot.molt.gateway
launchctl bootout gui/$UID/bot.molt.gateway

PlatformsMacosPage step 03: P5

PlatformsMacosPage step 03: P6

macOS 应用会以节点身份连接。常见命令：

- Canvas：''canvas.present''、''canvas.navigate''、''canvas.eval''、''canvas.snapshot''、''canvas.a2ui.*''

- Camera：''camera.snap''、''camera.clip''

- Screen：''screen.record''

- System：''system.run''、''system.notify''

节点会回报一份 ''permissions'' 映射，便于 Agent 判断哪些能力允许使用。

节点服务与应用 IPC：

- 当无头节点宿主服务运行时（远程模式），它会作为节点通过 WS 连接 Gateway。

- ''system.run'' 在 macOS 应用内执行（UI/TCC 上下文），通过本机 Unix socket 与应用通信；提示与输出保留在应用内。

示意图（SCI）：

''system.run'' 由 macOS 应用中的 ''Exec approvals'' 控制（Settings → Exec approvals）。安全策略、询问策略与 allowlist 存储在本机：

~/.openclaw/exec-approvals.json

示例：

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }]
    }
  }
}

说明：

- ''allowlist'' 条目是解析后可执行文件路径的 glob 匹配。

- 在弹窗里选择 "Always Allow" 会把该命令加入 allowlist。

''system.run'' 的环境变量覆盖会被过滤（丢弃 ''PATH''、''DYLD_*''、''LD_*''、''NODE_OPTIONS''、''PYTHON*''、''PERL*''、''RUBYOPT''），然后与应用环境合并。

应用注册了 ''openclaw://'' URL scheme 用于本机动作。

#

触发一次 Gateway ''agent'' 请求：

open 'openclaw://agent?message=Hello%20from%20deep%20link'

Query 参数：

- ''message''（必填）

- ''sessionKey''（可选）

- ''thinking''（可选）

- ''deliver'' / ''to'' / ''channel''（可选）

- ''timeoutSeconds''（可选）

- ''key''（可选：无人值守模式 key）

安全性：

- 没有 ''key'' 时，应用会弹窗确认。

- ''key'' 有效时为无人值守运行（用于个人自动化）。

1. 安装并启动 OpenClaw.app。

2. 完成权限清单（TCC 授权弹窗）。

3. 确保启用 本机模式 且 Gateway 正在运行。

4. 若需要终端访问，再安装 CLI。

- ''cd apps/macos && swift build''

- ''swift run OpenClaw''（或使用 Xcode）

- 打包：''scripts/package-mac-app.sh''

使用 debug CLI 复现 macOS 应用使用的 Gateway WebSocket 握手与发现逻辑，而无需启动应用：

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

Connect 参数：

- ''--url <ws://host:port>'': override config

- ''--mode <local|remote>'': resolve from config (default: per-config or local)

- ''--probe''：强制进行一次新的健康探针

- ''--timeout <ms>'': request timeout (default ''15000'')

- ''--json''：结构化输出，方便 diff

Discovery 参数：

- ''--include-local''：包含本来会被过滤为 "local" 的 gateways

- ''--timeout <ms>'': overall discovery window (default ''2000'')

- ''--json''：结构化输出

提示：可以与 ''openclaw gateway discover --json'' 对比，判断 macOS 应用的发现管线（NWBrowser + tailnet DNS‑SD fallback）是否与 Node CLI 的 ''dns-sd'' 发现不同。

当 macOS 应用运行在 远程 模式时，它会打开 SSH 隧道，让本机 UI 组件像访问 localhost 一样访问远端 Gateway。

#

- 用途： 健康检查、状态、Web Chat、配置等控制面调用

- ''本地端口：'' Gateway 端口（默认 ''18789''），固定不变

- 远端端口： 远端主机上的同一 Gateway 端口

- 行为： 不使用随机本地端口；应用会复用健康的隧道或在需要时重启

- ''SSH form:'' ''ssh -N -L <local>:127.0.0.1:<remote>'', with BatchMode, ExitOnForwardFailure, keepalive enabled

- ''IP 观测：'' SSH 隧道走 loopback，gateway 会把节点 IP 视为 ''127.0.0.1''。若希望显示真实客户端 IP，请使用 ''Direct（ws/wss）'' 传输（见 ''macOS remote access''）。

设置步骤见 ''macOS remote access''。协议细节见 ''Gateway protocol''。

- ''Gateway runbook''

- ''Gateway（macOS）''

- ''macOS permissions''

- ''Canvas''