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 部署指南。