OpenClaw节点配置指南：智能体Worker Webhook接入详解

为智能体 Worker 配置 Webhook 这件事，说起来其实就围绕一个核心——怎么把外部事件“喂”给 Worker，让 Worker 跑起来干活。今天这篇主要拆解整个配置流程，从基础设置到进阶用法，一整套方案都摆出来，方便大家按需取用。

配置思路与基础 Webhook 设置

Webhook 的 session 配置，核心集中在 hooks 这个配置节点上。先来看看最基础的框架长什么样：

{ hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", path: "/hooks", allowedAgentIds: ["worker", "main", "hooks"], defaultSessionKey: "hook:ingress", allowRequestSessionKey: false, allowedSessionKeyPrefixes: ["hook:"], maxBodyBytes: 262144, }, }

这里有几个关键点值得拎出来说一下。allowedAgentIds 是一个安全措施，限制哪些智能体可以通过 webhook 被路由到；defaultSessionKey 是推荐设置，给未指定 session 的请求一个默认值；而 allowRequestSessionKey 默认关闭，意味着不允许外部请求随意设置 sessionKey，如果确实需要开放这个能力，可以通过 allowedSessionKeyPrefixes 来限定允许的前缀，比如只允许 hook: 开头的 key。

配置 Worker 智能体

有了 webhook 的基础设施，接下来就是把 Worker 本身配置好。Worker 智能体的配置要跟 webhook 的路由绑定配合起来用：

{ agents: { list: [ { id: "worker", name: "Worker Agent", workspace: "~/.openclaw/workspace-worker", sandbox: { mode: "off", }, subagents: { allowAgents: ["main"], }, }, ], }, bindings: [ { agentId: "worker", match: { channel: "webhook", }, }, ], }

从这个小节可以看出，Worker 可以拥有自己的子智能体权限 —— 比如它可以派发任务给 main。而路由绑定部分，则是把 webhook 通道的消息定向发送给 Worker，完成初步的流量分发。

Webhook 映射配置：更精细的路由控制

仅仅把 webhook 消息一股脑丢给 Worker 还不够优雅。更推荐的做法是通过 mappings 来做精细化的路由，把不同类型的外部事件映射到不同的处理逻辑上：

{ hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", allowedAgentIds: ["worker", "main"], defaultSessionKey: "hook:ingress", allowedSessionKeyPrefixes: ["hook:"], presets: [], mappings: [ { match: { path: "worker" }, action: "agent", agentId: "worker", wakeMode: "now", name: "Worker Task", sessionKey: "hook:worker:{{eventId}}", messageTemplate: "Task: {{task}}\nContext: {{context}}", deliver: true, channel: "last", to: "+15551234567", model: "openai/gpt-5.2-mini", thinking: "low", }, { match: { path: "tasks" }, action: "agent", agentId: "worker", sessionKey: "hook:tasks:{{taskId}}", messageTemplate: "{{payload}}", deliver: false, }, ], transformsDir: "~/.openclaw/hooks/transforms", }, }

注意看，第一个映射匹配 /hooks/worker 端点，消息到达后会立即唤醒 Worker（wakeMode: "now"），并且可以设置投递目标——比如直接发到 Telegram。第二个映射则匹配 /hooks/tasks 端点，但不自动投递结果，交给 Worker 自己决定后续动作。这种灵活性在实际业务中非常实用。

如何调用 Webhook：两种方式

配置完成之后，如何触发呢？有两种常用方式。

方式一：POST 到 /hooks/agent

这是最通用的入口，请求体中明确指定要唤醒的智能体和会话参数：

curl -X POST http://127.0.0.1:18789/hooks/agent \ -H 'Authorization: Bearer YOUR_HOOKS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "message": "处理这个任务：分析最新的销售数据", "name": "WorkerTask", "agentId": "worker", "sessionKey": "hook:worker:task-001", "wakeMode": "now", "deliver": true, "channel": "telegram", "to": "+15551234567", "model": "openai/gpt-5.2-mini" }'

方式二：POST 到自定义映射端点

如果你已经配置了映射，可以直接向映射定义的路径发请求，结构更简洁：

curl -X POST http://127.0.0.1:18789/hooks/worker \ -H 'Authorization: Bearer YOUR_HOOKS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "eventId": "evt-12345", "task": "分析销售数据", "context": { "region": "CN", "period": "2026-Q1" } }'

两种方式各有用武之地：方式一更灵活，适合动态指定智能体和参数；方式二更规范，适合预先定义好的任务类型。

Session 配置注意事项

Webhook 触发的会话，需要遵循一套固定的命名规则。格式通常是 hook: 或 hook::。几个典型例子：

• hook:ingress —— 默认的 hook 会话
• hook:worker:task-001 —— Worker 特定任务会话
• hook:gmail:msg-123 —— Gmail 消息触发

这部分配置中的维护策略同样对 webhook 会话生效。比如可以设置 pruneAfter: "30d" 来清理超过 30 天的历史会话，以及 maxEntries: 500 来限制最大条目数。如果 Worker 需要线程支持，还可以启用 threadBindings，设置空闲保留时长和最大存活时长：

{ session: { maintenance: { mode: "enforce", pruneAfter: "30d", maxEntries: 500, }, threadBindings: { enabled: true, idleHours: 24, maxAgeHours: 168, }, }, }

完整配置示例

最后，把上面所有内容整合成一个完整的配置示例，方便直接参考使用：

// ~/.openclaw/openclaw.json { hooks: { enabled: true, token: "${OPENCLAW_HOOKS_TOKEN}", path: "/hooks", maxBodyBytes: 262144, allowedAgentIds: ["worker", "main", "hooks"], defaultSessionKey: "hook:ingress", allowRequestSessionKey: false, allowedSessionKeyPrefixes: ["hook:"], mappings: [ { match: { path: "worker" }, action: "agent", agentId: "worker", wakeMode: "now", sessionKey: "hook:worker:{{eventId}}", messageTemplate: "{{task}}", deliver: true, channel: "last", }, ], transformsDir: "~/.openclaw/hooks/transforms", }, agents: { list: [ { id: "worker", name: "Worker", workspace: "~/.openclaw/workspace-worker", model: "openai/gpt-5.2-mini", tools: { allow: ["exec", "read", "write", "web_search", "sessions_list", "sessions_send"], deny: ["browser", "canvas"], }, subagents: { allowAgents: ["main"], }, }, ], }, session: { dmScope: "per-channel-peer", maintenance: { mode: "enforce", pruneAfter: "14d", maxEntries: 300, }, }, }

从实践角度看，配置 webhook 的核心在于三件事：一是明确哪些智能体可以被外部路由访问，二是设计好映射规则来控制消息流转，三是管理好会话的生命周期。把这三点理清楚，整个系统的外部接入能力就能跑得稳当。