千灵

Back

发送待办示例图

给 AI Agent 接入 iOS 消息推送,通常需要依赖 Server酱、Bark 等第三方服务。

但其实苹果自带的 iCloud 日历就是天然且免费的通知通道,只需要一个简单的 HTTP/Python 脚本,就能向用户推送原生日历弹窗。

本教程演示如何利用 Apple CalDAV 开放接口,为 AI Agent 配置 iCloud 日历准点提醒技能,可将本文链接直接发给 AI 部署

兼容性:适用于所有 AI Agent(如 Hermes、OpenClaw、PI 等)。 环境验证:Debian 13 + Python 3.11 验证通过。

前置条件#

  1. Apple ID 已开启双重认证(2FA)
  2. 能直连 caldav.icloud.com:443

第一步:生成 App 专用密码#

  1. 浏览器打开 https://account.apple.com/account/manage/section/security
  2. 「登录与安全性」→ App 专用密码 → 生成
  3. 保存 xxxx-xxxx-xxxx-xxxx 格式密码(只显示一次)

生成 App 专用密码

第二步:确认 Apple ID#

点击电子邮件和电话号码,主要电话号码或主要电子邮件地址就是 Apple ID,用于接下来的 CalDAV 认证。

确认 Apple ID

第三步:连通性验证#

向 iCloud 日历列表发送 PROPFIND 请求,预期输出格式示例 /12112653923/principal/,需记录此数字 ID 给第五步用。

须填写:

  • 用户名 = 第二步的 Apple ID
  • 密码 = 第一步的 App 专用密码

Linux / macOS#

curl -s -u "用户名:密码" -X PROPFIND -H "Depth: 0" "https://caldav.icloud.com/.well-known/caldav" | grep -o '/[0-9]*/principal/'
bash

Windows (PowerShell)#

curl.exe -s -u "用户名:密码" -X PROPFIND -H "Depth: 0" "https://caldav.icloud.com/.well-known/caldav" | Select-String -Pattern '/[0-9]*/principal/' | ForEach-Object { $_.Matches.Value }
powershell

第四步:自定义日历(可选)#

推送通知默认写入「个人」日历(路径 calendars/home/),可以修改为写入其他日历,这样就能单独设置颜色和归属,以便区分是否由 AI 写入。

一、获取日历路径#

以下是获取所有日历路径的指令,须填写:

  • 用户名 = 第二步的 Apple ID
  • 密码 = 第一步的 App 专用密码

Linux / macOS#

curl -s -u "用户名:密码" -X PROPFIND -H "Depth: 1" \
  -H "Content-Type: application/xml" \
  --data-binary '<?xml version="1.0"?><d:propfind xmlns:d="DAV:"><d:prop><d:displayname/></d:prop></d:propfind>' \
  "https://caldav.icloud.com/{PRINCIPAL_ID}/calendars/" \
  | grep -oE '<href>[^<]+</href>|<displayname[^>]*>[^<]+</displayname>'
plaintext

Windows (PowerShell)#

$OutputEncoding = [Console]::OutputEncoding = [Text.Encoding]::UTF8

curl.exe -sL -u "用户名:密码" -X PROPFIND -H "Depth: 1" -H "Content-Type: application/xml; charset=utf-8" --data-binary '<?xml version="1.0"?><d:propfind xmlns:d="DAV:"><d:prop><d:displayname/></d:prop></d:propfind>' "https://caldav.icloud.com/{PRINCIPAL_ID}/calendars/" | Select-String -Pattern '<([^:]+:)?(href|displayname)[^>]*>[^<]+</([^:]+:)?(href|displayname)>' -AllMatches | ForEach-Object { $_.Matches.Value }
plaintext

二、查看日历路径#

查询结果示例:

<href>/12112653923/calendars/</href>
<displayname xmlns="DAV:">明子</displayname>
<href>/12112653923/calendars/478D5D08-0F22-4B80-A10B-615BCFBE9135/</href>
<displayname xmlns="DAV:">飞行计划</displayname>
<href>/12112653923/calendars/6ba4d928-4c4f-412c-8c52-4689177c1975/</href>
<displayname xmlns="DAV:">Reminders ⚠️</displayname>
<href>/12112653923/calendars/home/</href>
<displayname xmlns="DAV:">个人</displayname>
<href>/12112653923/calendars/inbox/</href>
<href>/12112653923/calendars/notification/</href>
<href>/12112653923/calendars/work/</href>
<displayname xmlns="DAV:">工作</displayname>
<href>/12112653923/calendars/outbox/</href>
plaintext

对照 hrefdisplayname 判断日历路径,把第五步各版本 URL 里的 calendars/home/ 换掉即可(如替换为 calendars/work/)。

需忽略无 displayname 的系统目录:inbox/notification/outbox/

第五步:配置脚本#

以下四种实现任选其一。

替换三处:

  • 用户名:Apple ID
  • 密码:App 专用密码
  • {PRINCIPAL_ID}:第三步连通性验证输出里 principal URL 的数字 ID,如 12112653923

Python(推荐 AI Agent 使用,便于程序内生成时间戳)#

把以下代码存为脚本,如 ~/scripts/add_reminder.py

注意事项:

  • 行尾必须 CRLF\r\n),纯 \n 部分客户端会拒绝
  • If-None-Match: "*" 防止覆盖同名事件
  • TRIGGER:-PT0M = 准点提醒;要提前 10 分钟就写 -PT10M
  • 时间戳一律 UTC(Z 后缀),时区转换在客户端做

curl(零依赖)#

先把事件内容保存为 event.ics(注意 Windows 记事本保存时需选 CRLF),DTSTART:20260909T070000Z = 北京时间 15:00(UTC+8 换算):

发送以下命令,返回 201 即成功,文件名(my-reminder-001.ics)是事件 UID,需保持唯一:

curl -u "用户名:密码" -X PUT \
  -H "Content-Type: text/calendar; charset=utf-8" \
  -H "If-None-Match: *" \
  --data-binary @event.ics \
  "https://caldav.icloud.com/{PRINCIPAL_ID}/calendars/home/my-reminder-001.ics"
bash

Node.js#

用法:addReminder(“取快递”, new Date(“2026-09-09T15:00:00+08:00”))

Windows PowerShell#

第六步:AI 自动调用#

在 AI Agent 技能目录里新建 SKILL.md,填入技能描述及第五步的脚本地址,以 Hermes 为例:

~/.hermes/skills/linux/apple-calendar/SKILL.md

---
name: apple-calendar-reminder
description: 当用户说"记个待办/提醒我 xxx(时间)"时使用。通过 CalDAV 写入 iCloud 日历,手机准点弹通知。
---
执行 `python ~/scripts/add_reminder.py "<标题>" "<YYYY-MM-DD HH:MM>"`
- 时间为北京时间 24 小时制;用户没给时间就设当天 21:00
- 执行成功回复"已记:xxx,将在 HH:MM 提醒"
plaintext

附:踩坑记录#

本方案的最佳实现应当是推送到「提醒事项」,但 iOS 13 之后提醒事项改用苹果私有 CloudKit 协议同步,CalDAV 只能访问遗留清单(写入后 App 里不显示),所以本方案被迫采用日历事件。

无需第三方 App,让 AI Agent 实现 iOS 原生通知提醒 | 全平台通用,保姆级教程
https://qianling.pw/ai-apple-calendar/
Author 千灵
Published at September 8, 2026
Comment seems to stuck. Try to refresh?✨