OpenClaw Hooksガイド：イベント駆動型オートメーション設計パターンと実践ケーススタディ

企業がAIエージェントの本番環境へのデプロイを真剣に検討し始めると、核心的な問題が浮上します：エージェントはどのようにして既存のエンジニアリング文化と運用システムに真に統合できるのか？ OpenClawチュートリアルの答えはHooks — イベント駆動アーキテクチャを基盤としたオートメーションフレームワークです。^[1]

本記事は「OpenClawシリーズ」の第3回であり、前2回のアーキテクチャ概要とデプロイウォークスルーを基に、Hooksシステムの設計哲学、技術的詳細、6つの完全なエンタープライズグレードのケーススタディを深く分析します。既存のCI/CDパイプラインの最適化、リアルタイムアラートシステムの構築、完全自動化レポートパイプラインの作成など、すぐに実装できる実践的なガイダンスを提供します。

1. ポーリングからイベント駆動へ：AIエージェントオートメーションのパラダイムシフト

1.1 ポーリングモデルの根本的な欠陥

Hooksシステムが登場する前、大多数のAIエージェントフレームワークはポーリングモデルに依存していました：エージェントプロセスが固定間隔（例：毎秒または5秒ごと）で各メッセージチャネルにクエリリクエストを送信し、新しいイベントの処理が必要かどうかを確認していました。シンプルで直感的ですが、この設計には3つの根本的な欠陥があります。

第一に、リソースの浪費。新しいイベントの有無に関わらず、ポーリングリクエストはCPUサイクルとネットワーク帯域を消費します。マルチエージェント環境で10のエージェントがそれぞれ5つのチャネルを1秒間隔でポーリングすると仮定すると、システムは1分間に3,000の空リクエストを生成します — その大部分はまったく無意味です。

第二に、制御不能なレイテンシ。ポーリング間隔がシステムの最大応答レイテンシを決定します。5秒のポーリング間隔では、最悪の場合、重大なアラートが処理されるまで約5秒待つ必要があります。金融取引やAIサイバーセキュリティアラートなどのレイテンシに敏感なシナリオでは、これはまったく許容できません。

第三に、スケーラビリティのボトルネック。エージェント数と監視チャネル数が増加すると、ポーリングリクエストは線形的またはさらには指数関的に増加し、最終的にバックエンドサービスを圧倒します。^[5]

1.2 イベント駆動アーキテクチャのパラダイム上の優位性

イベント駆動アーキテクチャ（EDA）はこのロジックを反転させます：「新しいイベントがあるか？」と積極的に問い合わせるのではなく、イベントが実際に発生した時にシステムがすべてのサブスクライバーに事前通知します。Martin Fowlerはこれを「命令的」から「反応的」思考への転換と表現しています。^[5]

AWSアーキテクチャホワイトペーパーでは、イベント駆動アーキテクチャが3つの重要な目標を達成すると述べています：疎結合（プロデューサーとコンシューマーに直接的な依存関係がない）、弾力性（コンシューマーが独立にスケール可能）、リアルタイム応答性（イベントがミリ秒以内にすべてのサブスクライバーに配信される）。^[6]

OpenClawのHooksシステムは、この成熟したエンタープライズアーキテクチャパラダイムをAIエージェント領域に持ち込んだものです。CNBCの報道が示すように、OpenClawはClawdBot時代から現在に至るまで進化を遂げ、Hooksシステムは「会話ツール」から「エンタープライズオートメーションプラットフォーム」へのアップグレードにおける鍵となる技術的飛躍を表しています。^[4]

1.3 定量比較：ポーリング vs イベント駆動

以下のデータは、典型的なエンタープライズデプロイシナリオ（10エージェント、8チャネルを監視、1日約2,000イベント）から得たものです：

（n = エージェント数、m = 監視チャネル数）

2. OpenClaw Hooksアーキテクチャの深掘り

2.1 アーキテクチャ概要

OpenClaw Hooksシステムは3つのコアコンポーネントで構成されています：イベントプロデューサー、Gatewayイベントバス、Hookエグゼキューター。^[2]

イベントプロデューサーはOpenClawの各サブシステムに分散しています — ユーザーがメッセージを送信した時、エージェントがタスクを完了した時、Skillが呼び出された時、スケジュールされた時間になった時、対応するサブシステムが標準化されたイベントオブジェクトを生成し、Gatewayにプッシュします。

GatewayはローカルのWebSocketエンドポイントws://127.0.0.1:18789で動作し、イベントバスとして機能します。すべてのイベントの受信、イベントタイプによるルーティング、サブスクライブしているすべてのHooksへの配信を担当します。Gatewayはノンブロッキング非同期モデルを使用し、高頻度のイベントがキューのバックログを引き起こさないようにしています。

HookエグゼキューターはGatewayからイベントを受信し、サンドボックス環境で対応するHookスクリプトを実行し、実行結果とエラーをキャプチャします。実行サイクル全体が包括的な監査ログに記録されます。

2.2 Hookのライフサイクル

各Hookはイベントのトリガーから実行完了まで、以下の標準ライフサイクルを経ます：

1. イベント生成：サブシステムがイベントをJSONオブジェクトにシリアライズ。イベントタイプ、タイムスタンプ、ソースエージェントID、イベント固有のペイロードを含む。
2. Gatewayルーティング：イベントを受信したGatewayがルーティングテーブルを検索し、そのイベントタイプにサブスクライブしているすべてのHooksを見つける。
3. フィルター評価：Hookにフィルター条件が定義されている場合、エンジンがまずフィルタールールを評価。条件を満たさないイベントは実行フェーズに入らず破棄される。
4. サンドボックス初期化：Hookに分離されたサンドボックスプロセスが割り当てられ、必要な環境変数と権限トークンが注入される。
5. Hook実行：Hookスクリプトのhandler関数がサンドボックス内で実行され、標準化されたイベントオブジェクトを受信する。
6. 結果キャプチャ：Hook実行結果（成功/失敗/戻り値）がキャプチャされ、監査ログに記録される。
7. サンドボックスクリーンアップ：サンドボックスリソースが解放され、Hook間の完全な分離が保証される。

2.3 CronおよびTraditional Webhooksとの根本的な違い

多くのエンジニアはOpenClaw HooksをCronジョブや従来のWebhooksと類推する傾向がありますが、本質的な違いがあります：

Cronとの違い：Cronジョブは時間に基づいてトリガーされ、処理が必要なイベントの有無に関わらず実行されます。OpenClaw HooksはWebhookエンドポイント（/hooks/wake）と外部スケジューリングツール（システムCronなど）を組み合わせて時間ベースのトリガーを実現でき、その実行コンテキストはOpenClawのエージェント環境であり、エージェントコンテキストへのアクセスと他のイベントとのインタラクションが可能です。

従来のWebhooksとの違い：従来のWebhooksにはパブリックにアクセス可能なHTTPエンドポイントが必要で、開発者はサーバーの管理、TLSの処理、オリジンの検証を行う必要があります。OpenClaw HooksはローカルGateway上で実行されるため、パブリックエンドポイントは不要で、エージェントの認証システムとネイティブに統合されています。

3. アクティベーションと基本設定

3.1 前提条件

OpenClaw Hooksをアクティベートする前に、以下の条件がすべて満たされていることを確認してください：^[10]

• OpenClawバージョン ≥ 2026.1.0（Hooksシステムはこのバージョン以降安定サポート、日付ベースのバージョニングを採用）
• Node.js ≥ 22（Hookスクリプト実行環境）
• ローカルGatewayが実行中（openclaw gateway start）
• 少なくとも1つの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は2つのアクティベーション方法を提供します：

方法1：グローバルアクティベーション（推奨）

openclaw hooks enable

このコマンドはグローバル設定~/.openclaw/openclaw.json（JSON5形式）を変更し、hooks.internal.enabledをtrueに設定してGatewayのHookルーティングモジュールを開始します。アクティベーション後のGateway再起動は不要です — 変更はすぐに反映されます（ホットリロード）。

方法2：特定のHookのアクティベーション

openclaw hooks enable my-custom-hook

このモードでは、指定された名前のHookのみがアクティベートされ、個別のHookの有効化/無効化を精密に制御できます。openclaw hooks listで利用可能なすべてのHookを確認できます。

3.3 設定ファイルフォーマット

OpenClawはディレクトリベースの自動検出メカニズムを採用しており、各Hookは独立したディレクトリで、HOOK.md（メタデータ）とhandler.ts（処理ロジック）を含みます：

# Workspace hooks（最高優先度）
project/hooks/
├── task-notifier/
│   ├── HOOK.md            # メタデータ + ドキュメント
│   └── handler.ts         # イベント処理関数
├── error-alert/
│   ├── HOOK.md
│   └── handler.ts
└── deploy-hook/
    ├── HOOK.md
    └── handler.ts

# ユーザーグローバル hooks
~/.openclaw/hooks/
└── shared-logger/
    ├── HOOK.md
    └── handler.ts

# グローバル設定
~/.openclaw/openclaw.json    # JSON5形式

HOOK.mdの基本構造は以下の通りです（YAML front matter + Markdownドキュメント）：

---
name: task-notifier
description: "当指令完成時発送 Slack 通知"
metadata:
  openclaw:
    events: ["command:new", "command:stop"]
    export: "default"
    requires:
      bins: ["node"]
      env: ["SLACK_WEBHOOK_URL"]
    always: false
---

# Task Notifier Hook

此 Hook 在指令完成或停止時，透過 Slack Webhook 發送通知。

対応するhandler.ts：

// hooks/task-notifier/handler.ts
export default async function handler(event) {
  // event.type: 'command' | 'message' | 'agent' | 'gateway'
  // event.action: 'new' | 'reset' | 'stop' | 'received' | 'sent' 等
  if (event.action !== "stop") return;

  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `指令已完成 — Session: ${event.sessionKey}`
    })
  });
}

3.4 グローバル設定オプション

~/.openclaw/openclaw.json（JSON5形式）のHooks関連の完全な設定オプション：

// ~/.openclaw/openclaw.json（JSON5，支援註解與尾逗號）
{
  "hooks": {
    // 內部 Hooks（事件驅動）
    "internal": {
      "enabled": true,
      "entries": {
        "task-notifier": { "enabled": true },
        "error-alert": {
          "enabled": true,
          "env": { "ALERT_LEVEL": "high" }
        }
      },
      "load": {
        "extraDirs": ["/shared/hooks"]  // 額外 Hook 搜索目錄
      }
    },
    // Webhook 端點（HTTP 觸發）
    "enabled": true,
    "token": "your-secret-token",       // Webhook 驗證 token
    "path": "/hooks",                   // Webhook 基礎路徑
    "maxBodyBytes": 262144,             // 最大請求 payload 大小
    "defaultSessionKey": "hook:ingress",
    "allowedAgentIds": ["hooks", "main"]
  }
}

4. 組み込みHookイベント一覧

4.1 コマンドイベント

コマンドイベントはエージェントがユーザーコマンドを処理する際にトリガーされます（イベント名はコロンで区切られます）：^[1]

4.2 エージェントとGatewayイベント

4.3 メッセージイベント

4.4 ツール結果イベント

注意：すべてのイベント名はコロン区切り（例：command:new）を使用し、ドット記法ではありません。HOOK.mdでHookがサブスクライブするイベントを宣言する際、actionを含まないワイルドカードタイプ（例：commandはすべてのcommand:*イベントにマッチ）も使用できます。

5. カスタムHookの作成ガイド

5.1 Hookスクリプトの基本構造

各Hookはディレクトリ形式で存在し、HOOK.md（メタデータ）とhandler.ts（処理ロジック）を含みます。Handlerはexport defaultで非同期関数をエクスポートする必要があります：

// hooks/my-custom-hook/HOOK.md
---
name: my-custom-hook
description: "示範用自定義 Hook"
metadata:
  openclaw:
    events: ["command:new", "command:stop"]
    export: "default"
    requires:
      bins: ["node"]
---
# My Custom Hook
此 Hook 在指令建立或停止時觸發，用於記錄與通知。

// hooks/my-custom-hook/handler.ts

/**
 * Hook 主處理函數（export default）
 * @param event.type - 事件類別（'command' | 'message' | 'agent' | 'gateway'）
 * @param event.action - 具體動作（'new' | 'reset' | 'stop' | 'received' 等）
 * @param event.sessionKey - 會話標識符
 * @param event.timestamp - ISO 時間戳
 * @param event.messages - 字串陣列，可 push 訊息給代理
 * @param event.context - 事件上下文（含 sessionId, workspaceDir, cfg 等）
 */
export default async function handler(event) {
  const { type, action, context, messages } = event;

  console.log(`Hook 觸發: ${type}:${action}`, {
    sessionKey: event.sessionKey,
    workspace: context.workspaceDir
  });

  // 在此撰寫你的自動化邏輯
  if (action === "stop") {
    // 透過 push 訊息到 messages 陣列，間接指示代理執行後續動作
    messages.push("請將本次會話摘要記錄到 memory/ 目錄");
  }
}

5.2 イベントフィルター構文

OpenClaw Hooksのイベントフィルタリングは2層のメカニズムで実現されます：HOOK.md宣言でサブスクライブするイベントタイプを指定し、handler内部ロジックできめ細かい条件判断を行います。公式ドキュメントでは「handler冒頭でearly returnして関連しないイベントを無視する」ことを推奨しています。

// hooks/filtered-hook/HOOK.md
---
name: filtered-hook
description: "只處理來自特定管道的訊息"
metadata:
  openclaw:
    events: ["message:received"]   # 第一層：只訂閱 message:received
    export: "default"
---

// hooks/filtered-hook/handler.ts
export default async function handler(event) {
  // 第二層：在 handler 內部進行細粒度過濾
  if (event.action !== "received") return;

  const { channelId, from, content } = event.context;

  // 只處理來自 Slack 管道的訊息
  if (channelId !== "slack-prod") return;

  // 忽略機器人自身的訊息
  if (from === "openclaw-bot") return;

  // 通過所有過濾條件，執行業務邏輯
  console.log("處理 Slack 訊息", { from, channelId });
  await processSlackMessage(content);
}

5.3 エージェントAPIへのアクセス

Hookは主に2つの方法でエージェントとインタラクションします：メッセージプッシュ（event.messages.push()）でエージェントにイベント受信後のアクションを実行させること、およびサイドエフェクトの直接実行（HTTPリクエスト、ファイル操作など）で自動化ロジックを処理することです。

// hooks/smart-responder/handler.ts
export default async function handler(event) {
  const { type, action, context, messages } = event;

  if (type !== "message" || action !== "received") return;

  const { content, channelId, from } = context;

  // 方式一：推送訊息給代理，讓代理處理後續
  if (content.includes("urgent")) {
    messages.push(
      `收到來自 ${from} 的緊急訊息，請分析並回覆：${content}`
    );
  }

  // 方式二：直接執行側效（HTTP 請求、外部 API 呼叫等）
  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `[${channelId}] 收到訊息 from ${from}: ${content.substring(0, 100)}`
    })
  });

  // 方式三：在 agent:bootstrap 時注入額外檔案
  if (type === "agent" && action === "bootstrap") {
    context.bootstrapFiles?.push({
      path: "extra-context.md",
      content: "# 額外上下文\n自動注入的啟動檔案"
    });
  }
}

5.4 エラー処理とリトライ

堅牢なエラー処理は本番環境のHooksに不可欠です。Handler内の未キャッチ例外はHook実行エンジンによってログに記録され、Gatewayのメインプロセスには影響しません：

// hooks/resilient-hook/handler.ts
export default async function handler(event) {
  try {
    const result = await riskyOperation(event.context);
    console.log("Hook 執行成功", { sessionKey: event.sessionKey });

  } catch (error) {
    // 記錄錯誤並優雅處理
    console.error("Hook 執行失敗", {
      error: error.message,
      type: `${event.type}:${event.action}`
    });

    // 可選：透過外部服務發送告警
    if (error.code === "NETWORK_TIMEOUT") {
      await sendAlert(`Hook 超時: ${error.message}`);
    }

    // 不重新拋出 = 靜默處理
    // 重新拋出 = 引擎記錄未捕獲例外
  }
}

async function riskyOperation(context) {
  const response = await fetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session: context.sessionId }),
    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();
}

async function sendAlert(message) {
  const webhook = process.env.ALERT_WEBHOOK_URL;
  if (!webhook) return;
  await fetch(webhook, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: message })
  });
}

6. ケーススタディ1：CI/CDパイプラインオートメーション

6.1 シナリオ説明

中規模ソフトウェア企業のエンジニアリングチームが、GitHub Pull Requestのマージごとに、テスト、ビルド、デプロイプロセスを自動トリガーし、各重要ノードでSlackチャネルに通知することを望んでいます。従来のソリューションでは複雑なGitHub Actionsワークフローを維持する必要がありますが、OpenClaw Hooksを使えば、フロー全体をAIエージェントがより柔軟に調整できます。^[9]

6.2 アーキテクチャ設計

全体のデータフロー：GitHub Webhook → /hooks/github エンドポイント → message:received イベント → Hook メッセージプッシュ → エージェントがデプロイタスクを実行 → command:stop イベント → 通知 Hook

6.3 完全な実装

ステップ1：Webhookエンドポイントの設定

~/.openclaw/openclaw.jsonでGitHub Webhookマッピングを設定：

// ~/.openclaw/openclaw.json（JSON5）
{
  "hooks": {
    "enabled": true,
    "token": "${GITHUB_WEBHOOK_SECRET}",
    "mappings": [
      {
        "match": { "path": "github" },
        "action": "agent",
        "agentId": "main",
        "wakeMode": "now",
        "sessionKey": "hook:github:{{body.pull_request.number}}",
        "messageTemplate": "GitHub PR #{{body.pull_request.number}} ({{body.action}}): {{body.pull_request.title}}"
      }
    ]
  }
}

ステップ2：HookディレクトリとHOOK.mdの作成

// hooks/github-pr-deploy/HOOK.md
---
name: github-pr-deploy
description: "PR 合併後觸發 CI/CD 部署流程"
metadata:
  openclaw:
    events: ["message:received"]
    export: "default"
    requires:
      env: ["SLACK_WEBHOOK_URL"]
---

ステップ3：Hookスクリプトのデプロイ

// hooks/github-pr-deploy/handler.ts
export default async function handler(event) {
  if (event.action !== "received") return;

  const { content, channelId } = event.context;
  // 過濾：只處理來自 GitHub webhook 管道的訊息
  if (!channelId?.startsWith("hook:github")) return;

  // 解析 PR 資訊（content 為 messageTemplate 渲染後的文字）
  console.log("PR 事件觸發", { channelId, content });

  // 推送訊息給代理，讓代理執行 CI/CD 流程
  event.messages.push(`
收到 GitHub PR 合併通知。請執行以下 CI/CD 流程：
1. 拉取最新程式碼：git pull origin main
2. 安裝依賴：npm ci
3. 執行測試套件：npm test
4. 如測試通過，建構生產包：npm run build
5. 部署至生產環境
6. 執行健康檢查確認部署成功
7. 將部署結果通知 Slack #deployments 頻道
  `.trim());
}

// hooks/deploy-notifier/handler.ts
// 搭配 command:stop 事件，在指令完成後發送 Slack 通知
export default async function handler(event) {
  if (event.type !== "command" || event.action !== "stop") return;

  // 透過 Webhook 直接通知 Slack
  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  if (!webhookUrl) return;

  const message = `✅ *部署流程完成*\nSession: ${event.sessionKey}\n時間: ${event.timestamp.toISOString()}`;

  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ text: message })
  });

  console.log("部署通知已發送");
}

7. ケーススタディ2：エンタープライズ自動レポートシステム

7.1 シナリオ説明

あるEコマース企業のAIデジタルトランスフォーメーションチームが、毎営業日午前8時に、4つの異なるデータソース（注文システム、在庫システム、広告プラットフォーム、カスタマーサービスシステム）からデータを自動集約し、管理層向け日次レポートを生成し、関連マネージャーにメールで送信する必要があります。

7.2 スケジュール設定

OpenClaw Hooksには組み込みCronスケジューラがないため、自動レポートは外部スケジューリングによるWebhookトリガーと組み合わせる必要があります：

# 系統 Crontab（搭配 OpenClaw Webhook 端點）
# 週一至週五早上 8 點觸發日報
0 8 * * 1-5 curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "請生成今日業務日報並發送至管理層信箱"}'

# 每週一早上 9 點觸發週報
0 9 * * 1 curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "請生成上週業務總結週報"}'

7.3 レポート通知Hook

// hooks/report-notifier/HOOK.md
---
name: report-notifier
description: "報表生成完成後發送 Email 通知"
metadata:
  openclaw:
    events: ["command:stop"]
    export: "default"
    requires:
      env: ["SMTP_HOST", "SMTP_USER", "SMTP_PASS"]
---

// hooks/report-notifier/handler.ts
import { createTransport } from "nodemailer";

export default async function handler(event) {
  if (event.action !== "stop") return;

  // 只處理報表相關的 session
  if (!event.sessionKey?.includes("report")) return;

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

  console.log("報表流程完成，發送通知", { date: dateStr });

  // 透過 SMTP 直接發送通知信（或使用 Webhook 呼叫外部 Email 服務）
  const transporter = createTransport({
    host: process.env.SMTP_HOST,
    auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
  });

  await transporter.sendMail({
    to: "[email protected]",
    subject: `【日報】${dateStr} 業務摘要已生成`,
    text: `今日業務日報已由 AI 代理自動生成，請至系統查閱完整報告。\nSession: ${event.sessionKey}`
  });

  console.log("日報通知已發送", { date: dateStr });
}

8. ケーススタディ3：リアルタイム異常検知とアラート

8.1 シナリオ説明

あるSaaSプラットフォームのSREチームが、システムエラー率が閾値を超えたとき、または特定の種類の重大エラーが発生したときに、30秒以内にオンコールエンジニアに通知し、自動的に初期診断を実行する必要があります。

8.2 多層アラートアーキテクチャ

message:receivedとcommand:stopイベントをWebhookエンドポイントと組み合わせて、多層リアルタイムアラートを実現：

// hooks/critical-alert/HOOK.md
---
name: critical-alert
description: "監控代理訊息中的錯誤關鍵字，觸發即時告警"
metadata:
  openclaw:
    events: ["message:received"]
    export: "default"
    requires:
      env: ["SLACK_WEBHOOK_URL", "PAGERDUTY_KEY"]
---

8.3 リアルタイムアラートHook

// hooks/critical-alert/handler.ts
export default async function handler(event) {
  if (event.action !== "received") return;

  const { content, channelId } = event.context;
  if (!content) return;

  // 檢測嚴重錯誤關鍵字
  const criticalPatterns = ["CRITICAL", "FATAL", "OOM", "503", "timeout"];
  const isCritical = criticalPatterns.some(p =>
    content.toUpperCase().includes(p.toUpperCase())
  );

  if (!isCritical) return;

  console.warn("嚴重錯誤觸發告警", { channelId });

  // 並行執行：Slack 告警 + PagerDuty 告警
  await Promise.allSettled([
    sendSlackAlert(content, channelId),
    sendPagerDutyAlert(content, channelId)
  ]);

  // 推送訊息讓代理執行初步診斷
  event.messages.push(
    `偵測到嚴重錯誤訊息，請執行初步診斷並將結果摘要回覆。錯誤內容：${content.substring(0, 500)}`
  );
}

async function sendSlackAlert(content, channelId) {
  const webhookUrl = process.env.SLACK_WEBHOOK_URL;
  if (!webhookUrl) return;

  await fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `🚨 *CRITICAL ERROR* — 需要立即處理\n*管道*：${channelId}\n*訊息*：${content.substring(0, 200)}\n*時間*：${new Date().toLocaleString("zh-TW")}`
    })
  });
}

async function sendPagerDutyAlert(content, channelId) {
  const routingKey = process.env.PAGERDUTY_KEY;
  if (!routingKey) return;

  await fetch("https://events.pagerduty.com/v2/enqueue", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      routing_key: routingKey,
      event_action: "trigger",
      payload: {
        summary: `[${channelId}] 嚴重錯誤`,
        severity: "critical",
        source: "openclaw-hooks"
      }
    })
  });
}

8.4 外部スケジューリングによるエラー率監視

# 每 5 分鐘透過 Webhook 觸發代理檢查錯誤率
*/5 * * * * curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "請查詢過去 5 分鐘的系統錯誤率，若超過 5% 請發送告警至 Slack #monitoring"}'

9. パフォーマンス最適化とベストプラクティス

9.1 Hook実行パフォーマンスベンチマーク

以下のHook実行パフォーマンスベンチマークは、標準的な開発マシン（Apple M2、16GB RAM）で測定されたものです：

9.2 デバウンスとスロットルパターン

高頻度イベントシナリオでは、Hookの直接トリガーが過負荷を引き起こす可能性があります。handler内でデバウンス（Debounce）またはスロットル（Throttle）パターンを実装することを推奨します：

// hooks/debounced-aggregator/handler.ts
// 在 handler 內部實現簡易防抖：利用檔案系統記錄事件，批量處理
import { readFileSync, writeFileSync, existsSync } from "fs";
import { join } from "path";

const BATCH_FILE = "/tmp/openclaw-hook-batch.json";
const WINDOW_MS = 10000;  // 10 秒視窗

export default async function handler(event) {
  if (event.action !== "received") return;

  // 讀取或初始化批次緩衝區
  let batch = [];
  if (existsSync(BATCH_FILE)) {
    batch = JSON.parse(readFileSync(BATCH_FILE, "utf-8"));
  }

  batch.push({
    timestamp: Date.now(),
    sessionKey: event.sessionKey,
    content: event.context.content?.substring(0, 200)
  });

  // 檢查是否超過視窗時間
  const firstTimestamp = batch[0]?.timestamp || Date.now();
  if (Date.now() - firstTimestamp < WINDOW_MS) {
    // 尚未到達視窗，繼續累積
    writeFileSync(BATCH_FILE, JSON.stringify(batch));
    return;
  }

  // 視窗到期，批量處理
  console.log("批量處理事件", { count: batch.length });
  await sendBatchNotification(batch);

  // 清空緩衝區
  writeFileSync(BATCH_FILE, "[]");
}

async function sendBatchNotification(batch) {
  const webhook = process.env.SLACK_WEBHOOK_URL;
  if (!webhook) return;
  await fetch(webhook, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `📊 過去 10 秒收到 ${batch.length} 則訊息`
    })
  });
}

9.3 Hook並行制御

openclaw.jsonのhooks.internal.entriesで各Hookの有効化状態と環境変数を精密に制御し、HOOK.mdのrequiresフィールドと組み合わせて条件を満たす場合のみロードされるようにします：

// ~/.openclaw/openclaw.json（JSON5）
{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        // 高優先級：告警類 Hook（確保始終啟用）
        "critical-alert": {
          "enabled": true,
          "env": { "ALERT_LEVEL": "critical" }
        },
        "github-pr-deploy": {
          "enabled": true
        },
        // 可按需停用低優先級 Hook
        "report-notifier": {
          "enabled": true
        }
      },
      "load": {
        // 額外 Hook 搜索目錄（團隊共享）
        "extraDirs": ["/shared/team-hooks"]
      }
    }
  }
}

9.4 冪等性設計

リトライメカニズムが有効な場合、Hookは複数回実行される可能性があります。Hookの冪等性（Idempotency）を確保することが極めて重要です：

// hooks/idempotent-hook/handler.ts
import { existsSync, writeFileSync, readFileSync } from "fs";
import { join } from "path";

const PROCESSED_DIR = "/tmp/openclaw-hook-processed";

export default async function handler(event) {
  if (event.action !== "stop") return;

  // 使用 sessionKey 作為冪等鍵
  const idempotencyKey = `${event.sessionKey}-${event.timestamp.toISOString().slice(0, 10)}`;
  const lockFile = join(PROCESSED_DIR, `${idempotencyKey}.lock`);

  // 檢查是否已處理過此事件
  if (existsSync(lockFile)) {
    console.log("事件已處理，跳過重複執行", { sessionKey: event.sessionKey });
    return;
  }

  // 執行實際業務邏輯
  await performNotification(event);

  // 記錄已處理狀態
  writeFileSync(lockFile, JSON.stringify({
    processed_at: new Date().toISOString(),
    sessionKey: event.sessionKey
  }));
}

async function performNotification(event) {
  // 具體通知邏輯...
}

10. セキュリティ考慮事項とリスク管理

10.1 Hookの脅威モデル

OpenClaw Hooksシステムが直面する主なセキュリティ脅威には以下が含まれます：Hookインジェクション攻撃（悪意のあるイベントペイロードによってHooksが意図しない操作を実行）、権限昇格（Hookスクリプトが許可範囲を超えたリソースへのアクセスを試行）、サプライチェーン攻撃（悪意のあるHookスクリプト依存関係）。CrowdStrikeとCiscoの両方のセキュリティレポートが、AIエージェントフレームワークにおけるHookメカニズムには厳格な分離設計が必要であることを強調しています。^[7][8]

10.2 サンドボックス分離メカニズム

OpenClawのHookシステムは多層セキュリティメカニズムを採用しています：

• 前提資格チェック：Hookロード前にHOOK.mdで宣言されたrequires（必要なバイナリ、環境変数、OS互換性）を自動検証し、条件を満たさないHookはロードされない。
• セキュアインストール：openclaw hooks installでHook Packをインストールする際、npm install --ignore-scriptsを実行し、インストールスクリプトによる任意コード実行を防止。
• ファイルパス検証：Hookがアクセスするファイルはworkspaceディレクトリ内に限定（realpathチェック）し、パストラバーサル攻撃を防止。
• ソース制限：openclaw hooks installはnpmレジストリのパッケージ名のみを受け付け、Git/URL/ローカルファイルパスを拒否し、サプライチェーンリスクを低減。

10.3 Hookスクリプトのセキュリティベストプラクティス

// hooks/secure-hook/handler.ts — 安全的 Hook 腳本範例
export default async function handler(event) {
  // 1. 嚴格驗證 context 結構（防範格式異常的惡意事件）
  if (!isValidContext(event.context)) {
    console.warn("Context 驗證失敗，拒絕執行", {
      type: event.type,
      action: event.action,
      contextKeys: Object.keys(event.context || {})
    });
    return;
  }

  // 2. 不信任 context 中的任何可執行內容
  const safeContent = sanitizeString(event.context.content);

  // 3. 避免在日誌中記錄敏感資料
  console.log("處理事件", {
    type: `${event.type}:${event.action}`,
    sessionKey: event.sessionKey
    // 不記錄：context 中可能包含的 API key、token 等
  });

  // ...業務邏輯
}

function isValidContext(context) {
  if (!context || typeof context !== "object") return false;
  return true;
}

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

10.4 監査ログ設定

OpenClawには組み込みのcommand-logger Hookがあり、すべてのコマンドを~/.openclaw/logs/commands.log（JSONL形式）に自動記録します。さらに、カスタムHookでより精密な監査ログを実装できます：

// hooks/audit-logger/handler.ts — 自定義審計日誌
import { appendFileSync } from "fs";

export default async function handler(event) {
  const auditEntry = {
    timestamp: event.timestamp.toISOString(),
    type: `${event.type}:${event.action}`,
    sessionKey: event.sessionKey,
    contextKeys: Object.keys(event.context || {})
  };

  appendFileSync(
    ".openclaw/logs/hooks-audit.jsonl",
    JSON.stringify(auditEntry) + "\n"
  );
}

組み込みのcommand-logger Hookも有効化できます：

openclaw hooks enable command-logger
# 日誌寫入 ~/.openclaw/logs/commands.log（JSONL 格式）

10.5 Hook依存パッケージ管理

openclaw hooks installでHook Packをインストールする際、依存関係は~/.openclaw/hooks/<hook-id>/にインストールされ、npm install --ignore-scriptsでインストールスクリプトによる任意コード実行を防止します。以下の原則に従うことを推奨します：

• サードパーティ依存関係を最小限にし、Node.js組み込みモジュールを優先的に使用
• openclaw hooks installはnpmレジストリのパッケージ名のみを受け付ける（Git/URL/ローカルパスを拒否）
• すべての依存関係はnpm auditでスキャンすべき

# 查看已安裝的 Hook 及其依賴狀態
openclaw hooks list --verbose

# 檢查 Hook 資格與依賴
openclaw hooks check --json

定期的にnpm auditで既知の脆弱性をスキャンし、自動化CIチェックを構築：

# 在 CI/CD 中加入 Hook 安全掃描
- name: Audit hook dependencies
  run: |
    openclaw hooks check
    npm audit --audit-level=high

10.6 緊急無効化メカニズム

Hookにセキュリティ上の問題が疑われる場合、設定を変更せずに即座に無効化できます：

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

# 查看目前所有 Hook 的狀態（含資格檢查）
openclaw hooks list --verbose

# 以 JSON 格式輸出（方便自動化處理）
openclaw hooks list --json

# 重新啟用
openclaw hooks enable critical-alert

まとめ：Hooksが AIエージェントをエンタープライズエンジニアリング文化に真に統合させる

OpenClaw Hooksシステムは単なる技術機能を超えたものです — それはAIエージェントをエンタープライズの本番環境に持ち込むための重要なステップです。ゼロポーリングのイベント駆動アーキテクチャを通じて、HooksはAIエージェントを「受動的な応答ツール」から「能動的な応答システム」へと変革し、エージェントがCI/CDワークフロー、モニタリングシステム、既存のDevOps文化に自然に統合できるようにします。

本記事の6つのケーススタディが示すように、Hooksの適用シナリオはこれらの例にとどまりません — 「Xが発生したら、自動的にYを実行する」というすべてのシナリオがHooksのユースケースです。OpenClawエコシステムが成熟を続ける中、Hooks Marketplaceが企業間でオートメーションロジックを共有するための重要なプラットフォームになることが期待されます。^[3]

セキュリティ面では、CrowdStrikeとCiscoの研究が示すように、AIエージェントの自動化機能は諸刃の剣です。^[7][8]本記事で概説したセキュリティベストプラクティス — 厳格なサンドボックス分離、最小権限の原則、包括的な監査ログ — に従うことが、責任あるHooksデプロイの最低限の要件です。

チームへのOpenClaw Hooksの導入を検討している場合は、リスクの低いログまたは通知Hookから始め、段階的に信頼を築いてからより複雑なオートメーションシナリオに拡張することをお勧めします。Hooksシステムの学習曲線は非常に緩やかですが、それがもたらすメリット — リソースの節約、応答速度、エンジニアを反復作業から解放するエネルギー — は、使用の深度が増すにつれて指数関数的に成長します。