OpenClaw 定时任务使用指南

什么是定时任务

如果你希望智能体能在特定时间自动执行某些操作，比如"每天早上 7 点发送日报"或"20 分钟后提醒我检查文档"，那么 OpenClaw 的定时任务功能就是你需要的工具。

简单来说，定时任务是 OpenClaw Gateway 网关内置的一个调度器。它的核心作用是：

• 持久化保存你设置的任务
• 在指定时间唤醒智能体执行任务
• 可以选择将执行结果发送到聊天渠道

所有任务都存储在 ~/.openclaw/cron/ 目录下，即使系统重启也不会丢失。

核心概念

在开始使用之前，我们需要理解几个关键概念。

任务的两个要素

每个定时任务本质上就是回答两个问题：

1. 何时运行：通过调度计划（schedule）来定义
2. 做什么：通过负载（payload）来定义

调度计划的三种类型

OpenClaw 支持三种调度方式：

1. 一次性任务（at）
指定一个具体的时间点执行，适合提醒类场景。

--at "2026-02-01T16:00:00Z"

2. 固定间隔（every）
按固定时间间隔重复执行。

--every "30m"  # 每 30 分钟执行一次

3. Cron 表达式（cron）
使用标准的 5 字段 cron 表达式，支持复杂的调度需求。

--cron "0 7 * * *"  # 每天早上 7 点执行

注意：如果使用 cron 表达式时没有指定时区，系统会使用 Gateway 主机的本地时区。你可以通过 --tz 参数指定时区，例如 --tz "America/Los_Angeles"。

执行方式：主会话 vs 隔离会话

这是理解定时任务的关键。OpenClaw 提供了两种执行方式：

主会话任务（main）

• 在主会话的上下文中运行
• 通过系统事件触发，在下一次心跳时执行
• 适合需要访问主会话历史记录的场景
• 使用 --session main 和 --system-event 参数

隔离任务（isolated）

• 在独立的会话中运行，不会污染主聊天记录
• 每次运行都是全新的会话（除非使用自定义会话）
• 可以将结果投递到指定渠道
• 适合后台任务、定期报告等场景
• 使用 --session isolated 和 --message 参数

此外，还有两种特殊的会话绑定方式：

• 当前会话（current）：绑定到创建任务时的会话
• 自定义会话（session:xxx）：在命名会话中运行，可以跨运行保持上下文

快速上手

创建一个简单的提醒

最简单的用法是创建一个一次性提醒：

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

这个命令做了什么：

• 创建一个名为"文档检查提醒"的任务
• 在 2026 年 2 月 1 日 16:00 UTC 时间执行
• 在主会话中运行
• 发送一个系统事件
• 立即唤醒（--wake now）
• 执行后自动删除（--delete-after-run）

创建周期性任务

如果你想每天早上 7 点收到简报：

openclaw cron add \
  --name "早间简报" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "总结昨晚的更新内容" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

这个任务会：

• 每天早上 7 点（洛杉矶时间）执行
• 在隔离会话中运行
• 将摘要发送到指定的 Slack 频道

查看和管理任务

# 列出所有任务
openclaw cron list

# 手动运行某个任务
openclaw cron run <job-id> --force

# 查看任务的运行历史
openclaw cron runs --id <job-id> --limit 50

# 编辑任务
openclaw cron edit <job-id> --cron "0 8 * * *"

# 删除任务
openclaw cron remove <job-id>

实用场景示例

场景 1：每周一早上的站会提醒

openclaw cron add \
  --name "周一站会" \
  --cron "0 6 * * 1" \
  --session isolated \
  --message "准备今天的站会议程" \
  --announce

场景 2：每晚的运维检查

openclaw cron add \
  --name "夜间运维检查" \
  --cron "0 22 * * *" \
  --session isolated \
  --message "检查系统状态和待处理事项" \
  --channel telegram \
  --to "-1001234567890:topic:123"

注意这里的 Telegram 目标格式：-1001234567890:topic:123 表示发送到特定的论坛主题。

场景 3：指定智能体执行任务

如果你有多个智能体，可以指定特定的智能体来执行任务：

openclaw cron add \
  --name "运维巡检" \
  --cron "0 6 * * *" \
  --session isolated \
  --message "检查运维队列" \
  --agent ops

场景 4：使用自定义会话保持上下文

对于需要基于历史信息的任务（如每日站会），可以使用自定义会话：

openclaw cron add \
  --name "每日站会" \
  --cron "0 9 * * 1-5" \
  --session-target "session:daily-standup" \
  --message "基于昨天的进展，准备今天的站会内容"

这样每次执行都能访问之前的会话历史。

消息投递配置

隔离任务的一个强大功能是可以将执行结果投递到各种聊天渠道。

支持的渠道

• WhatsApp
• Telegram
• Discord
• Slack
• Mattermost（通过插件）
• Signal
• iMessage
• last（最后一次对话的渠道）

投递模式

• announce：投递摘要（默认）
• none：内部运行，不投递

投递配置示例

openclaw cron add \
  --name "每日报告" \
  --cron "0 18 * * *" \
  --session isolated \
  --message "生成今日工作总结" \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

如果不指定 --channel 和 --to，系统会回退到"最后路由"，即智能体最后一次回复的位置。

高级功能

模型和思维级别覆盖

对于隔离任务，你可以指定使用特定的模型或思维级别：

openclaw cron add \
  --name "深度分析" \
  --cron "0 2 * * *" \
  --session isolated \
  --message "分析系统性能数据" \
  --model "anthropic/claude-sonnet-4-20250514" \
  --thinking "high"

唤醒模式

主会话任务支持两种唤醒模式：

• next-heartbeat（默认）：等待下一次计划心跳
• now：立即触发心跳运行

--wake now

任务存储和历史

• 任务定义存储在：~/.openclaw/cron/jobs.json
• 运行历史存储在：~/.openclaw/cron/runs/<jobId>.jsonl

你可以通过配置文件修改存储路径：

{
  "cron": {
    "store": "~/.openclaw/cron/jobs.json"
  }
}

如果需要完全禁用定时任务功能：

{
  "cron": {
    "enabled": false
  }
}

故障排查

问题：没有任务在运行

检查以下几点：

1. 确认定时任务功能已启用（检查 cron.enabled 配置和 OPENCLAW_SKIP_CRON 环境变量）
2. 确认 Gateway 网关进程持续运行（定时任务运行在 Gateway 进程内部）
3. 对于 cron 调度，确认时区设置是否正确

问题：Telegram 消息发送到错误的位置

如果你在日志中看到 telegram:... 前缀，这是正常的。定时任务投递系统能够正确解析这些前缀和主题 ID。

确保你的目标格式正确：

• 仅聊天：-1001234567890
• 带主题：-1001234567890:topic:123 或 -1001234567890:123

工具调用方式

除了 CLI，你也可以通过 Gateway API 或智能体工具调用来管理定时任务。

JSON 格式示例

创建一次性提醒：

{
  "name": "提醒任务",
  "schedule": {
    "kind": "at",
    "at": "2026-02-01T16:00:00Z"
  },
  "sessionTarget": "main",
  "payload": {
    "kind": "systemEvent",
    "text": "提醒文本"
  }
}

创建周期性隔离任务：

{
  "name": "早间简报",
  "schedule": {
    "kind": "cron",
    "expr": "0 7 * * *",
    "tz": "America/Los_Angeles"
  },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "总结昨晚的更新"
  },
  "delivery": {
    "mode": "announce",
    "channel": "slack",
    "to": "channel:C1234567890"
  }
}

可用的 API 方法

• cron.list：列出所有任务
• cron.status：查看任务状态
• cron.add：创建新任务
• cron.update：更新任务
• cron.remove：删除任务
• cron.run：手动运行任务
• cron.runs：查看运行历史

最佳实践

1. 合理选择执行方式：如果任务会产生大量输出或频繁执行，使用隔离会话避免污染主聊天
2. 设置合适的时区：使用 cron 表达式时明确指定时区，避免混淆
3. 使用描述性的任务名称：便于后续管理和排查问题
4. 定期检查运行历史：通过 openclaw cron runs 了解任务执行情况
5. 测试后再部署：使用 --force 参数手动运行任务，确认配置正确后再启用自动调度
6. 善用自定义会话：对于需要上下文连续性的任务，使用命名会话而不是每次创建新会话

总结

OpenClaw 的定时任务功能为智能体自动化提供了强大的支持。通过灵活的调度配置、多样的执行方式和丰富的投递选项，你可以轻松实现各种自动化场景。

记住核心要点：

• 定时任务 = 何时运行 + 做什么
• 主会话适合需要上下文的任务，隔离会话适合后台任务
• 合理使用投递功能，将结果发送到合适的渠道
• 善用 CLI 工具进行管理和调试

现在，你可以开始创建自己的第一个定时任务了！