打破沙盒: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 的桌面執行,而非你的筆電。