OpenClaw 技能库 | 最大的 OpenClaw 扩展库

网关可以为外部触发器公开一个小型 HTTP Webhook 端点。

Tutorial.step

启用

Json5

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

注意事项：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.enabled=true'</code>' 时需要 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.enabled=true'</code>'。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.path'</code>' 默认为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks'</code>'。

Tutorial.step

授权

每个请求都必须包含挂钩令牌。首选标题：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'Authorization: Bearer <token>'</code>' (recommended)

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'x-openclaw-token: <token>'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'?token=<token>'</code>' (deprecated; logs warning and will be removed in a future major version)

Tutorial.step

端点

Tutorial.step

`POST /hooks/wake`

有效负载：

Json

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

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'text'</code>' ''必需''（字符串）：事件的描述（例如，"收到新电子邮件"）。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mode'</code>' 可选 ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>' | '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'next-heartbeat'</code>')：是否立即触发心跳（默认 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>'）或等待下一次定期检查。

效果：

- 将系统事件排入 main 会话的队列

- 如果 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mode=now'</code>'，立即触发心跳

Tutorial.step

`POST /hooks/agent`

有效负载：

Json

{
  "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
}

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'message'</code>' ''必需''（字符串）：代理要处理的提示或消息。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'name'</code>' 可选（字符串）：人类可读的挂钩名称（例如"GitHub"），用作会话摘要中的前缀。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'sessionKey'</code>' optional (string): Key to identify the agent session. Defaults to a random '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hook:<uuid>'</code>'. Using a consistent key allows multi-turn conversations within the hook context.

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wakeMode'</code>' 可选 ('<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>' | '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'next-heartbeat'</code>')：是否立即触发心跳（默认 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'now'</code>'）或等待下一次定期检查。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'deliver'</code>' 可选（布尔值）：如果 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'true'</code>'，则代理的响应将发送到消息传递通道。默认为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'true'</code>'。仅是心跳确认的响应将被自动跳过。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channel'</code>' 可选（字符串）：用于传递的消息传递通道。以下之一：'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'last'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'whatsapp'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'telegram'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'discord'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'slack'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'mattermost'</code>'（插件）、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'signal'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'imessage'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'msteams'</code>'。默认为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'last'</code>'。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'to'</code>' 可选（字符串）：频道的收件人标识符（例如 WhatsApp/Signal 的电话号码、Telegram 的聊天 ID、Discord/Slack/Mattermost（插件）的频道 ID、MS Teams 的对话 ID）。默认为主会话中的最后一个收件人。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'model'</code>' 可选（字符串）：模型覆盖（例如，'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'anthropic/claude-3-5-sonnet'</code>' 或别名）。如果受到限制，则必须位于允许的型号列表中。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'thinking'</code>' 可选（字符串）：思维水平覆盖（例如，'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'low'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'medium'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'high'</code>'）。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'timeoutSeconds'</code>' 可选（数字）：代理运行的最大持续时间（以秒为单位）。

效果：

- 运行隔离代理轮次（自己的会话密钥）

- 始终将摘要发布到主会话中

- 如果 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wakeMode=now'</code>'，立即触发心跳

Tutorial.step

`POST /hooks/<name>` (mapped)

自定义挂钩名称通过 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.mappings'</code>' 解析（请参阅配置）。映射可以

使用可选模板或将任意有效负载转换为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'wake'</code>' 或 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agent'</code>' 操作

代码转换。

映射选项（摘要）：

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.presets: ["gmail"]'</code>' 启用内置 Gmail 映射。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.mappings'</code>' 允许您在 config.json 中定义 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'match'</code>'、'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'action'</code>' 和模板。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'hooks.transformsDir'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'transform.module'</code>' 加载自定义逻辑的 JS/TS 模块。

- 使用 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'match.source'</code>' 保留通用摄取端点（有效负载驱动的路由）。

- TS 转换需要 TS 加载器（例如 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'bun'</code>' 或 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'tsx'</code>'）或在运行时预编译 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'.js'</code>'。

- 在映射上设置 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'deliver: true'</code>' + '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channel'</code>'/'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'to'</code>' 以将回复路由到聊天界面

（'<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'channel'</code>' 默认为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'last'</code>'，并回退到 WhatsApp）。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowUnsafeExternalContent: true'</code>' 禁用该挂钩的外部内容安全包装器

（危险；仅适用于可信的内部来源）。

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw webhooks gmail setup'</code>' 为 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw webhooks gmail run'</code>' 写入 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'openclaw webhooks gmail run'</code>' 配置。

请参阅 '<a href="/automation/gmail-pubsub" className="text-emerald-400 hover:text-emerald-300 transition-colors">'Gmail Pub/Sub'</a>' 了解完整的 Gmail 观看流程。

Tutorial.step

回应

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'200'</code>' 代表 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks/wake'</code>'

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'202'</code>' 对应 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'/hooks/agent'</code>' （异步运行已开始）

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'401'</code>' 授权失败

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'400'</code>' 无效负载

- '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'413'</code>' 超大有效载荷

Tutorial.step

示例

Bash

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"}'

Bash

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"}'

Tutorial.step

使用不同的模型

将 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'model'</code>' 添加到代理有效负载（或映射）以覆盖该运行的模型：

Bash

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"}'

如果您强制执行 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'agents.defaults.models'</code>'，请确保其中包含覆盖模型。

Bash

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"}]}'

Tutorial.step

安全

- 将钩子端点保留在环回、尾网或受信任的反向代理后面。

- 使用专用的挂钩令牌；不要重复使用网关身份验证令牌。

- 避免在 Webhook 日志中包含敏感的原始有效负载。

- 默认情况下，挂钩有效负载被视为不受信任并包含安全边界。

如果必须为特定挂钩禁用此功能，请设置 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'allowUnsafeExternalContent: true'</code>'

在该钩子的映射中（危险）。

网络钩子

启用

授权

端点

`POST /hooks/wake`

`POST /hooks/agent`

`POST /hooks/&lt;name&gt;` (mapped)

回应

示例

使用不同的模型

安全

`POST /hooks/<name>` (mapped)