AI 自动化

打破沙盒:OpenClaw 联动 AppleScript 控制 Mac 原生软件

OpenClaw 联动 AppleScript macOS 桌面自动化 2026
披露: KuzCloud 发布 Mac 托管相关指南;本文为技术文档。OpenClaw 为第三方开源项目 — 见 openclaw.dev。
速览: 多数 OpenClaw 部署止步于终端里的文本与 Shell。在 macOS 上,可将 OpenClaw 技能(SKILL.md)与调用 osascript(AppleScript)或启动 Automator 工作流的桥接脚本配对,为智能体赋予实体桌面能力:打开 Keynote、导出 PDF、调节音量或降低亮度,而聊天触发仍走网关。需预期 TCC 权限(辅助功能 / 自动化),并将完整 GUI 控制视为高权限操作。

为何纯文本 OpenClaw 浪费了 macOS 能力

OpenClaw 擅长仓库、CI 钩子与多智能体扇出。在 Mac mini 或 MacBook 上,同一守护进程常通过 SSH 无头运行:改文件、跑 npm test,却从不碰邮件、Keynote、音乐或系统设置。

当你的流程是运营向而非纯开发向时,缺口很明显:

  • 干系人在团队频道说「导出 deck v3 PDF」
  • 录屏分享前要把亮度调低
  • 夜间任务要归档幻灯片,不能手动点 UI

macOS 自带胶水:AppleScript 对话可脚本化应用;Automator 把可重复的 UI 宏打成可从 Shell 触发的 .workflow。OpenClaw 的技能系统是第三根支柱:模型被允许调用的、有文档的工具。三者连通后,智能体不再是沙箱里的聊天机器人,而是能动手操作桌面的本地管家。

本文假定已安装 OpenClaw(安装参考),聚焦桌面自动化,不展开编排理论。

架构:网关 → 技能 → 桥接 → AppleScript / Automator

一句话数据流:频道消息 → OpenClaw 网关 → 技能处理 → /usr/local/bin/openclaw-mac-bridge → osascript 或 automator → 原生应用或 System Events。

层级职责典型路径
网关将聊天/Webhook 路由到智能体openclaw 守护进程
技能(SKILL.md)记录参数、安全规则、示例~/.openclaw/skills/mac-desktop/SKILL.md
桥接(bash)校验输入、写日志、调用 macOS~/bin/openclaw-mac-bridge
AppleScript应用动词(Keynote、Finder)内联或 ~/Scripts/*.applescript
AutomatorAppleScript 脆弱时的录制 UI~/Library/Services/Export-Keynote-PDF.workflow

Apple 在AppleScript 语言指南中说明可脚本化应用。通过 System Events 做 GUI 脚本时,须在系统设置 → 隐私与安全性中为终端(或 osascript)开启辅助功能。

安全立场: 桥接脚本只应在专用自动化 Mac(或可一键抹除的 VM/会话)上运行。完整桌面控制 + 智能体 Shell 权限 ≈ 等同 root 的 UX 风险,与为 Worker 关闭沙箱同类。

决策矩阵:AppleScript vs Automator vs 仅 Shell

需求AppleScriptAutomator 工作流Shell(仅 openclaw 工具)
Keynote 导出 PDF原生 export无 API 时录制菜单否
音量 / 亮度System Events大材小用osascript 一行
不可脚本化 Electron 应用脆弱常更易(UI 录制)否
远程 Linux CI不适用不适用是
可审计、可版本化git 中的 .applescriptgit 中的 .workflow仅 SKILL.md
无头 SSH Mac需已登录 GUI 会话需图形会话可用

规则: 应用词典有动词时优先 AppleScript;仅菜单栏操作回退 Automator;文件/Git 任务保留 Shell。

分步 Runbook:桥接 + SKILL.md + 三类操作

步骤 1 — 创建桥接脚本

保存为 ~/bin/openclaw-mac-bridge 并 chmod +x:

#!/usr/bin/env bash set -euo pipefail ACTION="${1:-}"; shift || true LOG="${HOME}/.openclaw/logs/mac-bridge.log" mkdir -p "$(dirname "$LOG")" log() { printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$*" >>"$LOG"; } case "$ACTION" in keynote-export-pdf) DECK="${1:?path to .key required}" OUT="${2:?output .pdf path required}" osascript <<EOF tell application "Keynote" activate open POSIX file "$DECK" delay 2 export front document to POSIX file "$OUT" as PDF close front document saving no end tell EOF log "keynote-export-pdf OK $OUT" ;; set-volume) PCT="${1:?0-100}" osascript -e "set volume output volume $PCT" log "set-volume $PCT" ;; set-brightness) PCT="${1:?0-100}" osascript <<EOF tell application "System Events" tell appearance preferences set brightness to ($PCT / 100) end tell end tell EOF log "set-brightness $PCT" ;; run-automator) WF="${1:?workflow path required}" automator "$WF" log "run-automator $WF" ;; *) echo "Usage: openclaw-mac-bridge {keynote-export-pdf|set-volume|set-brightness|run-automator} ..." >&2 exit 2 ;; esac

Apple Silicon macOS 14+ 上,通过 appearance preferences 调亮度可能需要已登录的 GUI 会话;接入聊天前先本地测试。

步骤 2 — 编写 mac-desktop 的 SKILL.md

路径:~/.openclaw/skills/mac-desktop/SKILL.md(按你的 OpenClaw 技能根目录调整):

# mac-desktop Control this Mac's GUI via openclaw-mac-bridge. Only run actions the user explicitly requested. ## Commands - keynote-export-pdf <path.key> <out.pdf> - set-volume <0-100> - set-brightness <0-100> - run-automator <path.workflow> ## Safety - Never export to paths outside ~/Documents/OpenClaw-Exports/ - Refuse destructive Finder/ Mail actions unless user names the target file

在智能体配置中注册技能(因版本而异 — 在 openclaw.json 中仿照现有 skills: ["git", "nodejs"] 条目)。

步骤 3 — 在工具策略中允许桥接

若编排器使用沙箱 Worker,仅给编排器智能体开桌面技能,并对该 agent ID 设 sandbox.mode: off。只改代码的 Worker 不应获得 mac-desktop。

步骤 4 — 构建 Automator 工作流(可选)

  1. 打开 Automator → 快速操作
  2. 录制:Keynote → 文件 → 导出为 → PDF(保存到 ~/Documents/OpenClaw-Exports/)
  3. 保存为 Export-Keynote-PDF.workflow 于 ~/Library/Services/
  4. 测试:automator ~/Library/Services/Export-Keynote-PDF.workflow

若你的 Keynote 版本 AppleScript 导出失败,用 openclaw-mac-bridge run-automator … 接入。

步骤 5 — 授予 macOS 隐私权限

  1. 系统设置 → 隐私与安全性 → 自动化 — 允许终端/iTerm(或 node)控制 Keynote
  2. 辅助功能 — 为同一宿主允许 System Events 亮度脚本
  3. 手动再跑一遍桥接并批准弹窗

步骤 6 — 挂钩聊天触发(概念示例)

在频道规则(Discord/Telegram/Webhook)中映射短语到编排任务:

When message matches ^/deck pdf (.+)$, call mac-desktop keynote-export-pdf with captured path.

具体挂钩语法取决于 OpenClaw 频道插件 — 视为编排器系统提示 + 允许的工具,而非魔法路由。

步骤 7 — 用 openclaw doctor 与干跑验证

openclaw doctor ~/bin/openclaw-mac-bridge set-volume 25 ~/bin/openclaw-mac-bridge keynote-export-pdf "$HOME/Desktop/demo.key" "$HOME/Documents/OpenClaw-Exports/demo.pdf"

确认 PDF 字节与 ~/.openclaw/logs/mac-bridge.log 日志行。

步骤 8 — 生产护栏

  • 专用用户 automation,钥匙串仅放 Keynote 相关项
  • 限速:每频道每小时最多 6 次 GUI 操作
  • 白名单:~/Documents/Decks/ 下的 deck 路径
  • 数据库/API 用 MCP 工具;GUI 仅留在 mac-desktop 技能

故障排查

错误:execution error: Not authorized to send Apple events to Keynote

特征: osascript 标准错误出现 (-1743) 或 “Not authorized”。

修复: 系统设置 → 隐私与安全性 → 自动化 → 为你的终端应用启用 Keynote。无头 SSH 时,通过屏幕共享会话跑一次桥接以弹出授权。

错误:System Events got an error: Can’t set brightness

特征: 音量成功、亮度失败。

修复: 为终端授予辅助功能;确保已登录 GUI 会话(非无控制台的 launchd)。回退:用 Automator「更改亮度」代替 AppleScript。

场景 A — 群聊「把 PDF 发出来」

团队机器人听到:「给投资人会议导出 keynote」。编排器解析 deck 名,调用 keynote-export-pdf,经独立文件工具上传 PDF,回复 SHA256 与路径。延迟: M4 上 40 页 deck 约 8–15 秒(磁盘 + Keynote 冷启动)。内存: Keynote 峰值约 400–900 MB — 16 GB 上单 OpenClaw 守护进程可接受;勿在同一 GUI 主机上并行扇出。

场景 B — 录制前环境重置

OBS 录制前,智能体执行 set-volume 35、set-brightness 60,再启动 Automator 隐藏菜单栏 extras。注意: 这些是全局变更 — 在同一会话中记录回滚(如 set-volume 70)。

若你…建议
只需文件/Git/CI跳过 GUI 技能,继续用 Shell 工具
需要 Keynote/Pages/Finder编排器上的 AppleScript 桥接 + SKILL.md
应用无词典Automator + run-automator
在远程 Mac 跑智能体保持持久 GUI 登录;见远程 OpenClaw 配置
需要 3+ 并行智能体不要共享同一 GUI 会话 — 串行 mac-desktop 调用

常见问题

OpenClaw 能在无头 SSH 会话里跑 AppleScript 吗?

仅当 macOS 为目标用户存在活跃的 WindowServer 会话(屏幕共享登录或本地控制台)。纯 SSH 无 GUI 登录时,Keynote 与 System Events UI 脚本会失败。

这与 OpenClaw 多智能体编排有何不同?

多智能体编排拆分推理 Worker。桌面自动化是单主机高权限工具 — 只在一个编排器上运行,勿扇出三个 Coder 同时点 Keynote。

AppleScript 适合生产吗?

它能力强,并非默认安全。将 mac-desktop 当作生产 Shell:白名单、日志、专用 Mac,同一用户会话中不放个人邮箱。

能与 Claude Code 或 Copilot CLI 一起用吗?

这些 CLI 不带 OpenClaw 技能路由。可从 Shell 工具复用同一桥接脚本,但会失去集中频道路由 — 选型见基准对比。

大陆网络环境怎么办?

国内开发者常把网关放在稳定的远程 Mac 上,使 npm/API 路由更一致(出口带宽有限时尤甚)— 与OpenClaw 远程部署同模式。AppleScript 仍在该 Mac 的桌面执行,而非你的笔记本。

相关指南

在把桌面技能接入生产聊天触发前,可先阅读多智能体编排与远程 Mac 部署指南。