14. OpenClaw 自动化与定时任务：Cron、Webhook 与 Gmail 集成

适用于 OpenClaw v2026.2 | 本文适合想让 AI 助手主动工作而非被动响应的用户。

TL;DR: Cron 定时任务："cron": [{"id": "daily", "schedule": "0 9 * * *", "message": "..."}]。Webhook 触发：POST /webhook/your-path。Gmail Pub/Sub 自动处理邮件。Heartbeat 主动检查。配置示例：每日晨报 0 8 * * 1-5，CI 通知 webhook，邮件过滤器 gmail pub/sub。

自动化概览

自动化类型

类型	触发方式	适用场景
Cron	定时触发	每日报告、定期检查
Webhook	HTTP 请求	外部系统集成
Gmail Pub/Sub	新邮件	邮件自动化
Heartbeat	周期检查	主动提醒、建议

架构图

flowchart TB
    subgraph Triggers["触发源"]
        CRON[Cron 定时]
        WH[Webhook HTTP]
        GM[Gmail Pub/Sub]
        HB[Heartbeat]
    end
    
    subgraph Gateway["Gateway"]
        SCHED[调度器]
        ROUTE[路由器]
        AGENT[Agent]
    end
    
    subgraph Actions["动作"]
        MSG[发送消息]
        EXEC[执行任务]
        NOTIF[发送通知]
    end
    
    CRON --> SCHED
    WH --> ROUTE
    GM --> ROUTE
    HB --> SCHED
    
    SCHED --> AGENT
    ROUTE --> AGENT
    AGENT --> MSG
    AGENT --> EXEC
    AGENT --> NOTIF

Cron 定时任务

Cron 表达式

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

常用表达式

表达式	说明
`0 9 * * *`	每天 9:00
`0 18 * * 1-5`	工作日 18:00
`/30 * * *`	每 30 分钟
`0 0 1 * *`	每月 1 日 0:00
`0 9,18 * * *`	每天 9:00 和 18:00
`0 9 * * 1`	每周一 9:00

配置 Cron 任务

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "请给我今天的日程安排和待办事项",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "生成本周工作总结",
      "enabled": true
    },
    {
      "id": "health-check",
      "schedule": "*/15 * * * *",
      "session": "main",
      "message": "检查系统状态，报告任何异常",
      "enabled": true
    }
  ]
}

Cron 配置项

字段	类型	说明
`id`	string	任务唯一标识
`schedule`	string	Cron 表达式
`session`	string	目标会话
`message`	string	发送的消息
`enabled`	boolean	是否启用
`timezone`	string	时区（默认系统时区）

管理 Cron 任务

# 列出所有任务
openclaw cron list

# 输出示例：
# ID               Schedule       Status    Last Run
# daily-briefing   0 9 * * *     enabled   2026-02-26 09:00
# weekly-summary   0 18 * * 5    enabled   2026-02-23 18:00
# health-check    */15 * * * *   enabled   2026-02-26 10:30

# 手动触发任务
openclaw cron run daily-briefing

# 启用/禁用任务
openclaw cron enable daily-briefing
openclaw cron disable daily-briefing

# 查看任务日志
openclaw cron logs daily-briefing

Webhook 触发器

配置 Webhook

{
  "webhooks": [
    {
      "id": "github-push",
      "path": "/webhook/github",
      "secret": "your-webhook-secret",
      "session": "main",
      "handler": "github-push"
    },
    {
      "id": "custom-alert",
      "path": "/webhook/alert",
      "secret": "your-webhook-secret",
      "session": "main",
      "message": "收到告警: {{data.message}}"
    }
  ]
}

Webhook 端点

POST http://your-gateway:18789/webhook/github-push
POST http://your-gateway:18789/webhook/alert

GitHub Webhook 示例

{
  "webhooks": [
    {
      "id": "github-push",
      "path": "/webhook/github",
      "secret": "${GITHUB_WEBHOOK_SECRET}",
      "session": "work",
      "handler": "github-push"
    }
  ]
}

Handler 脚本：

// ~/.openclaw/handlers/github-push.js
module.exports = async (payload, session) => {
  if (payload.ref === 'refs/heads/main') {
    const commits = payload.commits.map(c => c.message).join('\n- ');
    return `检测到新的推送:\n\n分支: main\n提交:\n- ${commits}\n\n需要我帮你做什么吗？`;
  }
  return null;
};

自定义 Webhook 处理

{
  "webhooks": [
    {
      "id": "monitoring-alert",
      "path": "/webhook/alert",
      "methods": ["POST"],
      "session": "main",
      "message": "🚨 告警通知\n\n级别: {{data.level}}\n服务: {{data.service}}\n信息: {{data.message}}\n时间: {{data.timestamp}}"
    }
  ]
}

发送 Webhook：

curl -X POST http://localhost:18789/webhook/alert \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: your-secret" \
  -d '{
    "level": "critical",
    "service": "api-server",
    "message": "CPU 使用率超过 90%",
    "timestamp": "2026-02-26T10:30:00Z"
  }'

Webhook 安全

{
  "webhooks": [
    {
      "id": "secure-webhook",
      "path": "/webhook/secure",
      "secret": "your-secret-key",
      "signatureHeader": "X-Signature",
      "signatureAlgorithm": "sha256",
      "ipWhitelist": ["192.168.1.0/24"]
    }
  ]
}

Gmail Pub/Sub 集成

配置 Gmail Pub/Sub

{
  "gmail": {
    "pubsub": {
      "enabled": true,
      "projectId": "your-project-id",
      "subscription": "gmail-subscription",
      "credentials": {
        "type": "service_account",
        "project_id": "your-project-id",
        "private_key_id": "...",
        "private_key": "...",
        "client_email": "..."
      },
      "filters": [
        {
          "from": "[email protected]",
          "session": "main",
          "message": "收到重要邮件:\n发件人: {{sender}}\n主题: {{subject}}"
        }
      ]
    }
  }
}

设置 Gmail Pub/Sub

创建 Google Cloud 项目
启用 Gmail API
创建 Pub/Sub 主题
创建服务账号
配置 Gmail watch

# 配置 Gmail watch
openclaw gmail watch --email [email protected]

Gmail 过滤器

过滤条件	说明
`from`	发件人邮箱
`to`	收件人邮箱
`subject`	主题关键词
`hasAttachment`	是否有附件
`label`	Gmail 标签

{
  "filters": [
    {
      "from": "[email protected]",
      "session": "work",
      "message": "收到 GitHub 通知: {{subject}}"
    },
    {
      "from": "[email protected]",
      "hasAttachment": true,
      "session": "main",
      "message": "收到 Stripe 文档，请处理"
    }
  ]
}

Heartbeat 主动检查

配置 Heartbeat

{
  "heartbeat": {
    "enabled": true,
    "interval": 3600000,
    "session": "main",
    "message": "Heartbeat: 请检查是否有需要我关注的事项"
  }
}

Heartbeat 用途

用途	说明
主动提醒	定期提醒用户
状态检查	检查系统或服务状态
任务建议	基于上下文提供建议
上下文维护	保持会话活跃

Heartbeat 示例

{
  "heartbeat": {
    "enabled": true,
    "interval": 1800000,
    "conditions": [
      {
        "type": "time",
        "start": "09:00",
        "end": "18:00"
      },
      {
        "type": "active",
        "session": "main"
      }
    ],
    "message": "根据当前时间，建议检查以下事项:\n1. 今日待办\n2. 邮件提醒\n3. 日程安排"
  }
}

自动化实战示例

示例一：每日晨报

{
  "cron": [
    {
      "id": "morning-briefing",
      "schedule": "0 8 * * 1-5",
      "session": "main",
      "message": "早上好！请给我今天的晨报：\n1. 天气预报\n2. 今日日程\n3. 待办事项\n4. 重要邮件摘要"
    }
  ]
}

示例二：CI/CD 通知

{
  "webhooks": [
    {
      "id": "ci-failure",
      "path": "/webhook/ci",
      "session": "dev",
      "message": "⚠️ CI 失败\n\n项目: {{data.repository}}\n分支: {{data.branch}}\n提交: {{data.commit}}\n错误: {{data.error}}\n\n需要我帮你分析吗？"
    }
  ]
}

示例三：邮件自动处理

{
  "gmail": {
    "pubsub": {
      "filters": [
        {
          "from": "[email protected]",
          "hasAttachment": true,
          "session": "main",
          "message": "收到发票邮件，正在处理...\n请将附件保存到财务文件夹"
        }
      ]
    }
  }
}

示例四：系统监控

{
  "cron": [
    {
      "id": "system-monitor",
      "schedule": "*/5 * * * *",
      "session": "main",
      "message": "检查系统状态",
      "skills": ["system-monitor"]
    }
  ]
}

故障排查

Cron 任务不执行

# 检查任务状态
openclaw cron list

# 检查日志
openclaw logs --filter cron

# 手动触发测试
openclaw cron run task-id

Webhook 不响应

# 检查 Webhook 端点
curl -X POST http://localhost:18789/webhook/test \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 查看日志
openclaw logs --filter webhook

Gmail Pub/Sub 不工作

# 检查订阅状态
openclaw gmail status

# 重新配置
openclaw gmail setup

# 检查权限
openclaw gmail check-permissions

小结

自动化让 OpenClaw 从被动响应变为主动工作：

Cron：定时执行任务
Webhook：外部事件触发
Gmail Pub/Sub：邮件自动化
Heartbeat：主动提醒和建议

更新记录：

2026-02-26：初版发布

系列导航：