Webhook

Webhook 是 Gateway 暴露的 HTTP 端点，让外部系统（GitHub、Gmail、Zapier 等）触发 Agent 操作。

启用 Webhook

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",  // 必填，建议从环境变量读取
    path: "/hooks",                    // 默认 /hooks
    allowedAgentIds: ["main", "ops"],  // 可选：限制允许路由的 Agent
  },
}

hooks.token 是必填项，所有入站请求都需要携带此 token。

认证

每个请求必须包含 token，推荐使用 Header：

# 推荐
Authorization: Bearer <token>

# 备选
x-openclaw-token: <token>

查询字符串 ?token=... 会返回 400，不支持。

两个核心端点

POST /hooks/wake — 唤醒主会话

向主会话注入系统事件，可选触发立即心跳：

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"收到新邮件","mode":"now"}'

参数：

参数	必填	说明	默认
text	是	事件描述文本	—
mode	否	now（立即心跳）或 next-heartbeat	now

POST /hooks/agent — 运行独立 Agent

在独立会话中运行 Agent 轮次，结果汇报到主会话：

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "处理新订单 #12345",
    "name": "Order",
    "wakeMode": "now"
  }'

参数：

参数	必填	说明	默认
message	是	Agent 的提示文本	—
name	否	会话摘要中的标识名（如 "GitHub"）	—
agentId	否	路由到指定 Agent（未知 ID 回退到默认 Agent）	默认 Agent
wakeMode	否	now 或 next-heartbeat	now
deliver	否	是否将结果发到消息渠道	true
channel	否	投递渠道（last、telegram、slack 等）	last
to	否	接收者标识（手机号、频道 ID 等）	主会话最后接收者
model	否	模型覆盖（如 openai/gpt-5.4-mini）	默认模型
thinking	否	思考级别（low/medium/high）	—
timeoutSeconds	否	Agent 运行超时（秒）	无限制

自定义路由（Hooks Mappings）

通过 hooks.mappings 将自定义路径映射到 wake 或 agent 操作：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    mappings: {
      github: {
        action: "agent",
        agentId: "ops",
        deliver: true,
        channel: "slack",
        to: "channel:C1234567890",
      },
    },
  },
}

触发方式：

curl -X POST http://127.0.0.1:18789/hooks/github \
  -H 'Authorization: Bearer SECRET' \
  -d '{"source":"github","event":"push","repo":"my-repo"}'

内置 Gmail 映射

OpenClaw 内置 Gmail Pub/Sub 集成：

openclaw webhooks gmail setup   # 配置 Gmail Pub/Sub
openclaw webhooks gmail run     # 启动 Gmail 监听器

启用后，Gmail 邮件到达时自动触发 Agent。

Session Key 策略

默认情况下，/hooks/agent 不允许请求自定义 sessionKey。推荐配置：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",     // 固定默认 Session Key
    allowRequestSessionKey: false,          // 不允许请求覆盖（默认）
    allowedSessionKeyPrefixes: ["hook:"],   // 若开放覆盖，限制前缀
  },
}

使用不同模型

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"分析日志","model":"openai/gpt-5.4-mini"}'

若配置了 agents.defaults.models，覆盖的模型必须在允许列表中。

响应状态码

状态码	含义
200	成功（/hooks/wake 立即返回，/hooks/agent 异步接受）
401	认证失败
429	同一客户端重复认证失败，被限速（查看 Retry-After 头）
400	请求格式错误
413	请求体过大

安全建议

• 将 Webhook 端点放在回环地址、Tailnet 或可信反向代理后面，不要直接暴露到公网
• Webhook token 专用，不要与 Gateway 认证 token 复用
• 若使用多 Agent 路由，设置 hooks.allowedAgentIds 限制可路由的 Agent
• 默认情况下，Webhook 负载会被安全边界包裹（不可信内容保护），仅对可信内部来源才设置 allowUnsafeExternalContent: true
• 避免在 Webhook 日志中记录敏感原始负载