AI 技术教程 | Gateway 定时任务完整配置指南

下午好！本文是 Gateway 定时任务的完整配置指南，从基础概念到高级应用，帮助你彻底掌握 OpenClaw 自动化系统。

一、引言：为什么需要 Gateway 定时任务

在自动化工作流中，定时任务是最基础也最重要的组成部分。无论是每日文章发布、定期数据备份，还是周期性报告生成，都离不开可靠的定时任务系统。

OpenClaw Gateway 提供了企业级的定时任务管理能力：

• ✅ 持久化存储（重启不丢失）
• ✅ 精确的 cron 表达式支持
• ✅ 时区感知（支持 Asia/Shanghai 等）
• ✅ 任务执行历史记录
• ✅ 错误检测和重试机制
• ✅ 与 OpenClaw 会话系统深度集成

二、核心概念

2.1 任务结构

每个 Gateway 定时任务由以下核心字段组成：

```json
{
  "id": "unique-task-id",           // 唯一标识符
  "name": "任务名称",                // 人类可读的名称
  "description": "任务描述",         // 详细说明
  "schedule": {                     // 调度配置
    "kind": "cron",                 // 调度类型
    "expr": "0 8 * * *",           // cron 表达式
    "tz": "Asia/Shanghai"          // 时区
  },
  "sessionTarget": "main",         // 目标会话
  "wakeMode": "next-heartbeat",    // 唤醒模式
  "payload": {                     // 任务内容
    "kind": "systemEvent",
    "text": "执行内容"
  },
  "enabled": true,                 // 是否启用
  "deleteAfterRun": false          // 运行后是否删除
}
```

2.2 Cron 表达式详解

Cron 表达式由 5 个字段组成，分别表示：

```
┌───────────── 分钟 (0 - 59)
│ ┌───────────── 小时 (0 - 23)
│ │ ┌───────────── 日期 (1 - 31)
│ │ │ ┌───────────── 月份 (1 - 12)
│ │ │ │ ┌───────────── 星期 (0 - 6)
│ │ │ │ │
* * * * *
```

常用示例：

```bash
# 每天早上 8 点
0 8 * * *

# 每小时整点
0 * * * *

# 每 15 分钟
*/15 * * * *

# 每周一上午 9 点
0 9 * * 1

# 每天中午 12 点和晚上 8 点
0 12,20 * * *
```

三、环境准备

在开始配置之前，请确保：

3.1 系统要求

```bash
# 检查 OpenClaw 版本（需要 2026.4.0+）
openclaw --version

# 检查 Gateway 状态
openclaw gateway status

# 预期输出：
# Gateway: running
# Version: 2026.4.5
```

3.2 配置文件位置

```bash
# 定时任务配置文件
~/.openclaw/cron/jobs.json

# Gateway 日志
~/.openclaw/logs/gateway.log

# 任务执行历史
~/.openclaw/cron/history.json
```

四、实操步骤

以下是完整的配置流程：

步骤 1：查看现有任务

```bash
# 列出所有定时任务
openclaw cron list

# 查看任务详情
openclaw cron get wp-generate-7h

# 查看任务执行历史
openclaw cron history --task wp-generate-7h --limit 10
```

步骤 2：创建新任务（手动编辑）

```bash
# 备份现有配置
cp ~/.openclaw/cron/jobs.json ~/.openclaw/cron/jobs.json.bak

# 编辑配置文件
vim ~/.openclaw/cron/jobs.json

# 添加新任务（在 jobs 数组中）
{
  "id": "my-daily-task",
  "name": "我的每日任务",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "text": "执行我的任务"
  },
  "enabled": true
}
```

步骤 3：验证配置

```bash
# 验证 JSON 格式
python3 -m json.tool ~/.openclaw/cron/jobs.json > /dev/null && echo "JSON 有效"

# 重新加载配置（Gateway 会自动检测）
openclaw gateway reload

# 验证任务已注册
openclaw cron list | grep "my-daily-task"
```

步骤 4：测试任务

```bash
# 手动触发任务
openclaw cron run my-daily-task

# 查看执行结果
openclaw cron history --task my-daily-task --limit 1

# 查看 Gateway 日志
tail -n 50 ~/.openclaw/logs/gateway.log | grep "my-daily-task"
```

步骤 5：监控和维护

```bash
# 查看任务状态
openclaw cron status my-daily-task

# 暂停任务
openclaw cron disable my-daily-task

# 恢复任务
openclaw cron enable my-daily-task

# 删除任务
openclaw cron remove my-daily-task
```

五、案例分析

让我们通过实际案例来学习：

案例 1：每日文章发布系统

```json
{
  "id": "wp-generate-7h",
  "name": "生成文章内容",
  "schedule": {
    "kind": "cron",
    "expr": "0 7 * * *",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "text": "生成今日 3 篇文章（早间/午间/晚间）"
  }
}
```

效果：每天早上 7 点自动生成 3 篇高质量文章

案例 2：每小时任务状态检测

```json
{
  "id": "task-detection-hourly",
  "name": "任务状态检测",
  "schedule": {
    "kind": "cron",
    "expr": "0 * * * *",
    "tz": "Asia/Shanghai",
    "staggerMs": 300000
  },
  "payload": {
    "text": "检测任务状态"
  }
}
```

效果：每小时检测一次任务执行情况，及时发现异常

案例 3：每周日解决方案整理

```json
{
  "id": "learning-solutions-sun-15h",
  "name": "解决方案整理",
  "schedule": {
    "kind": "cron",
    "expr": "0 15 * * 0",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "text": "整理解决方案"
  }
}
```

效果：每周日下午 3 点自动整理本周问题解决方案

六、故障排查

以下是常见问题及解决方案：

问题 1：任务未执行

```
症状：任务配置正确，但到时间未执行

排查步骤：
1. 检查 Gateway 状态：openclaw gateway status
2. 检查任务是否启用：openclaw cron get 
3. 查看 Gateway 日志：tail -f ~/.openclaw/logs/gateway.log
4. 检查 cron 表达式时区是否正确

解决方案：
- 重启 Gateway：openclaw gateway restart
- 重新加载配置：openclaw gateway reload
```

问题 2：任务执行失败

```
症状：任务触发但执行失败

排查步骤：
1. 查看任务历史：openclaw cron history --task 
2. 检查 payload 内容是否正确
3. 验证 sessionTarget 是否存在

解决方案：
- 修正 payload 内容
- 确保目标会话可用
- 添加错误处理逻辑
```

问题 3：配置丢失

```
症状：重启后任务配置丢失

原因：使用了系统 crontab 而非 Gateway 定时任务

解决方案：
1. 所有任务必须配置在 ~/.openclaw/cron/jobs.json
2. 不要使用 /etc/crontab 或 crontab -e
3. 定期备份 jobs.json 文件
```

七、最佳实践

• 实践 1：使用有意义的任务 ID（如 wp-generate-7h 而非 task-1）
• 实践 2：为重要任务添加详细描述
• 实践 3：配置时区为 Asia/Shanghai（北京时间）
• 实践 4：定期备份 jobs.json 文件
• 实践 5：使用 staggerMs 避免多个任务同时触发
• 实践 6：监控任务执行历史，及时发现异常

八、参考资源

• OpenClaw 官方文档 – 定时任务：https://docs.openclaw.ai/zh-CN/automation/cron-jobs
• OpenClaw GitHub 仓库：https://github.com/openclaw/openclaw
• Cron 表达式生成器：https://crontab.guru/
• Gateway 配置指南：https://docs.openclaw.ai/zh-CN/gateway

感谢阅读本教程。如有疑问，请在 OpenClaw 社区论坛提问。