Gateway 可以公开一个轻量级的 HTTP Webhook 端点，用于外部触发。

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

说明：

• 当 hooks.enabled=true 时，hooks.token 是必填项。
• hooks.path 默认为 /hooks。

每个请求都必须包含 hook 令牌。首选 Header 方式：

• Authorization: Bearer <token> (推荐)
• x-openclaw-token: <token>
• ?token=<token> (已弃用；会记录警告，并在未来的主版本中移除)

负载 (Payload)：

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

• text 必填 (字符串)：事件的描述（例如，“收到新邮件”）。
• mode 可选 (now | next-heartbeat)：是触发立即的心跳（默认 now）还是等待下一次周期性检查。

效果：

• 为主会话排队一个系统事件
• 如果 mode=now，触发立即的心跳运行

负载 (Payload)：

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

• message 必填 (字符串)：Agent 要处理的提示词或消息。
• name 可选 (字符串)：Hook 的易读名称（例如，“GitHub”），用作会话摘要的前缀。
• sessionKey 可选 (字符串)：用于标识 Agent 会话的键。默认为随机的 hook:<uuid>。使用一致的键允许在 hook 上下文中进行多轮对话。
• wakeMode 可选 (now | next-heartbeat)：是触发立即的心跳（默认 now）还是等待下一次周期性检查。
• deliver 可选 (布尔值)：如果为 true，Agent 的响应将发送到消息频道。默认为 true。仅为心跳确认的响应会自动跳过。
• channel 可选 (字符串)：用于投递的消息频道。可选值：last, whatsapp, telegram, discord, slack, mattermost (插件), signal, imessage, msteams。默认为 last。
• to 可选 (字符串)：频道的接收者标识符（例如，WhatsApp/Signal 的手机号，Telegram 的聊天 ID，Discord/Slack/Mattermost (插件) 的频道 ID，MS Teams 的对话 ID）。默认为主会话中的最后一个接收者。
• model 可选 (字符串)：模型覆盖（例如 anthropic/claude-3-5-sonnet 或别名）。如果受限，必须在允许的模型列表中。
• thinking 可选 (字符串)：思考等级覆盖（例如 low, medium, high）。
• timeoutSeconds 可选 (数字)：Agent 运行的最大持续时间（秒）。

效果：

• 运行一个隔离的 Agent 回合（拥有自己的会话键）
• 始终向主会话发布摘要
• 如果 wakeMode=now，触发立即的心跳运行

自定义 hook 名称通过 hooks.mappings 解析（见配置）。映射可以将任意负载转换为 wake 或 agent 动作，并支持模板或代码转换。

映射选项（摘要）：

• hooks.presets: ["gmail"] 启用内置的 Gmail 映射。
• hooks.mappings 允许你在配置中定义 match、action 和模板。
• hooks.transformsDir + transform.module 加载一个用于自定义逻辑的 JS/TS 模块。
• 使用 match.source 保持通用的接入端点（基于负载的路由）。
• TS 转换需要 TS 加载器（如 bun 或 tsx）或在运行时使用预编译的 .js。
• 在映射上设置 deliver: true + channel/to 以将回复路由到聊天界面（channel 默认为 last 并回退到 WhatsApp）。
• allowUnsafeExternalContent: true 禁用该 hook 的外部内容安全包裹（危险；仅限受信任的内部来源）。
• openclaw webhooks gmail setup 编写用于 openclaw webhooks gmail run 的 hooks.gmail 配置。有关完整的 Gmail 监听流程，请参阅 Gmail Pub/Sub。

• 200: /hooks/wake 成功
• 202: /hooks/agent 成功（异步运行已开始）
• 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-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"总结收件箱","name":"邮件","wakeMode":"next-heartbeat"}'

在 agent 负载（或映射）中添加 model 以覆盖该次运行的模型：

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

如果你强制使用了 agents.defaults.models，请确保覆盖的模型包含在其中。

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":"Hello","snippet":"Hi"}]}'

• 将 hook 端点保持在回环地址、Tailscale 网络或受信任的反向代理之后。
• 使用专门的 hook 令牌；不要重用 Gateway 认证令牌。
• 避免在 Webhook 日志中包含敏感的原始负载。
• 默认情况下，Hook 负载被视为不受信任，并会被安全边界包裹。如果必须为特定 hook 禁用此功能，请在该 hook 的映射中设置 allowUnsafeExternalContent: true（危险）。