Skip to main content

​
Webhooks

Gateway 可以为外部触发器暴露一个小型 HTTP webhook 端点。

​
启用

在 ~/.openclaw/openclaw.json 中： 
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    allowedAgentIds: ["hooks", "main"]
  }
}
说明：
  • 当 hooks.enabled=true 时，hooks.token 是必需的
  • hooks.path 默认为 /hooks

​
认证

每个请求必须包含 hook 令牌。优先使用请求头：
  • Authorization: Bearer <token>（推荐）
  • x-openclaw-token: <token>
不接受查询字符串中的令牌。

​
端点

​
POST /hooks/wake

将系统事件入队到主会话。 请求体： 
{ "text": "System line", "mode": "now" }
参数：
  • text (必填): 事件描述
  • mode (可选): now 或 next-heartbeat
示例： 
curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"收到新邮件","mode":"now"}'

​
POST /hooks/agent

运行一个独立代理行动。 请求体： 
{
  "message": "Run this",
  "name": "Email",
  "agentId": "hooks",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
参数：
  • message (必填): 代理需要处理的提示
  • name (可选): hook 的名称
  • agentId (可选): 将此 hook 路由到指定代理
  • sessionKey (可选): 用于识别代理会话的键
  • wakeMode (可选): now 或 next-heartbeat
  • deliver (可选): 是否发送回复到频道
  • channel (可选): 消息投递频道
  • to (可选): 频道的接收者标识
  • model (可选): 模型覆盖
  • thinking (可选): 思考级别
  • timeoutSeconds (可选): 代理运行的最大持续时间
示例： 
curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"总结收件箱","name":"Email","wakeMode":"next-heartbeat"}'

​
使用不同的模型

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"总结收件箱","name":"Email","model":"openai/gpt-5.2-mini"}'

​
会话键策略

/hooks/agent 请求体中的 sessionKey 覆盖默认禁用。 推荐配置： 
{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"]
  }
}

​
响应

  • /hooks/wake 返回 200
  • /hooks/agent 返回 200（异步运行已接受）
  • 认证失败时返回 401
  • 同一客户端多次认证失败后返回 429
  • 请求体无效时返回 400

​
安全性

  • 将 hook 端点放置于回环地址、tailnet 或受信任的反向代理之后
  • 使用专用 hook 令牌；不要重用 gateway 的认证令牌
  • 针对同一客户端地址的多次认证失败会进行速率限制
  • 若使用多代理路由，设置 hooks.allowedAgentIds 以限制显式的 agentId 选择
  • 除非需要调用方自行选择会话，保持 hooks.allowRequestSessionKey=false

​
映射配置

可以通过 hooks.mappings 将自定义路径映射到 wake 或 agent 动作。 示例： 
{
  hooks: {
    enabled: true,
    token: "secret",
    presets: ["gmail"],
    mappings: [
      {
        path: "/custom",
        action: "agent",
        message: "Process custom webhook",
        channel: "slack",
        to: "#alerts"
      }
    ]
  }
}

​
Gmail Pub/Sub 示例

设置 Gmail webhook： 
openclaw webhooks gmail setup
运行 Gmail 监听器： 
openclaw webhooks gmail run
详见 Gmail Pub/Sub 获取完整的 Gmail 监听流程。

​
相关文档