OpenClaw Hooks 完整指南：事件驅動自動化的設計模式與實戰案例

當企業開始認真考慮將 AI 代理部署到生產環境時，一個核心問題浮現：如何讓代理真正融入現有的工程文化與運維體系？OpenClaw 的答案是 Hooks——一套以事件驅動為核心的自動化框架。^[1]

本文是「OpenClaw 系列」的第三篇，承接前兩篇對架構概述與部署實戰的探討，深入剖析 Hooks 系統的設計哲學、技術細節與六個完整的企業級實戰案例。無論你是想優化現有 CI/CD 流程、建立即時告警系統，還是打造全自動報表管線，本文都將提供可直接落地的指引。

一、從輪詢到事件驅動：AI 代理自動化的典範轉移

1.1 輪詢模型的根本缺陷

在 Hooks 系統出現之前，大多數 AI 代理框架採用的是輪詢（Polling）模型：代理程式每隔固定時間（例如每秒、每五秒）向各個訊息管道發送查詢請求，確認是否有新事件需要處理。這種設計雖然簡單直觀，卻存在三個根本性缺陷。

第一是資源浪費。無論是否有新事件，輪詢請求都會消耗 CPU 週期與網路頻寬。在多代理環境中，假設有 10 個代理各自以 1 秒間隔輪詢 5 個管道，每分鐘將產生 3,000 次空請求——絕大多數都毫無意義。

第二是延遲不可控。輪詢間隔決定了系統的最大響應延遲。若設定 5 秒輪詢一次，則最壞情況下，一個緊急告警需要等待近 5 秒才能被處理。在金融交易、資安告警等時效敏感場景，這是完全不可接受的。

第三是擴展性瓶頸。隨著代理數量與監控管道的增加，輪詢請求呈線性甚至指數級增長，最終壓垮後端服務。^[5]

1.2 事件驅動的典範優勢

事件驅動架構（Event-Driven Architecture，EDA）顛覆了上述邏輯：不再主動詢問「有沒有新事件？」，而是當事件真正發生時，系統主動通知所有訂閱者。Martin Fowler 將此稱為從「命令式」到「響應式」的思維轉換。^[5]

AWS 的架構白皮書指出，事件驅動架構能夠實現三個關鍵目標：解耦（生產者與消費者無需直接依賴）、彈性（消費者可獨立擴縮容）、即時性（事件在毫秒內傳遞給所有訂閱者）。^[6]

OpenClaw 的 Hooks 系統正是將這套成熟的企業架構思想帶入 AI 代理領域。從 CNBC 的報導可以看到，OpenClaw 從 Clawdbot 時代演進至今，Hooks 系統是讓其從「對話工具」升級為「企業自動化平台」的關鍵技術跨越。^[4]

1.3 量化對比：輪詢 vs. 事件驅動

以下數據來自一個典型企業部署場景（10 個代理，監控 8 個管道，每日事件量約 2,000 次）：

（n = 代理數量，m = 監控管道數量）

二、OpenClaw Hooks 架構深度解析

2.1 整體架構概覽

OpenClaw Hooks 系統由三個核心元件構成：事件產生器（Event Producers）、Gateway 事件匯流排、以及Hook 執行引擎（Hook Executor）。^[2]

事件產生器散佈在 OpenClaw 的各個子系統中——當用戶發送訊息、代理完成任務、技能被呼叫，或排程時間到達，對應的子系統會生成一個標準化的事件物件並推送至 Gateway。

Gateway 運行於本地 WebSocket 端點 ws://127.0.0.1:18789，扮演事件匯流排的角色。它負責接收所有事件、根據事件類型進行路由、並將事件分發給所有已訂閱的 Hook。Gateway 採用非阻塞異步模型，確保高頻率事件不會造成隊列積壓。

Hook 執行引擎接收來自 Gateway 的事件後，在沙箱環境中執行對應的 Hook 腳本，並捕獲執行結果與錯誤。整個執行週期均有完整的審計日誌記錄。

2.2 Hook 生命週期

每個 Hook 從事件觸發到執行完畢，經歷以下標準生命週期：

1. 事件生成：子系統將事件序列化為 JSON 物件，包含事件類型、時間戳、來源代理 ID、以及事件特定的 payload。
2. Gateway 路由：Gateway 接收事件後，查詢路由表，找出所有訂閱該事件類型的 Hook。
3. 過濾評估：若 Hook 定義了過濾條件（Filter），引擎先評估過濾規則，不符合條件的事件直接丟棄，不進入執行階段。
4. 沙箱初始化：為 Hook 分配獨立沙箱進程，注入必要的環境變數與權限 token。
5. Hook 執行：在沙箱中執行 Hook 腳本的 handler 函數，傳入標準化的事件物件。
6. 結果回傳：Hook 執行結果（成功/失敗/回傳值）被捕獲並記錄至審計日誌。
7. 沙箱清理：釋放沙箱資源，確保 Hook 間完全隔離。

2.3 與 Cron 及傳統 Webhook 的根本差異

許多工程師習慣將 OpenClaw Hooks 類比為 Cron Job 或傳統的 Webhook，但兩者存在本質差異：

與 Cron 的差異：Cron Job 基於時間觸發，無論是否有需要處理的事件都會執行。OpenClaw Hooks 中的 schedule.triggered 事件雖然也支援時間排程，但其執行上下文是 OpenClaw 的代理環境，可以直接呼叫代理能力、存取代理上下文，並與其他事件互動。

與傳統 Webhook 的差異：傳統 Webhook 需要一個公開可達的 HTTP 端點，要求開發者管理伺服器、處理 TLS、以及驗證來源。OpenClaw Hooks 運行在本地 Gateway，不需要公開端點，且天然整合代理的身份認證體系。

三、啟用與基礎設定

3.1 前置條件確認

在啟用 OpenClaw Hooks 之前，請確認以下條件均已滿足：^[10]

• OpenClaw 版本 ≥ 0.8.0（Hooks 系統從此版本起穩定支援）
• Node.js ≥ 18.0.0（Hook 腳本執行環境）
• 本地 Gateway 已啟動（openclaw gateway start）
• 至少已配置一個 Agent Profile

確認 Gateway 狀態：

openclaw gateway status
# 預期輸出：
# Gateway Status: Running
# WebSocket: ws://127.0.0.1:18789
# Connected Agents: 2
# Active Hooks: 0

3.2 啟用 Hooks 系統

OpenClaw 提供兩種啟用方式：

方式一：全局啟用（推薦）

openclaw hooks enable

此指令會修改全局配置 ~/.openclaw/config.yaml，將 hooks.enabled 設為 true，並在 Gateway 中啟動 Hook 路由模組。啟用後無需重啟 Gateway，熱生效。

方式二：針對特定 Agent Profile 啟用

openclaw hooks enable --profile production-agent

此模式下，只有指定 Profile 的代理會觸發 Hook 事件，適合在多環境並存時進行隔離測試。

3.3 配置檔案格式

啟用 Hooks 後，OpenClaw 會在專案目錄下建立 Hook 配置目錄結構：

.openclaw/
├── config.yaml          # 全局配置
└── hooks/
    ├── hooks.yaml       # Hook 清單與路由規則
    └── scripts/         # Hook 腳本目錄
        ├── on-task-complete.js
        ├── on-error-alert.js
        └── daily-report.js

hooks.yaml 的基本結構如下：

version: "1.0"
hooks:
  enabled: true
  sandbox:
    timeout_ms: 30000      # Hook 執行超時（毫秒）
    max_memory_mb: 256     # 沙箱記憶體上限
    allow_network: false   # 是否允許 Hook 進行網路請求
    allow_fs: read         # 檔案系統權限：none / read / read-write

  definitions:
    - id: task-complete-notifier
      event: task.completed
      script: scripts/on-task-complete.js
      enabled: true
      filters:
        - field: payload.status
          operator: eq
          value: "success"

    - id: error-slack-alert
      event: error.occurred
      script: scripts/on-error-alert.js
      enabled: true
      filters:
        - field: payload.severity
          operator: gte
          value: "high"

    - id: daily-report-generator
      event: schedule.triggered
      script: scripts/daily-report.js
      enabled: true
      schedule: "0 8 * * 1-5"   # 週一至週五早上 8 點

3.4 全局配置選項

~/.openclaw/config.yaml 中與 Hooks 相關的完整配置選項：

hooks:
  enabled: true
  gateway:
    host: "127.0.0.1"
    port: 18789
    reconnect_interval_ms: 5000
    max_reconnect_attempts: 10
  execution:
    concurrency: 4           # 同時執行的 Hook 數量上限
    queue_size: 1000         # 事件隊列容量
    retry:
      enabled: true
      max_attempts: 3
      backoff: exponential   # linear / exponential / fixed
      initial_delay_ms: 1000
  logging:
    level: info              # debug / info / warn / error
    audit: true              # 是否啟用審計日誌
    audit_path: ".openclaw/logs/hooks-audit.jsonl"

四、內建 Hook 事件一覽

4.1 訊息類事件

訊息類事件在代理與用戶或外部系統進行訊息交換時觸發：^[1]

4.2 任務類事件

4.3 技能與代理類事件

4.4 連線與排程類事件

五、自定義 Hook 撰寫指南

5.1 Hook 腳本基本結構

每個 Hook 腳本都是一個標準的 Node.js 模組，必須導出一個 handler 異步函數：

// scripts/my-custom-hook.js

/**
 * Hook 元資料（選填，用於文檔與監控）
 */
export const meta = {
  name: "My Custom Hook",
  description: "示範用自定義 Hook",
  version: "1.0.0",
  author: "your-team"
};

/**
 * Hook 主處理函數
 * @param {Object} event - 標準化事件物件
 * @param {string} event.type - 事件類型（如 "task.completed"）
 * @param {string} event.id - 事件唯一 ID
 * @param {number} event.timestamp - Unix 時間戳（毫秒）
 * @param {string} event.agent_id - 觸發事件的代理 ID
 * @param {Object} event.payload - 事件特定的資料
 * @param {Object} context - Hook 執行上下文
 * @param {Function} context.log - 結構化日誌函數
 * @param {Function} context.agent - 呼叫代理 API 的函數
 * @returns {Promise<Object>} Hook 執行結果
 */
export async function handler(event, context) {
  const { payload } = event;
  const { log, agent } = context;

  log.info("Hook 觸發", { event_id: event.id, type: event.type });

  // 在此撰寫你的自動化邏輯
  const result = await processEvent(payload);

  log.info("Hook 執行完成", { result });
  return { success: true, data: result };
}

async function processEvent(payload) {
  // 具體業務邏輯
  return { processed: true, payload };
}

5.2 事件過濾器語法

過濾器讓你的 Hook 只響應特定條件的事件，避免不必要的執行開銷。過濾規則在 hooks.yaml 中定義：

definitions:
  - id: high-priority-task-notifier
    event: task.completed
    script: scripts/task-notifier.js
    filters:
      # 所有過濾條件為 AND 關係（全部滿足才觸發）
      - field: payload.status
        operator: eq          # eq / neq / gt / gte / lt / lte / contains / matches
        value: "success"
      - field: payload.duration_ms
        operator: gt
        value: 5000           # 只通知執行超過 5 秒的任務
      - field: payload.task_type
        operator: contains
        value: "data-pipeline"

      # 正規表達式匹配
      - field: payload.output.report_path
        operator: matches
        value: "^/reports/critical/.*\\.pdf$"

5.3 存取代理 API

Hook 腳本可透過 context.agent 直接與代理互動，無需另外建立連線：

export async function handler(event, context) {
  const { agent, log } = context;

  // 查詢代理狀態
  const status = await agent.getStatus();
  log.info("代理狀態", status);

  // 讓代理執行一個任務
  const taskResult = await agent.runTask({
    instruction: `請分析以下事件並生成摘要：${JSON.stringify(event.payload)}`,
    timeout_ms: 60000
  });

  // 存取代理的記憶體（Memory）
  const memories = await agent.memory.search({
    query: "上週的異常紀錄",
    limit: 10
  });

  // 呼叫特定技能
  const skillResult = await agent.skill.execute("send-slack-message", {
    channel: "#alerts",
    message: `事件 ${event.type} 已觸發，任務 ID: ${event.payload.task_id}`
  });

  return { success: true };
}

5.4 錯誤處理與重試

良好的錯誤處理是生產環境 Hook 的必備要素：

export async function handler(event, context) {
  const { log } = context;

  try {
    const result = await riskyOperation(event.payload);
    return { success: true, data: result };

  } catch (error) {
    // 可重試的暫時性錯誤：拋出 RetryableError
    if (error.code === "NETWORK_TIMEOUT" || error.code === "RATE_LIMITED") {
      const retryableError = new Error(error.message);
      retryableError.retryable = true;  // 標記為可重試
      throw retryableError;
    }

    // 不可重試的永久性錯誤：記錄並優雅返回
    log.error("Hook 執行失敗（不重試）", {
      error_code: error.code,
      error_message: error.message,
      event_id: event.id
    });

    return {
      success: false,
      error: {
        code: error.code,
        message: error.message
      }
    };
  }
}

async function riskyOperation(payload) {
  // 模擬可能失敗的操作
  const response = await fetch("https://api.example.com/data", {
    method: "POST",
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(5000)  // 5 秒超時
  });

  if (!response.ok) {
    const err = new Error(`HTTP ${response.status}`);
    err.code = response.status === 429 ? "RATE_LIMITED" : "HTTP_ERROR";
    throw err;
  }

  return response.json();
}

六、實戰案例一：CI/CD Pipeline 自動化

6.1 場景描述

一家中型軟體公司的工程團隊希望在每次 GitHub Pull Request 合併後，自動觸發測試、建構、部署流程，並在各個關鍵節點通知 Slack 頻道。傳統方案需要維護複雜的 GitHub Actions 工作流程，而透過 OpenClaw Hooks，整個流程可以更靈活地由 AI 代理協調。^[9]

6.2 架構設計

整體資料流：GitHub Webhook → OpenClaw 訊息管道 → message.received 事件 → Hook → 代理執行部署任務 → task.completed 事件 → 通知 Hook

6.3 完整實作

步驟一：配置 GitHub Webhook 管道

# ~/.openclaw/channels/github-webhook.yaml
channel:
  id: github-prod
  type: webhook-receiver
  config:
    port: 18790
    path: "/github"
    secret: "${GITHUB_WEBHOOK_SECRET}"
    events:
      - pull_request
      - push

步驟二：Hook 配置（hooks.yaml）

definitions:
  - id: github-pr-merged-handler
    event: message.received
    script: scripts/github-pr-deploy.js
    filters:
      - field: payload.channel_id
        operator: eq
        value: "github-prod"
      - field: payload.content.action
        operator: eq
        value: "closed"
      - field: payload.content.pull_request.merged
        operator: eq
        value: true

  - id: deploy-success-notifier
    event: task.completed
    script: scripts/notify-deploy-result.js
    filters:
      - field: payload.task_type
        operator: eq
        value: "ci-cd-deploy"

步驟三：部署 Hook 腳本

// scripts/github-pr-deploy.js
export async function handler(event, context) {
  const { agent, log } = context;
  const pr = event.payload.content.pull_request;

  log.info("PR 合併觸發部署流程", {
    pr_number: pr.number,
    branch: pr.base.ref,
    author: pr.user.login
  });

  // 根據目標分支決定部署環境
  const environment = pr.base.ref === "main" ? "production" : "staging";

  // 指示代理執行 CI/CD 流程
  const deployTask = await agent.runTask({
    type: "ci-cd-deploy",
    instruction: `
請執行以下 CI/CD 流程：
1. 拉取最新程式碼：git pull origin ${pr.base.ref}
2. 安裝依賴：npm ci
3. 執行測試套件：npm test
4. 如測試通過，建構生產包：npm run build
5. 部署至 ${environment} 環境
6. 執行健康檢查確認部署成功

PR 資訊：#${pr.number} - ${pr.title}
作者：${pr.user.login}
    `,
    metadata: {
      pr_number: pr.number,
      environment,
      branch: pr.base.ref
    },
    timeout_ms: 600000  // 10 分鐘超時
  });

  return { triggered: true, task_id: deployTask.id };
}

// scripts/notify-deploy-result.js
export async function handler(event, context) {
  const { agent, log } = context;
  const { status, output, metadata, duration_ms } = event.payload;

  const isSuccess = status === "success";
  const emoji = isSuccess ? "✅" : "❌";
  const durationSec = Math.round(duration_ms / 1000);

  const message = `
${emoji} *部署${isSuccess ? "成功" : "失敗"}* — ${metadata.environment} 環境
*PR*：#${metadata.pr_number}
*分支*：${metadata.branch}
*耗時*：${durationSec} 秒
${isSuccess ? `*版本*：${output.version || "N/A"}` : `*錯誤*：${output.error_summary}`}
  `.trim();

  await agent.skill.execute("send-slack-message", {
    channel: "#deployments",
    message,
    blocks: true
  });

  log.info("部署通知已發送", { status, environment: metadata.environment });
  return { notified: true };
}

七、實戰案例二：企業自動化報表系統

7.1 場景描述

一家電商企業的數位轉型團隊需要每個工作日早上 8 點，自動整合來自四個不同資料源的數據（訂單系統、庫存系統、廣告平台、客服系統），生成一份管理層日報，並通過 Email 發送給相關主管。

7.2 Hook 配置

definitions:
  - id: daily-business-report
    event: schedule.triggered
    script: scripts/daily-report.js
    schedule: "0 8 * * 1-5"    # 週一至週五早上 8 點
    enabled: true
    timeout_ms: 120000          # 報表生成最多 2 分鐘

  - id: weekly-summary-report
    event: schedule.triggered
    script: scripts/weekly-report.js
    schedule: "0 9 * * 1"      # 每週一早上 9 點（上週總結）
    enabled: true

7.3 報表生成 Hook

// scripts/daily-report.js
export async function handler(event, context) {
  const { agent, log } = context;
  const { trigger_time } = event.payload;

  const reportDate = new Date(trigger_time);
  const dateStr = reportDate.toLocaleDateString("zh-TW", {
    year: "numeric", month: "long", day: "numeric"
  });

  log.info("開始生成日報", { date: dateStr });

  // 並行從多個資料源拉取數據
  const [orders, inventory, ads, support] = await Promise.all([
    agent.skill.execute("query-database", {
      source: "order-system",
      query: "SELECT COUNT(*), SUM(amount) FROM orders WHERE date = CURRENT_DATE"
    }),
    agent.skill.execute("query-api", {
      endpoint: "https://inventory-api.internal/daily-summary",
      method: "GET"
    }),
    agent.skill.execute("query-api", {
      endpoint: "https://ads-platform.internal/metrics/daily",
      method: "GET"
    }),
    agent.skill.execute("query-database", {
      source: "support-system",
      query: "SELECT status, COUNT(*) as count FROM tickets WHERE created_date = CURRENT_DATE GROUP BY status"
    })
  ]);

  // 讓 AI 代理分析數據並生成自然語言摘要
  const analysiTask = await agent.runTask({
    instruction: `
請根據以下今日業務數據，生成一份簡潔的管理層日報（繁體中文，HTML 格式）：

訂單數據：${JSON.stringify(orders.data)}
庫存狀況：${JSON.stringify(inventory.data)}
廣告效果：${JSON.stringify(ads.data)}
客服工單：${JSON.stringify(support.data)}

報告應包含：
1. 關鍵指標一覽（突出與昨日對比）
2. 值得關注的異常（如庫存告急、退款激增等）
3. 今日行動建議（不超過 3 條）

日期：${dateStr}
    `,
    timeout_ms: 60000
  });

  // 發送報表 Email
  await agent.skill.execute("send-email", {
    to: [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ],
    subject: `【日報】${dateStr} 業務摘要`,
    html: analysiTask.output.content,
    cc: ["[email protected]"]
  });

  log.info("日報已發送", { date: dateStr });
  return { success: true, report_date: dateStr };
}

八、實戰案例三：即時異常偵測與告警

8.1 場景描述

一個 SaaS 平台的 SRE 團隊需要當系統錯誤率超過閾值、或特定類型的嚴重錯誤發生時，在 30 秒內通知值班工程師，並自動執行初步診斷。

8.2 多層次告警策略

definitions:
  # 第一層：嚴重錯誤即時告警
  - id: critical-error-immediate
    event: error.occurred
    script: scripts/critical-alert.js
    filters:
      - field: payload.severity
        operator: eq
        value: "critical"
    timeout_ms: 10000  # 告警本身不能慢

  # 第二層：高頻錯誤聚合告警（避免告警風暴）
  - id: error-rate-monitor
    event: schedule.triggered
    script: scripts/error-rate-check.js
    schedule: "*/5 * * * *"  # 每 5 分鐘檢查一次錯誤率

  # 第三層：技能執行失敗追蹤
  - id: skill-failure-tracker
    event: skill.failed
    script: scripts/skill-failure-log.js
    filters:
      - field: payload.error_code
        operator: neq
        value: "USER_CANCELLED"  # 忽略用戶主動取消

8.3 即時告警 Hook

// scripts/critical-alert.js
export async function handler(event, context) {
  const { agent, log } = context;
  const { error_code, severity, component, stack_trace, message } = event.payload;

  log.warn("嚴重錯誤觸發告警", { error_code, component });

  // 並行執行：發告警 + 初步診斷
  const [alertResult, diagResult] = await Promise.allSettled([
    // 告警通知（多管道確保送達）
    sendMultiChannelAlert(agent, { error_code, severity, component, message }),

    // 讓代理執行初步診斷
    agent.runTask({
      instruction: `
請針對以下錯誤執行初步診斷：

錯誤代碼：${error_code}
發生元件：${component}
錯誤訊息：${message}
Stack Trace：${stack_trace}

請執行：
1. 檢查 ${component} 的最近 5 分鐘日誌
2. 確認相關服務的健康狀態
3. 列出可能的根因（按可能性排序）
4. 建議的緊急應對步驟
      `,
      timeout_ms: 30000
    })
  ]);

  // 將診斷結果附加到告警
  if (diagResult.status === "fulfilled") {
    await agent.skill.execute("update-slack-message", {
      channel: "#incidents",
      thread_ts: alertResult.value?.slack_ts,
      message: `\n*初步診斷結果：*\n${diagResult.value.output.content}`
    });
  }

  return { alerted: true, diagnosed: diagResult.status === "fulfilled" };
}

async function sendMultiChannelAlert(agent, errorInfo) {
  const urgentMessage = `
🚨 *CRITICAL ERROR* — 需要立即處理
*元件*：${errorInfo.component}
*錯誤碼*：${errorInfo.error_code}
*訊息*：${errorInfo.message}
*時間*：${new Date().toLocaleString("zh-TW")}
  `.trim();

  return Promise.all([
    agent.skill.execute("send-slack-message", {
      channel: "#incidents",
      message: urgentMessage,
      notify: "@oncall"
    }),
    agent.skill.execute("send-pagerduty-alert", {
      severity: "critical",
      summary: `[${errorInfo.component}] ${errorInfo.error_code}`,
      details: errorInfo
    })
  ]);
}

8.4 錯誤率聚合監控

// scripts/error-rate-check.js
// 使用滑動視窗計算錯誤率，避免瞬間尖峰誤報
const ERROR_THRESHOLD_PERCENT = 5;  // 5% 錯誤率閾值
const WINDOW_MINUTES = 5;

export async function handler(event, context) {
  const { agent, log } = context;

  const metrics = await agent.skill.execute("query-metrics", {
    metric: "error_rate",
    window: `${WINDOW_MINUTES}m`,
    aggregation: "avg"
  });

  const errorRate = metrics.data.value;
  log.info("當前錯誤率", { error_rate: `${errorRate}%` });

  if (errorRate > ERROR_THRESHOLD_PERCENT) {
    log.warn("錯誤率超標", {
      current: errorRate,
      threshold: ERROR_THRESHOLD_PERCENT
    });

    await agent.skill.execute("send-slack-message", {
      channel: "#monitoring",
      message: `⚠️ 錯誤率告警：過去 ${WINDOW_MINUTES} 分鐘平均錯誤率為 ${errorRate.toFixed(2)}%，超過閾值 ${ERROR_THRESHOLD_PERCENT}%`
    });
  }

  return { error_rate: errorRate, threshold_exceeded: errorRate > ERROR_THRESHOLD_PERCENT };
}

九、效能優化與最佳實踐

9.1 Hook 執行效能基準

以下是在標準開發機（Apple M2，16GB RAM）上的 Hook 執行效能基準測試結果：

9.2 防抖與節流模式

在高頻事件場景（如每秒數百次的 skill.executed）中，直接觸發 Hook 可能造成過載。建議採用防抖（Debounce）或節流（Throttle）模式：

// scripts/debounced-aggregator.js
// 在 Hook 腳本層實現防抖：收集 10 秒內的事件後批量處理
import { createDebouncer } from "@openclaw/hooks-utils";

const debounce = createDebouncer({ window_ms: 10000 });

export async function handler(event, context) {
  const { agent, log } = context;

  // 將事件加入緩衝區，10 秒無新事件後觸發批量處理
  const batch = await debounce.accumulate(event);

  if (!batch) {
    // 尚未達到觸發條件，靜默返回
    return { queued: true };
  }

  log.info("批量處理事件", { count: batch.length });
  await processBatch(agent, batch);

  return { processed: batch.length };
}

async function processBatch(agent, events) {
  // 批量處理邏輯
  const summary = events.map(e => e.payload).reduce(/* 聚合邏輯 */);
  await agent.skill.execute("send-batch-notification", { summary });
}

9.3 Hook 並發控制

透過配置 concurrency 參數控制同時執行的 Hook 數量，並針對不同優先級的 Hook 設置獨立佇列：

hooks:
  execution:
    queues:
      # 高優先級佇列：告警類 Hook
      - id: critical
        concurrency: 8
        priority: 100
        hooks: ["critical-error-immediate", "github-pr-merged-handler"]

      # 標準佇列：一般自動化
      - id: standard
        concurrency: 4
        priority: 50
        hooks: ["task-complete-notifier", "skill-failure-tracker"]

      # 低優先級佇列：報表與統計
      - id: batch
        concurrency: 2
        priority: 10
        hooks: ["daily-business-report", "weekly-summary-report"]

9.4 冪等性設計

在重試機制啟用的情況下，Hook 可能被多次執行。確保 Hook 的冪等性（Idempotency）至關重要：

// scripts/idempotent-hook.js
export async function handler(event, context) {
  const { agent, log } = context;
  // 使用事件 ID 作為冪等鍵
  const idempotencyKey = `hook:deploy:${event.id}`;

  // 檢查是否已處理過此事件
  const alreadyProcessed = await agent.memory.get(idempotencyKey);
  if (alreadyProcessed) {
    log.info("事件已處理，跳過重複執行", { event_id: event.id });
    return { skipped: true, reason: "already_processed" };
  }

  // 執行實際業務邏輯
  const result = await performDeployment(event.payload);

  // 記錄已處理狀態（設置 24 小時 TTL 避免永久佔用記憶體）
  await agent.memory.set(idempotencyKey, {
    processed_at: Date.now(),
    result_summary: result.summary
  }, { ttl_seconds: 86400 });

  return result;
}

十、安全考量與風險控管

10.1 Hook 的安全威脅模型

OpenClaw Hooks 系統面臨的主要安全威脅包括：Hook 注入攻擊（惡意事件 payload 導致 Hook 執行非預期操作）、權限提升（Hook 腳本試圖存取超出授權範圍的資源）、以及供應鏈攻擊（惡意的 Hook 腳本依賴套件）。CrowdStrike 與 Cisco 的安全報告均強調，AI 代理框架的 Hook 機制需要嚴格的隔離設計。^[7][8]

10.2 沙箱隔離機制

OpenClaw 的 Hook 執行引擎採用多層沙箱機制：

• 進程隔離：每個 Hook 在獨立的子進程中執行，主進程崩潰不影響 Gateway。
• 記憶體隔離：透過 max_memory_mb 限制，防止單一 Hook 耗盡系統記憶體。
• 網路隔離：預設情況下（allow_network: false），Hook 腳本無法發起任何對外網路請求，必須透過代理 API 的受控介面進行。
• 檔案系統限制：透過 allow_fs 精確控制 Hook 的磁碟存取權限。

10.3 Hook 腳本安全最佳實踐

// 安全的 Hook 腳本範例：嚴格驗證 payload
export async function handler(event, context) {
  const { log } = context;

  // 1. 嚴格驗證 payload 結構（防範格式異常的惡意事件）
  if (!isValidPayload(event.payload)) {
    log.warn("Payload 驗證失敗，拒絕執行", {
      event_id: event.id,
      payload_keys: Object.keys(event.payload || {})
    });
    return { success: false, reason: "invalid_payload" };
  }

  // 2. 不信任 payload 中的任何可執行內容
  const safeName = sanitizeString(event.payload.name);  // 不要直接 eval()

  // 3. 避免在日誌中記錄敏感資料
  log.info("處理事件", {
    event_id: event.id,
    // 只記錄非敏感的元數據
    event_type: event.type,
    agent_id: event.agent_id
    // 不記錄：payload.api_key, payload.password 等
  });

  // ...業務邏輯
}

function isValidPayload(payload) {
  if (!payload || typeof payload !== "object") return false;
  if (typeof payload.task_id !== "string") return false;
  if (!["success", "failed", "cancelled"].includes(payload.status)) return false;
  return true;
}

function sanitizeString(input) {
  if (typeof input !== "string") return "";
  // 移除潛在的命令注入字符
  return input.replace(/[;&|`$(){}[\]<>]/g, "").substring(0, 255);
}

10.4 審計日誌配置

啟用完整的審計日誌，確保所有 Hook 執行均可追溯：

hooks:
  logging:
    audit: true
    audit_path: ".openclaw/logs/hooks-audit.jsonl"
    # 每個審計記錄的 JSON 結構：
    # {
    #   "timestamp": "2026-02-22T08:00:00.000Z",
    #   "hook_id": "daily-business-report",
    #   "event_id": "evt_abc123",
    #   "event_type": "schedule.triggered",
    #   "duration_ms": 4521,
    #   "status": "success",
    #   "sandbox_metrics": {
    #     "cpu_ms": 120,
    #     "memory_peak_mb": 45,
    #     "network_requests": 0
    #   }
    # }

10.5 Hook 依賴套件管理

Hook 腳本的 node_modules 與主應用完全隔離，建議遵循以下原則：

# .openclaw/hooks/package.json
{
  "name": "openclaw-hooks",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@openclaw/hooks-utils": "^1.2.0"
    # 盡量減少第三方依賴
    # 優先使用 OpenClaw 官方提供的工具套件
    # 每個依賴都應通過 npm audit 掃描
  }
}

定期執行 npm audit 掃描已知漏洞，並建立自動化 CI 檢查確保 Hook 依賴套件始終保持安全：

# 在 CI/CD 中加入 Hook 安全掃描
- name: Audit hook dependencies
  run: |
    cd .openclaw/hooks
    npm audit --audit-level=high
    npm run lint  # 確保 Hook 腳本通過靜態分析

10.6 緊急停用機制

當懷疑某個 Hook 存在安全問題時，可以立即停用而無需修改配置：

# 立即停用單一 Hook（不需重啟 Gateway）
openclaw hooks disable --id critical-error-immediate

# 停用所有 Hook（緊急狀況）
openclaw hooks disable --all

# 查看目前所有 Hook 的狀態
openclaw hooks list --verbose

# 重新啟用
openclaw hooks enable --id critical-error-immediate

結語：Hooks 讓 AI 代理真正融入企業工程文化

OpenClaw Hooks 系統代表的不僅是一個技術特性，更是 AI 代理走向企業生產環境的關鍵一步。透過零輪詢的事件驅動架構，Hooks 將 AI 代理從「被動回答工具」轉變為「主動響應系統」，讓代理能夠自然融入 CI/CD 流程、監控體系、以及既有的 DevOps 文化。

從本文的六個實戰案例可以看到，Hooks 的應用場景遠不止於此——任何需要「當 X 發生時，自動執行 Y」的場景，都是 Hooks 的用武之地。隨著 OpenClaw 生態的持續成熟，我們預期 Hooks Marketplace 將成為企業共享自動化邏輯的重要平台。^[3]

安全方面，如 CrowdStrike 與 Cisco 的研究所示，AI 代理的自動化能力是一把雙刃劍。^[7][8] 遵循本文提出的安全最佳實踐——嚴格的沙箱隔離、最小權限原則、完整審計日誌——是負責任部署 Hooks 系統的基本要求。

如果你正在考慮為團隊引入 OpenClaw Hooks，建議從一個低風險的日誌記錄或通知類 Hook 開始，逐步建立信心後再擴展到更複雜的自動化場景。Hooks 系統的學習曲線相當平緩，但其帶來的效益——資源節省、響應速度、以及工程師從重複性工作中解放出來的精力——將隨著使用深度的增加而指數級放大。