企业官网建设流程全解析

通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》

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

启用

{ hooks: { enabled: true, token: "shared-secret", path: "/hooks", // 可选：将显式的 `agentId` 路由限制到此允许列表。 // 省略或包含 "*" 以允许任何代理。 // 设置为 [] 以拒绝所有显式的 `agentId` 路由。 allowedAgentIds: ["hooks", "main"], }, }

注意事项：

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

认证

每个请求都必须包含钩子令牌。推荐使用请求头：

• Authorization: Bearer <token>(推荐)
• x-openclaw-token: <token>
• 查询字符串令牌会被拒绝（?token=...会返回400错误）。

端点

POST /hooks/wake

载荷：

{"text":"系统提示行","mode":"now"}

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

效果：

• 向主会话队列中添加一个系统事件。
• 如果mode=now，则触发即时心跳。

POST /hooks/agent

载荷：

{"message":"运行这个","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可选 (字符串): 钩子的可读名称（例如，“GitHub”），在会话摘要中用作前缀。
• agentId可选 (字符串): 将此钩子路由到特定的代理。未知的 ID 将回退到默认代理。设置后，钩子将使用已解析代理的工作区和配置运行。
• sessionKey可选 (字符串): 用于标识代理会话的键。默认情况下，除非hooks.allowRequestSessionKey=true，否则此字段会被拒绝。
• wakeMode可选 (now|next-heartbeat): 是触发即时心跳（默认now）还是等待下一次定期检查。
• deliver可选 (布尔值): 如果为true，代理的响应将被发送到消息通道。默认为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可选 (数字): 代理运行的最大持续时间，以秒为单位。

效果：

• 运行一个隔离的代理回合（拥有自己的会话键）。
• 总是向主会话发布一个摘要。
• 如果wakeMode=now，则触发即时心跳。

会话键策略（破坏性变更）

/hooks/agent载荷中的sessionKey覆盖默认是禁用的。

• 推荐：设置一个固定的hooks.defaultSessionKey并保持请求覆盖关闭。
• 可选：仅在需要时允许请求覆盖，并限制前缀。

推荐配置：

{ hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", defaultSessionKey: "hook:ingress", allowRequestSessionKey: false, allowedSessionKeyPrefixes: ["hook:"], }, }

兼容性配置（旧版行为）：

{ hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", allowRequestSessionKey: true, allowedSessionKeyPrefixes: ["hook:"], // 强烈推荐 }, }

POST /hooks/<name>(映射)

自定义钩子名称通过hooks.mappings解析（参见配置）。映射可以将任意载荷转换为wake或agent动作，并带有可选的模板或代码转换。

映射选项（摘要）：

• hooks.presets: ["gmail"]启用内置的 Gmail 映射。
• hooks.mappings允许你在配置中定义match、action和模板。
• hooks.transformsDir+transform.module加载一个 JS/TS 模块用于自定义逻辑。
• hooks.transformsDir（如果设置）必须位于 OpenClaw 配置目录下的转换根目录内（通常为~/.openclaw/hooks/transforms）。
• transform.module必须在有效的转换目录内解析（拒绝遍历/转义路径）。
• 使用match.source来维护一个通用的接收端点（载荷驱动的路由）。
• TS 转换需要 TS 加载器（例如bun或tsx）或在运行时预编译的.js文件。
• 在映射上设置deliver: true+channel/to以将回复路由到聊天界面（channel默认为last，并回退到 WhatsApp）。
• agentId将钩子路由到特定代理；未知 ID 将回退到默认代理。
• hooks.allowedAgentIds限制显式的agentId路由。省略它（或包含*）以允许任何代理。设置为[]以拒绝显式的agentId路由。
• 当没有提供显式键时，hooks.defaultSessionKey为钩子代理运行设置默认会话。
• hooks.allowRequestSessionKey控制/hooks/agent载荷是否可以设置sessionKey（默认：false）。
• hooks.allowedSessionKeyPrefixes可选地限制来自请求载荷和映射的显式sessionKey值。
• allowUnsafeExternalContent: true为该钩子禁用外部内容安全包装器（危险；仅适用于受信任的内部来源）。
• openclaw webhooks gmail setup为openclaw webhooks gmail run写入hooks.gmail配置。有关完整的 Gmail 监视流程，请参阅 Gmail Pub/Sub。

响应

• /hooks/wake返回200
• /hooks/agent返回200（异步运行已接受）
• 认证失败返回401
• 来自同一客户端的重复认证失败后返回429（检查Retry-After）
• 无效载荷返回400
• 载荷过大返回413

示例

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

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

使用不同的模型

向代理载荷（或映射）中添加model以覆盖该次运行的模型：

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

如果你强制执行agents.defaults.models，请确保覆盖模型包含在其中。

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

安全性

• 将钩子端点保持在回环地址、尾网或受信任的反向代理之后。
• 使用专用的钩子令牌；不要重复使用网关认证令牌。
• 每个客户端地址的重复认证失败会受到速率限制，以减缓暴力破解尝试。
• 如果你使用多代理路由，请设置hooks.allowedAgentIds来限制显式的agentId选择。
• 除非你需要调用者选择会话，否则保持hooks.allowRequestSessionKey=false。
• 如果你启用请求sessionKey，请限制hooks.allowedSessionKeyPrefixes（例如，["hook:"]）。
• 避免在 webhook 日志中包含敏感的原始载荷。
• 默认情况下，钩子载荷被视为不可信，并会使用安全边界进行包装。如果你必须为特定钩子禁用此功能，请在该钩子的映射中设置allowUnsafeExternalContent: true（危险）。