Skip to main content

​
OpenClaw macOS 伴随应用（菜单栏 + 网关代理）

macOS 应用是 OpenClaw 的菜单栏伴随。它拥有权限，管理/连接本地网关（通过 launchd 或手动启动），并将 macOS 功能作为节点暴露给代理。

​
功能介绍

  • 在菜单栏显示原生通知和状态
  • 管理 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）
  • 运行或连接网关（本地或远程）
  • 暴露 macOS 独有工具（Canvas、相机、屏幕录制、system.run）
  • 在远程模式下启动本地节点主机服务
  • 可选托管 PeekabooBridge 用于 UI 自动化
  • 可按需通过 npm/pnpm 安装全局 CLI

​
本地模式与远程模式

​
本地模式（默认）

  • 应用附加到本地网关（如果存在）
  • 否则通过 openclaw gateway install 启用 launchd 服务

​
远程模式

  • 应用通过 SSH/Tailscale 连接远程网关
  • 始终不启动本地进程
  • 启动本地节点主机服务，以便远程网关能够访问此 Mac

​
Launchd 控制

应用管理每用户级的 LaunchAgent，标签为 ai.openclaw.gateway。 
launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway
如果未安装 LaunchAgent，可从应用启用或运行： 
openclaw gateway install

​
节点功能 (macOS)

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

​
执行批准 (system.run)

system.run 由 macOS 应用中的执行批准控制。 安全策略、请求提示和允许列表本地存储于： 
~/.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" }]
    }
  }
}

​
深层链接

应用注册了 openclaw:// URL 方案，用于本地操作。

​
openclaw://agent

触发网关的 agent 请求。 
open 'openclaw://agent?message=Hello%20from%20deep%20link'
查询参数：
  • message（必需）
  • sessionKey（可选）
  • thinking（可选）
  • deliver / to / channel（可选）
  • timeoutSeconds（可选）
  • key（可选，无人值守模式密钥）
安全性：
  • 无 key 时，应用会提示确认
  • 携带有效 key 时，运行无人值守

​
新手流程

  1. 安装并启动 OpenClaw.app
  2. 完成权限清单（TCC 提示）
  3. 确保处于本地模式且网关正在运行
  4. 需要终端访问时，安装 CLI

​
状态目录路径位置 (macOS)

避免将 OpenClaw 状态目录存放在 iCloud 或其他云同步文件夹中。 推荐使用本地非同步状态路径： 
OPENCLAW_STATE_DIR=~/.openclaw
如果 openclaw doctor 检测到状态路径在云盘中，将发出警告。

​
构建与开发流程

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

​
调试网关连接

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

​
远程连接流程 (SSH 隧道)

当 macOS 应用运行在远程模式时，会打开 SSH 隧道。

​
控制隧道（网关 WebSocket 端口）

  • 目的：健康检查、状态、网页聊天、配置
  • 本地端口：网关端口（默认 18789）
  • 远程端口：远程主机上的相同网关端口
设置步骤请见 macOS 远程访问。

​
相关文档