iCalendar 同步

使用此技能可从 OpenClaw 代理执行 iCloud 日历 CRUD 操作。

1. 安全准备凭据

仅使用应用专用密码（切勿使用主 Apple ID 密码）。

优先使用密钥环存储：

bash
python -m icalendar_sync setup --username user@icloud.com

自动化场景使用非交互式设置：

bash
export ICLOUD_USERNAME=user@icloud.com
export ICLOUDAPPPASSWORD=xxxx-xxxx-xxxx-xxxx
python -m icalendar_sync setup --non-interactive

仅在密钥环不可用时（无头或 GUI 受限运行环境）使用文件存储：

bash
python -m icalendar_sync setup --non-interactive --storage file --config ~/.openclaw/icalendar-sync.yaml

2. 审慎选择提供商

• - --provider auto：macOS 使用原生桥接，非 macOS 使用 CalDAV。
• --provider caldav：强制直接使用 iCloud CalDAV。
• --provider macos-native：强制使用 Calendar.app 桥接（仅限 macOS）。

如需 CalDAV 诊断，添加：

bash
--debug-http --user-agent your-agent/1.0

3. 执行日历操作

列出日历：

bash
python -m icalendar_sync list

获取事件：

bash
python -m icalendar_sync get --calendar 个人 --days 7

创建事件：

bash
python -m icalendar_sync create --calendar 个人 --json {
summary: 会议,
dtstart: 2026-02-15T14:00:00+03:00,
dtend: 2026-02-15T15:00:00+03:00
}

更新事件（简单）：

bash
python -m icalendar_sync update --calendar 个人 --uid event-uid --json {summary:更新标题}

更新重复事件实例：

bash
python -m icalendar_sync update \
--calendar 工作 \
--uid series-uid \
--recurrence-id 2026-03-01T09:00:00+03:00 \
--mode single \
--json {summary:一次性变更}

重复事件更新的模式：

• - single：更新单个实例（使用 --recurrence-id）
• all：更新整个系列
• future：拆分系列并更新此事件及后续事件（使用 --recurrence-id）

删除事件：

bash
python -m icalendar_sync delete --calendar 个人 --uid event-uid

4. 输入契约

对于 create 操作，至少需要：

• - summary（字符串）
• dtstart（ISO 日期时间）
• dtend（ISO 日期时间，必须晚于 dtstart）

可选字段：

• - description
• location
• status
• priority（0-9）
• alarms
• rrule

5. 安全规则

• - 验证日历名称；拒绝类似路径的有效载荷。
• 确保凭据材料不进入日志/输出。
• 优先使用密钥环而非文件存储。
• 如果使用文件存储，强制设置严格的文件权限（0600）。

6. 故障处理

如果在 macOS 上 CalDAV 认证/网络失败且提供商为 auto/caldav，则切换到 macos-native 并重试相同操作。

如果 JSON 有效载荷以文件路径形式提供，确保在解析前文件大小保持在安全限制内。