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 已能正常打开并在前台
• 你运行脚本的宿主程序已授予“辅助功能”与“自动化”权限

建议先跑一个最小验证：

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

3) Reminders 读取不稳定

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

使用方式

从 OpenClaw workspace 运行：

python3 {baseDir}/scripts/main.py <command> key=value key=value ...

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

Commands（摘要）

只读类：

• mail.unread_count / mail.unread_list
• 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.new_board / freeform.add_text / freeform.add_sticky / freeform.add_shape / freeform.compose

Commands（详细示例）

打开应用 / 打开链接

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）

# 未读数量 / 未读列表（读取）
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）

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）

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="快捷指令名"
• 或环境变量：MACOS_SUITE_REMINDERS_SHORTCUT="快捷指令名"

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

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

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

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

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

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

日历（Calendar）

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）

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

mode：

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

其他应用（按需打开）

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- 要点1\n- 要点2" confirm=YES
python3 {baseDir}/scripts/main.py freeform.add_sticky text="TODO：联系供应商" confirm=YES
python3 {baseDir}/scripts/main.py freeform.add_shape kind=rectangle confirm=YES
python3 {baseDir}/scripts/main.py freeform.compose file="{baseDir}/examples/freeform.json" confirm=YES
python3 {baseDir}/scripts/main.py weather.open
python3 {baseDir}/scripts/main.py weather.current shortcut="你的天气快捷指令名"
python3 {baseDir}/scripts/main.py clock.open
python3 {baseDir}/scripts/main.py stocks.open symbol="AAPL"
python3 {baseDir}/scripts/main.py stocks.quote symbol="AAPL"
python3 {baseDir}/scripts/main.py stocks.quote symbol="600519"
python3 {baseDir}/scripts/main.py stocks.batch symbols="AAPL,600519,00700"
python3 {baseDir}/scripts/main.py stocks.history symbol="AAPL" range=1y

无边记（Freeform）绘图与排版

• 这些命令通过 UI 自动化完成（System Events 点击菜单 + 粘贴内容），需要系统开启“辅助功能”权限。
• freeform.compose JSON 示例：

{
  "boardTitle": "项目看板",
  "items": [
    {"type": "text", "text": "标题\\n- 要点1\\n- 要点2"},
    {"type": "sticky", "text": "TODO：联系供应商"},
    {"type": "shape", "kind": "rectangle"},
    {"type": "shape", "kind": "arrow"}
  ]
}

用无边记“绘制”走势图（建议）

本技能暂不支持把 PNG 图片直接插入 Freeform。要在无边记里呈现“走势图”，建议用 stocks.history 拉取数据后生成文本火花线（sparkline/ASCII 图），再用 freeform.add_text 插入到画板中。

最小流程：

python3 {baseDir}/scripts/main.py stocks.history symbol="AAPL" range=1y
python3 {baseDir}/scripts/main.py freeform.new_board title="AAPL 今年走势" confirm=YES
python3 {baseDir}/scripts/main.py freeform.add_text text="(把你生成的文本走势图粘贴在这里)" confirm=YES