Appearance
OpenClaw Webhook 外部触发完整指南：让外部服务驱动 AI 执行
定时任务让 OpenClaw 按时间行动，Webhook 则让它被外部事件驱动。GitHub 有新 Issue、监控告警触发、表单提交——这些事件都可以通过 Webhook 触发 OpenClaw 执行任务。
Webhook 是什么？
简单理解： Webhook 是一个 URL，外部服务向这个 URL 发送请求，OpenClaw 就会执行对应的任务。
外部事件 → 发送 HTTP 请求 → OpenClaw Webhook → Agent 执行任务典型应用场景：
| 场景 | 外部服务 | 触发动作 |
|---|---|---|
| GitHub 新 Issue | GitHub | 自动分析、回复 |
| 监控告警 | Prometheus | 发送通知、尝试修复 |
| 表单提交 | Typeform | 数据处理、入库 |
| 支付成功 | Stripe | 发送确认邮件 |
| 部署完成 | CI/CD | 通知团队 |
Webhook 配置方法
方法一：命令行配置
bash
# 创建 Webhook
openclaw webhook create my-webhook \
--path /webhooks/github-issue \
--agent github-assistant \
--secret my-secret-key方法二：配置文件
在 ~/.openclaw/openclaw.json 中添加：
json
{
"webhooks": [
{
"name": "github-issue",
"path": "/webhooks/github-issue",
"agent": "github-assistant",
"secret": "your-webhook-secret",
"enabled": true
}
]
}配置说明：
| 字段 | 说明 |
|---|---|
name | Webhook 名称，用于识别 |
path | URL 路径，如 /webhooks/github-issue |
agent | 触发的 Agent 名称 |
secret | 密钥，用于验证请求来源 |
enabled | 是否启用 |
获取 Webhook URL
配置后，Webhook URL 格式为：
http://你的服务器IP:18789/webhooks/github-issue或本地：
http://localhost:18789/webhooks/github-issue实战案例一：GitHub Issue 自动回复
场景
GitHub 有新 Issue 时，自动分析问题并回复。
Step 1：创建 Webhook
json
{
"webhooks": [
{
"name": "github-issue",
"path": "/webhooks/github-issue",
"agent": "github-assistant",
"secret": "gh-webhook-secret-2026",
"enabled": true
}
]
}Step 2：配置 GitHub Webhook
- 进入 GitHub 仓库 → Settings → Webhooks
- 点击 "Add webhook"
- 填写配置：
| 字段 | 值 |
|---|---|
| Payload URL | http://你的服务器:18789/webhooks/github-issue |
| Content type | application/json |
| Secret | gh-webhook-secret-2026 |
| Events | 选择 "Issues" |
- 点击 "Add webhook"
Step 3：配置 Agent
创建 Agent 处理 Issue：
json
{
"agents": {
"github-assistant": {
"model": "deepseek/deepseek-chat",
"systemPrompt": "你是 GitHub Issue 助手。收到新 Issue 时，分析问题并给出建议回复。回复要简洁、专业、有帮助。"
}
}
}Step 4：测试
创建一个测试 Issue，检查 OpenClaw 是否收到请求：
bash
# 查看 Webhook 日志
openclaw logs -f | grep webhook实战案例二：监控告警触发
场景
Prometheus 监控到异常时，发送告警到 OpenClaw，AI 自动分析并通知。
Step 1：创建 Webhook
json
{
"webhooks": [
{
"name": "prometheus-alert",
"path": "/webhooks/prometheus",
"agent": "monitor-assistant",
"secret": "prometheus-secret",
"enabled": true
}
]
}Step 2：配置 Prometheus Alertmanager
编辑 alertmanager.yml：
yaml
route:
receiver: 'openclaw-webhook'
receivers:
- name: 'openclaw-webhook'
webhook_configs:
- url: 'http://openclaw-server:18789/webhooks/prometheus'
send_resolved: trueStep 3：配置 Agent
json
{
"agents": {
"monitor-assistant": {
"model": "deepseek/deepseek-chat",
"systemPrompt": "你是运维监控助手。收到告警时，分析问题原因，给出排查建议，并通过微信通知相关负责人。"
}
}
}实战案例三：第三方服务集成
场景
使用 Zapier、Make 或 n8n 等 iPaaS 平台触发 OpenClaw。
配置方法
以 Zapier 为例：
- 创建 Zap，选择触发器（如 Google Forms 提交）
- 添加 Action，选择 "Webhooks by Zapier"
- 配置 POST 请求：
| 字段 | 值 |
|---|---|
| URL | http://your-server:18789/webhooks/form-submit |
| Method | POST |
| Data | 表单数据的 JSON |
- 测试并发布
请求格式
标准请求
bash
curl -X POST http://localhost:18789/webhooks/github-issue \
-H "Content-Type: application/json" \
-H "X-Webhook-Secret: your-secret" \
-d '{
"action": "opened",
"issue": {
"number": 42,
"title": "Bug: 安装失败",
"body": "在 Windows 上安装时报错..."
},
"repository": {
"name": "my-project"
}
}'请求头
| Header | 说明 |
|---|---|
Content-Type | application/json |
X-Webhook-Secret | 密钥验证（可选但推荐） |
安全认证
密钥验证
配置 secret 后，OpenClaw 会验证请求头中的 X-Webhook-Secret：
bash
# 正确的请求
curl -X POST http://localhost:18789/webhooks/test \
-H "X-Webhook-Secret: your-secret" \
-H "Content-Type: application/json" \
-d '{"test": true}'
# 错误的请求（密钥不匹配）
# 返回 401 UnauthorizedIP 白名单
在配置中添加 IP 白名单：
json
{
"webhooks": [
{
"name": "github-issue",
"path": "/webhooks/github-issue",
"agent": "github-assistant",
"secret": "your-secret",
"allowedIPs": [
"192.30.252.0/22",
"185.199.108.0/22"
]
}
]
}高级配置
条件触发
只在特定条件下执行：
json
{
"webhooks": [
{
"name": "github-issue",
"path": "/webhooks/github-issue",
"agent": "github-assistant",
"conditions": [
{
"field": "action",
"value": "opened"
},
{
"field": "issue.labels",
"contains": "bug"
}
]
}
]
}重试机制
请求失败时自动重试：
json
{
"webhooks": [
{
"name": "github-issue",
"retry": {
"enabled": true,
"maxAttempts": 3,
"delay": 5000
}
}
]
}超时设置
json
{
"webhooks": [
{
"name": "github-issue",
"timeout": 30000
}
]
}调试技巧
查看 Webhook 日志
bash
# 实时查看日志
openclaw logs -f --filter webhook
# 查看特定 Webhook
openclaw logs --filter "github-issue"测试 Webhook
bash
# 使用 curl 测试
curl -X POST http://localhost:18789/webhooks/test \
-H "Content-Type: application/json" \
-H "X-Webhook-Secret: test-secret" \
-d '{"test": true}'
# 使用在线工具
# webhook.site 或 requestbin.com查看 Webhook 列表
bash
# 列出所有 Webhook
openclaw webhook list
# 查看 Webhook 详情
openclaw webhook show github-issue常见问题
问题一：Webhook 不触发
排查步骤：
bash
# 1. 检查 Webhook 是否启用
openclaw webhook show github-issue
# 2. 检查端口是否开放
curl http://localhost:18789/webhooks/github-issue
# 3. 查看日志
openclaw logs -f | grep webhook问题二：返回 401 Unauthorized
原因： 密钥不匹配
解决：
bash
# 确认密钥配置
openclaw config get webhooks.github-issue.secret
# 测试时使用正确的密钥
curl -H "X-Webhook-Secret: 正确的密钥" ...问题三：Agent 不执行
原因： Agent 配置错误或不存在
解决：
bash
# 检查 Agent 是否存在
openclaw agent list
# 检查 Webhook 关联的 Agent
openclaw webhook show github-issue问题四：外网无法访问
原因： 防火墙或 NAT 问题
解决：
- 开放端口：
bash
# Linux
sudo ufw allow 18789
# 云服务器安全组放行 18789- 使用内网穿透：
bash
# 使用 ngrok
ngrok http 18789最佳实践
实践一：使用密钥验证
永远配置 secret，防止未授权请求：
json
{
"webhooks": [{
"secret": "强密钥-至少32字符"
}]
}实践二：记录请求日志
配置日志记录：
json
{
"webhooks": [{
"logging": {
"enabled": true,
"level": "debug"
}
}]
}实践三：条件触发
避免不必要的执行：
json
{
"conditions": [
{"field": "action", "value": "opened"}
]
}实践四：错误通知
配置失败通知：
json
{
"webhooks": [{
"onError": {
"notify": ["wechat", "email"]
}
}]
}总结
| 步骤 | 操作 |
|---|---|
| 1 | 创建 Webhook 配置 |
| 2 | 获取 Webhook URL |
| 3 | 在外部服务中配置 URL |
| 4 | 测试验证 |
| 5 | 监控日志 |
Webhook vs 定时任务：
| 场景 | 推荐 |
|---|---|
| 事件驱动 | Webhook |
| 定期执行 | 定时任务 |
| 外部触发 | Webhook |
| 自主执行 | 定时任务 |
Webhook 让 OpenClaw 从"被动响应"变成"事件驱动"。GitHub 有新 Issue、监控告警、表单提交——这些外部事件都能自动触发 AI 执行任务，真正实现自动化闭环。
