OpenClaw Webhook 集成：连接外部服务

2026-03-01 · 8 分钟进阶玩法

Webhook 能做什么

OpenClaw 的 Webhook 端点允许外部系统通过 HTTP 请求触发 AI 助手执行任务。常见场景包括：

GitHub 收到新 Issue 时，自动分析并分类
监控系统检测到异常时，让 AI 助手诊断问题
定时脚本触发 AI 助手生成报告
第三方服务通过 API 调用 AI 能力

启用 Webhook

在 ~/.openclaw/openclaw.json 中配置：

{
  hooks: {
    enabled: true,
    token: "your-webhook-secret-token"  // 认证令牌
  }
}

启用后，Webhook 端点默认挂载在网关的 /hooks 路径下。

认证方式

所有 Webhook 请求必须携带认证令牌，支持三种方式：

# 推荐：Authorization Header
curl -X POST http://localhost:18789/hooks/agent \
  -H "Authorization: Bearer your-webhook-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

# 备选：自定义 Header
curl -X POST http://localhost:18789/hooks/agent \
  -H "x-openclaw-token: your-webhook-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}'

核心端点

POST /hooks/wake

向主会话注入一个系统事件，适合简单的提醒和通知：

curl -X POST http://localhost:18789/hooks/wake \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "服务器 CPU 使用率超过 90%，请分析可能的原因",
    "mode": "now"
  }'

mode 参数控制执行时机：

now：立即触发 AI 处理
不设置：等待下次心跳时处理

POST /hooks/agent

启动一个隔离的 AI 代理任务，功能最强大：

curl -X POST http://localhost:18789/hooks/agent \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "分析以下错误日志并给出修复建议：Connection timeout on port 5432",
    "name": "log-analyzer",
    "deliver": true,
    "channel": "discord",
    "to": "频道ID",
    "timeoutSeconds": 120
  }'

参数说明：

参数	必填	说明
`message`	是	AI 需要处理的提示内容
`name`	否	任务名称标识
`sessionKey`	否	会话标识，相同 key 共享上下文
`deliver`	否	是否将结果投递到聊天频道
`channel`	否	投递目标频道（discord/slack 等）
`to`	否	频道内的具体目标
`model`	否	覆盖默认模型
`timeoutSeconds`	否	超时时间（秒）

响应状态码：

202：任务已接受并开始执行
401：认证失败
400：请求参数无效

实战示例

GitHub Issue 自动分析

创建一个 GitHub Webhook，当新 Issue 被创建时自动触发分析：

# GitHub Webhook 配置中设置 Payload URL
# http://your-server:18789/hooks/agent?token=your-token

# GitHub 发送的 Webhook 会被转发到 OpenClaw
# 通过自定义映射处理 GitHub 事件

在 OpenClaw 中配置自定义映射：

{
  hooks: {
    enabled: true,
    token: "your-token",
    mappings: {
      "github-issue": {
        message: "分析这个 GitHub Issue 并建议标签分类和优先级",
        deliver: true,
        channel: "discord",
        to: "开发频道ID"
      }
    }
  }
}

监控告警联动

当监控系统检测到异常时，调用 Webhook 让 AI 助手分析：

#!/bin/bash
# alertmanager-webhook.sh
curl -s -X POST http://localhost:18789/hooks/agent \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d "{
    \"message\": \"监控告警：$ALERT_NAME - $ALERT_DESCRIPTION 请分析可能的原因和建议的修复措施\",
    \"name\": \"alert-handler\",
    \"deliver\": true,
    \"channel\": \"discord\",
    \"to\": \"运维频道ID\"
  }"

定时报告生成

结合系统 cron 触发 AI 生成报告（也可以用 OpenClaw 内置的定时任务）：

# 每天 18:00 生成日报
0 18 * * * curl -s -X POST http://localhost:18789/hooks/agent \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"message": "生成今日工作摘要", "deliver": true, "channel": "discord"}'

安全注意事项

将 Webhook 端点限制在本地网络或受信任的环境中
如需公网访问，务必使用反向代理（如 Nginx）并启用 HTTPS
使用高强度的随机令牌，定期轮换
外部传入的内容会被 OpenClaw 自动包装处理，降低提示注入的风险
建议为 Webhook 使用专用令牌，与网关管理令牌分开