Webhooks

Gateway 可以暴露一个小型 HTTP Webhook 端点,用于接收外部触发。

启用

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

注意:

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

认证

每个请求都必须包含 hook token。推荐使用请求头:

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

端点

`POST /hooks/wake`

请求体:

{ "text": "System line", "mode": "now" }

text 必需(字符串):事件的描述(例如 “New email received”)。
mode 可选(now | next-heartbeat):是否触发立即 Heartbeat(默认 now)或等待下一次定期检查。

效果:

为主 Session 添加一个系统事件到队列
如果 mode=now,触发立即 Heartbeat

`POST /hooks/agent`

请求体:

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

效果:

运行一个独立的 Agent 轮次(拥有自己的 Session 键)
始终将摘要发布到主 Session
如果 wakeMode=now,触发立即 Heartbeat

`POST /hooks/<name>`(映射)

自定义 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 Pub/Sub 了解完整的 Gmail 监听流程。

响应

/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":"New email received","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":"Summarize inbox","name":"Email","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":"Summarize inbox","name":"Email","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 端点保持在本地回环、tailnet 或可信的反向代理后面。
使用专用的 hook token;不要重用 Gateway 认证 token。
避免在 Webhook 日志中包含敏感的原始请求体。
Hook 请求体默认被视为不可信,并用安全边界包装。如果你必须为特定 hook 禁用此功能,在该 hook 的映射中设置 allowUnsafeExternalContent: true(危险)。

Webhooks

启用

认证

端点

POST /hooks/wake

POST /hooks/agent

POST /hooks/<name>(映射)

响应

示例

使用不同的模型

安全

`POST /hooks/wake`

`POST /hooks/agent`

`POST /hooks/<name>`(映射)