macOS App

OpenClaw macOS Companion (menu bar + gateway broker)

macOS 应用是 OpenClaw 的菜单栏 companion。它拥有权限、管理/本地附加到 Gateway（launchd 或手动），并将 macOS 能力作为节点暴露给 agent。

功能

• 在菜单栏中显示原生通知和状态
• 拥有 TCC 提示（Notifications、Accessibility、Screen Recording、Microphone、Speech Recognition、Automation/AppleScript）
• 运行或连接到 Gateway（本地或远程）
• 暴露 macOS 专用工具（Canvas、Camera、Screen Recording、system.run）
• 在 remote 模式下启动本地节点宿主服务（launchd），在 local 模式下停止它
• 可选托管 PeekabooBridge 用于 UI 自动化
• 根据请求通过 npm/pnpm 安装全局 CLI（openclaw）（不建议 Gateway runtime 使用 bun）

Local vs remote mode

• Local（默认）：应用附加到运行的本地 Gateway（如果存在）；否则通过 openclaw gateway install 启用 launchd 服务
• Remote：应用通过 SSH/Tailscale 连接到 Gateway，从不启动本地进程。应用启动本地节点宿主服务，以便远程 Gateway 可以访问此 Mac。应用不将 Gateway 作为子进程生成

Launchd control

应用管理每用户 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 未安装，从应用启用或运行 openclaw gateway install。

节点能力（mac）

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 映射，以便 agents 决定允许什么。

节点服务 + 应用 IPC：

• 当无头节点宿主服务运行时（remote 模式），它作为节点连接到 Gateway WS
• system.run 在 macOS 应用（UI/TCC 上下文）中通过本地 Unix socket 执行；提示 + 输出保留在应用中

图示（SCI）：

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

Exec approvals (system.run)

system.run 由 macOS 应用中的 Exec approvals 控制（Settings → Exec approvals）。 Security + ask + allowlist 本地存储在 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 命令文本被视为 allowlist miss，需要明确批准（或将 shell 二进制添加到 allowlist）
• 在提示中选择"Always Allow"会将该命令添加到 allowlist
• system.run 环境变量覆盖被过滤（删除 PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4），然后与应用的 environment 合并
• 对于 shell wrappers（bash|sh|zsh ... -c/-lc），请求范围的环境变量覆盖减少为小的显式 allowlist（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）
• 对于 allowlist 模式中的 allow-always 决策，已知的 dispatch wrappers（env、nice、nohup、stdbuf、timeout）持久化内部可执行路径而不是 wrapper 路径。如果解包不安全，则不会自动持久化 allowlist 条目

Deep links

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

openclaw://agent

触发 Gateway agent 请求。

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

查询参数：

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

安全：

• 没有 key，应用提示确认
• 没有 key，应用对确认提示强制执行短消息限制，并忽略 deliver / to / channel
• 使用有效 key，运行是无人值守的（用于个人自动化）

Onboarding flow (typical)

1. 安装并启动 OpenClaw.app
2. 完成 permissions checklist（TCC 提示）
3. 确保 Local 模式激活且 Gateway 正在运行
4. 如果你想要终端访问，安装 CLI

State dir placement (macOS)

避免将 OpenClaw state dir 放在 iCloud 或其他云同步文件夹中。 同步支持的路径可能会增加延迟，并偶尔导致会话和凭证的文件锁定/同步竞争。

首选本地非同步 state 路径，例如：

OPENCLAW_STATE_DIR=~/.openclaw

如果 openclaw doctor 检测到 state 位于：

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

它将警告并建议移回本地路径。

Build & dev workflow (native)

• cd apps/macos && swift build
• swift run OpenClaw（或 Xcode）
• Package app：scripts/package-mac-app.sh

Debug gateway connectivity (macOS CLI)

使用 debug CLI 来练习 macOS 应用使用的相同 Gateway WebSocket 握手和发现逻辑，而无需启动应用。

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

Connect options：

• --url <ws://host:port>：覆盖配置
• --mode <local|remote>：从配置解析（默认：配置或 local）
• --probe：强制新的 health probe
• --timeout <ms>：请求超时（默认：15000）
• --json：结构化输出用于 diffing

Discovery options：

• --include-local：包括将被过滤为"local"的 gateways
• --timeout <ms>：总体发现窗口（默认：2000）
• --json：结构化输出用于 diffing

提示：与 openclaw gateway discover --json 比较，查看 macOS 应用的发现管道（NWBrowser + tailnet DNS‑SD fallback）是否与 Node CLI 的 dns-sd 基础发现不同。

Remote connection plumbing (SSH tunnels)

当 macOS 应用在 Remote 模式下运行时，它打开 SSH 隧道，以便本地 UI 组件可以像本地一样与远程 Gateway 通信。

Control tunnel (Gateway WebSocket port)

• Purpose： health checks、status、Web Chat、config 和其他 control-plane calls
• Local port： Gateway 端口（默认 18789），始终稳定
• Remote port： 远程主机上的相同 Gateway 端口
• Behavior： 无随机本地端口；应用重用现有的健康隧道或在需要时重启它
• SSH shape： ssh -N -L <local>:127.0.0.1:<remote> 带 BatchMode + ExitOnForwardFailure + keepalive options
• IP reporting： SSH 隧道使用 loopback，因此 gateway 将看到节点 IP 为 127.0.0.1。如果你想显示真实客户端 IP，使用 Direct (ws/wss) transport（参见 macOS remote access）

设置步骤，参见 macOS remote access。协议详情，参见 Gateway protocol。

相关文档

• Gateway runbook
• Gateway (macOS)
• macOS permissions
• Canvas