Moltbot macOS 配套应用（菜单栏 + 网关代理）

适用范围

在以下情况使用此页面：

• 实现 macOS 应用功能
• 更改 macOS 上的网关生命周期或节点桥接

macOS 应用是 Moltbot 的菜单栏配套应用。它拥有权限，在本地管理/附加到网关（launchd 或手动），并将 macOS 能力作为节点暴露给代理。

功能

• 在菜单栏中显示原生通知和状态。
• 拥有 TCC 提示（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）。
• 运行或连接到网关（本地或远程）。
• 暴露仅限 macOS 的工具（Canvas、相机、屏幕录制、system.run）。
• 在远程模式下启动本地节点主机服务（launchd），在本地模式下停止它。
• 可选择为 UI 自动化托管 PeekabooBridge。
• 根据请求通过 npm/pnpm 安装全局 CLI（moltbot）（出于网关运行时的考虑，不推荐 bun）。

本地 vs 远程模式

• 本地（默认）：如果存在运行的本地网关，应用会附加到它；否则通过 moltbot gateway install 启用 launchd 服务。
• 远程：应用通过 SSH/Tailscale 连接到网关，并且从不启动本地进程。 应用启动本地节点主机服务，以便远程网关可以到达此 Mac。 应用不会将网关作为子进程生成。

Launchd 控制

应用管理标记为 com.moltbot.gateway 的每用户 LaunchAgent（或在使用 --profile/MOLTBOT_PROFILE 时的 com.moltbot.<profile>）。

launchctl kickstart -k gui/$UID/com.moltbot.gateway
launchctl bootout gui/$UID/com.moltbot.gateway

运行命名配置文件时，将标签替换为 com.moltbot.<profile>。

如果未安装 LaunchAgent，请从应用中启用它或运行 moltbot 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 映射，以便代理可以决定允许什么。

节点服务 + 应用 IPC：

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

图表（SCI）：

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

执行批准（system.run）

system.run 由 macOS 应用中的执行批准控制（设置 → 执行批准）。 安全 + 询问 + 允许列表存储在 Mac 上的本地：

~/.moltbot/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 模式。
• 在提示中选择"始终允许"会将该命令添加到允许列表。
• system.run 环境覆盖被过滤（删除 PATH、DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT），然后与应用的环境合并。

深度链接

应用为本地操作注册 moltbot:// URL 方案。

moltbot://agent

触发网关 agent 请求。

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

查询参数：

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

安全：

• 没有 key，应用会提示确认。
• 使用有效的 key，运行是无人值守的（旨在用于个人自动化）。

配置流程（典型）

1. 安装并启动 Moltbot.app。
2. 完成权限检查清单（TCC 提示）。
3. 确保本地模式处于活动状态并且网关正在运行。
4. 如果需要终端访问，请安装 CLI。

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

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

调试网关连接（macOS CLI）

使用调试 CLI 来执行与 macOS 应用相同的网关 WebSocket 握手和发现逻辑，而无需启动应用。

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

连接选项：

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

发现选项：

• --include-local：包括会被过滤为"本地"的网关
• --timeout <ms>：整个发现窗口（默认：2000）
• --json：用于比较的结构化输出

提示：与 moltbot gateway discover --json 进行比较，以查看 macOS 应用的发现管道（NWBrowser + tailnet DNS-SD 后备）是否与 Node CLI 的基于 dns-sd 的发现不同。

远程连接管道（SSH 隧道）

当 macOS 应用在远程模式下运行时，它会打开一个 SSH 隧道，以便本地 UI 组件可以与远程网关通信，就像它在 localhost 上一样。

控制隧道（网关 WebSocket 端口）

• 目的： 健康检查、状态、Web 聊天、配置和其他控制平面调用。
• 本地端口： 网关端口（默认 18789），始终稳定。
• 远程端口： 远程主机上的同一网关端口。
• 行为： 没有随机本地端口；应用重用现有的健康隧道或在需要时重新启动它。
• SSH 形状： ssh -N -L <local>:127.0.0.1:<remote> 配置 BatchMode + ExitOnForwardFailure + keepalive 选项。
• IP 报告： SSH 隧道使用环回，因此网关会将节点 IP 视为 127.0.0.1。如果你希望显示真实的客户端 IP，请使用**直接（ws/wss）**传输（参见 macOS 远程访问）。

有关设置步骤，请参见 macOS 远程访问。有关协议详细信息，请参见 网关协议。

相关文档

• 网关运维手册
• 网关（macOS）
• macOS 权限
• Canvas