Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zhcndoc/openclaw/llms.txt
Use this file to discover all available pages before exploring further.
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-heartbeatdeliver (可选): 是否发送回复到频道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
openclaw webhooks gmail run
相关文档
