自动化：钩子、定时任务、Webhook

钩子系统概述

OpenClaw 的钩子系统（Hook）提供了一种强大的事件驱动机制，允许开发者在机器人生命周期的各个阶段插入自定义逻辑。钩子系统基于发布-订阅模式设计，核心概念包括事件类型、监听器和处理器。

enum HookEventType {
  // 消息事件
  MESSAGE_RECEIVED = 'message:received',
  MESSAGE_SENT = 'message:sent',
  MESSAGE_BEFORE_SEND = 'message:beforeSend',

  // 会话事件
  SESSION_STARTED = 'session:started',
  SESSION_ENDED = 'session:ended',

  // 用户事件
  USER_JOINED = 'user:joined',
  USER_LEFT = 'user:left',

  // 系统事件
  BOT_STARTED = 'bot:started',
  BOT_STOPPED = 'bot:stopped',
  ERROR_CAUGHT = 'error:caught',

  // 外部事件
  WEBHOOK_RECEIVED = 'webhook:received',
  CRON_TRIGGERED = 'cron:triggered',
}

interface HookHandler {
  /** 处理器优先级，数值越小越先执行 */
  priority: number;
  /** 事件处理函数，返回 false 可阻止后续处理器执行 */
  handler: (context: HookContext) => Promise<HookResult | void>;
}

interface HookContext {
  event: HookEventType;
  bot: BotInstance;
  payload: Record<string, unknown>;
  timestamp: Date;
  metadata: Record<string, unknown>;
}

支持的事件类型

钩子系统覆盖了机器人运行的所有关键阶段。消息类事件是最常用的，包括消息接收前、接收后的预处理和后处理。例如，可以使用 message:beforeSend 事件对模型输出进行内容审核，或者使用 message:received 事件实现自动翻译功能。

会话类事件用于管理用户与机器人的对话生命周期。当用户首次与机器人交互时触发 session:started 事件，可以利用这一时机发送欢迎语或初始化用户上下文数据。当会话结束时触发 session:ended 事件，适合在此处保存对话摘要或清理临时资源。

用户类事件主要应用于群组机器人场景。当新成员加入群组时，user:joined 事件可以触发欢迎消息和自动角色分配。当用户离开时，user:left 事件可用于清理与该用户相关的会话数据和权限缓存。

系统类事件中，bot:started 和 bot:stopped 事件分别在机器人启动和停止时触发，适合执行初始化资源加载和资源释放等操作。error:caught 事件是全局错误捕获的入口点，可以在该事件中实现错误日志记录、告警通知和自动恢复等逻辑。

外部事件中的 webhook:received 是连接外部系统的桥梁，当第三方服务通过 HTTP 回调推送数据时触发。cron:triggered 事件由定时调度器按配置的 Cron 表达式触发，适合执行周期性的后台任务。

Hook 配置与使用

通过配置文件可以灵活地启用和排序各种钩子。以下是一个完整的钩子配置示例：

import { defineConfig } from 'openclaw';

export default defineConfig({
  hooks: [
    {
      event: 'message:received',
      priority: 10,
      handler: async (ctx) => {
        // 敏感词过滤
        const sensitiveWords = ['敏感词1', '敏感词2'];
        const content = ctx.payload.content as string;
        for (const word of sensitiveWords) {
          if (content.includes(word)) {
            return { blocked: true, reason: '包含敏感内容' };
          }
        }
      },
    },
    {
      event: 'message:beforeSend',
      priority: 20,
      handler: async (ctx) => {
        // 自动添加签名
        const content = ctx.payload.content as string;
        ctx.payload.content = content + '\n\n---\n*由 AI 助手自动生成*';
      },
    },
    {
      event: 'session:started',
      handler: async (ctx) => {
        // 新会话欢迎语
        const bot = ctx.bot;
        await bot.sendMessage({
          chatId: ctx.payload.chatId as string,
          content: '你好！我是你的 AI 助手，有什么可以帮助你的吗？',
        });
      },
    },
  ],
});

Cron 定时任务配置

OpenClaw 内置了 Cron 任务调度器，支持标准的 Linux Cron 表达式。定时任务适合实现周期性推送、数据清理、状态检查等场景：

import { defineConfig } from 'openclaw';

export default defineConfig({
  cron: [
    {
      // 每天早上 8 点发送早安简报
      expression: '0 8 * * *',
      description: '每日早安推送',
      timezone: 'Asia/Shanghai',
      action: async (bot) => {
        const weather = await fetchWeather();
        const news = await fetchTopNews();
        const message = [
          '🌅 早上好！今天是 ' + new Date().toLocaleDateString('zh-CN'),
          '',
          '📊 今日天气：' + weather,
          '📰 今日要闻：' + news,
          '',
          '祝你拥有愉快的一天！',
        ].join('\n');

        // 推送到所有订阅用户
        const subscribers = await getSubscribers();
        for (const user of subscribers) {
          await bot.sendMessage({ chatId: user.chatId, content: message });
        }
      },
    },
    {
      // 每小时同步一次知识库
      expression: '0 * * * *',
      description: '知识库定时同步',
      action: async (bot) => {
        await syncKnowledgeBase();
        console.log('[Cron] 知识库同步完成');
      },
    },
    {
      // 每周一凌晨 3 点清理过期数据
      expression: '0 3 * * 1',
      description: '过期数据清理',
      action: async (bot) => {
        const cleaned = await cleanupExpiredData(30);
        console.log(`[Cron] 已清理 ${cleaned} 条过期记录`);
      },
    },
  ],
});

Webhook 事件处理流程

Webhook 机制允许 OpenClaw 接收来自外部系统的 HTTP 回调，是实现与第三方系统集成的关键通道。完整的 Webhook 处理流程包括请求验证、事件解析、业务处理和结果回执四个阶段：

import { defineConfig } from 'openclaw';

export default defineConfig({
  webhooks: {
    '/webhook/github': {
      secret: process.env.GITHUB_WEBHOOK_SECRET,
      verifySignature: true,
      handler: async (req, reply) => {
        const event = req.headers['x-github-event'];
        const payload = req.body;

        switch (event) {
          case 'issues:opened':
            await handleNewIssue(payload);
            break;
          case 'pull_request:opened':
            await handleNewPR(payload);
            break;
          case 'push':
            await handleCodePush(payload);
            break;
        }

        return { status: 'ok' };
      },
    },
    '/webhook/gmail': {
      secret: process.env.GMAIL_WEBHOOK_SECRET,
      handler: async (req) => {
        // 处理 Gmail Pub/Sub 推送
        const message = Buffer.from(req.body.message.data, 'base64')
          .toString('utf-8');
        const parsed = JSON.parse(message);
        await processGmailNotification(parsed);
        return { status: 'received' };
      },
    },
  },
});

Gmail Pub/Sub 集成示例

通过 Google Cloud Pub/Sub 服务，可以实现 Gmail 邮件的实时推送。每当收到新邮件时，Gmail 会通过 Pub/Sub 向配置的 Webhook 端点发送通知，OpenClaw 收到通知后可以自动处理邮件。具体流程如下：

首先在 Google Cloud Console 中创建 Pub/Sub Topic 和 Subscription，并将 Subscription 的推送端点指向 OpenClaw 的 Webhook 地址。然后在 Google Workspace 中配置 Gmail 的监控规则，将所有邮件通知发送到该 Topic。最后在 OpenClaw 中注册对应的 Webhook 处理器，即可实现邮件自动分类、自动回复等高级功能。

整个集成链路中需要注意几个关键配置点。第一，Pub/Sub 推送端点的验证需要配置适当的认证令牌，确保只有 Google 服务能向你的 Webhook 地址推送数据。第二，Gmail 推送的通知内容实际上是经过 Base64 编码的 JSON 负载，收到后需要先解码再解析。第三，邮件处理是一个比较耗时的操作，建议将具体的邮件处理逻辑放在异步任务队列中执行，避免阻塞 Webhook 响应。具体而言，可以在收到通知后将邮件 ID 写入 Redis 队列，再由后台 Worker 从队列中取出并执行实际的邮件分类、智能回复或工单创建等操作。

如果希望实现更复杂的邮件自动化，可以将多个钩子串联使用。例如，用 webhook:received 事件接收邮件通知，用 message:beforeSend 钩子在自动回复前检查邮件内容是否包含需要人工处理的标记，最后用 message:sent 事件记录邮件处理日志。这种多层钩子组合的方式可以灵活地构建出各种复杂的业务逻辑。

实战：完整自动化工作流

将 Hook、Cron 和 Webhook 三者结合可以构建强大的自动化工作流。以下是一个企业级客服机器人的自动化配置示例：

• 触发条件：用户发送消息触发 message:received 事件，经过敏感词过滤和意图识别后，由 AI 模型生成回复。
• 定时任务：每天早上 9 点通过 Cron 任务发送工单统计日报，每天晚上 10 点清理当日临时会话缓存。
• 外部集成：当 CRM 系统通过 Webhook 推送客户等级变更时，自动更新用户标签并调整服务优先级。

这种三合一的自动化架构能够显著减少人工干预，让机器人真正做到 7x24 小时无人值守运行。