OpenClaw AppleScript Mac Automation 2026: Control Native Apps from Your Agent
SKILL.md) with a small bridge script that calls osascript (AppleScript) or launches Automator workflows. The agent can then open Keynote, export a PDF, nudge system volume, or dim the display—while chat triggers stay in the gateway. Expect TCC prompts (Accessibility / Automation) and treat full GUI control as high privilege.
Why Text-Only OpenClaw Leaves macOS Power on the Table
OpenClaw excels at repos, CI hooks, and multi-agent fan-out. On a Mac mini or MacBook, the same daemon often runs headless over SSH: it edits files and runs npm test, but never touches Mail, Keynote, Music, or System Settings.
That gap matters when your workflow is operator-shaped, not developer-shaped:
- A stakeholder drops “export deck v3 PDF” in a team channel
- You want brightness lowered before a screen-share recording
- A nightly job should archive slides without you touching the UI
macOS already ships the glue: AppleScript talks to scriptable apps; Automator packages repeatable UI macros as .workflow files you can fire from the shell. OpenClaw’s skill system is the third leg: documented tools the model is allowed to call. Wire them together and the agent stops being a chatbot in a sandbox—it becomes a local concierge with hands on the desktop.
This guide assumes OpenClaw is installed (setup reference). We focus on desktop automation, not orchestration theory.
Architecture: Gateway → Skill → Bridge → AppleScript / Automator
Data flow in one sentence: channel message → OpenClaw gateway → skill handler → /usr/local/bin/openclaw-mac-bridge → osascript or automator → native app or System Events.
| Layer | Responsibility | Typical path |
|---|---|---|
| Gateway | Routes chat/webhook to an agent | openclaw daemon |
Skill (SKILL.md) | Documents args, safety rules, examples | ~/.openclaw/skills/mac-desktop/SKILL.md |
| Bridge (bash) | Validates input, logs, calls macOS | ~/bin/openclaw-mac-bridge |
| AppleScript | App verbs (Keynote, Finder) | inline or ~/Scripts/*.applescript |
| Automator | Recorded UI when AppleScript is brittle | ~/Library/Services/Export-Keynote-PDF.workflow |
Apple documents scriptable apps in the AppleScript Language Guide. For GUI scripting via System Events, you need Accessibility permission for the terminal (or osascript) in System Settings → Privacy & Security.
Security stance: Run bridge scripts only on a dedicated automation Mac (or a VM/session you can wipe). Full desktop control plus agent shell access equals root-equivalent UX—same class of risk as disabling sandbox for workers.
Decision Matrix: AppleScript vs Automator vs Shell Only
| Need | AppleScript | Automator workflow | Shell (openclaw tools only) |
|---|---|---|---|
| Keynote export PDF | Native export command | Record menu clicks if API missing | No |
| Volume / brightness | System Events | Overkill | osascript one-liner |
| Non-scriptable Electron app | Fragile | Often easier (UI recording) | No |
| CI on Linux remote | N/A | N/A | Yes |
| Auditable, versioned | .applescript in git | .workflow bundle in git | SKILL.md only |
| Headless SSH Mac | Works if GUI session logged in | Needs graphical session | Works |
Rule: Prefer AppleScript when the app dictionary exposes the verb; fall back to Automator for menu-bar-only actions; keep shell for file/git tasks.
Step-by-Step Runbook: Bridge + SKILL.md + Three Actions
Step 1 — Create the bridge script
Save as ~/bin/openclaw-mac-bridge and 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
On Apple Silicon macOS 14+, brightness via appearance preferences may require a logged-in GUI session; test locally before wiring to chat.
Step 2 — Author SKILL.md for the mac-desktop skill
Path: ~/.openclaw/skills/mac-desktop/SKILL.md (adjust to your OpenClaw skills root):
# 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
Register the skill in agent config (pattern varies by release—mirror your existing skills: ["git", "nodejs"] entries in openclaw.json).
Step 3 — Allow the bridge in agent tool policy
If your orchestrator uses sandboxed workers, keep desktop skill on the orchestrator agent only with sandbox.mode: off for that agent ID. Workers that only edit code should not receive mac-desktop.
Step 4 — Build an Automator workflow (optional)
- Open Automator → Quick Action
- Record: Keynote → File → Export To → PDF (save to
~/Documents/OpenClaw-Exports/) - Save as
Export-Keynote-PDF.workflowunder~/Library/Services/ - Test:
automator ~/Library/Services/Export-Keynote-PDF.workflow
Wire via openclaw-mac-bridge run-automator … when AppleScript export fails on your Keynote version.
Step 5 — Grant macOS privacy permissions
- System Settings → Privacy & Security → Automation — allow Terminal/iTerm (or
node) to control Keynote - Accessibility — allow the same host for
System Eventsbrightness scripts - Re-run bridge manually once; approve prompts
Step 6 — Hook a chat trigger (conceptual)
In your channel rules (Discord/Telegram/webhook), map a phrase to an orchestrator task:
When message matches ^/deck pdf (.+)$, call mac-desktop keynote-export-pdf with captured path.
Exact hook syntax depends on OpenClaw channel plugins—treat this as orchestrator system prompt + allowed tools, not magic routing.
Step 7 — Verify with openclaw doctor and a dry run
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"
Confirm PDF bytes and log lines in ~/.openclaw/logs/mac-bridge.log.
Step 8 — Production guardrails
- Dedicated user account
automationwith login keychain items for Keynote only - Rate limit: max 6 GUI actions/hour per channel
- Allowlist deck paths under
~/Documents/Decks/ - Pair with MCP tools for DB/API; keep GUI on mac-desktop skill only
Troubleshooting
Error: execution error: Not authorized to send Apple events to Keynote
Pattern: (-1743) or “Not authorized” in osascript stderr.
Fix: System Settings → Privacy & Security → Automation → enable your terminal app → Keynote. Re-run bridge; if headless SSH, run once from Screen Sharing session so prompts appear.
Error: System Events got an error: Can’t set brightness
Pattern: script succeeds for volume but fails on brightness.
Fix: Grant Accessibility to Terminal; ensure a logged-in GUI session (not launchd without console). Fallback: use Automator “Change brightness” action instead of AppleScript.
Scenario A — Group Chat “Ship the PDF”
Your team bot hears: “export keynote for investor call.” The orchestrator parses the deck name, calls keynote-export-pdf, uploads the PDF via a separate file tool, and replies with SHA256 + path. Latency: ~8–15 s for a 40-slide deck on M4 (disk + Keynote cold start). RAM: Keynote adds ~400–900 MB peak—fine beside a single OpenClaw daemon on 16 GB; avoid parallel fan-out on the same GUI host.
Scenario B — Pre-Recording Environment Reset
Before OBS capture, the agent runs set-volume 35 and set-brightness 60, then launches Automator to hide menu bar extras. Implication: These are global changes—document rollback (set-volume 70) in the same skill session.
Recommended Path
| If you… | Do this |
|---|---|
| Only need files/git/CI | Skip GUI skills; stay with shell tools |
| Need Keynote/Pages/Finder | AppleScript bridge + SKILL.md on orchestrator agent |
| App has no dictionary | Automator workflow + run-automator |
| Run agent on remote Mac | Ensure persistent GUI login; see remote OpenClaw setup |
| Need 3+ parallel agents | Do not share one GUI session—serialize mac-desktop calls |
FAQ
Can OpenClaw run AppleScript on a headless SSH session?
Only if macOS has an active WindowServer session for the target user (Screen Sharing login, or local console). Pure SSH without GUI login fails for Keynote and System Events UI scripting.
How is this different from OpenClaw multi-agent orchestration?
Multi-agent orchestration splits reasoning workers. Desktop automation is a single-host privilege tool—run it on one orchestrator, not fan-out to three coders hitting Keynote simultaneously.
Is AppleScript safe for production?
It is powerful, not safe-by-default. Treat mac-desktop like production shell: allowlists, logging, dedicated Mac, no personal email in the same user session.
Does this work with Claude Code or Copilot CLI?
Those CLIs do not ship OpenClaw’s skill router. You can reuse the same bridge script from a shell tool, but you lose centralized channel routing—see benchmark comparison for when to pick each stack.
What about mainland China network constraints?
Developers in CN often run the gateway on a stable remote Mac so npm/API routes stay consistent—same pattern as OpenClaw remote setup. AppleScript still executes on that Mac’s desktop, not on your laptop.
Related guides
Continue with multi-agent orchestration and remote Mac setup before wiring desktop skills to production chat triggers.