diff --git a/docs/zh-CN/automation/cron-jobs.md b/docs/zh-CN/automation/cron-jobs.md index ddaf7322b..f7fe725eb 100644 --- a/docs/zh-CN/automation/cron-jobs.md +++ b/docs/zh-CN/automation/cron-jobs.md @@ -1,27 +1,27 @@ --- read_when: - - 安排后台作业或唤醒任务 + - 调度后台任务或唤醒操作 - 将外部触发器（webhook、Gmail）接入 OpenClaw - - 为计划任务在 heartbeat 和 cron 之间做选择 + - 为计划任务决定使用 heartbeat 还是 cron summary: Gateway 网关调度器的计划任务、webhook 和 Gmail PubSub 触发器 title: 计划任务 x-i18n: - generated_at: "2026-04-12T04:25:12Z" + generated_at: "2026-04-20T18:24:53Z" model: gpt-5.4 provider: openai - source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f + source_hash: e25f4dc8ee7b8f88e22d5cbc86e4527a9f5ac0ab4921e7874f76b186054682a3 source_path: automation/cron-jobs.md workflow: 15 --- # 计划任务（Cron） -Cron 是 Gateway 网关的内置调度器。它会持久化作业，在正确的时间唤醒智能体，并可将输出回传到聊天渠道或 webhook 端点。 +Cron 是 Gateway 网关内置的调度器。它会持久化任务，在正确时间唤醒智能体，并可将输出回传到聊天渠道或 webhook 端点。 ## 快速开始 ```bash -# 添加一次性提醒 +# 添加一个一次性提醒 openclaw cron add \ --name "Reminder" \ --at "2026-02-01T16:00:00Z" \ @@ -30,105 +30,108 @@ openclaw cron add \ --wake now \ --delete-after-run -# 查看你的作业 +# 检查你的任务 openclaw cron list # 查看运行历史 openclaw cron runs --id ``` -## cron 的工作方式 +## Cron 的工作方式 -- Cron **在 Gateway 网关进程内部**运行（而不是在模型内部）。 -- 作业持久化保存在 `~/.openclaw/cron/jobs.json`，因此重启不会丢失计划。 +- Cron **在 Gateway 网关进程内部**运行（不是在模型内部）。 +- 任务定义持久化保存在 `~/.openclaw/cron/jobs.json`，因此重启不会丢失计划。 +- 运行时执行状态保存在旁边的 `~/.openclaw/cron/jobs-state.json`。如果你在 git 中跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 `.gitignore`。 +- 在拆分之后，较旧版本的 OpenClaw 可以读取 `jobs.json`，但可能会将任务视为全新任务，因为运行时字段现在位于 `jobs-state.json` 中。 - 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。 -- 一次性作业（`--at`）默认会在成功后自动删除。 -- 隔离的 cron 运行会在运行完成时，尽力关闭其 `cron:` 会话所跟踪的浏览器标签页/进程，这样分离的浏览器自动化就不会留下孤儿进程。 -- 隔离的 cron 运行还会防止过期的确认回复。如果第一次结果只是中间状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在交付前再次提示一次，以获取实际结果。 +- 一次性任务（`--at`）默认会在成功后自动删除。 +- 独立的 cron 运行会在运行完成后，尽力关闭其 `cron:` 会话所跟踪的浏览器标签页/进程，这样分离的浏览器自动化就不会留下孤儿进程。 +- 独立的 cron 运行还会防止过时的确认回复。如果第一个结果只是中间状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在交付前再次提示一次，以获取实际结果。 -cron 的任务协调由运行时负责：只要 cron 运行时仍将该作业跟踪为正在运行，活动中的 cron 任务就会保持存活，即使仍存在旧的子会话记录行也是如此。一旦运行时不再拥有该作业，并且 5 分钟宽限期到期，维护流程就可以将该任务标记为 `lost`。 +Cron 的任务协调由运行时负责：只要 cron 运行时仍在跟踪该任务为运行中，活动中的 cron 任务就会保持存活，即使旧的子会话记录仍然存在也是如此。 +一旦运行时不再拥有该任务，且 5 分钟的宽限窗口到期，维护流程就可以将该任务标记为 `lost`。 ## 计划类型 -| 类型 | CLI 标志 | 说明 | +| Kind | CLI 标志 | 说明 | | ------- | --------- | ---- | | `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） | | `every` | `--every` | 固定间隔 | | `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选 `--tz` | -不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地墙上时钟时间调度。 +不带时区的时间戳会被视为 UTC。如需按本地时钟时间调度，请添加 `--tz America/New_York`。 -每小时整点的循环表达式会自动错开最多 5 分钟，以减少负载峰值。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定显式窗口。 +整点循环表达式会自动错峰，最多延迟 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错峰窗口。 -### day-of-month 和 day-of-week 使用 OR 逻辑 +### 每月日期与每周日期使用 OR 逻辑 -Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在**任一**字段匹配时触发——而不是两者都匹配时。这是标准的 Vixie cron 行为。 +Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当“每月第几天”和“每周第几天”字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是两个字段都匹配时才触发。这是标准的 Vixie cron 行为。 ``` -# 预期："15 日上午 9 点，且仅当这天是周一" -# 实际："每月 15 日上午 9 点，以及每周一上午 9 点" +# 预期：“每月 15 日早上 9 点，并且只有当它是周一时” +# 实际： “每月每个 15 日早上 9 点，以及每个周一早上 9 点” 0 9 15 * 1 ``` -这会使它每月触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或只在一个字段上调度，并在你的作业提示或命令中对另一个条件进行保护判断。 +这会导致它每月触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都满足，请使用 Croner 的 `+` 星期修饰符（`0 9 15 * +1`），或仅按一个字段调度，并在任务的提示词或命令中对另一个条件进行判断。 -## 执行方式 +## 执行样式 -| 方式 | `--session` 值 | 运行位置 | 最适合 | -| --------------- | ------------------- | ------------------------ | ------ | -| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 | -| 隔离 | `isolated` | 专用 `cron:` | 报告、后台杂务 | -| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的循环工作 | -| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史构建的工作流 | +| 样式 | `--session` 值 | 运行位置 | 最适合 | +| --------------- | ------------------- | ------------------------ | ------------------------------- | +| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 | +| 独立 | `isolated` | 专用 `cron:` | 报告、后台杂务 | +| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的循环工作 | +| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史构建的工作流 | -**主会话**作业会将系统事件加入队列，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**隔离**作业会使用全新的会话运行专用的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持如基于此前摘要持续构建的每日站会等工作流。 +**主会话**任务会排入一个系统事件，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**独立**任务会在一个全新会话中运行专用的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持类似“每日站会”这类基于先前摘要持续构建的工作流。 -对于隔离作业，运行时拆除流程现在包含对此 cron 会话的浏览器尽力清理。清理失败会被忽略，以确保实际的 cron 结果仍然优先。 +对于独立任务，运行时清理现在包含对此 cron 会话的尽力浏览器清理。清理失败会被忽略，因此实际的 cron 结果仍然优先。 -当隔离的 cron 运行编排子智能体时，交付也会优先使用最终的后代输出，而不是过期的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该部分父级更新，而不是提前宣布它。 +当独立的 cron 运行编排子智能体时，交付也会优先使用最终后代输出，而不是过时的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该不完整的父级更新，而不是将其对外宣布。 -### 隔离作业的负载选项 +### 独立任务的负载选项 -- `--message`：提示文本（隔离模式必需） -- `--model` / `--thinking`：模型和 thinking 级别覆盖 +- `--message`：提示文本（独立任务必需） +- `--model` / `--thinking`：模型和思考级别覆盖 - `--light-context`：跳过工作区引导文件注入 -- `--tools exec,read`：限制作业可使用的工具 +- `--tools exec,read`：限制任务可使用的工具 -`--model` 会为该作业使用所选的允许模型。如果请求的模型不被允许，cron 会记录警告，并回退到该作业的智能体/默认模型选择。已配置的回退链仍然适用，但仅指定模型覆盖而未显式提供按作业定义的回退列表时，不再把智能体主模型作为隐藏的额外重试目标附加进去。 +`--model` 会为该任务使用所选的允许模型。如果请求的模型不被允许，cron 会记录一条警告，并回退到该任务的智能体/默认模型选择。已配置的回退链仍然适用，但如果只是普通的模型覆盖且没有显式的每任务回退列表，就不会再把智能体主模型作为隐藏的额外重试目标附加进去。 -隔离作业的模型选择优先级如下： +独立任务的模型选择优先级如下： -1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时） -2. 按作业定义的负载 `model` +1. Gmail hook 模型覆盖（当该运行来自 Gmail，且该覆盖模型被允许时） +2. 每任务负载 `model` 3. 已保存的 cron 会话模型覆盖 4. 智能体/默认模型选择 -快速模式也会遵循解析后的实际选择。如果所选模型配置带有 `params.fastMode`，隔离的 cron 会默认使用它。已保存的会话 `fastMode` 覆盖在任一方向上都仍优先于配置。 +快速模式也会遵循解析后的实时选择。如果所选模型配置包含 `params.fastMode`，独立 cron 默认也会使用它。已保存的会话 `fastMode` 覆盖在两种方向上都仍然优先于配置。 -如果隔离运行遇到实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前持久化该实时选择。当切换同时携带新的凭证配置文件时，cron 也会持久化该凭证配置文件覆盖。重试次数是有上限的：初次尝试后最多再进行 2 次切换重试，之后 cron 会中止，而不是无限循环。 +如果独立运行命中了实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前持久化该实时选择。如果该切换还携带新的凭证配置文件，cron 也会持久化该凭证配置文件覆盖。重试次数是有上限的：初始尝试加上 2 次切换重试之后，cron 会中止，而不是无限循环。 ## 交付与输出 -| 模式 | 发生的情况 | -| ---------- | ---------- | -| `announce` | 将摘要交付到目标渠道（隔离模式的默认值） | -| `webhook` | 将完成事件负载 POST 到某个 URL | +| 模式 | 发生的事情 | +| ---------- | -------------------------------------------------------- | +| `announce` | 将摘要交付到目标渠道（独立任务默认） | +| `webhook` | 向某个 URL `POST` 已完成事件负载 | | `none` | 仅内部使用，不交付 | -使用 `--announce --channel telegram --to "-1001234567890"` 可进行渠道交付。对于 Telegram forum topic，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:`、`user:`）。 +使用 `--announce --channel telegram --to "-1001234567890"` 可进行渠道交付。对于 Telegram forum 话题，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:`、`user:`）。 -对于由 cron 拥有的隔离作业，运行器拥有最终交付路径。系统会提示智能体返回纯文本摘要，然后该摘要会通过 `announce`、`webhook` 发送，或在 `none` 模式下仅保留在内部。`--no-deliver` 不会把交付重新交还给智能体；它只会让本次运行保持内部化。 +对于由 cron 拥有的独立任务，运行器拥有最终交付路径。系统会提示智能体返回纯文本摘要，然后该摘要会通过 `announce`、`webhook` 发送，或在 `none` 模式下保留为内部内容。`--no-deliver` 不会把交付权交还给智能体；它会让该运行保持内部状态。 -如果原始任务明确说明要给某个外部接收方发送消息，智能体应在其输出中注明该消息应发送给谁/发送到哪里，而不是尝试直接发送。 +如果原始任务明确要求向某个外部接收方发送消息，智能体应在其输出中说明该消息应发给谁/发往哪里，而不是尝试直接发送。 失败通知遵循单独的目标路径： - `cron.failureDestination` 设置失败通知的全局默认目标。 -- `job.delivery.failureDestination` 会按作业覆盖该设置。 -- 如果两者都未设置，且作业已经通过 `announce` 交付，失败通知现在会回退到该主 announce 目标。 -- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业上受支持，除非主交付模式是 `webhook`。 +- `job.delivery.failureDestination` 按任务覆盖该设置。 +- 如果两者都未设置，且该任务已经通过 `announce` 进行交付，则失败通知现在会回退到该主 announce 目标。 +- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 任务上受支持，除非主交付模式是 `webhook`。 ## CLI 示例 @@ -143,7 +146,7 @@ openclaw cron add \ --wake now ``` -带交付的循环隔离作业： +带交付的循环独立任务： ```bash openclaw cron add \ @@ -157,7 +160,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -带模型和 thinking 覆盖的隔离作业： +带模型和思考覆盖的独立任务： ```bash openclaw cron add \ @@ -173,7 +176,7 @@ openclaw cron add \ ## Webhooks -Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配置中启用： +Gateway 网关可以公开 HTTP webhook 端点，用于外部触发器。在配置中启用： ```json5 { @@ -196,7 +199,7 @@ Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配 ### POST /hooks/wake -为主会话加入一个系统事件： +为主会话排入一个系统事件： ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -205,12 +208,12 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ -d '{"text":"New email received","mode":"now"}' ``` -- `text`（必填）：事件描述 +- `text`（必需）：事件描述 - `mode`（可选）：`now`（默认）或 `next-heartbeat` ### POST /hooks/agent -运行一个隔离的智能体轮次： +运行一个独立的智能体轮次： ```bash curl -X POST http://127.0.0.1:18789/hooks/agent \ @@ -219,27 +222,27 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}' ``` -字段：`message`（必填）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。 +字段：`message`（必需）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。 ### 映射 hooks（POST /hooks/\） -自定义 hook 名称会通过配置中的 `hooks.mappings` 解析。映射可以通过模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 +自定义 hook 名称通过配置中的 `hooks.mappings` 解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。 ### 安全性 - 将 hook 端点放在 loopback、tailnet 或受信任的反向代理之后。 -- 使用专用 hook token；不要复用 Gateway 网关身份验证 token。 +- 使用专用的 hook token；不要复用 gateway 身份验证 token。 - 将 `hooks.path` 保持在专用子路径下；`/` 会被拒绝。 -- 设置 `hooks.allowedAgentIds` 以限制显式的 `agentId` 路由。 -- 除非你需要让调用方选择会话，否则保持 `hooks.allowRequestSessionKey=false`。 -- 如果你启用了 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以约束允许的会话键形态。 +- 设置 `hooks.allowedAgentIds` 以限制显式 `agentId` 路由。 +- 保持 `hooks.allowRequestSessionKey=false`，除非你确实需要由调用方选择会话。 +- 如果你启用了 `hooks.allowRequestSessionKey`，也要设置 `hooks.allowedSessionKeyPrefixes`，以限制允许的会话键形状。 - 默认情况下，hook 负载会被安全边界包装。 ## Gmail PubSub 集成 通过 Google PubSub 将 Gmail 收件箱触发器接入 OpenClaw。 -**前置条件**：`gcloud` CLI、`gog`（gogcli）、已启用 OpenClaw hooks，以及用于公共 HTTPS 端点的 Tailscale。 +**前置条件**：`gcloud` CLI、`gog`（gogcli）、已启用 OpenClaw hooks，以及用于公开 HTTPS 端点的 Tailscale。 ### 向导设置（推荐） @@ -247,7 +250,7 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \ openclaw webhooks gmail setup --account openclaw@gmail.com ``` -这会写入 `hooks.gmail` 配置、启用 Gmail 预设，并为推送端点使用 Tailscale Funnel。 +这会写入 `hooks.gmail` 配置，启用 Gmail 预设，并使用 Tailscale Funnel 作为推送端点。 ### Gateway 网关自动启动 @@ -294,16 +297,16 @@ gog gmail watch start \ } ``` -## 管理作业 +## 管理任务 ```bash -# 列出所有作业 +# 列出所有任务 openclaw cron list -# 编辑作业 +# 编辑任务 openclaw cron edit --message "Updated prompt" --model "opus" -# 立即强制运行作业 +# 立即强制运行任务 openclaw cron run # 仅在到期时运行 @@ -312,7 +315,7 @@ openclaw cron run --due # 查看运行历史 openclaw cron runs --id --limit 50 -# 删除作业 +# 删除任务 openclaw cron remove # 智能体选择（多智能体设置） @@ -322,10 +325,10 @@ openclaw cron edit --clear-agent 模型覆盖说明： -- `openclaw cron add|edit --model ...` 会更改作业所选的模型。 -- 如果该模型被允许，那个精确的提供商/模型会传递到隔离的智能体运行中。 -- 如果不被允许，cron 会发出警告，并回退到作业的智能体/默认模型选择。 -- 已配置的回退链仍然适用，但普通的 `--model` 覆盖如果没有显式的按作业定义的回退列表，就不再静默地回退到智能体主模型作为额外重试目标。 +- `openclaw cron add|edit --model ...` 会更改任务所选的模型。 +- 如果该模型被允许，该确切的提供商/模型会传递给独立智能体运行。 +- 如果不被允许，cron 会发出警告，并回退到任务的智能体/默认模型选择。 +- 已配置的回退链仍然适用，但普通的 `--model` 覆盖如果没有显式的每任务回退列表，就不会再回落到智能体主模型作为静默的额外重试目标。 ## 配置 @@ -347,13 +350,15 @@ openclaw cron edit --clear-agent } ``` +运行时状态 sidecar 由 `cron.store` 推导得出：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而不带 `.json` 后缀的存储路径则会追加 `-state.json`。 + 禁用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。 -**一次性作业重试**：临时错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久性错误会立即禁用。 +**一次性任务重试**：瞬时错误（限流、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久性错误会立即禁用。 -**循环作业重试**：重试之间使用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。 +**循环任务重试**：在重试之间使用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。 -**维护**：`cron.sessionRetention`（默认 `24h`）会清理隔离运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。 +**维护**：`cron.sessionRetention`（默认 `24h`）会清理独立运行会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。 ## 故障排除 @@ -373,27 +378,27 @@ openclaw doctor ### Cron 未触发 - 检查 `cron.enabled` 和 `OPENCLAW_SKIP_CRON` 环境变量。 -- 确认 Gateway 网关在持续运行。 -- 对于 `cron` 计划，核对时区（`--tz`）与主机时区是否一致。 -- 运行输出中的 `reason: not-due` 表示手动运行是通过 `openclaw cron run --due` 检查的，而该作业尚未到期。 +- 确认 Gateway 网关持续运行中。 +- 对于 `cron` 计划，确认时区（`--tz`）与主机时区是否一致。 +- 运行输出中的 `reason: not-due` 表示手动运行是通过 `openclaw cron run --due` 检查的，而该任务当时尚未到期。 ### Cron 已触发但没有交付 -- 如果交付模式是 `none`，则不会有外部消息。 -- 如果交付目标缺失/无效（`channel`/`to`），则会跳过对外发送。 -- 渠道身份验证错误（`unauthorized`、`Forbidden`）表示由于凭证问题，交付被阻止。 -- 如果隔离运行只返回静默令牌（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接对外发送，也会抑制后备的排队摘要路径，因此不会有任何内容回发到聊天中。 -- 对于由 cron 拥有的隔离作业，不要期望智能体将 message 工具作为后备。运行器拥有最终交付；`--no-deliver` 会让它保持内部化，而不是允许直接发送。 +- 交付模式为 `none` 表示不应有任何外部消息。 +- 缺少或无效的交付目标（`channel`/`to`）表示出站已被跳过。 +- 渠道认证错误（`unauthorized`、`Forbidden`）表示交付被凭证阻止。 +- 如果独立运行仅返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站交付，也会抑制回退的排队摘要路径，因此不会有任何内容回发到聊天中。 +- 对于由 cron 拥有的独立任务，不要期待智能体将 message 工具作为回退方案使用。运行器拥有最终交付权；`--no-deliver` 会让其保持内部状态，而不是允许直接发送。 ### 时区注意事项 - 不带 `--tz` 的 cron 使用 gateway 主机时区。 - 不带时区的 `at` 计划会被视为 UTC。 -- Heartbeat 的 `activeHours` 使用已配置的时区解析。 +- Heartbeat `activeHours` 使用已配置的时区解析。 ## 相关内容 - [自动化与任务](/zh-CN/automation) — 所有自动化机制总览 -- [后台任务](/zh-CN/automation/tasks) — cron 执行的任务台账 -- [Heartbeat](/zh-CN/gateway/heartbeat) — 定期主会话轮次 +- [后台任务](/zh-CN/automation/tasks) — cron 执行的任务账本 +- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 - [时区](/zh-CN/concepts/timezone) — 时区配置 diff --git a/docs/zh-CN/automation/tasks.md b/docs/zh-CN/automation/tasks.md index ff5b13bd3..1ba9ad57a 100644 --- a/docs/zh-CN/automation/tasks.md +++ b/docs/zh-CN/automation/tasks.md @@ -1,56 +1,56 @@ --- read_when: - - 检查正在进行或最近完成的后台工作 - - 调试分离式智能体运行的投递失败 - - 了解后台运行与会话、cron 和 heartbeat 的关系 + - 检查正在进行中或刚刚完成的后台工作 + - 调试已分离的智能体运行的交付失败问题 + - 了解后台运行与会话、cron 和心跳之间的关系 summary: 用于跟踪 ACP 运行、子智能体、隔离的 cron 作业和 CLI 操作的后台任务 title: 后台任务 x-i18n: - generated_at: "2026-04-09T11:48:36Z" + generated_at: "2026-04-20T18:24:53Z" model: gpt-5.4 provider: openai - source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac + source_hash: ba5511b1c421bdf505fc7d34f09e453ac44e85213fcb0f082078fa957aa91fe7 source_path: automation/tasks.md workflow: 15 --- # 后台任务 -> **在找调度功能？** 请参阅 [Automation & Tasks](/zh-CN/automation)，以选择合适的机制。本页介绍的是如何**跟踪**后台工作，而不是如何调度它。 +> **在找调度功能？** 请参阅 [Automation & Tasks](/zh-CN/automation) 以选择合适的机制。本页介绍的是如何**跟踪**后台工作，而不是如何调度它。 -后台任务用于跟踪**主对话会话之外**运行的工作： -ACP 运行、子智能体启动、隔离的 cron 作业执行，以及由 CLI 发起的操作。 +后台任务用于跟踪**在你的主会话之外**运行的工作： +ACP 运行、子智能体生成、隔离的 cron 作业执行，以及由 CLI 发起的操作。 -任务**不会**取代会话、cron 作业或 heartbeat —— 它们是记录分离式工作发生了什么、何时发生以及是否成功的**活动账本**。 +任务**不会**替代会话、cron 作业或心跳——它们是记录已分离工作发生了什么、何时发生以及是否成功的**活动账本**。 -并非每次智能体运行都会创建任务。Heartbeat 回合和普通交互式聊天不会。所有 cron 执行、ACP 启动、子智能体启动以及 CLI 智能体命令都会创建任务。 +并非每次智能体运行都会创建任务。心跳轮次和普通交互式聊天不会。所有 cron 执行、ACP 生成、子智能体生成和 CLI 智能体命令都会。 ## TL;DR -- 任务是**记录**，不是调度器 —— cron 和 heartbeat 决定工作_何时_运行，任务跟踪_发生了什么_。 -- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。Heartbeat 回合不会。 -- 每个任务都会经历 `queued → running → terminal`（`succeeded`、`failed`、`timed_out`、`cancelled` 或 `lost`）。 -- 只要 cron 运行时仍拥有该作业，cron 任务就会保持活跃；基于聊天的 CLI 任务则只会在其所属运行上下文仍处于活动状态时保持活跃。 -- 完成采用推送驱动：分离式工作可以在完成时直接通知，或唤醒请求方会话 / heartbeat，因此轮询状态通常不是正确方式。 -- 隔离的 cron 运行和子智能体完成时，会尽力为其子会话清理已跟踪的浏览器标签页 / 进程，然后再完成最终清理记账。 -- 隔离的 cron 投递会在后代子智能体工作仍在收尾时抑制过时的中间父级回复，并在后代最终输出先于投递到达时优先使用该输出。 -- 完成通知会直接投递到渠道，或排队等待下一次 heartbeat。 -- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 会显示问题。 -- 终态记录会保留 7 天，随后自动清理。 +- 任务是**记录**，不是调度器——cron 和心跳决定工作_何时_运行，任务跟踪_发生了什么_。 +- ACP、子智能体、所有 cron 作业和 CLI 操作都会创建任务。心跳轮次不会。 +- 每个任务都会经历 `queued → running → terminal`（succeeded、failed、timed_out、cancelled 或 lost）。 +- 只要 cron 运行时仍拥有该作业，cron 任务就会保持活动状态；基于聊天的 CLI 任务仅在其所属运行上下文仍然活跃时保持活动状态。 +- 完成采用推送驱动：已分离工作完成时可以直接通知，或唤醒请求方会话/心跳，因此状态轮询循环通常不是正确方式。 +- 隔离的 cron 运行和子智能体完成时，会尽力在最终清理记账前清理其子会话所跟踪的浏览器标签页/进程。 +- 隔离的 cron 交付会在后代子智能体工作仍在收尾时抑制过期的中间父级回复，并在后代最终输出先于交付到达时优先使用它。 +- 完成通知会直接投递到某个渠道，或排队等待下一次心跳。 +- `openclaw tasks list` 显示所有任务；`openclaw tasks audit` 会暴露问题。 +- 终态记录会保留 7 天，之后自动清理。 ## 快速开始 ```bash -# 列出所有任务（最新优先） +# 列出所有任务（最新的在前） openclaw tasks list -# 按运行时或状态筛选 +# 按运行时或状态过滤 openclaw tasks list --runtime acp openclaw tasks list --status running -# 显示特定任务的详情（按 ID、运行 ID 或会话键） +# 显示特定任务的详细信息（按 ID、run ID 或 session key） openclaw tasks show # 取消正在运行的任务（终止子会话） @@ -76,22 +76,22 @@ openclaw tasks flow cancel | 来源 | 运行时类型 | 何时创建任务记录 | 默认通知策略 | | ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | -| ACP 后台运行 | `acp` | 启动 ACP 子会话时 | `done_only` | -| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 启动子智能体时 | `done_only` | -| Cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离式均包括） | `silent` | +| ACP 后台运行 | `acp` | 生成子 ACP 会话时 | `done_only` | +| 子智能体编排 | `subagent` | 通过 `sessions_spawn` 生成子智能体时 | `done_only` | +| cron 作业（所有类型） | `cron` | 每次 cron 执行时（主会话和隔离执行均包括） | `silent` | | CLI 操作 | `cli` | 通过 Gateway 网关运行的 `openclaw agent` 命令 | `silent` | | 智能体媒体作业 | `cli` | 基于会话的 `video_generate` 运行 | `silent` | -主会话 cron 任务默认使用 `silent` 通知策略 —— 它们会创建记录以供跟踪，但不会生成通知。隔离的 cron 任务也默认使用 `silent`，但由于它们在自己的会话中运行，因此更明显。 +主会话 cron 任务默认使用 `silent` 通知策略——它们会创建用于跟踪的记录，但不会生成通知。隔离的 cron 任务默认也为 `silent`，但由于它们在自己的会话中运行，因此更容易被看到。 -基于会话的 `video_generate` 运行也使用 `silent` 通知策略。它们仍会创建任务记录，但完成会通过内部唤醒交还给原始智能体会话，以便智能体自行编写后续消息并附加完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`，异步 `music_generate` 和 `video_generate` 完成会先尝试直接投递到渠道，失败后再回退到唤醒请求方会话的路径。 +基于会话的 `video_generate` 运行同样使用 `silent` 通知策略。它们仍会创建任务记录，但完成结果会作为内部唤醒交还给原始智能体会话，以便智能体自己编写后续消息并附上生成完成的视频。如果你启用了 `tools.media.asyncCompletion.directSend`，异步 `music_generate` 和 `video_generate` 完成时会先尝试直接向渠道投递，失败后再回退到唤醒请求方会话的路径。 -当基于会话的 `video_generate` 任务仍在活动时，该工具还会充当保护机制：在同一会话中重复调用 `video_generate` 会返回活动任务状态，而不是启动第二个并发生成任务。如果你想从智能体侧显式查询进度 / 状态，请使用 `action: "status"`。 +当某个基于会话的 `video_generate` 任务仍在活动时，该工具还会充当一道保护措施：在同一会话中重复调用 `video_generate` 会返回活动任务状态，而不是启动第二个并发生成任务。当你希望从智能体侧显式查询进度/状态时，请使用 `action: "status"`。 -**以下情况不会创建任务：** +**不会创建任务的情况：** -- Heartbeat 回合 —— 主会话；请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) -- 普通交互式聊天回合 +- 心跳轮次——主会话；请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) +- 普通交互式聊天轮次 - 直接 `/command` 响应 ## 任务生命周期 @@ -99,59 +99,59 @@ openclaw tasks flow cancel ```mermaid stateDiagram-v2 [*] --> queued - queued --> running : 智能体开始 - running --> succeeded : 成功完成 - running --> failed : 错误 - running --> timed_out : 超出超时时间 - running --> cancelled : 操作者取消 - queued --> lost : 会话消失超过 5 分钟 - running --> lost : 会话消失超过 5 分钟 + queued --> running : agent starts + running --> succeeded : completes ok + running --> failed : error + running --> timed_out : timeout exceeded + running --> cancelled : operator cancels + queued --> lost : session gone > 5 min + running --> lost : session gone > 5 min ``` | 状态 | 含义 | | ----------- | -------------------------------------------------------------------------- | -| `queued` | 已创建，正在等待智能体启动 | -| `running` | 智能体回合正在主动执行 | +| `queued` | 已创建，等待智能体启动 | +| `running` | 智能体轮次正在积极执行 | | `succeeded` | 已成功完成 | -| `failed` | 已因错误完成 | -| `timed_out` | 超过配置的超时时间 | -| `cancelled` | 被操作者通过 `openclaw tasks cancel` 停止 | -| `lost` | 在 5 分钟宽限期后，运行时丢失了权威的后端状态 | +| `failed` | 因错误而结束 | +| `timed_out` | 超出配置的超时时间 | +| `cancelled` | 由操作员通过 `openclaw tasks cancel` 停止 | +| `lost` | 在 5 分钟宽限期后，运行时丢失了权威的后备状态 | -转换会自动发生 —— 当关联的智能体运行结束时，任务状态会更新为对应结果。 +状态转换会自动发生——当关联的智能体运行结束时，任务状态会更新为匹配的结果。 -`lost` 具有运行时感知能力： +`lost` 是运行时感知的： -- ACP 任务：其后端 ACP 子会话元数据已消失。 -- 子智能体任务：其后端子会话已从目标智能体存储中消失。 -- Cron 任务：cron 运行时不再将该作业视为活动。 -- CLI 任务：隔离的子会话任务使用子会话；基于聊天的 CLI 任务则改用实时运行上下文，因此残留的渠道 / 群组 / 直接会话行不会让它们继续保持活跃。 +- ACP 任务：后备 ACP 子会话元数据消失。 +- 子智能体任务：后备子会话从目标智能体存储中消失。 +- cron 任务：cron 运行时不再将该作业视为活动状态。 +- CLI 任务：隔离的子会话任务使用子会话；基于聊天的 CLI 任务则改为使用活动运行上下文，因此残留的渠道/群组/直接会话行不会让它们继续保持活动。 -## 投递与通知 +## 交付与通知 -当任务进入终态时，OpenClaw 会通知你。共有两种投递路径： +当任务进入终态时，OpenClaw 会通知你。有两种交付路径： -**直接投递** —— 如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程 / 主题路由，并可在放弃直接投递之前，从请求方会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 `to` / account。 +**直接交付**——如果任务有渠道目标（`requesterOrigin`），完成消息会直接发送到该渠道（Telegram、Discord、Slack 等）。对于子智能体完成，OpenClaw 还会在可用时保留已绑定的线程/话题路由，并可在直接交付前尝试从请求方会话的存储路由（`lastChannel` / `lastTo` / `lastAccountId`）中补全缺失的 `to` / account。 -**会话排队投递** —— 如果直接投递失败，或未设置来源，更新会作为系统事件排入请求方会话，并在下一次 heartbeat 时显示。 +**会话排队交付**——如果直接交付失败，或未设置来源，则更新会作为系统事件排入请求方会话，并在下一次心跳时呈现。 -任务完成会立即触发 heartbeat 唤醒，因此你可以快速看到结果 —— 你不需要等到下一次计划中的 heartbeat tick。 +任务完成会立即触发一次心跳唤醒，因此你可以快速看到结果——无需等到下一次计划中的心跳 tick。 -这意味着通常的工作流是基于推送的：只需启动一次分离式工作，然后让运行时在完成时唤醒或通知你。只有在你需要调试、干预或进行显式审计时，才去轮询任务状态。 +这意味着常见工作流是基于推送的：只需启动一次已分离工作，然后让运行时在完成时唤醒或通知你。只有在你需要调试、干预或进行显式审计时，才去轮询任务状态。 ### 通知策略 -控制你会收到多少关于每个任务的通知： +控制你会收到多少关于每个任务的信息： -| 策略 | 会投递的内容 | +| 策略 | 交付内容 | | --------------------- | ----------------------------------------------------------------------- | -| `done_only`（默认） | 仅终态（`succeeded`、`failed` 等）—— **这就是默认值** | -| `state_changes` | 每次状态变化和进度更新 | +| `done_only`（默认） | 仅终态（succeeded、failed 等）——**这就是默认值** | +| `state_changes` | 每次状态转换和进度更新 | | `silent` | 完全不通知 | -在任务运行时更改策略： +在任务运行期间更改策略： ```bash openclaw tasks notify state_changes @@ -165,7 +165,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` -输出列：任务 ID、类型、状态、投递、运行 ID、子会话、摘要。 +输出列：任务 ID、类型、状态、交付、运行 ID、子会话、摘要。 ### `tasks show` @@ -173,7 +173,7 @@ openclaw tasks list [--runtime ] [--status ] [--j openclaw tasks show ``` -查找标记接受任务 ID、运行 ID 或会话键。会显示完整记录，包括时间信息、投递状态、错误和终态摘要。 +查找令牌接受任务 ID、运行 ID 或会话键。显示完整记录，包括时间、交付状态、错误和终态摘要。 ### `tasks cancel` @@ -181,7 +181,7 @@ openclaw tasks show openclaw tasks cancel ``` -对于 ACP 和子智能体任务，这会终止子会话。对于 CLI 跟踪的任务，取消会记录在任务注册表中（没有单独的子运行时句柄）。状态会转为 `cancelled`，并在适用时发送投递通知。 +对于 ACP 和子智能体任务，这会终止子会话。对于由 CLI 跟踪的任务，取消操作会记录到任务注册表中（不存在单独的子运行时句柄）。状态会转换为 `cancelled`，并在适用时发送交付通知。 ### `tasks notify` @@ -195,16 +195,16 @@ openclaw tasks notify openclaw tasks audit [--json] ``` -显示运维问题。检测到问题时，这些发现也会出现在 `openclaw status` 中。 +暴露运行问题。检测到问题时，结果也会出现在 `openclaw status` 中。 -| 发现项 | 严重性 | 触发条件 | +| 发现项 | 严重级别 | 触发条件 | | ------------------------- | -------- | ----------------------------------------------------- | | `stale_queued` | warn | 排队超过 10 分钟 | | `stale_running` | error | 运行超过 30 分钟 | -| `lost` | error | 运行时支持的任务归属已消失 | -| `delivery_failed` | warn | 投递失败且通知策略不是 `silent` | -| `missing_cleanup` | warn | 已终态任务没有清理时间戳 | -| `inconsistent_timestamps` | warn | 时间线违规（例如结束早于开始） | +| `lost` | error | 运行时支撑的任务归属已消失 | +| `delivery_failed` | warn | 交付失败且通知策略不是 `silent` | +| `missing_cleanup` | warn | 终态任务没有清理时间戳 | +| `inconsistent_timestamps` | warn | 时间线冲突（例如结束时间早于开始时间） | ### `tasks maintenance` @@ -213,20 +213,20 @@ openclaw tasks maintenance [--json] openclaw tasks maintenance --apply [--json] ``` -使用此命令可预览或应用任务及 Task Flow 状态的对账、清理时间戳设置和清理。 +使用它来预览或应用针对任务和 Task Flow 状态的对账、清理标记和修剪。 -对账具有运行时感知能力： +对账是运行时感知的： -- ACP / 子智能体任务会检查其后端子会话。 -- Cron 任务会检查 cron 运行时是否仍拥有该作业。 -- 基于聊天的 CLI 任务会检查所属的实时运行上下文，而不只是聊天会话行。 +- ACP/子智能体任务会检查其后备子会话。 +- cron 任务会检查 cron 运行时是否仍拥有该作业。 +- 基于聊天的 CLI 任务会检查所属的活动运行上下文，而不只是聊天会话行。 -完成后的清理同样具有运行时感知能力： +完成清理同样是运行时感知的： -- 子智能体完成时，会尽力在公告清理继续之前关闭该子会话中已跟踪的浏览器标签页 / 进程。 -- 隔离的 cron 完成时，会尽力在运行彻底结束前关闭 cron 会话中已跟踪的浏览器标签页 / 进程。 -- 隔离的 cron 投递会在需要时等待后代子智能体后续处理完成，并抑制过时的父级确认文本，而不是宣布它。 -- 子智能体完成投递会优先使用最新可见的 assistant 文本；如果为空，则回退到经过净化的最新 tool / toolResult 文本，而仅包含超时工具调用的运行可折叠为简短的部分进度摘要。 +- 子智能体完成时，会尽力在宣布清理继续之前关闭该子会话所跟踪的浏览器标签页/进程。 +- 隔离的 cron 完成时，会尽力在该运行彻底拆除前关闭该 cron 会话所跟踪的浏览器标签页/进程。 +- 隔离的 cron 交付会在需要时等待后代子智能体的后续工作完成，并抑制过期的父级确认文本，而不是直接宣布它。 +- 子智能体完成交付会优先使用最新的可见 assistant 文本；如果为空，则回退到已净化的最新 tool/toolResult 文本，而仅包含超时工具调用的运行可收缩为简短的部分进度摘要。 - 清理失败不会掩盖真实的任务结果。 ### `tasks flow list|show|cancel` @@ -241,33 +241,33 @@ openclaw tasks flow cancel ## 聊天任务看板（`/tasks`） -在任意聊天会话中使用 `/tasks`，即可查看与该会话关联的后台任务。该看板会显示活动中和最近完成的任务，包括运行时、状态、时间信息，以及进度或错误详情。 +在任何聊天会话中使用 `/tasks` 可查看链接到该会话的后台任务。看板会显示活动中和最近完成的任务，包括运行时、状态、时间，以及进度或错误详情。 -当当前会话没有可见的关联任务时，`/tasks` 会回退为智能体本地任务计数，因此你仍能看到概览，而不会泄露其他会话的详情。 +当当前会话没有可见的关联任务时，`/tasks` 会回退为显示智能体本地任务计数，这样你仍能获得概览，同时不会泄露其他会话的详细信息。 -如需查看完整的操作者账本，请使用 CLI：`openclaw tasks list`。 +如需查看完整的操作员账本，请使用 CLI：`openclaw tasks list`。 ## 状态集成（任务压力） -`openclaw status` 包含一目了然的任务摘要： +`openclaw status` 包含一个可快速浏览的任务摘要： ``` Tasks: 3 queued · 2 running · 1 issues ``` -摘要会报告： +该摘要报告： -- **active** —— `queued` + `running` 的数量 -- **failures** —— `failed` + `timed_out` + `lost` 的数量 -- **byRuntime** —— 按 `acp`、`subagent`、`cron`、`cli` 分类的明细 +- **active** — `queued` + `running` 的数量 +- **failures** — `failed` + `timed_out` + `lost` 的数量 +- **byRuntime** — 按 `acp`、`subagent`、`cron`、`cli` 分类的明细 -`/status` 和 `session_status` 工具都会使用具备清理感知能力的任务快照：优先显示活动任务，隐藏过时的已完成行，并且只有在没有活动工作剩余时才显示近期失败。这让状态卡片聚焦于当前最重要的内容。 +`/status` 和 `session_status` 工具都使用具备清理感知能力的任务快照：优先显示活动任务，隐藏陈旧的已完成记录，且仅在没有活动工作残留时才显示最近失败项。这让状态卡片聚焦于当前真正重要的内容。 ## 存储与维护 ### 任务存储位置 -任务记录会持久化到 SQLite，位置为： +任务记录会持久化到 SQLite，位置如下： ``` $OPENCLAW_STATE_DIR/tasks/runs.sqlite @@ -279,44 +279,44 @@ $OPENCLAW_STATE_DIR/tasks/runs.sqlite 清理器每 **60 秒** 运行一次，并处理三件事： -1. **对账** —— 检查活动任务是否仍有权威的运行时后端支持。ACP / 子智能体任务使用子会话状态，cron 任务使用活动作业归属，基于聊天的 CLI 任务使用所属运行上下文。如果该后端状态消失超过 5 分钟，任务会被标记为 `lost`。 -2. **清理时间戳设置** —— 为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。 -3. **清理** —— 删除超过其 `cleanupAfter` 日期的记录。 +1. **对账** — 检查活动任务是否仍有权威运行时后备状态。ACP/子智能体任务使用子会话状态，cron 任务使用活动作业归属状态，基于聊天的 CLI 任务使用其所属运行上下文。如果该后备状态消失超过 5 分钟，任务会被标记为 `lost`。 +2. **清理标记** — 为终态任务设置 `cleanupAfter` 时间戳（`endedAt + 7 days`）。 +3. **修剪** — 删除超过其 `cleanupAfter` 日期的记录。 -**保留期**：终态任务记录会保留 **7 天**，之后自动清理。无需额外配置。 +**保留期**：终态任务记录会保留 **7 天**，之后自动修剪。无需任何配置。 ## 任务与其他系统的关系 ### 任务与 Task Flow -[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个流程在其生命周期内可能通过托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排流程。 +[Task Flow](/zh-CN/automation/taskflow) 是位于后台任务之上的流程编排层。单个 flow 在其生命周期内可能通过托管或镜像同步模式协调多个任务。使用 `openclaw tasks` 检查单个任务记录，使用 `openclaw tasks flow` 检查编排 flow。 详情请参阅 [Task Flow](/zh-CN/automation/taskflow)。 ### 任务与 cron -一个 cron 作业的**定义**存放在 `~/.openclaw/cron/jobs.json` 中。**每一次** cron 执行都会创建一条任务记录 —— 无论是主会话还是隔离式。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。 +cron 作业的**定义**位于 `~/.openclaw/cron/jobs.json`；运行时执行状态则位于同目录旁边的 `~/.openclaw/cron/jobs-state.json`。**每一次** cron 执行都会创建一条任务记录——无论是主会话还是隔离执行。主会话 cron 任务默认使用 `silent` 通知策略，因此它们会被跟踪，但不会生成通知。 请参阅 [Cron Jobs](/zh-CN/automation/cron-jobs)。 -### 任务与 heartbeat +### 任务与心跳 -Heartbeat 运行属于主会话回合 —— 它们不会创建任务记录。当任务完成时，它可以触发 heartbeat 唤醒，以便你及时看到结果。 +心跳运行属于主会话轮次——它们不会创建任务记录。任务完成时，它可以触发一次心跳唤醒，让你及时看到结果。 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。 ### 任务与会话 -任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（谁发起了它）。会话是对话上下文；任务则是在其之上的活动跟踪。 +任务可能会引用 `childSessionKey`（工作运行的位置）和 `requesterSessionKey`（发起者）。会话是对话上下文；任务是在其之上的活动跟踪层。 ### 任务与智能体运行 -任务的 `runId` 链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态 —— 你无需手动管理生命周期。 +任务的 `runId` 会链接到执行该工作的智能体运行。智能体生命周期事件（开始、结束、错误）会自动更新任务状态——你无需手动管理生命周期。 ## 相关内容 -- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制一览 -- [Task Flow](/zh-CN/automation/taskflow) —— 位于任务之上的流程编排 -- [Scheduled Tasks](/zh-CN/automation/cron-jobs) —— 调度后台工作 -- [Heartbeat](/zh-CN/gateway/heartbeat) —— 周期性的主会话回合 -- [CLI: Tasks](/cli/index#tasks) —— CLI 命令参考 +- [Automation & Tasks](/zh-CN/automation) — 一览所有自动化机制 +- [Task Flow](/zh-CN/automation/taskflow) — 位于任务之上的流程编排 +- [Scheduled Tasks](/zh-CN/automation/cron-jobs) — 调度后台工作 +- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次 +- [CLI: Tasks](/cli/index#tasks) — CLI 命令参考