iCloud CalDAV — Direct Calendar Access
Manage iCloud Calendar directly via CalDAV protocol. No third-party services, no data leaves your machine except to Apple's servers.
When to Use
Activate when the user wants to:
- - Check their calendar or upcoming events
- Create new calendar events
- Delete existing events
- List available calendars
Do NOT use for:
- - Reminders (use
apple-reminders skill if available) - Contacts (CalDAV is calendar-only)
- Non-iCloud calendars (Google, Outlook, etc.)
Prerequisites
Required credentials:
- -
APPLE_ID — Your Apple ID email address - INLINECODE2 — An app-specific password (NOT your regular Apple ID password)
To generate app-specific password:
- 1. Go to appleid.apple.com
- Sign in → Sign-In and Security → App-Specific Passwords
- Generate a new password
- Use this password (not your regular one)
Quick Start
CODEBLOCK0
Available Operations
| Operation | Command | Description |
|---|
| List calendars | INLINECODE3 | Show all iCloud calendars |
| List events |
list-events | Events in a date range |
| Create event |
create-event | Add new calendar event |
| Delete event |
delete-event | Remove event by filename or UID |
Workflow Patterns
Creating Events
CODEBLOCK1
Batch Operations
Note: CalDAV does not support native batch operations. To create multiple events, run the script multiple times:
CODEBLOCK2
iCloud handles rapid sequential requests well, but there is no single API call for creating multiple events.
Deleting Events
CODEBLOCK3
Warning: Deletions are permanent. iCloud may have its own backup, but standard CalDAV DELETE immediately removes the event.
Date/Time Formats
- - ISO 8601:
2025-07-23T14:00:00 (assumes local timezone if none specified) - With timezone: INLINECODE8
- All-day:
2025-07-23 (date only)
Security Notes
- - Credentials are read from environment variables only
- No credentials are logged or stored
- All communication is HTTPS to INLINECODE10
- App-specific passwords can be revoked anytime at appleid.apple.com
Error Handling
| Error | Cause | Solution |
|---|
| 401 Unauthorized | Bad credentials | Check APPLEID and APPLEAPP_PASSWORD |
| 404 Not Found |
Calendar/event doesn't exist | List calendars/events first |
| 403 Forbidden | Read-only calendar | Try a different calendar |
| Timeout | Network issue | Retry the request |
References
- - See
references/caldav-protocol.md for CalDAV implementation details - See
references/icloud-endpoints.md for iCloud-specific endpoints
iCloud CalDAV — 直接日历访问
通过CalDAV协议直接管理iCloud日历。无需第三方服务，除Apple服务器外，您的数据不会离开本机。
使用场景
在用户希望以下操作时启用：
- - 查看日历或即将到来的事件
- 创建新的日历事件
- 删除现有事件
- 列出可用日历
请勿用于：
- - 提醒事项（如有可用，请使用apple-reminders技能）
- 联系人（CalDAV仅限日历）
- 非iCloud日历（Google、Outlook等）
前提条件
所需凭证：
- - APPLEID — 您的Apple ID邮箱地址
- APPLEAPPPASSWORD — 一个应用专用密码（不是您的常规Apple ID密码）
生成应用专用密码的步骤：
- 1. 访问 appleid.apple.com
- 登录 → 登录与安全 → 应用专用密码
- 生成新密码
- 使用此密码（而非您的常规密码）
快速开始
bash
设置凭证
export APPLE_ID=your.email@icloud.com
export APPLE
APPPASSWORD=xxxx-xxxx-xxxx-xxxx
列出日历
./scripts/caldav.py list-calendars
列出未来7天的事件
./scripts/caldav.py list-events --days 7
创建事件
./scripts/caldav.py create-event \
--title 团队会议 \
--start 2025-07-23T14:00:00 \
--duration 60 \
--calendar 工作
可用操作
| 操作 | 命令 | 描述 |
|---|
| 列出日历 | list-calendars | 显示所有iCloud日历 |
| 列出事件 |
list-events | 日期范围内的事件 |
| 创建事件 | create-event | 添加新的日历事件 |
| 删除事件 | delete-event | 按文件名或UID删除事件 |
工作流模式
创建事件
bash
基本事件
./scripts/caldav.py create-event \
--title 牙医预约 \
--start 2025-07-25T09:30:00 \
--duration 30
带地点和描述
./scripts/caldav.py create-event \
--title 项目评审 \
--start 2025-07-26T14:00:00 \
--duration 60 \
--location B会议室 \
--description Q3规划评审 \
--calendar 工作
全天事件
./scripts/caldav.py create-event \
--title 假期 \
--start 2025-08-01 \
--all-day
批量操作
注意： CalDAV不支持原生批量操作。如需创建多个事件，请多次运行脚本：
bash
通过多次运行命令创建多个事件
./scripts/caldav.py create-event --title 会议1 --start 2025-07-26T10:00:00 --duration 60
./scripts/caldav.py create-event --title 会议2 --start 2025-07-26T14:00:00 --duration 60
./scripts/caldav.py create-event --title 会议3 --start 2025-07-27T09:00:00 --duration 60
iCloud能很好地处理快速连续请求，但没有用于创建多个事件的单一API调用。
删除事件
bash
按文件名删除
./scripts/caldav.py delete-event \
--file event-name.ics \
--calendar 日历
按UID删除（在日历中搜索匹配事件）
./scripts/caldav.py delete-event \
--uid openclaw-xxx@openclaw.local \
--calendar 日历
警告： 删除操作不可逆。iCloud可能有自己的备份，但标准CalDAV DELETE会立即移除事件。
日期/时间格式
- - ISO 8601：2025-07-23T14:00:00（若未指定时区，则假定为本地时区）
- 带时区：2025-07-23T14:00:00+08:00
- 全天：2025-07-23（仅日期）
安全说明
- - 凭证仅从环境变量读取
- 不会记录或存储任何凭证
- 所有通信均通过HTTPS连接到caldav.icloud.com
- 可随时在appleid.apple.com撤销应用专用密码
错误处理
| 错误 | 原因 | 解决方案 |
|---|
| 401 未授权 | 凭证错误 | 检查APPLEID和APPLEAPP_PASSWORD |
| 404 未找到 |
日历/事件不存在 | 先列出日历/事件 |
| 403 禁止访问 | 只读日历 | 尝试其他日历 |
| 超时 | 网络问题 | 重试请求 |
参考
- - 有关CalDAV实现细节，请参阅references/caldav-protocol.md
- 有关iCloud特定端点，请参阅references/icloud-endpoints.md
