Cron持久化与自动过期机制

一、durable参数详解

在 Claude Code 的 cron 系统中，durable 参数是最核心的调度配置选项之一。它决定了一个 cron 任务的生命周期范围：是跨越会话持续存在，还是仅在当前会话中生效。理解这一参数的行为差异，对于正确设计定时任务策略至关重要。

durable: true — 持久化任务

任务会被写入文件系统，保存在 .claude/scheduled_tasks.json 中。即使关闭并重启 Claude Code，这些任务依然存在并在后台自动恢复调度。

durable: false — 非持久化任务

任务仅绑定到当前会话的内存中。一旦会话结束或 Claude Code 重启，这些任务将被永久删除，不会留下任何痕迹。

持久化任务（durable: true）

当创建一个 cron 任务并将 durable 设置为 true 时，Claude Code 会将该任务的完整定义保存到磁盘上的持久化存储文件中。这个文件位于项目目录下的 .claude/scheduled_tasks.json。持久化任务的核心价值在于它能够跨越 Claude Code 会话的边界继续存在——你可以在今天创建一个每天早上8点运行的任务，关闭终端，明天再打开 Claude Code，这个任务依然会在后台活跃并按时触发。

持久化机制的内部工作流程如下：任务创建时，系统将任务定义（含 cron 表达式、prompt 内容、创建时间戳等信息）序列化为 JSON 并写入文件；Claude Code 启动时，引导程序会自动扫描 .claude/scheduled_tasks.json，读取其中所有未过期的任务；每个任务会被注册到调度引擎中，按照其 cron 表达式计算下一次触发时间；调度引擎在后台线程中持续运行，按时触发任务。

持久化任务的位置

# 持久化任务存储路径（项目根目录下）
.claude/scheduled_tasks.json

# 典型路径示例
/home/user/my-project/.claude/scheduled_tasks.json
/Users/name/workspace/.claude/scheduled_tasks.json

每个项目拥有独立的 .claude/ 目录和独立的 scheduled_tasks.json 文件。这意味着不同项目的 cron 任务彼此隔离，互不干扰。当你在多个项目中分别创建持久化任务时，每个项目各自管理自己的任务列表。

跨会话恢复

跨会话恢复是持久化任务最重要的能力。当 Claude Code 重启时，系统会自动执行以下恢复流程：

加载阶段：读取 .claude/scheduled_tasks.json，验证 JSON 格式的正确性
校验阶段：逐项检查每个任务的状态——是否已过期、是否已完成、cron 表达式是否仍然合法
注册阶段：将所有有效任务重新注册到调度引擎中，分配新的内存句柄
恢复阶段：首次加载时立即检查是否有错过的触发窗口，避免因重启导致任务遗漏

提示：跨会话恢复机制对长期运行的项目非常有用。例如，你可以设置一个每周发送代码审查提醒的 cron 任务，即使这期间你多次开关 Claude Code，它都会在每周一的指定时间准确触发。

二、持久化任务的存储结构

文件格式与内容

.claude/scheduled_tasks.json 使用标准的 JSON 格式存储所有持久化 cron 任务的配置信息。每个任务记录包含以下关键字段：

{
  "tasks": [
    {
      "id": "task_abc123",          // 任务唯一标识符
      "cron": "0 8 * * *",          // cron 表达式（每天早上8点）
      "prompt": "检查待办事项并发送提醒", // 任务执行的 prompt
      "created_at": "2026-05-01T10:30:00Z", // 创建时间（UTC）
      "type": "recurring",         // 任务类型：recurring 或 one_shot
      "status": "active"             // 任务状态：active / expired / completed
    }
  ]
}

各字段的详细说明：

字段	说明	示例值
id	任务的唯一标识符，由系统自动生成，用于任务的管理和删除	task_abc123
cron	标准的 5 字段 cron 表达式，定义任务的执行时间规则	0 8 * * *
prompt	任务触发时要执行的 prompt 文本，作为 Agent 的输入指令	"检查待办事项并发送提醒"
created_at	任务的创建时间戳，使用 ISO 8601 格式（UTC 时区）	2026-05-01T10:30:00Z
type	任务类型：recurring（周期性）或 one_shot（一次性）	recurring
status	任务当前状态：active（活跃）、expired（已过期）、completed（已完成）	active

文件的读写机制

系统对 scheduled_tasks.json 的读写采用同步加锁策略，以避免并发访问导致的数据损坏。每次新增、更新或删除任务时，系统会读取整个文件内容到内存，修改后再完整写回磁盘。这种全量读写方式虽然对于大量任务时效率不高，但因为持久化任务数量通常很少（一般不超过几十个），所以性能影响可以忽略。

写操作遵循"先写临时文件，再原子重命名"的安全写入模式。系统先将新内容写入一个临时文件（如 scheduled_tasks.json.tmp），写入成功后再通过原子重命名操作覆盖原文件。这样做可以防止在写入过程中发生崩溃导致文件损坏——要么原文件保持不变，要么完整的新文件写入成功，不会出现半写状态。

文件损坏的恢复策略

尽管有写入保护机制，文件仍然可能因为磁盘错误、手动编辑不当或版本控制冲突而损坏。系统内置了以下恢复策略：

自动校验：每次读取文件时进行 JSON 语法验证，格式错误时触发恢复流程
备份恢复：系统会在每次成功写入前创建备份文件（scheduled_tasks.json.bak），主文件损坏时自动尝试从备份恢复
降级处理：如果主文件和备份文件均损坏，系统将清空任务列表并以空文件重新初始化，同时记录错误日志
手动修复：用户可以直接编辑 JSON 文件进行手动修复，修复后重新加载即可生效

注意：手动编辑 scheduled_tasks.json 时需要特别小心，无效的 JSON 格式会导致所有持久化任务丢失。建议编辑前先手动备份文件。

三、非持久化任务

会话级生命周期

当创建的 cron 任务使用 durable: false（或省略该参数，因 false 为默认值）时，任务的生命周期被限定在当前 Claude Code 会话中。这类任务不会被写入文件系统，而是完全存在于内存中的调度器内部。以下是其核心行为特征：

任务仅在创建它的 Claude Code 实例中运行
任务数据存储在进程内存中，不占用磁盘空间
会话结束后（终端关闭、Claude Code 退出），任务被立即销毁
重新打开 Claude Code 后，非持久化任务不会自动恢复

非持久化任务适合临时性、探索性的定时需求。例如，你在调试某个自动化流程时，可能需要每5分钟运行一次测试脚本来验证修改效果，这个任务仅在当前调试会话中有意义，不需要在下次打开 Claude Code 时继续存在。

适用场景

场景	说明	推荐持久化
临时调试任务	数据分析或故障排查期间临时设置的定时检查	否（非持久化）
一次性提醒	仅需在当前会话中提醒一次的任务	否（非持久化）
日常自动化	每天/每周固定执行的例行任务	是（持久化）
监控告警	需要长期持续监控的项目状态检查	是（持久化）

重启行为

理解非持久化任务在重启时的行为非常重要。当 Claude Code 重启时：

所有非持久化任务被立即从内存中清除，无恢复可能
调度器的内部状态完全重置，包括下次触发时间、已触发次数等
如果重启后仍然需要同样的任务，必须重新创建
多个并行会话之间互不共享非持久化任务

最佳实践：当发现某个非持久化任务经常需要跨会话使用时，可以考虑将其升级为持久化任务（创建时将 durable 设置为 true），以避免重复创建的工作。

四、7天自动过期机制

过期规则

Claude Code 的 cron 系统对所有周期性任务（recurring）实施了7天自动过期限制。这个设计是为了防止长期运行的 Agent 任务堆积，避免因任务被遗忘而持续消耗系统资源。过期机制的核心规则如下：

所有 type 为 recurring 的任务，从创建时间起计算，7天后自动过期
过期后，任务不再触发任何新的执行
系统会在任务最后一次触发后将其从调度列表中自动删除
一次性任务（one_shot）不受7天限制，触发一次后即自动删除

核心要点：7天过期限制仅适用于周期性（recurring）任务。一次性任务在触发后立即完成并删除，不存在过期问题。

过期判断逻辑

系统判断一个任务是否过期的方式是比对创建时间和当前时间。每次调度引擎触发任务之前，都会检查当前时间是否已经超过了"创建时间 + 7天"的截止时间点。如果已过期，则该任务被标记为 expired 状态，从调度队列中移除，并在下次执行文件持久化写入时从 JSON 文件中清除。

# 过期判断伪代码
function isTaskExpired(task):
    createdAt = task.created_at
    expiresAt = createdAt + 7 days
    return currentTime > expiresAt

过期后的行为

当一个周期性任务达到过期时限时，系统会执行以下清理流程：

任务从调度引擎的内存队列中移除，不再参与下一次触发时间计算
如果任务正好在过期时间点前最后一次触发，则允许该次执行正常完成
.claude/scheduled_tasks.json 中对应的任务记录被标记为 expired 或直接删除
用户下次通过任务管理命令查看时，过期任务不再出现在活跃列表中

一次性任务的特殊处理

一次性任务（one_shot）的生命周期与周期性任务不同：

创建后，系统根据其指定的延迟时间（如"5分钟后"）计算触发时间
触发执行后，任务立即从系统中删除，不留任何痕迹
不会被7天过期限制影响——无论设置的延迟时间是多久，只要触发就结束
如果 Claude Code 在任务触发前重启，一次性任务默认也会丢失（除非设置为 durable: true）

五、持久化任务管理

定期检查任务列表

对于使用了持久化 cron 任务的项目，定期检查任务列表是一项重要的维护工作。你可以通过 Claude Code 提供的调度管理命令来查看当前所有活跃的持久化任务，了解每个任务的 cron 表达式、创建时间、剩余有效期等信息。

建议的检查频率：对于任务较多的项目，每天检查一次；对于只有少量任务的项目，每周检查一次即可。检查时重点关注以下几点：

是否有任务已经过期但尚未被清理
是否有任务不再需要但仍占用调度资源
任务的 cron 表达式是否仍然满足当前需求
任务的 prompt 内容是否需要更新

清理不再需要的任务

长期运行的项目会在 .claude/scheduled_tasks.json 中积累一些不再需要的任务记录。虽然系统会自动清理过期任务，但主动管理仍然很有必要：

确认不再需要的周期性任务，及时手动删除
对于测试期间创建的各种临时任务，完成后移除
当项目停止维护时，清理所有关联的 cron 任务
定期检查 JSON 文件的尺寸，避免异常增长

注意：删除持久化任务是不可逆操作。删除前请确认该任务确实不再需要，或者已有关联的替代方案。

安全注意事项

持久化 cron 任务在被触发时会执行指定的 prompt，其中可能包含具有系统级影响的指令。因此，在管理持久化任务时需要关注以下安全事项：

任务 prompt 中不应包含敏感信息（如密码、API Key 等），因为 prompt 以明文存储在 JSON 文件中
.claude/scheduled_tasks.json 中包含任务的完整配置，应避免将该文件提交到公开的版本控制仓库
建议将 .claude/scheduled_tasks.json 添加到 .gitignore 中，防止意外泄露任务内容
定期审计任务 prompt 的内容，确保它们不会被滥用或误用

安全建议：如果必须将持久化任务纳入版本控制，考虑使用环境变量引用敏感信息，而不是直接在 prompt 中硬编码。或者使用外部密钥管理服务来动态获取凭据。

多会话间的任务协调

在使用持久化任务时，可能会出现多个 Claude Code 会话同时访问同一个 .claude/scheduled_tasks.json 文件的场景。这种情况下需要了解系统的协调机制和注意事项：

文件锁：系统在读写 JSON 文件时会尝试获取文件锁，避免并发写入导致数据损坏。如果无法获取锁，会等待重试
主从协调：在多个会话同时存在的情况下，只有一个会话承担实际的调度触发职责，其他会话不会重复触发同一个任务
状态同步：当一个会话修改了任务状态（如删除或添加任务），其他会话需要重新加载文件才能看到变更
冲突处理：如果两个会话几乎同时修改文件，后写入的修改会覆盖先写入的。这是目前系统采用的"最后写入者胜出"策略

在团队协作场景中，建议指定一个明确的主管理会话，避免多人同时修改持久化任务配置导致混乱。如果需要进行任务转移或交接，确保先导出当前任务列表再由另一方导入。