Webhooks - 外部 HTTP 触发器

Webhooks 允许外部系统通过 HTTP 请求触发 OpenClaw Agent（智能体）执行任务。这是将 OpenClaw 集成到 CI/CD Pipeline（持续集成/持续部署管线）、GitHub Actions、企业应用等外部系统的核心机制。

启用 Webhooks

在 openclaw.json 中启用并配置 Webhooks：

{
  "webhooks": {
    "enabled": true,
    "token": "${WEBHOOK_SECRET}",
    "path": "/hooks",
    "rateLimit": {
      "maxRequests": 100,
      "windowMs": 60000
    }
  }
}

安全提示

token 字段建议使用环境变量引用（${WEBHOOK_SECRET}），不要将明文 Token 写入配置文件。

认证方式 (Authentication)

外部请求必须携带有效的认证信息，支持两种方式：

Authorization Header

curl -X POST https://your-gateway.com/hooks/wake \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "New email arrived"}'

自定义 Token Header

curl -X POST https://your-gateway.com/hooks/wake \
  -H "x-openclaw-token: YOUR_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "New email arrived"}'

内置端点 (Endpoints)

POST /hooks/wake

将 System Event（系统事件）加入队列，在下一次 Heartbeat（心跳）时由 Agent 处理。

请求体：

{
  "text": "触发消息内容",
  "metadata": {
    "source": "github",
    "event": "push"
  }
}

成功响应：

{
  "status": 200,
  "message": "Event queued",
  "eventId": "evt_a1b2c3d4"
}

POST /hooks/agent

启动隔离的 Agent Turn（代理回合），支持覆盖模型、渠道和会话参数。

请求体：

{
  "message": "分析这个 PR 的代码变更",
  "model": "gpt-4o",
  "channel": "slack",
  "session": "webhook:github-pr",
  "context": {
    "pr_url": "https://github.com/org/repo/pull/42",
    "pr_title": "Add user authentication"
  }
}

成功响应：

{
  "status": 200,
  "message": "Agent turn started",
  "sessionId": "webhook:github-pr",
  "turnId": "turn_e5f6g7h8"
}

自定义路由 (Custom Mappings)

定义 Payload-Driven Routing（载荷驱动路由），根据请求内容自动分发到不同处理逻辑：

{
  "webhooks": {
    "enabled": true,
    "token": "${WEBHOOK_SECRET}",
    "mappings": {
      "github-push": {
        "match": { "headers.x-github-event": "push" },
        "message": "GitHub 仓库 {body.repository.full_name} 有新的推送：{body.head_commit.message}",
        "session": "webhook:github"
      },
      "github-pr": {
        "match": { "headers.x-github-event": "pull_request" },
        "message": "PR #{body.number} {body.action}: {body.pull_request.title}",
        "model": "gpt-4o",
        "session": "webhook:github-pr"
      },
      "alert": {
        "match": { "body.type": "alert" },
        "message": "收到告警：{body.message}",
        "delivery": "announce"
      }
    }
  }
}

响应状态码

状态码	含义	说明
200	成功	事件已入队或 Agent Turn 已启动
400	请求错误	请求体格式不正确或缺少必要字段
401	认证失败	Token 无效或缺失
429	请求过多	超过 Rate Limit（速率限制）
500	服务器错误	Gateway 内部错误

集成示例

GitHub Actions

在 GitHub Actions Workflow（工作流）中触发 OpenClaw：

# .github/workflows/notify-openclaw.yml
name: Notify OpenClaw
on:
  push:
    branches: [main]

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger OpenClaw
        run: |
          curl -X POST ${{ secrets.OPENCLAW_WEBHOOK_URL }}/hooks/agent \
            -H "Authorization: Bearer ${{ secrets.OPENCLAW_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d '{
              "message": "main 分支有新提交，请检查代码质量并生成变更摘要",
              "session": "webhook:ci",
              "context": {
                "repo": "${{ github.repository }}",
                "sha": "${{ github.sha }}",
                "committer": "${{ github.actor }}"
              }
            }'

CI/CD Pipeline

# Jenkins / GitLab CI 中触发
curl -X POST https://gateway.example.com/hooks/wake \
  -H "Authorization: Bearer ${OPENCLAW_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "{
    \"text\": \"构建 #${BUILD_NUMBER} 完成，状态: ${BUILD_STATUS}\",
    \"metadata\": {
      \"build_id\": \"${BUILD_NUMBER}\",
      \"status\": \"${BUILD_STATUS}\",
      \"duration\": \"${BUILD_DURATION}\"
    }
  }"

企业微信机器人转发

# 接收企业微信消息后转发给 OpenClaw
curl -X POST https://gateway.example.com/hooks/agent \
  -H "x-openclaw-token: ${OPENCLAW_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "处理来自企业微信的客户咨询",
    "session": "webhook:wecom",
    "context": {
      "from": "客户A",
      "content": "请问你们的产品支持私有化部署吗？"
    }
  }'

安全最佳实践

安全要求

1. Token 轮换：定期更换 Webhook Token，建议每 90 天轮换一次
2. IP 白名单：在网络层限制只允许可信 IP 访问 Webhook 端点
3. HTTPS 必选：生产环境必须使用 HTTPS，禁止明文传输 Token
4. 速率限制：合理配置 rateLimit 防止恶意刷接口
5. 日志审计：开启 Webhook 请求日志，便于追溯异常访问

🇨🇳 中国用户须知

• 如果 Gateway 部署在国内服务器，GitHub Webhooks 可能存在网络不稳定的问题，建议通过 Gitee 或自建 Git 服务中转
• 企业微信、钉钉的 Webhook 回调需要配置白名单 IP，确保 Gateway 的公网 IP 已添加
• 国内云平台（阿里云、腾讯云）的函数计算也可作为 Webhook 的中转层