openclaw webhooks 配置教程

Webhook 概述

Webhook 是 OpenClaw 与外部平台通信的核心机制。频道平台（Telegram、Discord 等）通过 Webhook 将用户消息推送到 OpenClaw，OpenClaw 也可以配置出站 Webhook 将事件推送到外部系统。

查看 Webhook 列表

openclaw webhooks list

Webhooks:
  Inbound:
    /webhook/telegram     ✓ Active    telegram-main
    /webhook/discord      ✓ Active    discord-dev
    /webhook/slack        ✗ Inactive  slack-team

  Outbound:
    event-logger          ✓ Active    https://log.example.com/events
    backup-bot            ✓ Active    https://backup.example.com/messages

入站 Webhook（频道接收）

入站 Webhook 用于接收频道平台的消息推送。

查看入站 Webhook 详情

openclaw webhooks show telegram

Webhook: telegram
  Path: /webhook/telegram
  Full URL: https://gateway.example.com/webhook/telegram
  Channel: telegram-main
  Status: Active
  Signature Verification: enabled
  Last Received: 2 minutes ago
  Messages Today: 230

设置入站 Webhook

# Telegram
openclaw webhooks set-inbound telegram \
  --url "https://gateway.example.com/webhook/telegram" \
  --verify-signature

# Discord
openclaw webhooks set-inbound discord \
  --url "https://gateway.example.com/webhook/discord" \
  --public-key "discord-public-key"

测试入站 Webhook

openclaw webhooks test telegram --inbound

这会向 Webhook URL 发送一个测试请求，验证连通性。

出站 Webhook（事件推送）

出站 Webhook 用于将 OpenClaw 的事件推送到外部系统。

创建出站 Webhook

openclaw webhooks create event-logger \
  --url "https://log.example.com/events" \
  --events message.received,message.sent,error \
  --secret "webhook-signing-secret"

配置推送事件类型

可用的事件类型：

message.received：收到用户消息
message.sent：发送 AI 回复
message.error：消息处理出错
channel.connected：频道连接成功
channel.disconnected：频道断开
agent.switched：代理切换
system.started：Gateway 启动
system.stopped：Gateway 停止

openclaw webhooks update event-logger \
  --events message.received,message.sent,channel.disconnected

出站 Webhook 负载格式

{
  "event": "message.received",
  "timestamp": "2026-03-15T10:30:00Z",
  "data": {
    "channel": "telegram-main",
    "user": "user123",
    "message": "你好",
    "sessionId": "session-456"
  },
  "signature": "sha256=abc123..."
}

签名验证

出站 Webhook 支持 HMAC-SHA256 签名，接收方可以验证请求来源：

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

重试策略

出站 Webhook 的重试配置：

openclaw webhooks update event-logger \
  --retries 3 \
  --retry-delay 5000 \
  --timeout 10000

{
  "webhooks": {
    "outbound": {
      "event-logger": {
        "url": "https://log.example.com/events",
        "retries": 3,
        "retryDelay": 5000,
        "timeout": 10000,
        "retryStatusCodes": [500, 502, 503, 504]
      }
    }
  }
}

Webhook 日志

# 查看 webhook 调用日志
openclaw webhooks logs event-logger --last 20

# 查看失败的调用
openclaw webhooks logs event-logger --failed

暂停和恢复

openclaw webhooks pause event-logger
openclaw webhooks resume event-logger

删除 Webhook

openclaw webhooks delete event-logger

总结

Webhook 系统是 OpenClaw 与外部世界连接的桥梁。入站 Webhook 接收频道消息，出站 Webhook 将事件推送到外部系统。合理配置重试策略和签名验证，可以确保消息传递的可靠性和安全性。