Claude OAuth Auto-Renewal 是一个专为 OpenClaw 代理设计的自动化工具，用于在 Claude Code 作为 AI 提供商的场景下，持续监控并自动续期即将过期的 OAuth 令牌。该工具通过心跳检测机制主动识别令牌状态，防止因认证失效导致的代理中断运行。其核心设计基于 macOS 平台，利用系统级 Keychain 存储和 Chrome 浏览器自动化能力，实现无缝的令牌生命周期管理。当检测到 Claude Code 的访问令牌或刷新令牌接近过期时，系统将启动三级递进式续期流程，最大限度减少人工干预需求。 该工具的运行环境要求严格限定于 macOS 系统，依赖内置的 security CLI 命令读取 Keychain 中名为 `Claude Code-credentials` 的服务凭证。OAuth 令牌以 JSON 格式存储，包含 `accessToken`（前缀 sk-ant-oat01-）、`refreshToken`（前缀 sk-ant-ort01-）以及 `expiresAt` 时间戳等关键字段。为确保自动化流程顺利执行，还需配置 Google Chrome 开启 AppleScript 支持，并保证用户已提前完成 `claude auth login` 初始认证。整个续期过程完全透明，不会记录或外传任何实际令牌内容，仅通过脚本逻辑完成本地操作。 工作流程分为三个层级：第一级尝试使用现有刷新令牌进行静默续期；若失败则进入第二级浏览器自动化流程，模拟登录 claude.ai 并完成授权点击，提取回调中的新认证码回传给命令行；最后一级为兜底措施，当自动续期均不可行时，向预设通知渠道发送告警提醒用户手动处理。这种分层策略既保证了大多数情况下的无感运行，也为极端情形保留了应急通道。
核心功能特点
- 自动检测 Claude Code OAuth 令牌有效期，在心跳周期内触发续期检查
- 采用三级递进续期策略：优先刷新令牌 → 次选浏览器自动化授权 → 最终用户告警提醒
- 完全基于 macOS 原生组件实现：Keychain 存储、security CLI、osascript 及 Chrome JXA 集成
- 无需人工介入即可完成大部分续期任务，仅在必要时通知用户手动处理
- 安全合规设计：不存储、不记录实际令牌值，所有操作均在本地完成
适用场景
该工具最适合部署在长期运行的 OpenClaw 代理环境中，特别是那些依赖 Claude Code 作为后端 AI 服务且无法容忍中断的生产场景。例如，当企业需要构建持续运行的智能客服机器人、自动化代码审查流水线或实时数据分析助手时，OAuth 令牌的稳定性直接关系到服务的可用性。传统手动续期方式不仅繁琐低效，还容易因人为疏忽导致服务中断，而 Claude OAuth Auto-Renewal 通过自动化机制彻底解决了这一痛点。 另一个典型适用场景是开发者在本地或远程服务器上运行长时间任务的 Claude Code 实例。无论是执行大规模代码生成、文档分析还是多轮对话测试，一旦开始往往需要数小时甚至数天连续运行。在此期间，OAuth 令牌可能因自然老化或系统重启等原因意外过期，导致任务突然终止。启用此工具后，系统将在后台默默完成续期操作，确保任务不间断执行，显著提升自动化流程的可靠性和用户体验。 此外，对于团队协作项目而言，该工具也极具价值。多个成员可能共享同一台 macOS 设备上的 Claude Code 实例，但各自拥有独立的 claude.ai 账户。通过统一配置心跳检测脚本，团队可避免因个人账户令牌过期引发的集体性服务故障，同时降低运维复杂度。尤其适用于 CI/CD 环境、自动化测试平台或内部知识库系统中集成 Claude Code 功能的情形，真正实现‘设置即忘’的稳定运行模式。