配置 — 自动化和媒体模板变量

位于 cron.* 下的计划自动化键，以及媒体模型模板变量表面。

完整的键索引以及其他顶层配置域，请参阅配置参考。

自动化（cron）¶

{
  cron: {
    enabled: true,
    triggers: {
      enabled: true,
    },
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    webhookSsrfPolicy: {
      allowedHostnames: ["127.0.0.1"], // optional exact exception for a trusted receiver
    },
    sessionRetention: "24h", // duration string ("0h" disables) or false
  },
}

• enabled：执行已存储的自动化任务（默认：true）。设置为 false 可暂停所有自动化执行，而不会删除任务。
• skipMissedJobs：在启动时跳过错过的周期性（cron/every）时间槽，并推进到下一个未来发生时间（默认：false）。一次性（at）补跑行为保持不变。
• triggers.enabled：运行事件驱动的自动化触发器（默认：true）。设置为 false 可禁用条件触发器、脚本负载和流式计划。
• sessionRetention：在清理 SQLite 会话行之前，保留已完成的隔离自动化运行会话的时间。它还控制已归档的已删除自动化转录的清理。默认：24h；设置为 false 或零时长（如 "0h"）可禁用（负时长无效）。
• 终端运行历史保留 7 天（lost 行保留 24 小时），并且每个任务和历史类别强制以最新的 2000 行作为额外上限。
• webhookToken：用于自动化 webhook POST 投递的 bearer token（delivery.mode = "webhook"）；如果省略，则不发送认证头。
• webhookSsrfPolicy：主 webhook、完成 webhook、失败目标 webhook 和失败告警 webhook 共用的出站 SSRF 策略。省略时，私有/内部目标会被阻止。优先使用精确的 allowedHostnames；仅对受信任的私有网络接收方使用 dangerouslyAllowPrivateNetwork: true。窄范围的 fake-IP 代理标志为 allowRfc2544BenchmarkRange 和 allowIpv6UniqueLocalRange。
• webhookSsrfPolicy.blockedHostnames：在 DNS 和所有允许规则之前拒绝精确主机和通配符子域。*.example.com 不包含根域；需单独添加 example.com 才能阻止它。为空或未设置时不会添加任何拒绝项。

cron 块是严格的；cron.enabled、cron.skipMissedJobs、cron.triggers、cron.webhookToken、cron.webhookSsrfPolicy、cron.sessionRetention 和 cron.failureAlert 是唯一接受的键。已弃用的 cron.webhook 回退 URL 已移除：运行时投递使用每个任务的 delivery.mode = "webhook" 加上 delivery.to，或在保留 announce 投递时使用 delivery.completionDestination。openclaw doctor --fix 会从现有配置文件中移除遗留的 cron.webhook。

cron.failureAlert¶

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 2,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

cron.failureAlert 拥有全局告警策略及其默认目标。具有现有失败路由的任务默认在连续 2 次执行失败后受到覆盖，冷却时间为 1 小时；即使不存在路由，cron.failureAlert 对象也会显式激活/调整该策略。已弃用的 cron.failureDestination 块会通过 openclaw doctor --fix 合并到其中。

• enabled：显式启用或禁用全局策略。false 会禁用继承的通知，除非任务有自己的 failureAlert 对象；true 会显式全局启用。省略它会保留基于路由的默认值。
• after：触发告警前的连续失败次数（正整数，最小值：1；默认：2）。
• cooldownMs：同一任务重复告警之间的最小毫秒数（非负整数；默认：3600000）。
• includeSkipped：将连续跳过的运行计入告警阈值（默认：false）。跳过的运行会单独跟踪，并且不影响执行错误退避。
• mode：投递模式 - "announce" 通过频道消息发送；"webhook" 发布到 to 中的目标。当存在足够的目标数据时，默认为 "announce"。
• channel：announce 投递的频道覆盖。"last" 复用最后已知的投递频道。
• to：显式 announce 目标或 webhook URL。webhook 模式必需。
• accountId：可选的账户或频道 id，用于限定告警投递范围。
• 路由优先级依次为：每个任务的 failureAlert 路由字段，然后是每个任务的 delivery.failureDestination 叠加在这些全局目标字段之上，最后是主 announce 目标。
• 每个任务的 failureAlert: false 会禁用该任务的执行和必需投递失败告警；自动禁用的安全通知仍然有效。任何每个任务的 failureAlert 对象都会显式启用并调整该任务。
• delivery.bestEffort: true 会抑制继承/默认的执行告警；显式的每个任务 failureAlert 仍然具有权威性。
• 必需的完成投递失败（status: "ok"、completionStatus: "failed"）不会增加执行退避，并且只能通过已解析的备用失败目标立即通知，而不是失败的主路由。
• delivery.failureDestination 仅支持 sessionTarget="isolated" 任务，除非该任务的主 delivery.mode 为 "webhook"。

参阅自动化。Cron 记录隔离自动化运行历史。

媒体模型模板变量¶

在 tools.media.models[].args 中展开的模板占位符：

旧版 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 名称在插件 SDK 兼容期内仍可用，但已弃用。新配置应使用 Attachment* 变量。