核心用法
calendar-reminders是一个配置驱动的日历提醒管道工具，主要面向需要自动化日程提醒的技术用户。核心组件包括：
1. gcalcli包装器 (scripts/calendar)：简化Google Calendar命令行交互，自动处理OAuth的无服务器认证流程
2. 提醒规划器 (scripts/calendar_reminder_plan.py)：分析日历事件并输出JSON格式的提醒计划
3. 配置系统：支持~/.config/openclaw/calendar.json标准路径，可通过环境变量覆盖
典型工作流程：
- 可选CalDAV同步（vdirsyncer+khal）→ 运行规划器生成JSON → 由cron或agent创建一次性OpenClaw
systemEvent提醒 → 写入状态文件防重复
智能过滤策略：
- 自动忽略生日事件
- 定时事件默认为是重要提醒
- 全天事件仅当标题匹配配置关键词时才触发
显著优点
- 双源支持：原生Google Calendar + 可选CalDAV/iCloud，覆盖主流日历生态
- 无头友好：针对服务器环境优化OAuth流程，支持SSH端口转发方案
- 声明式配置：JSON配置驱动，易于版本管理和自动化部署
- 防重复机制：状态文件追踪确保不会重复创建提醒
- 模块化设计：规划与执行分离，用户可自由选择调度机制（cron/systemd/agent）
潜在缺点与局限性
- 依赖链条复杂：核心需Python3+gcalcli，CalDAV功能额外需要vdirsyncer+khal三个工具
- OAuth手动步骤：Google认证仍需人工介入，无法完全自动化
- 无内置调度器：必须自行配置cron或agent逻辑，对非技术用户门槛较高
- 状态文件本地单点：无分布式状态同步，多机部署需额外处理
- 关键词匹配粗糙：全天事件过滤仅支持简单标题关键词，无自然语义理解
适合人群
- 习惯命令行工作流的技术用户
- 需要在服务器/无头环境运行日历自动化的开发者
- 已使用OpenClaw生态、希望统一提醒管理的用户
- 对数据主权敏感、希望本地处理日历数据的隐私意识用户
常规风险
- OAuth令牌泄露：配置文件存储凭证，需确保
~/.config/openclaw/目录权限严格（建议700） - 时区处理：跨时区旅行时，UTC转换逻辑可能产生偏差
- API配额：高频同步可能触发Google Calendar API速率限制
- 状态文件损坏：异常中断可能导致状态不一致，需定期清理或监控