打破沙盒:OpenClaw 联动 AppleScript 控制 Mac 原生软件
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 |
| Automator | AppleScript 脆弱时的录制 UI | ~/Library/Services/Export-Keynote-PDF.workflow |
Apple 在AppleScript 语言指南中说明可脚本化应用。通过 System Events 做 GUI 脚本时,须在系统设置 → 隐私与安全性中为终端(或 osascript)开启辅助功能。
安全立场: 桥接脚本只应在专用自动化 Mac(或可一键抹除的 VM/会话)上运行。完整桌面控制 + 智能体 Shell 权限 ≈ 等同 root 的 UX 风险,与为 Worker 关闭沙箱同类。
决策矩阵:AppleScript vs Automator vs 仅 Shell
| 需求 | AppleScript | Automator 工作流 | Shell(仅 openclaw 工具) |
|---|---|---|---|
| Keynote 导出 PDF | 原生 export | 无 API 时录制菜单 | 否 |
| 音量 / 亮度 | System Events | 大材小用 | osascript 一行 |
| 不可脚本化 Electron 应用 | 脆弱 | 常更易(UI 录制) | 否 |
| 远程 Linux CI | 不适用 | 不适用 | 是 |
| 可审计、可版本化 | git 中的 .applescript | git 中的 .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 工作流(可选)
- 打开 Automator → 快速操作
- 录制:Keynote → 文件 → 导出为 → PDF(保存到
~/Documents/OpenClaw-Exports/) - 保存为
Export-Keynote-PDF.workflow于~/Library/Services/ - 测试:
automator ~/Library/Services/Export-Keynote-PDF.workflow
若你的 Keynote 版本 AppleScript 导出失败,用 openclaw-mac-bridge run-automator … 接入。
步骤 5 — 授予 macOS 隐私权限
- 系统设置 → 隐私与安全性 → 自动化 — 允许终端/iTerm(或
node)控制 Keynote - 辅助功能 — 为同一宿主允许
System Events亮度脚本 - 手动再跑一遍桥接并批准弹窗
步骤 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 的桌面执行,而非你的笔记本。