Webhooks

网关可以暴露一个小型 HTTP webhook 端点用于外部触发。

启用

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks"
  }
}

注意：

• 当 hooks.enabled=true 时，hooks.token 是必需的
• hooks.path 默认为 /hooks

认证

每个请求必须包含 hook 令牌。推荐使用 headers：

• Authorization: Bearer <token>（推荐）
• x-clawdbot-token: <token>
• ?token=<token>（已弃用；将在未来主版本中移除）

端点

POST /hooks/wake

载荷：

{ "text": "系统消息", "mode": "now" }

• text 必需（字符串）：事件描述（例如"收到新邮件"）
• mode 可选（now | next-heartbeat）：是否触发立即心跳（默认 now）或等待下次周期检查

效果：

• 为主会话入队系统事件
• 如果 mode=now，触发立即心跳

POST /hooks/agent

载荷：

{
  "message": "运行这个",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+8613800138000",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}

• message 必需（字符串）：代理要处理的提示或消息
• name 可选（字符串）：hook 的可读名称（如"GitHub"），用作会话摘要前缀
• sessionKey 可选（字符串）：标识代理会话的键。默认随机 hook:<uuid>
• wakeMode 可选（now | next-heartbeat）：是否触发立即心跳
• deliver 可选（布尔）：如果 true，代理响应将发送到消息渠道。默认 true
• channel 可选（字符串）：投递的消息渠道。last、whatsapp、telegram、discord 等
• to 可选（字符串）：渠道的接收者标识符
• model 可选（字符串）：模型覆盖
• thinking 可选（字符串）：思考级别覆盖
• timeoutSeconds 可选（数字）：代理运行的最大持续时间（秒）

效果：

• 运行隔离代理轮次（自己的会话键）
• 始终将摘要发布到主会话
• 如果 wakeMode=now，触发立即心跳

POST /hooks/<name>（映射）

自定义 hook 名称通过 hooks.mappings 解析。映射可以将任意载荷转换为 wake 或 agent 动作。

映射选项：

• hooks.presets: ["gmail"] 启用内置 Gmail 映射
• hooks.mappings 在配置中定义 match、action 和模板
• hooks.transformsDir + transform.module 加载 JS/TS 模块用于自定义逻辑

响应

• /hooks/wake 返回 200
• /hooks/agent 返回 202（异步运行已启动）
• 认证失败返回 401
• 无效载荷返回 400
• 过大载荷返回 413

示例

唤醒端点

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

代理端点

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

Gmail hook

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"你好","snippet":"嗨"}]}'

安全

• 将 hook 端点保持在回环、tailnet 或受信任的反向代理后面
• 使用专用的 hook 令牌；不要重用网关认证令牌
• 避免在 webhook 日志中包含敏感原始载荷
• "Hook 载荷默认被视为不受信任并用安全边界包装"
• 如果您必须为特定 hook 禁用此功能，在该 hook 的映射中设置 allowUnsafeExternalContent: true（危险）