macos-suite

macOS 本地应用对接技能（偏安全、可扩展）。通过 AppleScript / UI 自动化（System Events）/ URL Scheme / open 命令实现对系统应用的打开、读取与常用动作。

规范符合性（官方）

• - Skill 目录以 SKILL.md 为核心（YAML frontmatter + 说明），并使用 metadata 单行 JSON 进行 gating（仅 darwin、需要 python3/osascript）。参见 OpenClaw 官方 Skills 规范：https://docs.openclaw.ai/tools/skills
• ClawHub 发布/安装以文件 bundle + metadata进行版本化管理，核心仍是 SKILL.md。参见官方 ClawHub 文档：https://docs.openclaw.ai/tools/clawhub

⚠️ 安全与权限

• - 本技能会触发本机应用自动化：首次调用可能弹出允许控制某某应用的系统授权提示。
• 读取类操作不需要 confirm=YES，但可能触发系统隐私授权（例如 Mail/Notes/Reminders/Calendar/Photos）。
• 修改型操作默认需要显式确认参数（否则拒绝执行）：

- mail.send / calendar.add / reminders.add / notes.create - freeform.*（绘图/排版通过 UI 自动化，会修改画板内容）

• - 若缺少 confirm=YES，命令会返回 needsConfirm=true 的 JSON，提示用户确认并给出只读替代命令（agent 应转述并向用户发起确认）。
• Freeform 的 UI 自动化需要系统开启辅助功能/自动化权限；若被拦截，命令返回 JSON 中会包含 hint 指引路径。

常见问题（权限与故障排查）

1) 首次调用弹权限框/被拒绝

在系统设置 -> 隐私与安全性中检查：

• - 自动化：允许你运行脚本的宿主程序（例如 Terminal / iTerm / OpenClaw）控制 System Events，并允许控制 Mail/Calendar/Reminders/Notes/Freeform 等目标应用
• 辅助功能：如使用 Freeform 绘图/排版（UI 自动化），需要允许 Terminal/osascript 等具备辅助功能
• 日历/提醒事项/照片/通讯录/文件与文件夹：对应读取类能力若失败，通常是未授权导致

如果命令返回中出现 osascript 的 not allowed to send keystrokes / 不允许发送按键 (1002)，就是辅助功能未开启。

2) Freeform 绘图/排版没反应或报错

Freeform 的绘图/排版命令依赖 UI 自动化（点击菜单 + 粘贴内容），请确认：

• - Freeform 已能正常打开并在前台
• 你运行脚本的宿主程序已授予辅助功能与自动化权限

建议先跑一个最小验证：

bash
python3 {baseDir}/scripts/main.py freeform.add_shape kind=rectangle confirm=YES

3) Reminders 读取不稳定

部分系统版本/隐私设置下 Reminders 的 AppleScript 读取会失败。此时建议启用 Shortcuts 兜底（见下方Shortcuts 兜底章节）。

使用方式

从 OpenClaw workspace 运行：

bash
python3 {baseDir}/scripts/main.py key=value key=value ...

输出为 JSON（便于 agent 解析）。

Commands（摘要）

只读类：

• - mail.unreadcount / mail.unreadlist
• calendar.today / calendar.list
• reminders.lists / reminders.list（读取不稳定时可用 Shortcuts 兜底）
• notes.folders / notes.search
• photos.recent（不支持时降级打开 Photos）
• weather.current（优先 Shortcuts；不配置则打开 Weather）
• stocks.quote / stocks.batch
• stocks.history（使用 stooq 返回近 N 个交易日历史数据）

修改类（均需 confirm=YES）：

• - mail.send / mail.draft
• calendar.add / reminders.add / notes.create
• freeform.newboard / freeform.addtext / freeform.addsticky / freeform.addshape / freeform.compose

Commands（详细示例）

打开应用 / 打开链接

bash
python3 {baseDir}/scripts/main.py open app=Mail
python3 {baseDir}/scripts/main.py open app=Maps
python3 {baseDir}/scripts/main.py open url=http://maps.apple.com/?q=咖啡

邮件（Mail）

bash

未读数量 / 未读列表（读取）

python3 {baseDir}/scripts/main.py mail.unread_count
python3 {baseDir}/scripts/main.py mail.unread_list limit=20

创建草稿（不发送）

python3 {baseDir}/scripts/main.py mail.draft to=a@b.com subject=主题 body=正文

发送邮件（需要确认）

python3 {baseDir}/scripts/main.py mail.send to=a@b.com subject=主题 body=正文 confirm=YES

可选参数：

• - cc、bcc：逗号分隔
• attachments：逗号分隔的本地文件路径

备忘录（Notes）

bash
python3 {baseDir}/scripts/main.py notes.folders
python3 {baseDir}/scripts/main.py notes.search query=购物 limit=10
python3 {baseDir}/scripts/main.py notes.create title=购物清单 body=牛奶\n鸡蛋 folder=备忘录 confirm=YES

提醒事项（Reminders）

bash
python3 {baseDir}/scripts/main.py reminders.lists
python3 {baseDir}/scripts/main.py reminders.list list=提醒事项 limit=20
python3 {baseDir}/scripts/main.py reminders.add list=提醒事项 title=倒垃圾 notes=晚饭后 due=2026-03-03 20:30:00 confirm=YES

Shortcuts 兜底（推荐）

macOS 的 Reminders/Weather 在不同系统版本与隐私设置下，AppleScript 读取可能不稳定。本技能支持用快捷指令兜底，做到稳定输出 JSON。

Reminders 兜底：reminders.list

当 reminders.list 的 AppleScript 读取失败时，会尝试运行你指定的快捷指令：

• - 通过参数：shortcut=快捷指令名
• 或环境变量：MACOSSUITEREMINDERS_SHORTCUT=快捷指令名

调用时会把如下 JSON 作为快捷指令输入（Shortcuts 获取快捷指令输入拿到文件）：

json
{list:提醒事项,limit:20,includeCompleted:false}

快捷指令需要输出 JSON（文本即可）。推荐输出格式：

json
{items:[{title:倒垃圾,completed:false,due:2026-03-03 20:30:00}]}

快捷指令搭建建议（动作顺序示例）：

• - 获取快捷指令输入（会收到一个文件）
• 获取文件内容（文本）
• 从文本获取字典（把输入 JSON 转为字典）
• 获取提醒事项（可按清单过滤、按完成状态过滤、限制数量）
• 从列表创建字典数组（title/completed/due）
• 从字典创建 JSON（文本输出）

日历（Calendar）

bash
python3 {baseDir}/scripts/main.py calendar.today limit=50
python3 {baseDir}/scripts/main.py calendar.list start=2026-03-03 00:00:00 end=2026-03-03 23:59:59 limit=50
python3 {baseDir}/scripts/main.py calendar.add calendar=家庭 title=家和钢琴课 start=2026-03-03 18:00:00 end=2026-03-03 19:00:00 location=XX琴行 notes=提前10分钟出门 confirm=YES

时间格式建议：

• - YYYY-MM-DD HH:MM:SS（macOS AppleScript 可直接解析）

地图（Maps）

bash
python3 {baseDir}/scripts/main.py maps.search query=北京三里屯停车场
python3 {baseDir}/scripts/main.py maps.directions saddr=我家 daddr=北京南站 mode=d

mode：

• - d 驾车 / w 步行 / r 公交

其他应用（按需打开）

bash
python3 {baseDir}/scripts/main.py photos.open
python3 {baseDir}/scripts/main.py photos.recent limit=20
python3 {baseDir}/scripts/main.py freeform.open
python3 {baseDir}/scripts/main.py freeform.new_board title=项目看板 confirm=YES
python3 {baseDir}/scripts/main.py freeform.add_text text=标题\n-