为智能体 Worker 配置 Webhook

核心配置思路

Webhook 的 session 配置主要涉及 hooks 配置节点，以下是完整配置方案：

1. 基础 Webhook 配置

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",  // Webhook 认证令牌
    path: "/hooks",
    // 限制允许路由的智能体（安全措施）
    allowedAgentIds: ["worker", "main", "hooks"],
    // 默认会话键（推荐）
    defaultSessionKey: "hook:ingress",
    // 禁止请求覆盖 sessionKey（安全默认）
    allowRequestSessionKey: false,
    // 如果需要允许请求设置 sessionKey，限制前缀
    allowedSessionKeyPrefixes: ["hook:"],
    // 请求体大小限制
    maxBodyBytes: 262144,
  },
}

2. 配置 Worker 智能体

{
  agents: {
    list: [
      {
        id: "worker",
        name: "Worker Agent",
        workspace: "~/.openclaw/workspace-worker",
        // Worker 的会话相关配置
        sandbox: {
          mode: "off",  // 或根据需要设置
        },
        // 子智能体权限
        subagents: {
          allowAgents: ["main"],  // Worker 可以派发任务给 main
        },
      },
    ], 
   },
  // 路由绑定：将特定 webhook 消息路由到 worker
  bindings: [
    {
      agentId: "worker",
      match: {
        channel: "webhook",
        // 可以添加更多匹配条件
      },
    },
  ],
}

3. Webhook 映射配置（推荐）

使用 mappings 将外部事件路由到 Worker：

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowedAgentIds: ["worker", "main"],
    defaultSessionKey: "hook:ingress",
    allowedSessionKeyPrefixes: ["hook:"],
    // 预设映射
    presets: [],
    // 自定义映射
    mappings: [
      {
        // 匹配 /hooks/worker 端点
        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",  // 或指定渠道如 "telegram"
        to: "+15551234567",  // 投递目标
        // 模型覆盖
        model: "openai/gpt-5.2-mini",
        thinking: "low",
      },
      {
        // 另一个映射示例：将所有外部任务路由到 Worker
        match: { path: "tasks" },
        action: "agent",
        agentId: "worker",
        sessionKey: "hook:tasks:{{taskId}}",
        messageTemplate: "{{payload}}",
        deliver: false,  // 不自动投递，由 Worker 决定
      },
    ],
    // 变换脚本目录
    transformsDir: "~/.openclaw/hooks/transforms",
  },
}

4. 调用 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"}
  }'

5. Session 配置注意事项

Webhook 触发的会话遵循以下规则：

{
  session: {
    // Webhook 会话键格式
    // hook:<name> 或 hook:<name>:<identifier>
    // 例如：
    // hook:ingress - 默认 hook 会话
    // hook:worker:task-001 - Worker 特定任务会话
    // hook:gmail:msg-123 - Gmail 消息触发
    // 维护配置对 webhook 会话同样生效
    maintenance: {
      mode: "enforce",
      pruneAfter: "30d",
      maxEntries: 500,
    },
    // 线程绑定（如果 Worker 需要线程支持）
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 168,  // 7天
    },
  },
}

6. 完整配置示例

// ~/.openclaw/openclaw.json
{
  // Hooks/Webhook 配置
  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",
  },
  // Worker 智能体
  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 配置
  session: {
    dmScope: "per-channel-peer",
    maintenance: {
      mode: "enforce",
      pruneAfter: "14d",
      maxEntries: 300,
    },
  },
}

关键要点