- name
- icalendar-sync
- description
- Secure iCloud Calendar operations for OpenClaw with CalDAV and macOS native bridge providers. Use when tasks require calendar listing, event retrieval, event creation, event updates (including recurring series modes), event deletion, or credential setup via keyring/environment/config file.
iCalendar Sync
Use this skill to perform iCloud calendar CRUD operations from OpenClaw agents.
1. Prepare Credentials Securely
Use App-Specific Passwords only (never the primary Apple ID password).
Prefer keyring storage:
python -m icalendar_sync setup --username user@icloud.comUse non-interactive setup for automation:
export ICLOUD_USERNAME="user@icloud.com"
export ICLOUD_APP_PASSWORD="xxxx-xxxx-xxxx-xxxx"
python -m icalendar_sync setup --non-interactiveUse file storage only when keyring is unavailable (headless or GUI-restricted runtime):
python -m icalendar_sync setup --non-interactive --storage file --config ~/.openclaw/icalendar-sync.yaml2. Choose Provider Deliberately
--provider auto: macOS uses native bridge, non-macOS uses CalDAV.--provider caldav: force direct iCloud CalDAV.--provider macos-native: force Calendar.app bridge (macOS only).
For CalDAV diagnostics, add:
--debug-http --user-agent "your-agent/1.0"3. Execute Calendar Operations
List calendars:
python -m icalendar_sync listGet events:
python -m icalendar_sync get --calendar "Personal" --days 7Create event:
python -m icalendar_sync create --calendar "Personal" --json '{
"summary": "Meeting",
"dtstart": "2026-02-15T14:00:00+03:00",
"dtend": "2026-02-15T15:00:00+03:00"
}'Update event (simple):
python -m icalendar_sync update --calendar "Personal" --uid "event-uid" --json '{"summary":"Updated title"}'Update recurring event instance:
python -m icalendar_sync update \
--calendar "Work" \
--uid "series-uid" \
--recurrence-id "2026-03-01T09:00:00+03:00" \
--mode single \
--json '{"summary":"One-off change"}'Modes for recurring updates:
single: update one instance (use--recurrence-id)all: update whole seriesfuture: split series and update this+future (use--recurrence-id)
Delete event:
python -m icalendar_sync delete --calendar "Personal" --uid "event-uid"4. Input Contract
For create, require at least:
summary(string)dtstart(ISO datetime)dtend(ISO datetime, must be later thandtstart)
Optional fields:
descriptionlocationstatuspriority(0-9)alarmsrrule
5. Safety Rules
- Validate calendar names; reject path-like payloads.
- Keep credential material out of logs/output.
- Prefer keyring over file storage.
- If file storage is used, enforce strict file permissions (
0600).
6. Failure Handling
If CalDAV auth/network fails on macOS and provider is auto/caldav, switch to macos-native and retry the same operation.
If JSON payload is supplied as file path, ensure file size stays within safe limits before parsing.