gcal-oauth-bridge 是一个轻量级的自托管 Node.js 服务，专为解决 Google Calendar 与第三方应用集成时的 OAuth 令牌管理难题而设计。它运行在本地端口 3000，通过封装 Google Calendar API 的认证流程，实现了对日历事件的持久化访问和自动化令牌刷新。该工具的核心价值在于彻底解决了传统方式中 OAuth 令牌有效期仅7天、需频繁手动续期的问题，使得开发者可以构建长期稳定运行的日历相关应用或技能（如智能家居语音助手、自动化提醒系统等）。用户只需完成一次浏览器授权流程，后续所有请求均由服务自动处理令牌更新，无需干预。整个系统以 RESTful API 形式对外暴露功能，支持获取个人及多日历事件、列出可用日历、检查服务状态等操作，非常适合需要持续访问 Google 日历数据但又不希望依赖外部云服务或复杂客户端库的场景。
核心功能特点
- 一次授权，永久有效：通过浏览器完成 Google 账户授权后，服务自动存储并定期刷新 OAuth 令牌，避免因令牌过期导致的访问中断。
- 极简 REST API 接口：提供健康检查、事件查询、日历列表等标准端点，支持按天数、指定日历过滤事件，返回结构化的 JSON 数据。
- 本地安全存储：OAuth 令牌保存在服务器本地的 tokens.json 文件中，不上传至 GitHub，保障用户隐私与数据安全。
- 支持多日历与批量查询：可检索主日历、全部日历或特定 ID 的日历事件，灵活应对不同集成需求。
- 兼容个人 Gmail 账户：即使遇到 Google 的“未验证应用”警告，也允许用户手动继续授权流程，适用于个人项目或小规模部署。
适用场景
gcal-oauth-bridge 特别适合那些需要长期、自动化访问 Google Calendar 数据的开发者和系统集成者。例如，在构建智能家居控制系统时，你可以利用该服务定期检查用户的日程安排，当检测到会议即将开始时自动关闭灯光或启动咖啡机；对于远程办公场景，它可以作为时间管理工具，在特定时间段内触发工作模式切换。此外，各类基于日历的自动化脚本、个人助理类应用（如语音提醒、行程同步）以及企业内部使用的轻量级调度平台都能从中受益。由于服务采用自托管架构且无需公网 API 密钥，它尤其适合注重数据主权和离线能力的用户环境。无论是搭配 OpenClaw 技能框架使用，还是独立部署于树莓派、家庭服务器上，gcal-oauth-bridge 都能提供可靠、低延迟的日历数据访问能力，显著降低集成复杂度与维护成本。