管理任务

存储任务的日常操作：可直接复制的 CLI 示例、管理命令、运行历史语义，以及 cron.* 配置键。属于 Automations 指南的一部分。

CLI 示例¶

openclaw automations add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

openclaw automations create "0 7 * * *" \
  "Summarize overnight updates." \
  --name "Morning brief" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw automations add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Weekly deep analysis of project progress." \
  --model "opus" \
  --thinking high \
  --announce

openclaw automations create "0 18 * * 1-5" \
  "Summarize today's deploys as JSON." \
  --name "Deploy digest" \
  --webhook "https://example.invalid/openclaw/cron"

openclaw automations create "*/15 * * * *" \
  --name "Queue depth probe" \
  --command "scripts/check-queue.sh" \
  --command-cwd "/srv/app" \
  --announce \
  --channel telegram \
  --to "-1001234567890"

管理任务¶

在 Control UI 中，当调度器事件到达时，已打开的自动化会刷新其下次运行时间和条件活动。这些运行时更新会保留未保存的设置以及用于冲突检测的已保存定义，即使所选自动化位于当前列表页面或筛选条件之外也是如此。

对话式管理¶

在 commands.ownerAllowFrom 中明确列出的已认证频道发送者，或具有 operator.admin 的 Control UI 管理员，可以要求代理列出、检查、更新、运行或移除该 Gateway 上的任何现有自动化，无论其创建者或频道是什么。例如，可以要求它禁用一个在 Telegram 中创建的提醒。这与 Automations 页面上管理员的权限一致。通过 operator CLI 或 Gateway API 创建命令负载。

新的已认证 Control UI 管理员轮次也可以通过聊天创建普通自动化，包括在当前对话中带有 timeoutSeconds: 0 的周期性代理轮次。创建会保留调用方的账户/会话所有权以及已捕获的工具限制。远程管理不会授予本地主机或 provider 读取权限，也不会授予捕获新的 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 退出。完成失败或未知以及等待超时会以非零值退出。

立即运行的投递会从手动请求被接受时开始衡量延迟。旧的待处理计划槽位不会使其新输出过期；自动运行和 --due 运行在该检查中保留原始计划时间。手动运行仍会保留任务的重复周期或未来一次性触发。

运行一个已暂停的未来一次性任务会使其保持暂停，并保留其已保存的触发时间。如果需要自动执行，请重新启用它。如果手动运行在计划时间之前被接受，但在命令队列中等待超过了该时间，那么该触发在重新启用或重启 Gateway 后仍可用。

运行历史在 status（ok、error 或 skipped）中保留负载执行状态，并在 completionStatus（succeeded、failed 或 unknown）中保留整个运行的完成状态。除非已接纳的任务显式设置 delivery.bestEffort: true，否则请求的投递是必需的；仅投递失败会使执行保持 status: "ok"，不会增加执行错误计数器或进入重试退避，并记录 completionStatus: "failed"。没有投递身份的适配器发送会保持 unknown，不会进行可能导致消息重复的自动重发。

Control UI 运行历史在执行成功但整个运行完成失败或仍未知时，显示 OK · Error 或 OK · Unknown。其状态筛选器仍选择执行状态。

运行历史在所选历史不可用时显示加载指示器。失败的请求会显示错误和一个 重试 按钮；同一选择下先前加载的运行仍保持可见。空历史提示仅在成功请求确认当前选择和筛选条件下没有运行后出现。

在某个运行上选择 查看转录 以读取该运行记录的对话，包括较早的页面。当调度器复用其会话别名时，转录选择仍绑定到记录的运行。Gateway 客户端使用带有任务 id 以及精确 runId 或 runAtMs 的 cron.history；响应包含 messages、可选的 activity 和不透明的 nextCursor。缺失或含糊的运行记录仍保持不可用，而不是打开另一个运行。所选运行标识其记录的对话世代：隔离运行具有新的世代，而自定义会话在多次运行之间保留其共享对话历史。当前任务和会话权限适用于每一页。

有意静默（NO_REPLY）、有意为空的输出、心跳确认以及频道回复转换会记录 deliverySuppressionReason，而不会声称已投递或触发投递失败告警。这些成功但未产生结果以及显式设置 delivery.bestEffort: true 的成功执行会正常删除一次性任务。传输钩子否决则会记录投递错误，而没有有意抑制原因。没有最终回复的活跃后代、过期的中间输出以及被 TTS 清空的输出则会记录投递错误。保留的一次性任务不会自动重新运行；在重试或删除它们之前，请检查其历史和投递结果。

直接 Gateway 事件源可以使用带有 mode: "if-enabled" 的 cron.run 立即运行，而不会覆盖操作员禁用或自动禁用的任务。显式的操作员立即运行命令仍继续使用 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 时间戳），后跟位置参数代理提示。在 automations add|create 或 automations edit 上使用 --webhook <url>，可将完成的运行负载 POST 到 HTTP 端点；webhook 投递不能与聊天投递标志（--announce、--channel、--to、--thread-id、--account）组合使用。在 automations edit 上，--clear-channel、--clear-to、--clear-thread-id 和 --clear-account 会分别取消设置这些路由字段（每个都会与其对应的设置标志一起被拒绝）——这与 --no-deliver 不同，后者仅禁用运行器回退投递。

Webhook URL 仍受严格出站策略约束；如需有意指向本地或私有接收方，请配置 cron.webhookSsrfPolicy。

在控制界面中清除 超时（秒） 并保存后，将移除已保存的覆盖值，恢复默认运行时预算。对于 API 客户端，cron.update 载荷补丁使用数字设置超时，使用 timeoutSeconds: null 清除超时，并在省略 timeoutSeconds 时保留已保存的值。新任务省略该字段以使用默认值；null 仅作为更新指令。

配置¶

{
  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 会在自动化 webhook POST 请求中作为 Authorization: Bearer <token> 发送。 Webhook URL 不得包含嵌入的用户名/密码凭据；当接收方支持 Bearer 认证时，请使用 webhookToken。 webhookSsrfPolicy 适用于所有出站自动化 webhook，省略时采用严格策略。优先使用范围较窄的 allowedHostnames 条目，而不是宽泛的 dangerouslyAllowPrivateNetwork 选择加入。

自动化任务、运行历史以及被隔离的格式错误任务都存储在共享的 SQLite 状态数据库中。请使用 CLI 或 Gateway API 修改任务；cron.store 已弃用。

设置 cron.skipMissedJobs: true 可跳过在 Gateway 离线期间错过的周期性（cron 和 every）时间槽。启动时，这些任务会推进到下一个未来发生时间，而不是补跑，从而避免过期提醒和不必要的模型调用，代价是丢弃错过的工作。默认值为 false（补跑）；一次性（at）任务无论如何都保留其正常的补跑行为。