核心用法
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 作业的退出状态。