计划任务

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

快速开始

openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "提醒：检查 cron 文档草稿" \
  --wake now \
  --delete-after-run

openclaw cron list
openclaw cron show <job-id>

openclaw cron runs --id <job-id>

​

Cron 的工作方式

• 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 中。
• 当 Gateway 正在运行或已停止时编辑了 jobs.json，OpenClaw 会将变更后的计划字段与待处理的运行时槽位元数据进行比较，并清除过时的 nextRunAtMs 值。仅格式化或仅键顺序重写会保留待处理槽位。
• 所有 cron 执行都会创建 后台任务 记录。
• 在 Gateway 启动时，已过期的独立 agent-turn 作业会被重新调度到 channel-connect 窗口之外，而不是立即回放，因此 Discord/Telegram 启动和 native-command 设置在重启后仍能保持响应。
• 一次性作业（--at）默认会在成功后自动删除。
• 独立 cron 运行会尽最大努力在运行完成时关闭其 cron:<jobId> 会话所跟踪的浏览器标签页/进程，因此分离的浏览器自动化不会留下孤儿进程。
• 独立 cron 运行还会防止过时的确认回复。如果第一个结果只是一个中间状态更新（on it、pulling everything together 以及类似提示），并且没有后代子 agent 运行仍然负责最终答案，OpenClaw 会在交付前再提示一次以获取真实结果。
• 独立 cron 运行优先使用嵌入式运行中的结构化执行拒绝元数据，然后回退到已知的最终摘要/输出标记，例如 SYSTEM_RUN_DENIED 和 INVALID_REQUEST，因此被阻止的命令不会被报告为成功运行。
• 独立 cron 运行还会将运行级别的 agent 失败视为作业错误，即使没有生成回复载荷也是如此，因此模型/提供方失败会增加错误计数并触发失败通知，而不是将作业清除为成功。
• 当独立 agent-turn 作业达到 timeoutSeconds 时，cron 会中止底层 agent 运行，并给予其一个短暂的清理窗口。如果运行未能完成收尾，Gateway 拥有的清理会在 cron 记录超时之前强制清除该运行的会话所有权，因此排队的聊天工作不会被遗留在一个过时的处理会话之后。

​

计划类型

​

月中的日期和星期采用 OR 逻辑

# 期望："15 日上午 9 点，且仅当那天是星期一"
# 实际：  "每个 15 日上午 9 点，以及每个星期一上午 9 点"
0 9 15 * 1

​

执行样式

​

独立作业的载荷选项

1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时）
2. 每个作业的载荷 model
3. 用户选择的已存储 cron 会话模型覆盖
4. Agent/default 模型选择

​

交付与输出

• cron.failureDestination 设置失败通知的全局默认值。
• job.delivery.failureDestination 可按作业覆盖该设置。
• 如果两者都未设置，且作业已经通过 announce 交付，那么失败通知现在会回退到该主 announce 目标。
• delivery.failureDestination 仅在 sessionTarget="isolated" 的作业上受支持，除非主要交付模式是 webhook。
• failureAlert.includeSkipped: true 可让作业或全局 cron 告警策略纳入重复的跳过运行告警。跳过运行会保留单独的连续跳过计数，因此不会影响执行错误退避。

​

CLI 示例

openclaw cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "下一次 heartbeat：检查日历。"
  --wake now

openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "总结夜间更新。" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

openclaw cron add \
  --name "Deep analysis" \
  --cron "0 6 * * 1" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "每周对项目进展进行深度分析。" \
  --model "opus" \
  --thinking high \
  --announce

​

Webhooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
}

​

认证

• Authorization: Bearer <token>（推荐）
• x-openclaw-token: <token>

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"收到新邮件","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"总结收件箱","name":"Email","model":"openai/gpt-5.4"}'

​

Gmail PubSub 集成

​

向导设置（推荐）

openclaw webhooks gmail setup --account openclaw@gmail.com

​

Gateway 自动启动

​

手动一次性设置

gcloud auth login
gcloud config set project <project-id>
gcloud services enable gmail.googleapis.com pubsub.googleapis.com

gcloud pubsub topics create gog-gmail-watch
gcloud pubsub topics add-iam-policy-binding gog-gmail-watch \
  --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \
  --role=roles/pubsub.publisher

gog gmail watch start \
  --account openclaw@gmail.com \
  --label INBOX \
  --topic projects/<project-id>/topics/gog-gmail-watch

​

Gmail 模型覆盖

{
  hooks: {
    gmail: {
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

​

管理作业

# 列出所有作业
openclaw cron list

# 显示一个作业，包括解析后的交付路由
openclaw cron show <jobId>

# 编辑一个作业
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"

# 立即强制运行一个作业
openclaw cron run <jobId>

# 仅在到期时运行
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

​

配置

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "replace-with-dedicated-webhook-token",
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
  },
}

​

故障排除

​

命令阶梯

openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
openclaw doctor

​

相关内容

• 自动化与任务 — 一览所有自动化机制
• 后台任务 — cron 执行的任务账本
• Heartbeat — 周期性的主会话轮次
• 时区 — 时区配置