OpenClaw Gateway 定时任务系统完整指南

引言：为什么需要自动化定时任务

在现代工作流自动化中，定时任务系统扮演着至关重要的角色。无论是每日报告生成、定期数据同步、还是自动化内容发布，可靠的定时任务系统都能将重复性工作转变为自动化流程，让你专注于更有价值的创造性工作。

OpenClaw Gateway 内置的定时任务系统提供了一个强大而灵活的解决方案，支持 Cron 表达式、固定间隔、一次性任务等多种调度模式，并与会话系统深度集成，实现智能化的任务执行和结果交付。

本指南将深入探讨 OpenClaw Gateway 定时任务系统的配置、使用和最佳实践，帮助你构建稳定可靠的自动化工作流。

核心概念：定时任务系统架构

任务存储与持久化

OpenClaw 定时任务存储在 ~/.openclaw/cron/jobs.json 文件中，采用 JSON 格式，支持版本控制和手动编辑。任务配置在 Gateway 启动时自动加载，修改后可通过热重载或重启生效。

{
  "version": 1,
  "jobs": [
    {
      "id": "task-detection-hourly",
      "name": "任务状态检测",
      "schedule": {
        "kind": "cron",
        "expr": "0 * * * *",
        "tz": "Asia/Shanghai"
      },
      "sessionTarget": "main",
      "wakeMode": "next-heartbeat",
      "payload": {
        "kind": "systemEvent",
        "text": "检测任务状态"
      },
      "enabled": true
    }
  ]
}

执行模式

定时任务支持多种执行模式，适应不同的使用场景：

主会话模式：任务在主会话中执行，适合需要访问上下文的任务
隔离会话模式：任务在独立会话中执行，适合后台报告和批量处理
心跳唤醒模式：任务触发后等待下次心跳时处理，适合非紧急任务
立即执行模式：任务触发后立即执行，适合紧急提醒

环境准备：配置步骤

步骤一：检查 Gateway 状态

在配置定时任务之前，确保 Gateway 服务正常运行：

# 检查 Gateway 状态
openclaw gateway status

# 查看日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

步骤二：验证配置文件

检查定时任务配置文件是否存在且格式正确：

# 查看当前任务列表
cat ~/.openclaw/cron/jobs.json | jq '.jobs | length'

# 验证 JSON 格式
cat ~/.openclaw/cron/jobs.json | jq .

步骤三：配置时区

确保定时任务使用正确的时区，避免执行时间偏差：

{
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",
    "tz": "Asia/Shanghai"
  }
}

代码示例：三种典型场景

示例一：每小时任务检测

{
  "id": "task-detection-hourly",
  "name": "任务状态检测",
  "description": "每小时检测停滞、阻塞、超期任务",
  "schedule": {
    "kind": "cron",
    "expr": "0 * * * *",
    "tz": "Asia/Shanghai",
    "staggerMs": 300000
  },
  "sessionTarget": "main",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "systemEvent",
    "text": "检测任务状态"
  },
  "enabled": true,
  "deleteAfterRun": false
}

说明：此任务每小时整点执行，检测系统中的异常任务状态，并将结果写入 HEARTBEAT.md 文件。

示例二：每日文章发布

{
  "id": "wp-morning-8h",
  "name": "早间文章发布",
  "description": "08:00 发布早间热点文章到 WordPress",
  "schedule": {
    "kind": "cron",
    "expr": "0 8 * * *",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "main",
  "wakeMode": "now",
  "payload": {
    "kind": "systemEvent",
    "text": "执行：/root/.openclaw/workspace/skills/wordpress-auto-publish/publish_wp_post_v4.sh morning"
  },
  "enabled": true
}

说明：此任务每天 08:00 执行，调用发布脚本将早间文章发布到 WordPress 网站。

示例三：学习任务

{
  "id": "learning-openclaw-daily-0h10",
  "name": "OpenClaw 文档每日学习",
  "description": "每日 00:10 学习 OpenClaw 官方文档所有内容",
  "schedule": {
    "kind": "cron",
    "expr": "10 0 * * *",
    "tz": "Asia/Shanghai"
  },
  "sessionTarget": "main",
  "wakeMode": "next-heartbeat",
  "payload": {
    "kind": "systemEvent",
    "text": "学习 OpenClaw 官方文档 https://docs.openclaw.ai/zh-CN 所有内容，总结 Gateway 配置、定时任务、技能系统、故障排查等问题的解决方案"
  },
  "enabled": true
}

说明：此任务每天凌晨 00:10 执行，学习官方文档并总结关键知识点。

实操教程：配置定时任务

第一步：创建任务配置

编辑定时任务配置文件，添加新任务：

# 备份原配置
cp ~/.openclaw/cron/jobs.json ~/.openclaw/cron/jobs.json.bak

# 编辑配置
nano ~/.openclaw/cron/jobs.json

第二步：验证配置格式

使用 jq 工具验证 JSON 格式是否正确：

# 验证格式
cat ~/.openclaw/cron/jobs.json | jq .

# 检查任务数量
cat ~/.openclaw/cron/jobs.json | jq '.jobs | length'

第三步：重启 Gateway

配置修改后重启 Gateway 使其生效：

# 重启 Gateway
openclaw gateway restart

# 验证状态
openclaw gateway status

第四步：手动测试任务

在预定时间之前手动测试任务执行：

# 查看任务列表
cat ~/.openclaw/cron/jobs.json | jq -r '.jobs[] | "\(.id): \(.name)"'

# 手动执行任务（通过 Gateway API）
curl -X POST http://127.0.0.1:12315/cron/run \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jobId": "task-detection-hourly"}'

第五步：监控执行状态

定期检查任务执行状态和日志：

# 查看 Gateway 日志
tail -100 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep cron

# 查看 HEARTBEAT 报告
cat /root/.openclaw/workspace/HEARTBEAT.md

故障排查：常见问题及解决方案

问题一：任务未执行

症状：定时任务到达执行时间但没有反应

可能原因：

Gateway 服务未运行
任务配置中 enabled 为 false
Cron 表达式格式错误
时区配置不正确

解决方案：

# 1. 检查 Gateway 状态
openclaw gateway status

# 2. 验证任务配置
cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | select(.enabled == true)'

# 3. 验证 Cron 表达式
# 使用 crontab.guru 等在线工具验证

# 4. 检查日志
grep "cron" /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

问题二：任务执行失败

症状：任务执行后返回错误状态

排查步骤：

# 1. 查看详细错误日志
tail -200 /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -A 10 "ERROR"

# 2. 检查任务 payload 是否正确
cat ~/.openclaw/cron/jobs.json | jq '.jobs[] | .payload'

# 3. 手动执行 payload 内容
# 复制 payload.text 内容手动执行测试

问题三：任务重复执行

症状：同一任务在短时间内多次执行

可能原因：

多个 Gateway 实例运行
配置文件重复加载
Cron 表达式配置错误

解决方案：

# 1. 检查 Gateway 进程数量
ps aux | grep "openclaw gateway" | grep -v grep

# 2. 停止多余实例
kill -9 <PID>

# 3. 验证配置文件唯一性
find ~ -name "jobs.json" 2>/dev/null

最佳实践：五条可操作建议

建议一：使用描述性任务 ID

任务 ID 应该清晰表达任务用途，便于日志分析和故障排查：

// ✅ 好的命名
"task-detection-hourly"
"wp-morning-8h"
"learning-feishu-daily-0h05"

// ❌ 避免的命名
"job1"
"task_a"
"temp"

建议二：配置任务交错执行

对于同时触发的多个任务，配置 staggerMs 参数避免瞬时负载过高：

{
  "schedule": {
    "kind": "cron",
    "expr": "0 * * * *",
    "staggerMs": 300000
  }
}

这会让任务在 5 分钟内随机分布执行，避免同时触发造成资源竞争。

建议三：实现任务监控告警

配置任务执行失败时的告警机制：

# 创建监控脚本
cat > /root/.openclaw/workspace/scripts/cron-monitor.sh << 'EOF'
#!/bin/bash
LOG_FILE="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"
if grep -q "cron.*ERROR" "$LOG_FILE"; then
  echo "定时任务执行失败，请检查日志" | \
    curl -X POST "YOUR_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d "{\"text\":\"$(cat)\"}"
fi
EOF
chmod +x /root/.openclaw/workspace/scripts/cron-monitor.sh

建议四：定期备份任务配置

定时备份任务配置文件，防止配置丢失：

# 添加到 crontab
0 5 * * 0 cp ~/.openclaw/cron/jobs.json ~/.openclaw/cron/jobs.json.$(date +\%Y\%m\%d).bak

建议五：文档化任务依赖关系

维护任务依赖关系文档，便于理解和维护：

## 任务依赖关系

### 早间发布流程
1. wp-generate-7h (07:00) → 生成文章
2. wp-morning-8h (08:00) → 发布文章
3. wp-quality-check-8h30 (08:30) → 质量检查

### 学习任务流程
1. learning-openclaw-0h10 (00:10) → 学习文档
2. learning-summary-0h30 (00:30) → 生成总结

参考资源

总结：OpenClaw Gateway 定时任务系统提供了强大而灵活的自动化能力。通过合理配置和最佳实践，你可以构建稳定可靠的自动化工作流，将重复性工作转变为无人值守的自动化流程。记住，良好的任务设计、监控和文档化是长期成功的关键。

published_at: 2026-04-12T08:03:01+08:00
post_id: 1508