投递
一次已完成的运行将其输出发送到哪里、运行或投递失败时会发生什么,以及如何固定回复语言。属于 Automations 指南的一部分。
投递与输出¶
| Mode | 说明 |
|---|---|
announce |
如果 agent 未发送内容,则将最终文本回退投递给目标 |
webhook |
将 finished 事件负载 POST 到 URL |
none |
不进行 runner 回退投递 |
一次成功的主 webhook 运行如果没有非空摘要,会故意跳过 POST,并记录 deliverySuppressionReason: "empty",这与 announce 投递的可选输出约定一致。即使没有摘要,执行错误仍会发送错误事件。
主 webhook 在收到 HTTP 2xx 确认后记录投递。HTTP 拒绝会记录为 Not delivered(未投递)。如果请求可能已到达接收方,但其响应丢失或超时,投递状态保持为 Unknown(未知);传输层不会重试这种模糊的发送。必需投递也会使完成状态保持未知,而尽力而为的投递可以在不声称已投递的情况下成功完成。
当配置了 gateway.publicOrigin 且启用了 Control UI 时,聊天通知会包含一个指向 Control UI 的 Inspect 链接。命令和脚本完成通知会打开自动化运行;隔离 agent 的通知会打开该运行的会话。
对于使用 announce(默认方式)的 current 任务,最终 assistant 结果是一等公民的会话完成事件,而不是 WebChat 特有的出站消息。OpenClaw 会等待创建时所绑定会话中的活动 turn,验证同一个会话 generation 仍然拥有该 key,然后通过规范的 transcript writer 提交结果,并附带 cron 任务/运行来源和一个任务/运行幂等键。重试不会两次追加同一结果。
从会话创建的隔离 agent-turn 任务也会在创建时捕获该会话的 session key 和 generation。当 announce 没有显式 channel、recipient、account 或 thread,且创建会话没有记住的外部路由时,最终结果会使用相同的会话完成路径。channel: "last" 也允许此行为。该运行保留自己的隔离会话;投递其结果不会使其成为 current 运行,也不会赋予它创建会话的历史。这适用于提供创建会话的 automations 工具和 cron.add 请求。
该创建会话绑定是不可变的。编辑公开的 sessionKey 不会重定向隐式 announce 投递;请从预期的会话重新创建任务,或设置显式投递坐标。隐式 channel 投递也会在使用其路由和发送之前检查捕获的 generation,包括排队恢复时。
会话结果使用与 channel 通知相同的静默回复处理。内部控制 token 不会出现在会话历史中,而抑制标题会保留其附带的媒体。
如果运行在等待会话时被取消,它会停止等待,而不会中断活动 turn 或追加结果。
WebChat 会立即收到已提交的 session.message 事件。刷新或重新连接后,可从 chat.history 获得相同的 assistant 结果;无需后续用户消息。只有在 transcript/event 提交成功之后,投递才算成功。
对于隔离任务,如果创建会话已被删除或重置,OpenClaw 会记录投递失败,而不是将结果追加到缺失的或替代的会话。请检查运行的投递错误,并从预期的会话重新创建任务。
对于绑定会话为外部 channel 的 current 任务,OpenClaw 还会执行其正常的持久化 channel 发送。该发送仍然最多发生一次,必需的会话提交不会创建第二条外部消息。一次已验证的 message 工具发送会抑制自动 channel 重发,但不会抑制会话提交。只有在外部接收方交接(如果必需)和规范会话提交都成功后,该运行才会被报告为已投递。
当绑定会话没有外部 channel 路由——WebChat/Control UI 会话,或未配置 channel 插件的 gateway——仅会话提交即可完成投递,运行会在不尝试外部发送的情况下成功。对于 current 任务,如果会话确实指定了在运行时无法解析的外部路由,已提交的结果会保留在会话中,并且运行会将解析失败记录为其投递错误:这是投递失败,而不是 turn 失败。
对于 current agent-turn 任务,配置不相关的外部 channel 不会改变此行为。显式 delivery channel、recipient、account 或 thread 仍使用正常的 channel 解析。如果解析失败,报告会保留在会话中,并且运行会记录投递错误,即使无法选择任何外部 channel。
从 WebChat 创建 current 或 isolated agent-turn 任务时,请使用 delivery: { mode: "announce" }(或省略 delivery)。该工具不会将内部 WebChat 会话坐标复制到外部 announce 路由。不要设置 delivery.channel: "webchat";显式 channel 仍然必须通过正常的已配置 channel 验证。条件触发器使用相同的投递规则。
创建会话具有外部路由的隔离任务保留正常的 channel 投递。显式 channel、recipient、account 或 thread 设置也使用正常的 channel 解析;webhook 和 none 不变。没有捕获创建会话的隔离任务无法提交到会话中。如果其 channel 路由无法解析,或显式 channel 不可用,投递仍然会失败关闭。创建和列出操作的结果会预览会话提交或未解析路由;更新操作的结果包含未解析路由警告。对于未解析的路由,请从预期的会话重新创建任务,配置 channel 和目标,或为静默运行选择 delivery: { mode: "none" }。警告不会拒绝写入或更改投递设置。
Warning
对于主投递、完成和失败目标,以及失败告警 webhook,回环、私有/内部、链路本地以及其他特殊用途目标默认会被拒绝。每个出站自动化 webhook 都使用严格的 SSRF 防护。
仅通过精确的主机名或 IP 豁免,允许你信任的接收方:
仅当所有已配置的自动化 webhook 都可以访问受信任的私有网络服务时,才在 webhookSsrfPolicy 下使用 dangerouslyAllowPrivateNetwork: true。保持策略未设置会维持严格行为。
使用 --announce --channel telegram --to "-1001234567890" 用于频道投递。对于 Telegram 论坛主题,使用 -1001234567890:topic:123;OpenClaw 也接受 Telegram 专有的 -1001234567890:123 简写。直接 RPC/配置调用方可以将 delivery.threadId 作为字符串或数字传递。Slack/Discord/Mattermost 目标使用显式前缀(channel:<id>、user:<id>)。Matrix 房间 ID 区分大小写;请使用精确的房间 ID 或来自 Matrix 的 room:!room:server 形式。
在 Control UI 的 Automations 编辑器中,对于 announce 投递,选择一个频道,并在 高级 下选择显式的 账户 ID,即可在 收件人 字段中看到已配置的会话目标。选择目标会保留你选择的账户,并且不会推断主题。这些已配置的建议仅适用于主 announce 目标;失败告警路由仍然独立。你仍然可以输入不在建议中的目标。
在配置了多个频道的主机上,使用 automations add|create 创建或使用 automations edit 修改的隔离 announce 任务必须设置 --channel <channel-plugin-id>,除非带提供程序前缀的 --to 或保留的会话路由选择了频道。仅当可接受未解析的回退投递时使用 --best-effort-deliver;它不会选择频道,并且投递失败不会使任务失败。
频道公告仅在没有任何负载可能已到达接收方时,才会重试瞬时失败。成功的重试会记录投递,而不会保留先前尝试的错误,包括在尽力投递中。部分或模糊的发送不会被公告重试循环重放。
当 announce 投递使用 channel: "last" 或省略 channel 时,带提供程序前缀的目标(例如 telegram:123)可以在调度器回退到会话历史或单个已配置频道之前选择频道。只有已加载插件通告的前缀才是提供程序选择器。如果 delivery.channel 是显式的,目标前缀必须指定同一提供程序;channel: "whatsapp" 与 to: "telegram:123" 会被拒绝,而不是让 WhatsApp 将 Telegram ID 解释为电话号码。目标类型和服务前缀(channel:<id>、user:<id>、imessage:<handle>、sms:<number>)仍然是频道拥有的目标语法,而不是提供程序选择器。
对于隔离任务,聊天投递是共享的:如果聊天路由可用,即使使用 --no-deliver,代理也可以使用 message 工具。如果代理发送到已配置/当前目标,OpenClaw 会跳过回退 announce。否则,announce、webhook 和 none 仅控制运行器在代理轮次之后如何处理最终回复。
计划任务中的 message 操作使用拥有实时运行的 Gateway。保留任务的账户、频道、目标和已配置的投递路由,但不要提供每次调用的 gatewayUrl 或 gatewayToken 字段。普通和独立的消息调用仍可使用这些字段。要恢复一个现有受信任任务,如果其提示词或模板提供了这些字段,请仅编辑该提示词或模板以移除这两个字段,然后再次运行同一任务。Gateway 操作会报告 Scheduled message actions require the active bound Gateway. Remove per-call gatewayUrl and gatewayToken fields and retry.,直到这些字段被移除;如果没有调度器宿主绑定,它会报告 Scheduled message actions require an active bound Gateway. 请在任务所属的 Gateway 上运行该任务,而不是将连接字段复制到提示词中。下一次发送随后会使用实时绑定,包括当前取消和工具策略撤回。
当代理从活动聊天中创建隔离提醒时,OpenClaw 会为回退 announce 路由存储保留的实时投递目标。内部会话键可能是小写的;当当前聊天上下文可用时,不会从这些键重建提供程序投递目标。
隐式 announce 投递使用已配置的频道允许列表来验证并重定向过期目标。DM 配对存储中的批准不是回退自动化接收方;当计划任务应主动发送到 DM 时,请设置 delivery.to 或配置频道的 allowFrom 条目。
失败通知¶
失败告警 webhook 在请求可能已到达接收方但其响应丢失时保持 Unknown。显式的 HTTP 拒绝或可证明发生在发送之前的失败会记录 Not delivered,并允许应用内回退通知。未知结果不会触发该回退。
执行失败使用一个由调度器拥有的阈值和冷却策略。具有现有失败路由的任务在连续 2 次失败后默认适用,冷却时间为 1 小时。该路由可以是已解析的失败目标或任务的主 announce 目标。没有此类路由的任务保持静默,除非按任务或全局 failureAlert 对象显式激活该策略。
相同原因导致的重复失败构成一个事件,并且不会发送重复告警,即使冷却期结束或 Gateway 重启也是如此。原因或目标发生变化后,可以在冷却期后发送新告警。成功运行会清除事件及其冷却,而不会发送通知,因此下一次失败可以再次告警;恢复状态仍会显示在自动化历史中。跳过的运行和未知投递结果不会确认恢复。成功的静默触发检查可以恢复触发失败,但不能确认先前失败的负载已恢复。
启动恢复会根据已保存的运行结果对事件进行对账,而不会发送历史通知。即使作业状态更新被中断,已保存的成功运行也会清除旧事件,因此后续再次发生时可以再次发出警报。
失败通知路由按以下顺序解析:
- 作业的
failureAlert对象中的路由字段。 job.delivery.failureDestination,覆盖全局cron.failureAlert(mode、channel、to、accountId)中的目标字段。cron.failureDestination块不会直接读取;openclaw doctor --fix会将其合并到全局对象中。-
作业的主公告目标。
-
job.failureAlert: false会禁用该作业的执行和必需投递失败警报。自动禁用安全通知仍保持活动。 - 全局
cron.failureAlert.enabled: false会禁用继承的通知。作业级failureAlert对象可显式重新启用该作业;enabled: true显式启用全局策略。 - 即使作业原本没有路由,作业级
failureAlert对象或任何全局cron.failureAlert对象也会激活并调整策略。 delivery.bestEffort: true会抑制继承/默认的执行失败警报。显式的作业级failureAlert仍具有权威性。delivery.failureDestination仅支持sessionTarget="isolated"的作业,除非主投递模式为webhook。failureAlert.includeSkipped: true会让作业或全局自动化警报策略选择接收重复跳过运行警报。跳过的运行会单独维护连续跳过计数器,因此不会影响执行错误退避。openclaw automations edit提供作业级警报调整:--failure-alert/--no-failure-alert、--failure-alert-after <n>、--failure-alert-channel、--failure-alert-to、--failure-alert-cooldown、--failure-alert-include-skipped/--failure-alert-exclude-skipped、--failure-alert-mode以及--failure-alert-account-id。
在 Control UI 中,自定义失败警报会显示存储的阈值、冷却时间和模式覆盖。省略的频道会显示中性的 last 选项,但不会存储它。将阈值或冷却时间留空,或为警报模式选择 Inherit global setting(继承全局设置),即可使用 Gateway 正常的全局和路由默认值。冷却时间接受带毫秒精度的小数秒,包括 0 表示无冷却;例如 1.001 秒会保留 1001 毫秒。编辑其他作业字段或克隆作业会保留其警报策略,包括跳过运行设置。
必需完成投递失败与执行失败不同:一次运行可以记录 status: "ok" 但 completionStatus: "failed"。它不会增加执行失败连续次数或退避。投递失败警报可以通过解析出的备用失败目标发送通知,而无需等待 failureAlert.after。重复的投递失败也会形成单个事件。对于变化后的失败发送的警报(包括执行警报后的首次投递失败),都会遵循共享的作业/全局 failureAlert.cooldownMs(默认 1 小时);被抑制的警报仍会在运行历史中留下投递失败记录。跳过的运行和静默触发器检查不会清除投递事件或其冷却时间;成功完成才会清除。调度器永远不会为警报重试已经失败的主路由。
聊天失败通知会包含在代理配置的用户时区中的运行开始时间。当配置了 gateway.publicOrigin 且启用 Control UI 时,通知还会包含指向自动化运行的 Inspect 链接。Webhook 消息文本保持稳定;集成可以从结构化的 runAtMs 字段读取同一时间点并构建自己的链接。
聊天通知会显示规范化后的失败原因,或针对已知命令和脚本失败的允许列表中的生产者事实。任意命令、路径、提供者主体、机密、投递错误、跳过原因、诊断信息以及堆栈/错误文本仍保留在自动化历史中。失败 Webhook 会保留结构化的原始错误,供诊断集成使用。
所有者会话修复¶
修复功能默认开启。升级后,对于在聊天中发出警报的所属自动化,您看到的行为会发生变化:连续失败中的首个失败警报会变为创建该作业的会话中的修复请求,而警报则作为回退。failureAlert: false 的作业两者都不会收到。
当从会话创建的作业(具有所有者会话)达到其执行失败警报阈值,且警报原本会发送到聊天(announce 模式)时,OpenClaw 会向该所有者会话发送修复请求,而不是发送警报。该请求会指明作业,并包含其计划、名称、负载和最后错误;名称、负载和错误被标记为不可信数据。命令作业以及 on-exit 或 stream 计划仅限操作员使用,并像以前一样发出警报。
会话会像收到普通消息一样处理该请求,即作为普通的代理回合:它在该会话的会话上下文中运行,使用其对话记录、工作区和工具策略,回复会发送到会话自己的路由,包括其线程或主题。心跳设置不适用。短暂中断不会得到回复;如果问题能在工作区中修复(例如作业遵循的辅助脚本或说明文件),则修复后会附上一行说明;其他情况下,它会准确地询问您需要什么。该请求不会携带您的发送者身份,因此仅限所有者使用的工具(如自动化控制)仍然不可用;更改作业本身需要您在回复回合中操作。
每个连续失败最多只收到一个修复请求,即使之后失败原因发生变化。当作业没有所有者会话,或不会再次运行(例如已用完重试次数的一次性作业)时,警报会像以前一样发送。如果作业在请求之后再次失败,您会收到正常的失败警报,并注明已请求修复;连续失败中的后续警报遵循通常的冷却时间。成功运行会静默清除连续失败。
当提供者网络故障、请求超时、过载、速率限制或服务器错误获得快速调度器重试(30 秒、1 分钟、然后 5 分钟,或作业的下一次计划运行如果更早到来)时,警报和修复请求会等待。该等待最多覆盖上述三次重试,无论计划如何;当作业没有下一次运行(已禁用作业、已完成的一次性作业,或没有未来时间槽的计划)时,等待永远不会适用。如果这些重试也失败,则会以完整失败计数发送正常警报或修复;如果其中一次成功,则不发送任何内容。作业自身导致的失败不会被等待:其自身的执行超时、脚本失败和命令作业超时通常指向作业本身,因此它们会在正常阈值下发出警报或修复。
脚本设置会在执行开始前,于插件重新加载后刷新已退役的工具。如果该恢复失败,告警会说明工具无法刷新且脚本未运行,然后指向自动化历史和插件状态。无法运行的监控不会提供关于其所监控系统的新证据。
提供商拒绝不支持的模型时,会在任务状态和运行历史中记录 model_not_found。失败通知会指向 openclaw doctor --fix 以处理提供商声明的退役,或修改/移除自动化的模型覆盖。已知退役的自动化模型路由会在另一次推理请求之前失败。当代理的模型策略允许时,Doctor 会用提供商声明的继任者替换覆盖。如果没有声明继任者,它会清除覆盖,使任务继承代理默认值。如果固定覆盖的继任者不被允许,Doctor 会保留该引用并报告所需的策略变更。仅缺少账户目录条目或发现服务中断本身不会授权迁移。
调度器还提供安全兜底。基于时间的周期性任务在连续 10 次执行失败后会自动禁用;一次成功运行会重置该连续计数。一个例外:没有启用失败告警策略的 delivery.mode: "none" 任务,永远不会因其代理自身的 AUTOMATION_FAILED 报告而被自动禁用,因为它没有可通知的对象。这些运行仍会计入 consecutiveErrors 和错误退避,其运行时错误仍会自动禁用它。在最终失败时,更丰富的自动禁用通知会替代常规阈值告警。重复的调度计算失败会在 3 次错误后自动禁用。任务会将 state.autoDisabled.reason 记录为 consecutive-failures 或 schedule-errors,所属代理会收到包含安全原因和恢复命令的通知。原始错误保留在自动化历史中。修复原因后,运行 openclaw automations enable <jobId>;启用会清除记录的原因和失败连续计数。由于默认列表会隐藏已禁用的任务,请使用 openclaw automations list --all 检查它们。
输出语言¶
自动化任务不会根据渠道、区域设置或先前消息推断回复语言。请将语言规则放在计划消息或模板中:
openclaw automations edit <jobId> \
--message "Summarize the updates. Respond in Chinese; keep URLs, code, and product names unchanged."
对于模板文件,请在渲染后的提示中保留语言指令,并在任务运行前确认 {{language}} 等占位符已填充。如果输出混合了多种语言,请明确规则,例如:“叙述文本使用中文,技术术语保留英文。”
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw