OpenClaw Cron安全约束完整详解

一、定位与原生风险背景

Cron安全约束属于 UpClaw「调度自动化、并发安全、安全隔离、权限合规」四大板块，与前文 CronContextHolder、SessionLock、Per-Request 三位一体构成后台定时任务完整安全底座；管控两类定时载体：

1. 网关内置Scheduler调度器通过cron.add创建持久定时任务；
2. 会话内HEARTBEAT.md驱动的会话绑定后台心跳任务。

定时任务原生高危风险（约束要解决的核心问题）

1. 资源抢占风险：后台批量归档、上下文压缩、报表任务与前台用户会话争抢算力，导致聊天响应卡顿；
2. 竞态数据错乱：定时任务与用户消息并发读写同一会话上下文、LongTermMemory，引发视图撕裂；
3. 权限逃逸风险：AI自主调度定时任务，持续后台执行、自我修改MD配置、持久化后门；
4. 重复执行/雪崩风险：任务超时未退出，下一轮调度再次触发，多实例集群重复跑批；
5. 上下文污染风险：定时任务复用前台会话上下文，造成租户、trace、权限串扰；
6. 无审计、无熔断：后台静默执行，异常无限循环调用模型、工具产生巨额成本。

Cron安全约束整体分为五层纵深防护体系：

1. 执行上下文隔离（CronContextHolder）
2. 会话锁抢占规则（非阻塞抢占、优先保障前台流量）
3. 任务生命周期管控（防并发、防雪崩、超时熔断）
4. 权限与工具收缩（最小权限、禁止高危操作）
5. 观测、审计与熔断兜底

核心设计原则：前台用户流量优先，后台定时任务退让；定时任务默认隔离、默认权限收紧；禁止定时任务随意侵入主会话状态。

二、第一层：CronContextHolder 上下文隔离约束（基础边界）

前文并发安全中介绍的CronContextHolder是所有安全约束的载体，建立与前台Per-Request物理隔离边界。

1. 两种上下文类型

• 全局独立Cron上下文：不属于任何会话（全局记忆清理、系统巡检、跨租户报表）
• 会话绑定Cron上下文 ：归属sessionId（会话心跳、定时后台压缩、过期记忆清理）

2. 强制隔离约束规则

1. Cron上下文永远不直接复用前台Per-Request原始引用；不会继承前台请求全部上下文快照；
2. 标记context_type = cron，四层Langfuse追踪自动区分前台用户流量/后台定时流量；
3. 定时任务内部产生的日志、Span、告警独立标签，便于成本分摊、故障排查；
4. 禁止定时任务直接向主会话推送系统事件（开关disable_system_event），防止定时输出污染用户对话窗口；
5. 会话绑定Cron上下文仅拥有会话只读快照权限，默认不允许直接修改会话可变状态。

3. 与防污染体系联动

定时任务操作会话上下文时，必须经过副本拷贝；修改完成后受控回写，避免一边用户聊天一边后台修改上下文造成ContextEngine视图撕裂。

三、第二层：SessionLock 抢占规则（优先级调度约束，核心）

最关键生产约束：前台会话消息拥有锁抢占优先权；定时任务使用【非阻塞尝试获取锁】模式。

1. 标准抢占逻辑

1. 用户消息入站：阻塞式抢占SessionLock，排队模式持续等待直至拿到锁；
2. Cron定时心跳/后台任务：tryLock()非阻塞抢占
   • ✅ 获取锁成功 → 执行压缩、记忆归档、会话清理；
   • ❌ 获取锁失败（会话正在处理用户消息）→ 直接跳过本轮执行，等待下一个调度周期。

2. 可配置策略分支（ConditionalOnProperty切换）

claw.scheduler.cron.sessionLockStrategy:
  # skip：默认生产，抢不到锁直接跳过（推荐）
  # wait_short：最多短暂等待N秒，仍失败则跳过（低并发内部场景）
  mode: skip
  maxWaitMs: 2000

3. 边界规则

1. 锁持有超时复用全局sessionLockTimeout，防止定时任务卡死会话；
2. 定时任务持有锁期间，不阻断新用户消息进入会话等待队列；
3. 全局独立Cron任务（不绑定任何session）不参与SessionLock，受全局调度线程池限流管控。

解决故障场景

用户正在持续对话，后台定时上下文压缩不会抢占会话锁、不会打断用户推理；杜绝前台响应延迟抖动，完美适配IM聊天场景。

四、第三层：任务生命周期安全约束（防并发、防雪崩、幂等）

4.1 单机防并发执行（单任务互斥锁 ActiveJobMarker）

每一条定时任务拥有唯一jobId + generation标记；Gateway重启自动递增generation，旧标记自动失效，解决进程重启后死标记永久阻塞问题。

规则：同一个job同一时刻只能运行一个实例

• 到达调度时间，先检查Marker；任务正在运行则直接跳过本次触发；
• 任务正常完成/异常终止自动清除Marker；
• 任务卡死超时，后台清扫线程自动失效Marker，避免永久阻塞调度。

4.2 资源配额约束

1. 全局定时任务线程池上限 scheduler.maxConcurrentCronJobs，防止大量定时任务瞬间并发耗尽网关算力；
2. 单任务最大执行超时 job.timeoutSeconds，超时强制kill执行链路，释放沙箱、模型连接；
3. 单会话最多并发定时任务数量，防止单个会话大量心跳任务堆积。

4.3 调度雪崩防护（阶梯退让+最大重试管控）

1. 任务执行失败：支持指数退避重试，但配置最大重试次数；到达上限停止重试并告警；
2. 禁止短周期高频定时（最小间隔保护，默认≥60s，可配置），防止AI生成每秒执行的恶意定时；
3. 批量类后台任务支持分片限速，禁止一次性全量扫描所有会话。

4.4 会话目标隔离约束（sessionTarget三模式管控）

创建定时任务时强制指定执行会话模式，防止任务随意挂载会话：

1. isolated【推荐生产】：在独立隔离cron会话执行，不挂载用户主会话；后台报表、安全扫描、批量处理首选；
2. session_attached：绑定指定主会话（仅限心跳、会话专属压缩）；受SessionLock非阻塞规则严格管控；
3. global：全局无会话任务；
   ❌ 禁止定时任务随意注入任意未知会话。

重大风险防控：限制AI通过cron.add只能创建isolated隔离会话任务；禁止AI直接创建session_attached绑定主会话的定时任务，防止Agent安排后台持续修改自身rules/SOUL.md实现自我修改逃逸。

五、第四层：权限、工具与操作约束（最小权限纵深）

5.1 定时任务独立权限剖面（区别于前台Agent权限）

1. Cron任务默认启用工具权限收缩：自动剔除高危工具组（shell/exec、文件删除、数据库DDL）；
2. 支持配置cron.allowToolGroups白名单，仅开放记忆读写、报表查询等安全工具；
3. 定时任务执行代码沙箱时，强制启用最严格双层沙箱防护（正则前置拦截+强化Preamble+unprivileged账号）；

5.2 HEARTBEAT.md 约束配套

心跳定时脚本遵循两条硬性规则：

1. 心跳逻辑只能执行运维清理类操作（归档、压缩、过期回收），禁止主动发起对外业务调用、消息推送；
2. 心跳不允许调用spawn_subagent创建子代理，防止定时触发无限多子代理。

5.3 定时任务创建准入控制（防AI恶意注册定时）

由rules.md + ConditionalOnProperty双重管控：

1. cron.requireReview: true：AI通过工具创建定时任务，必须人工二次审批；
2. cron.maxUserCreatedJobs：限制单个Agent最多创建用户自定义定时数量；
3. 黑名单规则：禁止创建间隔<30s高频任务；禁止定时任务执行删除、内网扫描类高危指令。

5.4 记忆读写隔离约束

1. 全局定时任务只能访问全局共享只读记忆视图，禁止跨租户写入记忆；
2. 会话绑定定时任务读写LongTermMemory时，启用版本校验，防止覆盖前台会话新产生对话；
3. 定时写入记忆自动附加source=cron标签，便于审计区分人工交互/后台自动写入。

六、第五层：观测、审计、熔断兜底约束

6.1 四层Langfuse追踪完整埋点

所有Cron动作生成独立Span：

1. CronScheduleSpan：任务触发、是否因锁抢占失败跳过、并发拦截；
2. CronExecutionSpan：完整执行链路、工具调用、记忆读写；
3. 标签统一携带：context_type=cron、jobId、sessionTarget；
4. 区分：正常跳过、执行成功、超时终止、权限拦截、工具黑名单拦截。

6.2 独立告警策略

1. 定时连续多次执行失败 → 推送运维告警；
2. 定时任务持续占用大量Token、长时间运行 → 资源超限告警；
3. 检测AI自主创建高危定时任务（高频、绑定主会话、包含高危工具）→ 安全告警。

6.3 紧急全局熔断开关

通过ConditionalOnScheduler总开关：

claw.plugin.scheduler.enable: true
# cron.globalBlock: true 紧急情况下一键暂停所有定时任务

发生算力失控、数据错乱时，无需重启网关，直接全局冻结所有后台定时任务。

七、Cron安全约束完整标准执行时序（会话绑定心跳任务示例）

Scheduler到达调度时间
        ↓
1. 创建CronContextHolder（独立后台上下文，标记context_type=cron）
        ↓
2. 检查ActiveJobMarker：任务正在运行 → 直接跳过，流程结束
        ↓
3. 尝试非阻塞抢占 SessionLock(sessionId)
    ├─ 获取失败（用户正在聊天）→ 标记【因前台会话繁忙跳过本轮】写入Span，结束
    └─ 获取锁成功
        ↓
4. 权限校验：加载cron工具白名单，收缩高危工具
        ↓
5. 执行心跳逻辑（后台压缩/记忆归档）
        ↓
6. 所有工具调用、记忆读写全链路埋点至Langfuse
        ↓
7. 任务完成/超时终止
        ↓
8. 清除ActiveJobMarker、释放SessionLock
        ↓
9. 销毁CronContextHolder，释放所有临时资源

八、与OpenClaw全体系联动汇总

1. 联动 并发安全（Per-Request + SessionLock）

• Per-Request：前台流量标准上下文模型；
• CronContextHolder：后台定时隔离模型；
• SessionLock：优先级调度，前台优先，定时非阻塞抢占。

2. 联动 SubAgent 三层安全约束

定时任务默认禁止spawn_subagent；如需启用，必须在rules.md显式放开，同时限制子代理最大深度、工具权限。

3. 联动 Context Compaction

后台定时压缩由Cron任务承载；受非阻塞锁管控，不会抢占用户会话；压缩执行遵循完整四阶段流水线+反抖动+CJK优化。

4. 联动三层Tool治理

定时任务自动收紧工具白名单，高危工具组默认黑名单；代码执行启用强化双层沙箱防护。

5. 联动 12+ ConditionalOnProperty

可按环境、租户、Agent精细化开关：

• ConditionalOnGlobalEnv：离线环境关闭非必要定时；
• ConditionalOnAgentName：客服Agent开启会话定时归档，简易闲聊Agent关闭；
• ConditionalOnTenant：金融租户限制定时仅可查询，禁止修改类操作。

6. 联动六层提示词工程

定时任务运行加载独立精简MD基线；不会加载主会话完整六层提示词，防止大量静态基线Token消耗。

九、优缺点总结

优势

1. 流量优先级隔离，保障前台IM聊天体验，后台任务自动退让；
2. 多层隔离杜绝定时任务与前台会话上下文竞态、数据错乱；
3. 防并发、防重复跑批、防定时雪崩，控制算力成本；
4. 权限自动收缩，限制AI自主创建恶意持久后台任务，防止逃逸与自我修改；
5. 前后台流量观测分层，便于成本核算、故障定位；
6. 全部约束可配置，区分开发/测试/生产环境。

短板

1. 非阻塞跳过机制导致定时任务有可能延迟执行（业务可接受的前提下换取用户体验优先）；
2. 配置项较多，初期需要合理划分任务使用isolated还是session_attached模式；
3. 集群多网关部署时，内置单机锁无法跨节点防重复执行；大规模分布式场景需要额外引入分布式锁扩展。

十、横向对比：原生AgentScope / Codex / Claude Code

1. 原生AgentScope
   无标准化Cron上下文；定时任务与前台共用一套上下文；无会话锁优先级机制；无权限自动收缩；极易出现并发争抢、上下文污染，仅适合本地原型调试。
2. OpenAI Codex
   不存在持久定时调度体系，任务都是单次临时执行，没有后台常驻心跳模型，不存在Cron安全约束场景。
3. Claude Code
   本地单进程运行，无网关调度层、无会话持久会话概念，缺少企业级后台定时安全管控模型。
4. OpenClaw Cron安全约束
   专为7×24小时常驻多租户Agent中台设计，形成「上下文隔离→锁优先级调度→生命周期防雪崩→权限收缩→观测审计」完整五层安全闭环，是支撑长会话后台自动化可上线必备能力。

十一、典型风险落地案例

案例1：定时后台压缩频繁抢占会话，用户回复延迟大

根因：定时任务使用阻塞等待锁；

修复：启用默认skip模式，会话繁忙时自动跳过本轮压缩，优先保障用户对话。

案例2：AI自主创建每分钟执行的定时任务，持续调用接口产生高额费用

根因：未限制用户创建定时任务频率、无审批开关；

修复：开启cron.requireReview=true，限制最小调度间隔，禁止高频定时。

案例3：定时任务读写会话记忆，和用户并发聊天导致历史对话错乱

根因：定时任务直接复用前台上下文，无副本隔离；

修复：强制使用独立CronContextHolder，记忆读写采用副本+受控回写机制。

十二、生产最佳实践规范

1. 所有后台批量任务优先使用 sessionTarget=isolated 独立定时会话，不要绑定主会话；
2. 会话心跳、定时压缩等绑定会话任务，保留默认skip锁抢占策略；
3. 生产环境开启cron.requireReview，禁止AI无审批创建定时；
4. 严格限制定时任务可用工具组，默认关闭shell、文件删除、DDL修改工具；
5. 定时任务执行超时统一设置上限，避免无限占用资源；
6. Langfuse设置告警规则，监控大量定时任务被跳过、连续执行失败场景。