OpenClaw macOS 配套应用（菜单栏 + Gateway 代理）

macOS 应用?OpenClaw ?菜单栏配套应?。它负责权限管理? 在本地管?连接 Gateway（launchd 或手动），并?macOS 功能作为节点暴露给代理?

功能

  • 在菜单栏显示原生通知和状态?
  • 负责 TCC 提示（通知、辅助功能、屏幕录制、麦克风? 语音识别、自动化/AppleScript）?
  • 运行或连?Gateway（本地或远程）?
  • 暴露 macOS 专属工具（Canvas、Camera、屏幕录制、system.run）?
  • ?*远程模式启动本地节点主机服务（launchd），并在本地**模式下停止它?
  • 可选托?PeekabooBridge 用于 UI 自动化?
  • 按需通过 npm/pnpm 安装全局 CLI（openclaw）（不推荐将 bun 用于 Gateway 运行时）?

本地 vs 远程模式

  • 本地（默认）：如果存在已运行的本?Gateway，应用会连接它； 否则通过 openclaw gateway install 启用 launchd 服务?
  • 远程：应用通过 SSH/Tailscale 连接?Gateway，从不启? 本地进程? 应用启动本地节点主机服务，以便远?Gateway 可以访问?Mac? 应用不会?Gateway 作为子进程启动?

Launchd 控制

应用管理一个每个用户的 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

运行命名配置文件时将标签替换?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 映射，以便代理决定允许的内容?

节点服务 + 应用 IPC?

  • 当无头节点主机服务正在运行时（远程模式），它作为节点连接?Gateway WebSocket?
  • system.run 通过本地 Unix _socket ?macOS 应用（UI/TCC 上下文）中执行；提示和输出保留在应用内?

流程图（SCI）：

Gateway -> 节点服务 (WS)
                 |  IPC (UDS + token + HMAC + TTL)
                 v
             Mac 应用 (UI + TCC + system.run)

执行批准（system.run?

system.run ?macOS 应用中的执行批准控制（设??执行批准）? 安全 + 询问 + 白名单存储在 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），然后与应用的环境合并?
  • 对于 shell 包装器（bash|sh|zsh ... -c/-lc），请求作用域的环境覆盖会缩减为明确的白名单（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）?
  • 对于白名单模式中?始终允许”决策，已知的调度包装器（env、nice、nohup、stdbuf、timeout）会保留内部可执行文件路径而非包装器路径。如果无法安全展开，则不会自动保留白名单条目?

深度链接

应用注册?openclaw:// URL 方案用于本地操作?

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 流程

  1. 安装并启?OpenClaw.app?
  2. 完成权限检查列表（TCC 提示）?
  3. 确保本地模式处于活动状态且 Gateway 正在运行?
  4. 如果需要终端访问，则安?CLI?

构建和开发工作流程（原生?

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

调试 Gateway 连接性（macOS CLI?

使用 debug CLI 练习?macOS 应用相同?Gateway WebSocket 握手和发? 逻辑，无需启动应用?

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

连接选项?

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

发现选项?

  • --include-local：包含会被过滤为”本地”?Gateway
  • --timeout <ms>：总体发现窗口（默认：2000?
  • --json：结构化输出用于对比

提示：与 openclaw gateway discover --json 对比，看? macOS 应用的发现管道（NWBrowser + tailnet DNS-SD 后备）与 Node CLI ?dns-sd 基于的发现有何不同?

远程连接管道（SSH 隧道?

?macOS 应用?*远程**模式运行时，它会打开 SSH 隧道，以便本?UI 组件可以与远?Gateway 通信，就像它?localhost 上一样?

控制隧道（Gateway WebSocket 端口?

  • 用途： 健康检查、状态、Web Chat、配置及其他控制平面调用?
  • *本地端口? Gateway 端口（默?18789），始终稳定?
  • *远程端口? 远程主机上的相同 Gateway 端口?
  • *行为? 无随机本地端口；应用重用现有健康隧道 或在需要时重新启动它?
  • *SSH 形式? ssh -N -L <local>:127.0.0.1:<remote>，带 BatchMode + ExitOnForwardFailure + keepalive 选项?
  • *IP 报告? SSH 隧道使用 loopback，因?Gateway 会将节点 IP 视为 127.0.0.1。如果您希望显示真实客户? IP，请使用**直连（ws/wss?*传输（请参阅 macOS 远程访问）?

设置步骤请参?macOS 远程访问。协? 详情请参?Gateway 协议?

相关文档