基于 gcalcli 和 CalDAV 的日历提醒自动化工具，通过 JSON 计划输出实现 OpenClaw 提醒集成，适合需要本地化处理日历提醒的技术用户。
说明：
## 核心用法
calendar-reminders 是一个配置驱动的日历提醒管道工具，主要提供两大功能模块：一是 `scripts/calendar` 包装器，封装了 gcalcli（Google Calendar CLI）和可选的 CalDAV 同步工具链（vdirsyncer + khal）；二是 `scripts/calendar_reminder_plan.py` 提醒计划生成器，输出 JSON 格式的提醒调度计划，供 OpenClaw 系统创建一次性提醒。
用户需将示例配置复制到 `~/.config/openclaw/calendar.json` 或通过环境变量 `OPENCLAW_CALENDAR_CONFIG` 指定路径。对于 Google 日历，需完成 OAuth 认证（headless 服务器可通过 SSH 端口转发配合 `–noauth_local_server` 参数）。CalDAV/iCloud 支持为可选项。典型部署模式是设置每日 cron 任务：先同步 CalDAV（如启用），再运行计划生成器，最后遍历 JSON 输出创建 OpenClaw `systemEvent` 提醒，同时通过状态文件避免重复调度。
## 显著优点
该技能的最大优势在于**解耦设计**——它将日历数据获取、提醒计划生成与实际调度执行分离，使用户可以灵活选择调度后端（cron、systemd timer 或 Agent 轮询）。这种架构既保留了 gcalcli 和 khal 成熟工具的可靠性，又避免了深度绑定特定提醒系统。
**配置灵活性**体现在多源支持（Google Calendar + CalDAV/iCloud）、环境变量覆盖路径、以及细粒度的提醒规则（自动忽略生日、区分定时/全天事件的关键词匹配）。**本地优先**的隐私设计确保日历数据不经过第三方中转，JSON 输出格式也便于与其他自动化工具链集成。
## 潜在缺点与局限性
**外部工具依赖**是首要门槛：gcalcli 的 OAuth 流程对非技术用户不够友好，headless 环境的端口转发配置可能困扰新手；vdirsyncer 和 khal 的 CalDAV 支持虽强大，但增加了系统复杂度。**调度责任外置**意味着用户必须自行实现 cron 作业或 Agent 逻辑，技能本身不提供开箱即用的提醒触发机制。
**功能边界**方面，提醒规则相对基础（关键词匹配、时间类型判断），不支持复杂的重复模式或条件逻辑；状态文件机制虽防重复，但在分布式或多实例场景下可能产生竞态条件。此外，技能仅输出计划而不执行实际通知，最终用户体验取决于下游 OpenClaw 提醒系统的可靠性。
## 适合的目标群体
该技能面向**技术型用户**和**自动化爱好者**：熟悉命令行操作、有 cron/systemd 经验、希望自建日历提醒工作流的开发者或运维人员。适合已使用 gcalcli/khal 管理日历、需要将提醒集成到 OpenClaw 或其他自动化平台的场景。对个人隐私敏感、偏好本地处理而非云服务托管的用户也是理想受众。
**不适合**追求零配置开箱体验的普通用户，或需要复杂提醒规则（如地理位置触发、智能推迟）的高级日程管理需求。
## 使用风险
**性能风险**较低：计划生成操作为只读，不修改日历数据；状态文件 I/O 轻量。但大规模日历（数千事件）的 JSON 序列化可能产生内存压力。**依赖项风险**需关注：gcalcli 和 khal 的版本兼容性、Google OAuth token 的过期刷新、CalDAV 服务器的可用性均可能影响服务连续性。**配置风险**包括：配置文件权限设置不当导致日历信息泄露；状态文件损坏可能导致提醒重复或遗漏。建议将配置目录权限设为 700，并监控 cron 作业的退出状态。
会员专属
