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

macOS 应用是 OpenClaw 的菜单栏伴侣。它持有权限、管理/连接本地 Gateway（launchd 或手动），并作为节点向 agent 暴露 macOS 能力。

功能概述

  • 在菜单栏显示原生通知和状态。
  • 持有 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音识别、Automation/AppleScript）。
  • 运行或连接 Gateway（本地或远程）。
  • 暴露 macOS 专有工具（Canvas、相机、屏幕录制、system.run）。
  • 在 remote 模式下启动本地节点 host 服务（launchd），local 模式下则停止。
  • 可选托管 PeekabooBridge 做 UI 自动化。
  • 应请求通过 npm/pnpm 安装全局 CLI（openclaw）（不建议用 bun 运行 Gateway）。

Local 与 Remote 模式

  • Local（默认）：应用连接已在运行的本地 Gateway；如果没有则通过 openclaw gateway install 启用 launchd 服务。
  • Remote：应用通过 SSH/Tailscale 连接远程 Gateway，不启动本地进程。 应用启动本地节点 host 服务以便远程 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

使用命名 profile 时把标签换成 ai.openclaw.<profile>。

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

节点能力（mac）

macOS 应用以节点身份展示自己。常用命令：

  • Canvas：canvas.present、canvas.navigate、canvas.eval、canvas.snapshot、canvas.a2ui.*
  • 相机：camera.snap、camera.clip
  • 屏幕：screen.record
  • 系统：system.run、system.notify

节点上报 permissions 映射，agent 据此判断可用操作。

节点服务 + 应用 IPC：

  • 无界面节点 host 服务运行时（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)

执行审批（system.run）

system.run 由 macOS 应用中的 Exec approvals 控制（Settings → Exec approvals）。 安全策略、询问模式和允许列表存储在 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 二进制）。
  • 在提示中选择 “Always Allow” 会将该命令加入允许列表。
  • 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）。
  • 在允许列表模式下做 always-allow 决定时，已知的调度包装器（env、nice、nohup、stdbuf、timeout）会持久化内部可执行文件路径而非包装器路径。如果解包不安全，则不自动持久化允许列表条目。

应用注册了 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 时，运行为无人值守模式（用于个人自动化）。

引导流程（典型）

  1. 安装并启动 OpenClaw.app。
  2. 完成权限清单（TCC 提示）。
  3. 确保 Local 模式已启用且 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）
  • 打包应用：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

Connect 选项：

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

Discovery 选项：

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

提示：与 openclaw gateway discover --json 比较，看 macOS 应用的发现管线（NWBrowser + tailnet DNS-SD 回退）是否与 Node CLI 基于 dns-sd 的发现有差异。

远程连接管道（SSH 隧道）

macOS 应用在 Remote 模式下会打开 SSH 隧道，让本地 UI 组件能像访问 localhost 一样与远程 Gateway 通信。

控制隧道（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，使用 Direct (ws/wss) 传输方式（见 macOS 远程访问）。

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

相关文档

arrow_back
上一页
Platforms
下一页
Linux
arrow_forward