chore(i18n): refresh zh-CN translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-12 04:26:00 +00:00
parent 81fb4c385c
commit 52646f78ed

View File

@ -2,26 +2,26 @@
read_when:
- 安排后台作业或唤醒任务
- 将外部触发器webhook、Gmail接入 OpenClaw
- 为计划任务决定使用心跳还是 cron】【。analysis to=final code 21 րոպե
- 为计划任务在 heartbeat 和 cron 之间做选择
summary: Gateway 网关调度器的计划任务、webhook 和 Gmail PubSub 触发器
title: 计划任务
x-i18n:
generated_at: "2026-04-10T20:41:23Z"
generated_at: "2026-04-12T04:25:12Z"
model: gpt-5.4
provider: openai
source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665
source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f
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,93 +30,105 @@ openclaw cron add \
--wake now \
--delete-after-run
# 检查你的任务
# 查看你的作业
openclaw cron list
# 查看运行历史
openclaw cron runs --id <job-id>
```
## Cron 的工作方式
## cron 的工作方式
- Cron **在 Gateway 网关进程内部**运行(而不是在模型内部)。
- 任务会持久化到 `~/.openclaw/cron/jobs.json`,因此重启不会丢失调度
- 所有 Cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。
- 一次性任务(`--at`)默认在成功后自动删除。
- 隔离的 Cron 运行会在运行完成后,尽力关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程,因此分离的浏览器自动化不会遗留孤儿进程。
- 隔离的 Cron 运行还会防止陈旧的确认回复。如果第一次结果只是一个临时状态更新(`on it`、`pulling everything together` 以及类似提示并且没有任何后代子智能体运行仍负责最终答案OpenClaw 会在交付前再次提示一次以获取实际结果。
- 作业持久化保存在 `~/.openclaw/cron/jobs.json`,因此重启不会丢失计划
- 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。
- 一次性作业(`--at`)默认会在成功后自动删除。
- 隔离的 cron 运行会在运行完成时,尽力关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程,这样分离的浏览器自动化就不会留下孤儿进程。
- 隔离的 cron 运行还会防止过期的确认回复。如果第一次结果只是中间状态更新(如 `on it`、`pulling everything together` 以及类似提示并且没有任何后代子智能体运行仍负责最终答案OpenClaw 会在交付前再次提示一次以获取实际结果。
<a id="maintenance"></a>
Cron 的任务协调由运行时负责:只要 Cron 运行时仍将某个任务跟踪为正在运行,该活动的 Cron 任务就会保持存活,即使旧的子会话记录仍然存在也是如此。一旦运行时不再拥有该任务,且 5 分钟宽限期已过,维护流程就可以将该任务标记为 `lost`
cron 的任务协调由运行时负责:只要 cron 运行时仍将该作业跟踪为正在运行,活动中的 cron 任务就会保持存活,即使仍存在旧的子会话记录行也是如此。一旦运行时不再拥有该作业,并且 5 分钟宽限期到期,维护流程就可以将该任务标记为 `lost`
## 调度类型
## 计划类型
| 类型 | CLI 标志 | 描述 |
| ------- | -------- | ------------------------------------------------ |
| `at` | `--at` | 一次性时间戳ISO 8601 或类似 `20m` 的相对时间) |
| `every` | `--every`| 固定间隔 |
| `cron` | `--cron` | 5 字段或 6 字段的 Cron 表达式,可选 `--tz` |
| 类型 | 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 逻辑
| 样式 | `--session` 值 | 运行位置 | 最适合 |
| ------------ | ------------------ | ------------------------ | ------------------------------ |
| 主会话 | `main` | 下一个心跳轮次 | 提醒、系统事件 |
| 隔离 | `isolated` | 专用的 `cron:<jobId>` | 报告、后台杂务 |
| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的重复工作 |
| 自定义会话 | `session:custom-id`| 持久化命名会话 | 基于历史记录持续推进的工作流 |
Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时croner 会在**任一**字段匹配时触发——而不是两者都匹配时。这是标准的 Vixie cron 行为。
**主会话**任务会将一个系统事件加入队列,并可选择唤醒心跳(`--wake now` 或 `--wake next-heartbeat`)。**隔离**任务会在一个全新的专用会话中运行一次独立的智能体轮次。**自定义会话**`session:xxx`)会在多次运行之间持久化上下文,从而支持诸如基于先前摘要生成每日站会之类的工作流。
```
# 预期:"15 日上午 9 点,且仅当这天是周一"
# 实际:"每月 15 日上午 9 点,以及每周一上午 9 点"
0 9 15 * 1
```
对于隔离任务,运行时拆除现在也包括对此 Cron 会话进行尽力而为的浏览器清理。清理失败会被忽略,因此实际的 Cron 结果仍然优先。
这会使它每月触发约 56 次,而不是 01 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件,请使用 Croner 的 `+` day-of-week 修饰符(`0 9 15 * +1`),或只在一个字段上调度,并在你的作业提示或命令中对另一个条件进行保护判断
当隔离的 Cron 运行编排子智能体时交付也会优先选择最终的后代输出而不是陈旧的父级临时文本。如果后代仍在运行OpenClaw 会抑制该父级的部分更新,而不是将其公布出来。
## 执行方式
### 隔离任务的负载选项
| 方式 | `--session` 值 | 运行位置 | 最适合 |
| --------------- | ------------------- | ------------------------ | ------ |
| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 |
| 隔离 | `isolated` | 专用 `cron:<jobId>` | 报告、后台杂务 |
| 当前会话 | `current` | 在创建时绑定 | 依赖上下文的循环工作 |
| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史构建的工作流 |
- `--message`:提示文本(隔离任务必填)
- `--model` / `--thinking`:模型和思考级别覆盖
**主会话**作业会将系统事件加入队列,并可选择唤醒 heartbeat`--wake now` 或 `--wake next-heartbeat`)。**隔离**作业会使用全新的会话运行专用的智能体轮次。**自定义会话**`session:xxx`)会在多次运行之间保留上下文,从而支持如基于此前摘要持续构建的每日站会等工作流。
对于隔离作业,运行时拆除流程现在包含对此 cron 会话的浏览器尽力清理。清理失败会被忽略,以确保实际的 cron 结果仍然优先。
当隔离的 cron 运行编排子智能体时交付也会优先使用最终的后代输出而不是过期的父级中间文本。如果后代仍在运行OpenClaw 会抑制该部分父级更新,而不是提前宣布它。
### 隔离作业的负载选项
- `--message`:提示文本(隔离模式必需)
- `--model` / `--thinking`:模型和 thinking 级别覆盖
- `--light-context`:跳过工作区引导文件注入
- `--tools exec,read`:限制任务可使用的工具
- `--tools exec,read`:限制作业可使用的工具
`--model` 会为该任务使用所选且允许的模型。如果请求的模型不被允许Cron 会记录一条警告,并回退到该任务的智能体/默认模型选择。已配置的回退链仍然适用,但仅设置模型覆盖且未显式设置按任务回退列表时,不再将智能体主模型作为隐藏的额外重试目标附加进去。
`--model` 会为该作业使用所选的允许模型。如果请求的模型不被允许cron 会记录警告,并回退到该作业的智能体/默认模型选择。已配置的回退链仍然适用,但仅指定模型覆盖而未显式提供按作业定义的回退列表时,不再把智能体主模型作为隐藏的额外重试目标附加进去。
隔离任务的模型选择优先级如下:
隔离作业的模型选择优先级如下:
1. Gmail hook 模型覆盖(当运行来自 Gmail 且该覆盖被允许时)
2. 按任务负载中的 `model`
3. 已存储的 Cron 会话模型覆盖
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 |
| `none` | 仅内部保留,不进行交付 |
| 模式 | 发生的情况 |
| ---------- | ---------- |
| `announce` | 将摘要交付到目标渠道(隔离模式的默认值) |
| `webhook` | 将完成事件负载 POST 到某个 URL |
| `none` | 仅内部使用,不交付 |
使用 `--announce --channel telegram --to "-1001234567890"`交付到某个渠道。对于 Telegram 论坛话题,请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀(`channel:<id>`、`user:<id>`)。
使用 `--announce --channel telegram --to "-1001234567890"`进行渠道交付。对于 Telegram forum topic,请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀(`channel:<id>`、`user:<id>`)。
对于由 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 示例
@ -131,7 +143,7 @@ openclaw cron add \
--wake now
```
带交付的重复隔离任务
带交付的循环隔离作业
```bash
openclaw cron add \
@ -145,7 +157,7 @@ openclaw cron add \
--to "channel:C1234567890"
```
带模型和思考覆盖的隔离任务
带模型和 thinking 覆盖的隔离作业
```bash
openclaw cron add \
@ -159,9 +171,9 @@ openclaw cron add \
--announce
```
## Webhook
## Webhooks
Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用:
Gateway 网关可以暴露 HTTP webhook 端点,用于外部触发器。在配置中启用:
```json5
{
@ -173,9 +185,9 @@ Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配
}
```
###
### 身份验
每个请求都必须通过请求头包含 hook token
每个请求都必须通过请求头携带 hook token
- `Authorization: Bearer <token>`(推荐)
- `x-openclaw-token: <token>`
@ -198,7 +210,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
### POST /hooks/agent
运行一隔离的智能体轮次:
运行一隔离的智能体轮次:
```bash
curl -X POST http://127.0.0.1:18789/hooks/agent \
@ -209,19 +221,19 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
字段:`message`(必填)、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。
### 映射 hooksPOST /hooks/\<name\>
### 映射 hooksPOST /hooks/\<name\>
自定义 hook 名称会通过配置中的 `hooks.mappings` 进行解析。映射可以使用模板或代码转换,将任意负载转换为 `wake``agent` 动作。
自定义 hook 名称会通过配置中的 `hooks.mappings` 解析。映射可以通过模板或代码转换,将任意负载转换为 `wake``agent` 动作。
### 安全
### 安全
- 将 hook 端点保留在 loopback、tailnet 或受信任的反向代理之后。
- 使用专用的 hook token不要复用网关认证 token。
- 将 `hooks.path` 在专用子路径下;`/` 会被拒绝。
- 将 hook 端点在 loopback、tailnet 或受信任的反向代理之后。
- 使用专用 hook token不要复用 Gateway 网关身份验证 token。
- 将 `hooks.path` 保持在专用子路径下;`/` 会被拒绝。
- 设置 `hooks.allowedAgentIds` 以限制显式的 `agentId` 路由。
- 除非你确实需要由调用方选择会话,否则请保持 `hooks.allowRequestSessionKey=false`
- 除非你需要让调用方选择会话,否则保持 `hooks.allowRequestSessionKey=false`
- 如果你启用了 `hooks.allowRequestSessionKey`,也要设置 `hooks.allowedSessionKeyPrefixes`,以约束允许的会话键形态。
- 默认情况下hook 负载会被安全边界包
- 默认情况下hook 负载会被安全边界包
## Gmail PubSub 集成
@ -235,15 +247,15 @@ 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 网关自动启动
`hooks.enabled=true` 且设置了 `hooks.gmail.account`Gateway 网关会在启动时启动 `gog gmail watch serve`,并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出此行为
`hooks.enabled=true` 且设置了 `hooks.gmail.account`Gateway 网关会在启动时运行 `gog gmail watch serve`,并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。
### 手动一次性设置
1. 选择拥有 `gog`使用 OAuth 客户端的 GCP 项目:
1. 选择拥有 `gog` 所用 OAuth 客户端的 GCP 项目:
```bash
gcloud auth login
@ -251,7 +263,7 @@ gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
```
2. 创建主题并授予 Gmail 推送访问权限:
2. 创建 topic 并授予 Gmail 推送访问权限:
```bash
gcloud pubsub topics create gog-gmail-watch
@ -282,16 +294,16 @@ gog gmail watch start \
}
```
## 管理任务
## 管理作业
```bash
# 列出所有任务
# 列出所有作业
openclaw cron list
# 编辑任务
# 编辑作业
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
# 立即强制运行任务
# 立即强制运行作业
openclaw cron run <jobId>
# 仅在到期时运行
@ -300,20 +312,20 @@ openclaw cron run <jobId> --due
# 查看运行历史
openclaw cron runs --id <jobId> --limit 50
# 删除任务
# 删除作业
openclaw cron remove <jobId>
# 智能体选择(多智能体置)
# 智能体选择(多智能体置)
openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --message "Check ops queue" --agent ops
openclaw cron edit <jobId> --clear-agent
```
模型覆盖说明:
- `openclaw cron add|edit --model ...` 会更改任务所选的模型。
- 如果该模型被允许,该确切的提供商/模型会传递给隔离的智能体运行
- 如果不被允许,Cron 会发出警告,并回退到该任务的智能体/默认模型选择。
- 已配置的回退链仍然适用,但仅设置 `--model` 覆盖且未显式设置按任务回退列表时,不再悄悄回落到智能体主模型作为额外的重试目标。
- `openclaw cron add|edit --model ...` 会更改作业所选的模型。
- 如果该模型被允许,那个精确的提供商/模型会传递到隔离的智能体运行中
- 如果不被允许,cron 会发出警告,并回退到作业的智能体/默认模型选择。
- 已配置的回退链仍然适用,但普通的 `--model` 覆盖如果没有显式的按作业定义的回退列表,就不再静默地回退到智能体主模型作为额外重试目标。
## 配置
@ -335,11 +347,11 @@ openclaw cron edit <jobId> --clear-agent
}
```
禁用 Cron`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`
禁用 cron`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`
**一次性任务重试**:瞬时错误(速率限制、过载、网络、服务器错误)最多重试 3 次,并使用指数退避。永久性错误会立即禁用。
**一次性作业重试**:临时错误(速率限制、过载、网络、服务器错误)最多重试 3 次,并使用指数退避。永久性错误会立即禁用。
**重复任务重试**:在重试之间使用指数退避30 秒到 60 分钟)。下一次成功运行后,退避会重置。
**循环作业重试**重试之间使用指数退避30 秒到 60 分钟)。下一次成功运行后,退避会重置。
**维护**`cron.sessionRetention`(默认 `24h`)会清理隔离运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。
@ -362,26 +374,26 @@ openclaw doctor
- 检查 `cron.enabled``OPENCLAW_SKIP_CRON` 环境变量。
- 确认 Gateway 网关在持续运行。
- 对于 `cron` 调度,核对时区(`--tz`)与主机时区是否一致。
- 运行输出中的 `reason: not-due` 表示手动运行是通过 `openclaw cron run <jobId> --due` 检查的,而该任务尚未到期。
- 对于 `cron` 计划,核对时区(`--tz`)与主机时区是否一致。
- 运行输出中的 `reason: not-due` 表示手动运行是通过 `openclaw cron run <jobId> --due` 检查的,而该作业尚未到期。
### Cron 已触发但没有交付
- 交付模式为 `none` 表示不期望有任何外部消息。
- 缺少/无效的交付目标(`channel`/`to`)表示出站发送已被跳过
- 渠道认证错误(`unauthorized`、`Forbidden`)表示交付被凭据阻止。
- 如果隔离运行只返回静默令牌(`NO_REPLY` / `no_reply`OpenClaw 会抑制直接的对外交付,同时也会抑制回退的排队摘要路径,因此不会有任何内容回发到聊天中。
- 对于由 Cron 拥有的隔离任务,不要期待智能体使用消息工具作为回退。运行器负责最终交付;`--no-deliver` 会使其保持为内部运行,而不是允许直接发送。
- 如果交付模式是 `none`,则不会有外部消息。
- 如果交付目标缺失/无效(`channel`/`to`),则会跳过对外发送
- 渠道身份验证错误(`unauthorized`、`Forbidden`)表示由于凭证问题,交付被阻止。
- 如果隔离运行只返回静默令牌(`NO_REPLY` / `no_reply`OpenClaw 会抑制直接对外发送,也会抑制后备的排队摘要路径,因此不会有任何内容回发到聊天中。
- 对于由 cron 拥有的隔离作业,不要期望智能体将 message 工具作为后备。运行器拥有最终交付;`--no-deliver` 会让它保持内部化,而不是允许直接发送。
### 时区注意事项
- 未使用 `--tz` 的 Cron 会使用 Gateway 网关主机的时区。
- 不带时区的 `at` 调度会被视为 UTC。
- Heartbeat `activeHours` 使用已配置的时区解析。
- 不带 `--tz` 的 cron 使用 gateway 主机时区。
- 不带时区的 `at` 计划会被视为 UTC。
- Heartbeat `activeHours` 使用已配置的时区解析。
## 相关内容
- [自动化与任务](/zh-CN/automation) — 一览所有自动化机制
- [后台任务](/zh-CN/automation/tasks) — Cron 执行的任务账本
- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次
- [自动化与任务](/zh-CN/automation) — 所有自动化机制总览
- [后台任务](/zh-CN/automation/tasks) — cron 执行的任务台账
- [Heartbeat](/zh-CN/gateway/heartbeat) — 定期主会话轮次
- [时区](/zh-CN/concepts/timezone) — 时区配置