管理任务
存储任务的日常操作:可直接复制的 CLI 示例、管理命令、运行历史语义以及 cron.* 配置键。属于 Automations 指南的一部分。
CLI 示例¶
管理任务¶
在 Control UI 中,当调度器事件到达时,已打开的自动化会刷新其下次运行时间和条件活动。这些运行时更新会保留未保存的设置以及用于冲突检测的已保存定义,即使所选自动化不在当前列表页或筛选范围内也是如此。
对话式管理¶
在 commands.ownerAllowFrom 中明确列出的已认证频道发送者,或具有 operator.admin 的 Control UI 管理员,可以要求代理列出、检查、更新、运行或移除该 Gateway 上的任何现有自动化,无论其创建者或频道是什么。例如,可以要求它禁用一个在 Telegram 中创建的提醒。这与管理员在 Automations 页面上的权限一致。通过 operator CLI 或 Gateway API 创建命令负载。
新的已认证 Control UI 管理员轮次也可以通过聊天创建普通自动化,包括在当前对话中带有 timeoutSeconds: 0 的周期性代理轮次。创建会保留调用者的账户/会话所有权以及已捕获的工具限制。远程管理不会授予本地主机或 provider-read 权限,也不会授予捕获新的 configured-MCP 执行权限的许可。不完整的工具捕获仍然会阻止继承未捕获的工具表面。
Gateway 会根据已认证轮次的准入事实授予此权限。每个操作使用一次性授权,该授权在 60 秒后过期,并始终绑定到该确切的活动运行。当使用此能力时,以及在任何变更提交之前,都会针对当前全局所有者列表重新检查频道所有者成员资格。频道允许列表、通配符条目、显示名称、账户 ID 和会话路由不会确立所有权。其他频道轮次以及没有 operator.admin 的 Control UI 轮次不会获得管理授权。如果访问被拒绝或授权过期,请从新的已认证配置频道所有者或 Control UI 管理员轮次重试,或使用 Automations 页面。
当已准入的所有者或管理员轮次使用 sessions_yield 等待其子代理时,经过验证的请求者延续会保留该任务的自动化管理权限。它会为新的运行获得新的授权;原始运行的授权会正常过期。该延续仍仅限管理;它不能捕获新的创建者执行权限。将频道发送者从全局所有者列表中移除、取消、会话重置或归档、新的直接用户轮次以及 Gateway 重启会使交接失效。普通的跨会话消息和子结果不会授予管理访问权限。
每个管理员管理请求都会将其方法、运行、操作实例以及成功或失败记录在 Gateway 的 cron: admin management 日志中,与普通工具审计记录并列。管理权限不会转移创建者归属,也不会替换任务的计划执行策略。
CLI 管理¶
对于缺少创建者账户元数据的旧自动化,请运行 openclaw doctor --fix。
Doctor 仅在存储的创建者身份能够证明该账户时才会协调账户,
并报告修复情况。匹配的创建者会话随后可以更新代理
提示,而无需提供新的工具上限。现有工具权限和创建者
归属保持不变;无上限任务保留其旧版执行策略。
显式权限编辑仍需要匹配的所有者权限。存储身份
无法证明账户的任务需要已认证管理员恢复;
Doctor 不会从投递设置或当前调用者推断所有权。
# List enabled jobs
openclaw automations list
# Include disabled jobs
openclaw automations list --all
# Get one stored job as JSON
openclaw automations get <jobId>
# Show one job, including resolved delivery route
openclaw automations show <jobId>
# Enable/disable without deleting
openclaw automations enable <jobId>
openclaw automations disable <jobId>
# Edit a job
openclaw automations edit <jobId> --message "Updated prompt" --model "opus"
# Force run a job now
openclaw automations run <jobId>
# Force run a job now and wait for its terminal status
openclaw automations run <jobId> --wait --wait-timeout 10m --poll-interval 2s
# Run only if due
openclaw automations run <jobId> --due
# View run history
openclaw automations runs <jobId> --limit 50
# View one exact run
openclaw automations runs <jobId> --run-id <runId>
# Delete a job
openclaw automations remove <jobId>
# Agent selection (multi-agent setups)
openclaw automations create "0 6 * * *" "Check ops queue" --name "Ops sweep" --session isolated --agent ops
openclaw automations edit <jobId> --clear-agent
归档会话(Control UI,或使用来自 sessions.list 的持久 ID 调用 sessions.patch { key, archived: true, expectedSessionId })会禁用绑定到该会话的所有已启用自动化任务:其隔离的 cron:<jobId> 会话、session:<key> 目标,或投递/唤醒 sessionKey 通道。恢复会话需要相同的已观察身份,并且不会重新启用这些任务;请使用 openclaw automations enable <jobId>。具有已启用绑定任务的会话会在 Control UI 侧边栏中显示时钟徽章。
openclaw automations run <jobId> 在将手动运行加入队列后返回。对于关机钩子、维护脚本或其他必须阻塞到排队运行完成的其他自动化,请使用 --wait;它会轮询返回的 runId(默认超时 10m,轮询间隔 2s),并且仅在 completionStatus: "succeeded" 时以 0 退出。完成状态为失败或未知,以及等待超时,都会以非零状态退出。
代理 automations 工具的 run 操作改为在 Gateway 中等待:当运行在调用的 timeoutMs 内结束时(默认 60 秒,上限 10 分钟),它会返回已完成的运行(状态、错误、投递状态和摘要)。更长的运行会返回其 runId;之后可使用 runs 操作和该 runId 读取它。主会话任务以及在调用会话中运行的任务会立即返回,因为它们只在调用轮次结束后才开始。
立即运行的投递会从手动请求被接受时开始衡量延迟。旧的待处理计划槽位不会使其新输出过期;自动运行和 --due 运行在该检查中保留原始计划时间。手动运行仍会保留任务的重复周期或未来一次性发生时间。
运行一个已暂停的未来一次性任务会使其保持暂停,并保留其已保存的发生时间。如果需要自动执行,请重新启用它。如果手动运行在计划时间之前被接受,但在命令队列中等待超过了该时间,那么在重新启用或重启 Gateway 后,该发生时间仍可用。
运行历史将载荷执行保存在 status(ok、error 或 skipped)中,并将整个运行的完成状态保存在 completionStatus(succeeded、failed 或 unknown)中。除非被接受的任务明确设置 delivery.bestEffort: true,否则请求的投递是必需的;仅投递失败会使执行 status: "ok",不会增加执行错误计数器或进入重试退避,并记录 completionStatus: "failed"。没有投递身份的适配器发送保持为 unknown,不会进行可能导致消息重复的自动重发。
一旦成功的一次性任务消耗了其计划发生时间,其完成事件和运行历史就会省略 nextRunAtMs,包括任务自动删除时。保留未来发生时间的提前手动运行仍会报告该发生时间。
Control UI 运行历史在执行成功但整个运行完成失败或仍未知时,会显示 OK · Error 或 OK · Unknown。其状态筛选器仍选择执行状态。
当所选历史不可用时,运行历史会显示加载指示器。失败的请求会显示错误和一个 重试 按钮;同一选择下先前加载的运行仍保持可见。空历史提示仅在成功请求确认当前选择和筛选条件下没有运行后出现。
在某个运行上选择 查看转录,以读取该运行记录的对话,包括较早的页面。当调度器复用其会话别名时,转录选择仍绑定到记录的运行。Gateway 客户端使用 cron.history 并传入任务 id 以及精确的 runId 或 runAtMs;响应包含 messages、可选的 activity 和不透明的 nextCursor。缺失或含糊的运行记录仍保持不可用,而不是打开另一个运行。所选运行标识其记录的对话代:隔离运行具有新的代,而自定义会话在多次运行之间保留其共享对话历史。当前任务和会话权限适用于每一页。
有意静默(NO_REPLY)、有意为空输出、心跳确认和频道回复转换会记录 deliverySuppressionReason,而不会声称已投递或触发投递失败警报。这些成功的非结果以及明确设置 delivery.bestEffort: true 的成功执行会正常删除一次性任务。传输钩子否决则会记录投递错误,而没有有意抑制原因。没有最终回复的活动后代、过期的中间输出以及被 TTS 清空的输出则会记录投递错误。保留的一次性任务不会自动重新运行;在重试或删除它们之前,请检查其历史和投递结果。
直接 Gateway 事件源可以使用 cron.run 并设置 mode: "if-enabled",立即运行而不会覆盖操作员禁用或自动禁用的任务。显式的操作员立即运行命令仍继续使用 force。
重新启用自动禁用的任务或已耗尽的流会重置其失败计数器。协调 declarationKey 的 API 客户端可以通过显式 enabled: true 执行相同操作;省略启用状态的常规声明会保留已停止的任务,常规协调会保留现有失败连续计数。
代理 automations 工具从 automations(action: "list") 返回紧凑的任务摘要(id、name、enabled、effectiveAgentId、nextRunAt、nextRunAtMs、scheduleKind、lastRunAt、lastRunStatus)。effectiveAgentId 标识已解析的执行所有者,或在所有权未解析时为 null。运行日期是精确的 ISO 时间戳,或在缺失时为 null;毫秒字段仍可供编程调用方使用。基于时间的任务还包括其精确的 schedule(at、every 或 cron),包括没有下次运行的已禁用任务。事件驱动的计划、载荷和投递定义仍被省略;使用 automations(action: "get", jobId: "...") 获取一个完整任务定义。直接 Gateway 调用方可以向 cron.list 传递 compact: true;省略它会保留包含投递预览的完整响应。cron.add 在创建的任务上包含相同的试运行预览,以便创建时输出指明已解析的路由或失败关闭结果。
openclaw automations create 是 openclaw automations add 的别名。新任务可以使用位置参数形式的计划("0 9 * * 1"、"every 1h"、"20m" 或 ISO 时间戳),后跟位置参数形式的 agent 提示。在 automations add|create 或 automations edit 上使用 --webhook <url>,可将完成的运行 payload POST 到 HTTP 端点;webhook 投递不能与聊天投递标志(--announce、--channel、--to、--thread-id、--account)组合使用。在 automations edit 中,--clear-channel、--clear-to、--clear-thread-id 和 --clear-account 会分别取消设置这些路由字段(每个清除标志都会与其对应的设置标志一起被拒绝)——这与 --no-deliver 不同,后者仅禁用 runner 回退投递。
Webhook URL 仍受严格出站策略约束;如有意使用本地或私有接收方,请配置 cron.webhookSsrfPolicy。
在 Control UI 中清除 超时(秒) 并保存,会移除已保存的覆盖值,恢复默认运行时预算。对于 API 客户端,cron.update payload 补丁使用数字设置超时,使用 timeoutSeconds: null 清除超时,并在省略 timeoutSeconds 时保留已保存的值。新任务省略该字段以使用默认值;null 仅作为更新指令。
Note
模型覆盖说明:
openclaw automations add|edit --model ...更改任务所选模型。- 如果模型被允许,该确切的 provider/model 会传递到隔离的 agent 运行。
- 如果未被允许或无法解析,调度器会以明确的验证错误使运行失败。
- API
cron.updatepayload 补丁可以设置model: null以清除已存储的任务模型覆盖。 openclaw automations edit <job-id> --clear-model从 CLI 清除该覆盖(与model: null补丁效果相同),且不能与--model组合使用。- 已配置的回退链仍然适用,因为 automation 的
--model是任务主模型,而不是会话/model覆盖。 openclaw automations add|edit --fallbacks ...设置 payloadfallbacks,替换该任务已配置的回退;--fallbacks ""禁用回退并使运行严格。openclaw automations edit <job-id> --clear-fallbacks清除按任务的覆盖。- 没有显式或已配置回退列表的普通
--model不会作为静默的额外重试目标回落到 agent 主模型。
配置¶
{
cron: {
enabled: true,
triggers: {
enabled: false,
},
webhookToken: "replace-with-dedicated-webhook-token",
webhookSsrfPolicy: {
allowedHostnames: ["127.0.0.1"], // optional exact exception for a trusted receiver
},
sessionRetention: "24h",
},
}
webhookToken 会在 automation webhook POST 中作为 Authorization: Bearer <token> 发送。
Webhook URL 不得包含内嵌的用户名/密码凭据;当接收方支持 Bearer 认证时使用
webhookToken。
webhookSsrfPolicy 适用于每个出站 automation webhook,省略时严格。优先使用范围较窄的
allowedHostnames 条目,而不是宽泛的 dangerouslyAllowPrivateNetwork 选择加入。
Automation 任务、运行历史以及被隔离的格式错误任务都存储在共享 SQLite 状态数据库中。使用 CLI 或 Gateway API 修改任务;cron.store 已弃用。
设置 cron.skipMissedJobs: true 以跳过 Gateway 离线期间错过的周期性(cron 和 every)时间槽。启动时,这些任务会推进到下一次未来发生时间,而不是补跑,从而避免过期提醒和不必要的模型调用,代价是丢弃错过的工作。默认值为 false(补跑);一次性(at)任务无论如何都保留正常的补跑行为。
禁用 automations:cron.enabled: false 或 OPENCLAW_SKIP_CRON=1。
重试行为
一次性重试:瞬时错误(速率限制、过载、网络、超时、服务器错误)使用内置重试计划。永久错误会立即禁用任务。
周期性重试:连续执行错误会按扩展计划退避(30s、60s、5m、15m、60m)。下一次成功运行后重置退避。
维护
cron.sessionRetention(默认 24h,false 或 "0h" 禁用)会修剪隔离的运行会话条目。终态运行历史保留 7 天(lost 行保留 24 小时),并按每个任务和历史类别强制执行最新 2000 行作为额外上限。
Gateway 保留策略在首次清扫前会等待延迟的 agent 数据库启动准备,并将等待记录为有意延迟。即使禁用计划执行,保留策略仍会继续。
会话保留会跳过待删除或已完成删除的 agent,同时继续维护健康 agent。待删除清理仍由 agent 删除操作负责。
旧存储迁移
openclaw doctor --fix 会将受支持的 jobs-quarantine.json 伴随文件导入 SQLite,并以 .migrated 后缀归档原始文件。已弃用的 jobs.json、jobs-state.json 和 runs/*.jsonl 输入保持不变:安装 OpenClaw 2026.9.7,运行其 Doctor,然后升级到最新版本。参见保留策略。格式错误的 SQLite 任务行仍可在隔离区中恢复,同时有效任务继续运行。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw