OpenClaw Webhook集成与事件回调

前言

在实际生产环境中，AI Agent 往往不是孤立运行的——它需要与企业现有的系统进行双向集成。OpenClaw 提供了完善的 Webhook 机制，允许你在特定事件发生时向外部系统发送回调通知，也支持从外部系统接收事件触发 Agent 动作。

本文将全面介绍 OpenClaw 的 Webhook 集成方案，帮助你构建事件驱动的 AI 工作流。

Webhook 基本概念

OpenClaw 的 Webhook 系统分为两个方向：

出站 Webhook（Outgoing）：当 OpenClaw 内部发生特定事件时，向你配置的 URL 发送 HTTP POST 请求
入站 Webhook（Incoming）：外部系统通过 HTTP 请求触发 OpenClaw 的 Agent 执行任务

出站流程：
  OpenClaw 事件 → HTTP POST → 你的服务器

入站流程：
  你的服务器 → HTTP POST → OpenClaw → Agent 处理 → 回调通知

配置出站 Webhook

基本配置

在 openclaw.json5 中添加 Webhook 配置：

{
  webhooks: {
    endpoints: [
      {
        // Webhook 名称
        name: "main-webhook",
        // 目标 URL
        url: "https://your-server.com/openclaw/events",
        // 签名密钥（用于验证请求真实性）
        secret: "whsec_xxxxxxxxxxxxxxxx",
        // 订阅的事件类型
        events: [
          "message.received",
          "message.sent",
          "session.created",
          "session.ended",
          "tool.called",
          "tool.completed",
          "error.occurred"
        ],
        // 重试配置
        retry: {
          maxAttempts: 3,
          backoffMs: 1000
        }
      }
    ]
  }
}

事件类型详解

事件类型	触发时机	用途
`message.received`	收到用户消息时	日志记录、消息审计
`message.sent`	AI 回复发送后	回复监控、内容审核
`session.created`	新会话创建时	用户行为追踪
`session.ended`	会话结束或超时	数据归档
`tool.called`	MCP 工具被调用时	安全审计
`tool.completed`	工具调用完成时	性能监控
`error.occurred`	发生错误时	告警通知

事件负载格式

每个 Webhook 请求的 Body 遵循统一格式：

{
  "id": "evt_abc123def456",
  "type": "message.sent",
  "timestamp": "2026-03-14T10:30:00Z",
  "instanceId": "node-1",
  "data": {
    "agentId": "my-agent",
    "sessionId": "session-001",
    "channel": "telegram",
    "userId": "user_12345",
    "message": {
      "role": "assistant",
      "content": "这是AI的回复内容...",
      "messageId": "msg_xyz789"
    },
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 200,
      "outputTokens": 450
    }
  }
}

签名验证

为了确保 Webhook 请求确实来自你的 OpenClaw 实例，每个请求都会携带签名头：

X-OpenClaw-Signature: sha256=5a8c3f2b...
X-OpenClaw-Timestamp: 1710400200

验证示例（Node.js）：

const crypto = require("crypto");

function verifyWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");
  return `sha256=${expected}` === signature;
}

配置入站 Webhook

入站 Webhook 允许外部系统主动触发 OpenClaw 的 Agent：

{
  webhooks: {
    inbound: {
      enabled: true,
      // 入站Webhook路径前缀
      basePath: "/webhooks/inbound",
      // 端点配置
      endpoints: {
        // 当收到 POST /webhooks/inbound/alert 时触发
        "alert": {
          agentId: "alert-handler",
          // 消息模板，支持变量替换
          template: "收到告警：{{body.title}} - 严重级别：{{body.severity}}"
        },
        "deploy": {
          agentId: "devops-agent",
          template: "{{body.repo}} 的 {{body.branch}} 分支部署{{body.status}}"
        }
      }
    }
  }
}

外部系统调用示例：

# CI/CD 部署通知
curl -X POST http://openclaw.example.com/webhooks/inbound/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "my-app",
    "branch": "main",
    "status": "成功",
    "commit": "abc123"
  }'

实际集成场景

场景一：消息审计与合规

将所有 AI 对话记录发送到企业的审计系统：

{
  webhooks: {
    endpoints: [{
      name: "audit-log",
      url: "https://audit.company.com/api/logs",
      events: ["message.received", "message.sent"],
      // 只发送特定Agent的事件
      filter: {
        agentIds: ["customer-support", "hr-assistant"]
      }
    }]
  }
}

场景二：Slack 告警通知

当 AI Agent 遇到错误时，自动发送 Slack 告警：

{
  webhooks: {
    endpoints: [{
      name: "slack-alert",
      url: "https://hooks.slack.com/services/T00/B00/xxxxx",
      events: ["error.occurred"],
      // 转换为Slack消息格式
      transform: {
        text: "🚨 OpenClaw 告警: {{data.error.message}}\nAgent: {{data.agentId}}\n时间: {{timestamp}}"
      }
    }]
  }
}

场景三：CRM 系统集成

当用户通过聊天开始新会话时，自动在 CRM 中创建记录：

{
  webhooks: {
    endpoints: [{
      name: "crm-integration",
      url: "https://crm.company.com/api/interactions",
      events: ["session.created"],
      headers: {
        "X-API-Key": "${CRM_API_KEY}"
      }
    }]
  }
}

场景四：双向集成——工单系统

结合入站和出站 Webhook，实现 AI Agent 与工单系统的双向联动：

用户通过聊天描述问题 → AI 自动创建工单（出站 Webhook）
工单状态更新 → 通知 AI Agent（入站 Webhook）→ AI 主动通知用户

{
  webhooks: {
    // 出站：新会话 → 创建工单
    endpoints: [{
      name: "create-ticket",
      url: "https://ticketing.company.com/api/tickets",
      events: ["session.created"],
      filter: { agentIds: ["support-bot"] }
    }],
    // 入站：工单更新 → 通知Agent
    inbound: {
      endpoints: {
        "ticket-update": {
          agentId: "support-bot",
          template: "工单 #{{body.ticketId}} 状态已更新为：{{body.status}}"
        }
      }
    }
  }
}

Webhook 调试

查看 Webhook 发送日志

# 查看最近的Webhook事件
openclaw webhooks list --recent 20

# 查看失败的Webhook
openclaw webhooks list --status failed

使用 Dashboard 监控

OpenClaw 的 Web Dashboard 提供了 Webhook 监控面板，可以实时查看事件发送状态、响应时间和失败原因。

本地测试

使用 ngrok 或类似工具在本地测试 Webhook：

# 启动本地代理
ngrok http 8080

# 将生成的URL配置为Webhook目标
# https://xxxx.ngrok.io/openclaw/events

小结

OpenClaw 的 Webhook 机制为 AI Agent 与外部系统之间架起了桥梁。通过出站 Webhook，你可以将 AI 的行为数据发送到审计系统、监控平台和业务系统；通过入站 Webhook，外部事件可以直接触发 AI Agent 的响应。这种事件驱动的架构让 OpenClaw 能够深度融入企业的技术生态，而不仅仅是一个独立的聊天工具。