OpenClaw macOS 伴侣（菜单栏 + Gateway 管理）

macOS App 是 OpenClaw 的菜单栏伴侣。它负责权限管理，在本地管理/连接 Gateway（通过 launchd 或手动方式），并将 macOS 能力作为 Node 暴露给 Agent。

主要功能

• 在菜单栏显示原生通知和状态。
• 统一处理 TCC 弹框（通知、辅助功能、录屏、麦克风、语音识别、Automation/AppleScript）。
• 运行或连接 Gateway（本地或远程）。
• 暴露 macOS 专属工具（Canvas、摄像头、录屏、system.run）。
• 远程模式下启动本地 Node 宿主服务（通过 launchd），本地模式下停止该服务。
• 可选：托管 PeekabooBridge 用于 UI 自动化。
• 按需通过 npm/pnpm 安装全局 CLI（openclaw）（Gateway 运行时不推荐使用 bun）。

本地模式 vs 远程模式

• 本地模式（默认）：如果本地有运行中的 Gateway，App 会连接到它；否则通过 openclaw gateway install 启用 launchd 服务。
• 远程模式：App 通过 SSH/Tailscale 连接远程 Gateway，不在本地启动任何进程。App 会启动本地 Node 宿主服务，以便远程 Gateway 能够访问这台 Mac。App 不作为子进程生成 Gateway。

Launchd 控制

App 管理一个用户级 LaunchAgent，标签为 ai.openclaw.gateway（使用 --profile/OPENCLAW_PROFILE 时为 ai.openclaw.<profile>；旧版 com.openclaw.* 仍会被卸载）。

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

使用命名 profile 时，将标签替换为 ai.openclaw.<profile>。

如果 LaunchAgent 尚未安装，可从 App 中启用，或运行 openclaw gateway install。

Node 能力（macOS）

macOS App 以 Node 身份接入 Gateway。常用指令：

• Canvas：canvas.present、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.*
• 摄像头：camera.snap、camera.clip
• 录屏：screen.record
• 系统：system.run、system.notify

Node 会上报 permissions 映射，供 Agent 判断哪些操作被允许。

Node 服务 + App IPC：

• 无头 Node 宿主服务运行时（远程模式），它作为 Node 连接到 Gateway WebSocket。
• system.run 通过本地 Unix socket 在 macOS App（UI/TCC 上下文）中执行；授权弹框和输出均在 App 内处理。

架构图（SCI）：

Gateway -> Node Service (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac App (UI + TCC + system.run)

Exec 授权（system.run）

system.run 由 macOS App 中的 Exec 授权控制（设置 → Exec 授权）。安全策略、询问规则和白名单存储在 Mac 本地：

~/.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 模式。
• 含有 shell 控制或扩展语法（&&、||、;、|、`、$、<、>、(、)）的原始 shell 命令会被视为白名单未命中，需要显式授权（或将 shell 二进制加入白名单）。
• 在提示框中选择"始终允许"会将该命令添加到白名单。
• system.run 的环境变量覆盖会被过滤（丢弃 PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4），然后与 App 环境变量合并。
• 对于 shell 包装器（bash|sh|zsh ... -c/-lc），请求范围内的环境变量覆盖仅限于较小的显式白名单（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
• 对于白名单模式下的"始终允许"决策，已知的调度包装器（env、nice、nohup、stdbuf、timeout）会持久化内部可执行路径而非包装器路径。如果解包不安全，则不会自动持久化白名单条目。

深层链接

App 注册了 openclaw:// URL scheme 用于本地操作。

openclaw://agent

触发 Gateway agent 请求。

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

查询参数：

• message（必填）
• sessionKey（可选）
• thinking（可选）
• deliver / to / channel（可选）
• timeoutSeconds（可选）
• key（可选无人值守模式密钥）

安全性：

• 不提供 key 时，App 会弹出确认提示。
• 不提供 key 时，App 会限制确认提示中的消息长度，并忽略 deliver / to / channel。
• 提供有效 key 时，运行为无人值守模式（适用于个人自动化场景）。

引导流程（典型步骤）

1. 安装并启动 OpenClaw.app。
2. 完成权限检查清单（TCC 弹框授权）。
3. 确认本地模式已激活且 Gateway 正在运行。
4. 如需终端访问，安装 CLI。

状态目录位置（macOS）

避免将 OpenClaw 状态目录放在 iCloud 或其他云同步文件夹中。云同步路径可能增加延迟，偶尔会对会话和凭据造成文件锁/同步竞争问题。

推荐使用本地非同步路径，例如：

OPENCLAW_STATE_DIR=~/.openclaw

如果 openclaw doctor 检测到状态目录位于以下路径之下：

• ~/Library/Mobile Documents/com~apple~CloudDocs/...
• ~/Library/CloudStorage/...

它会发出警告并建议迁移回本地路径。

构建与开发工作流（原生）

• cd apps/macos && swift build
• swift run OpenClaw（或使用 Xcode）
• 打包 App：scripts/package-mac-app.sh

调试 Gateway 连接（macOS CLI）

使用调试 CLI 来测试与 macOS App 相同的 Gateway WebSocket 握手和发现逻辑，无需启动 App。

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

Connect 选项：

• --url <ws://host:port>：覆盖配置中的 URL
• --mode <local|remote>：从配置解析（默认：配置或本地）
• --probe：强制重新进行健康探测
• --timeout <ms>：请求超时（默认：15000）
• --json：结构化输出，便于 diff 对比

Discover 选项：

• --include-local：包含通常会被过滤为"本地"的 Gateway
• --timeout <ms>：整体发现窗口（默认：2000）
• --json：结构化输出，便于 diff 对比

提示：与 openclaw gateway discover --json 对比，可以看出 macOS App 的发现管道（NWBrowser + tailnet DNS-SD 回退）与 Node CLI 基于 dns-sd 的发现有何差异。

远程连接管道（SSH 隧道）

macOS App 在远程模式运行时，会建立 SSH 隧道，让本地 UI 组件可以像访问 localhost 一样访问远程 Gateway。

控制隧道（Gateway WebSocket 端口）

• 用途： 健康检查、状态、Web Chat、配置及其他控制平面调用。
• 本地端口： Gateway 端口（默认 18789），始终稳定。
• 远程端口： 远程主机上相同的 Gateway 端口。
• 行为： 不使用随机本地端口；App 会复用已有的健康隧道，或在需要时重启。
• SSH 形式： ssh -N -L <local>:127.0.0.1:<remote>，附带 BatchMode + ExitOnForwardFailure + keepalive 选项。
• IP 上报： SSH 隧道使用回环地址，因此 Gateway 会将 Node IP 看到为 127.0.0.1。如果希望真实客户端 IP 出现，请使用**直连（ws/wss）**传输方式（详见 macOS 远程访问）。

设置步骤详见 macOS 远程访问。协议细节详见 Gateway 协议。

相关文档

• Gateway 运行手册
• Gateway（macOS）
• macOS 权限
• Canvas