フック

フックは、エージェントコマンドとイベントに応答してアクションを自動化するための拡張可能なイベント駆動システムを提供します。フックはディレクトリから自動的に検出され、CLI コマンドで管理できます。これは OpenClaw でのスキルの動作と同様です。

概要

フックは何かが起こったときに実行される小さなスクリプトです。2 種類あります：

  • フック（このページ）：/new、/reset、/stop、またはライフサイクルイベントなどのエージェントイベントが発生したときに Gateway 内で実行されます。
  • Webhook：他のシステムが OpenClaw で作業をトリガーできるようにする外部 HTTP webhook。Webhook フック を参照するか、Gmail ヘルパーコマンドには openclaw webhooks を使用してください。

フックはプラグイン内にバンドルすることもできます。プラグイン を参照してください。

一般的な用途：

  • セッションをリセットするときにメモリスナップショットを保存する
  • トラブルシューティングまたはコンプライアンスのためにコマンドの監査証跡を保持する
  • セッションが開始または終了したときにフォローアップオートメーションをトリガーする
  • イベントが発生したときにエージェントワークスペースにファイルを書き込むか、外部 API を呼び出す

小さな TypeScript 関数を書けるなら、フックを書くことができます。フックは自動的に検出され、CLI で有効化または無効化できます。

概要

フックシステムでは以下のことができます：

  • /new が発行されたときにセッションコンテキストをメモリに保存する
  • 監査のためにすべてのコマンドをログに記録する
  • エージェントライフサイクルイベントでカスタムオートメーションをトリガーする
  • コアコードを変更することなく OpenClaw の動作を拡張する

はじめに

バンドルされたフック

OpenClaw には、自動的に検出される 4 つのバンドルされたフックが付属しています：

  • 💾 session-memory：/new を発行したときに、セッションコンテキストをエージェントワークスペース（デフォルト ~/.openclaw/workspace/memory/）に保存します
  • 📝 command-logger：すべてのコマンドイベントを ~/.openclaw/logs/commands.log にログに記録します
  • 🚀 boot-md：gateway が起動したときに BOOT.md を実行します（内部フックを有効にする必要があります）
  • 😈 soul-evil：パージウィンドウ中またはランダムチャンスで、注入された SOUL.md コンテンツを SOUL_EVIL.md に交換します

利用可能なフックをリストします：

openclaw hooks list

フックを有効化：

openclaw hooks enable session-memory

フックのステータスを確認：

openclaw hooks check

詳細情報を取得：

openclaw hooks info session-memory

オンボーディング

オンボーディング（openclaw onboard）中に、推奨フックを有効化するよう求められます。ウィザードは自動的に適格なフックを検出し、選択のために提示します。

フックの検出

フックは 3 つのディレクトリから自動的に検出されます（優先順位順）：

  1. ワークスペースフック：<workspace>/hooks/（エージェントごと、最高優先度）
  2. 管理フック：~/.openclaw/hooks/（ユーザーインストール、ワークスペース間で共有）
  3. バンドルされたフック：<openclaw>/dist/hooks/bundled/（OpenClaw に同梱）

管理フックディレクトリは、単一フックまたはフックパック（パッケージディレクトリ）のいずれかです。

各フックは、以下を含むディレクトリです：

my-hook/
├── HOOK.md          # メタデータ + ドキュメント
└── handler.ts       # ハンドラー実装

フックパック（npm/アーカイブ）

フックパックは、package.json の openclaw.hooks を介して 1 つ以上のフックをエクスポートする標準の npm パッケージです。以下でインストールします：

openclaw hooks install <path-or-spec>

package.json の例：

{
  "name": "@acme/my-hooks",
  "version": "0.1.0",
  "openclaw": {
    "hooks": ["./hooks/my-hook", "./hooks/other-hook"]
  }
}

各エントリは、HOOK.md と handler.ts（または index.ts）を含むフックディレクトリを指しています。 フックパックは依存関係を配布できます。これらは ~/.openclaw/hooks/<id> 配下にインストールされます。

フックの構造

HOOK.md フォーマット

HOOK.md ファイルには、YAML frontmatter のメタデータと Markdown ドキュメントが含まれています：

---
name: my-hook
description: "このフックが何をするかの短い説明"
homepage: https://docs.openclaw.ai/hooks#my-hook
metadata: {"openclaw":{"emoji":"🔗","events":["command:new"],"requires":{"bins":["node"]}}}
---

# My Hook

詳細なドキュメントはここに...

## 何をするか

- `/new` コマンドをリッスンする
- 何らかのアクションを実行する
- 結果をログに記録する

## 要件

- Node.js がインストールされている必要があります

## 設定

設定は不要です。

メタデータフィールド

metadata.openclaw オブジェクトは以下をサポートします：

  • emoji：CLI 用の表示絵文字（例："💾"）
  • events：リッスンするイベントの配列（例：["command:new", "command:reset"]）
  • export：使用する名前付きエクスポート（デフォルトは "default"）
  • homepage：ドキュメント URL
  • requires：オプションの要件
    • bins：PATH 上で必要なバイナリ（例：["git", "node"]）
    • anyBins：これらのバイナリのうち少なくとも 1 つが存在する必要があります
    • env：必要な環境変数
    • config：必要な設定パス（例：["workspace.dir"]）
    • os：必要なプラットフォーム（例：["darwin", "linux"]）
  • always：適格性チェックをバイパス（ブール値）
  • install：インストール方法（バンドルされたフックの場合：[{"id":"bundled","kind":"bundled"}]）

ハンドラー実装

handler.ts ファイルは HookHandler 関数をエクスポートします：

import type { HookHandler } from '../../src/hooks/hooks.js';

const myHandler: HookHandler = async (event) => {
  // 'new' コマンドでのみトリガー
  if (event.type !== 'command' || event.action !== 'new') {
    return;
  }

  console.log(`[my-hook] New コマンドがトリガーされました`);
  console.log(`  セッション: ${event.sessionKey}`);
  console.log(`  タイムスタンプ: ${event.timestamp.toISOString()}`);

  // ここにカスタムロジックを追加

  // オプションでユーザーにメッセージを送信
  event.messages.push('✨ マイフックが実行されました！');
};

export default myHandler;

イベントコンテキスト

各イベントには以下が含まれます：

{
  type: 'command' | 'session' | 'agent' | 'gateway',
  action: string,              // 例：'new'、'reset'、'stop'
  sessionKey: string,          // セッション識別子
  timestamp: Date,             // イベントが発生したとき
  messages: string[],          // ユーザーに送信するメッセージをここにプッシュ
  context: {
    sessionEntry?: SessionEntry,
    sessionId?: string,
    sessionFile?: string,
    commandSource?: string,    // 例：'whatsapp'、'telegram'
    senderId?: string,
    workspaceDir?: string,
    bootstrapFiles?: WorkspaceBootstrapFile[],
    cfg?: OpenClawConfig
  }
}

イベントタイプ

コマンドイベント

エージェントコマンドが発行されたときにトリガーされます：

  • command：すべてのコマンドイベント（一般リスナー）
  • command:new：/new コマンドが発行されたとき
  • command:reset：/reset コマンドが発行されたとき
  • command:stop：/stop コマンドが発行されたとき

エージェントイベント

  • agent:bootstrap：ワークスペースブートストラップファイルが注入される前（フックは context.bootstrapFiles を変更できます）

Gateway イベント

gateway が起動したときにトリガーされます：

  • gateway:startup：チャネルが開始し、フックがロードされた後

ツール結果フック（プラグイン API）

これらのフックはイベントストリームリスナーではありません。プラグインが OpenClaw が永続化する前にツール結果を同期的に調整できるようにします。

  • tool_result_persist：セッション転写に書き込まれる前にツール結果を変換します。同期である必要があります。更新されたツール結果ペイロードを返すか、そのままにするために undefined を返します。エージェントループ を参照してください。

将来のイベント

計画されているイベントタイプ：

  • session:start：新しいセッションが開始したとき
  • session:end：セッションが終了したとき
  • agent:error：エージェントがエラーに遭遇したとき
  • message:sent：メッセージが送信されたとき
  • message:received：メッセージが受信されたとき

カスタムフックの作成

1. 場所を選択

  • ワークスペースフック（<workspace>/hooks/）：エージェントごと、最高優先度
  • 管理フック（~/.openclaw/hooks/）：ワークスペース間で共有

2. ディレクトリ構造を作成

mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook

3. HOOK.md を作成

---
name: my-hook
description: "便利なことをする"
metadata: {"openclaw":{"emoji":"🎯","events":["command:new"]}}
---

# My Custom Hook

これは `/new` を発行したときに便利なことをするフックです。

4. handler.ts を作成

import type { HookHandler } from '../../src/hooks/hooks.js';

const handler: HookHandler = async (event) => {
  if (event.type !== 'command' || event.action !== 'new') {
    return;
  }

  console.log('[my-hook] 実行中！');
  // ここにロジックを追加
};

export default handler;

5. 有効化してテスト

# フックが検出されたことを確認
openclaw hooks list

# 有効化
openclaw hooks enable my-hook

# gateway プロセスを再起動（macOS ではメニューバーアプリを再起動、または開発プロセスを再起動）

# イベントをトリガー
# メッセージングチャネル経由で /new を送信

設定

新しい設定フォーマット（推奨）

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

フックごとの設定

フックはカスタム設定を持つことができます：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": {
            "MY_CUSTOM_VAR": "value"
          }
        }
      }
    }
  }
}

追加ディレクトリ

追加のディレクトリからフックをロードします：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

レガシー設定フォーマット（引き続きサポート）

古い設定フォーマットは後方互換性のために引き続き動作します：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts",
          "export": "default"
        }
      ]
    }
  }
}

移行：新しいフックには新しい検出ベースのシステムを使用してください。レガシーハンドラーは、ディレクトリベースのフックの後にロードされます。

CLI コマンド

フックをリスト

# すべてのフックをリスト
openclaw hooks list

# 適格なフックのみを表示
openclaw hooks list --eligible

# 冗長出力（不足している要件を表示）
openclaw hooks list --verbose

# JSON 出力
openclaw hooks list --json

フック情報

# フックの詳細情報を表示
openclaw hooks info session-memory

# JSON 出力
openclaw hooks info session-memory --json

適格性を確認

# 適格性サマリーを表示
openclaw hooks check

# JSON 出力
openclaw hooks check --json

有効化 / 無効化

# フックを有効化
openclaw hooks enable session-memory

# フックを無効化
openclaw hooks disable command-logger

バンドルされたフック

session-memory

/new を発行したときにセッションコンテキストをメモリに保存します。

イベント：command:new

要件：workspace.dir が設定されている必要があります

出力：<workspace>/memory/YYYY-MM-DD-slug.md（デフォルトは ~/.openclaw/workspace）

何をするか：

  1. リセット前のセッションエントリを使用して正しい転写を見つけます
  2. 会話の最後の 15 行を抽出します
  3. LLM を使用して説明的なファイル名スラグを生成します
  4. セッションメタデータを日付付きメモリファイルに保存します

出力例：

# セッション：2026-01-16 14:30:00 UTC

- **セッションキー**：agent:main:main
- **セッション ID**：abc123def456
- **ソース**：telegram

ファイル名の例：

  • 2026-01-16-vendor-pitch.md
  • 2026-01-16-api-design.md
  • 2026-01-16-1430.md（スラグ生成が失敗した場合のフォールバックタイムスタンプ）

有効化：

openclaw hooks enable session-memory

command-logger

すべてのコマンドイベントを一元化された監査ファイルにログ記録します。

イベント：command

要件：なし

出力：~/.openclaw/logs/commands.log

何をするか：

  1. イベントの詳細（コマンドアクション、タイムスタンプ、セッションキー、送信者 ID、ソース）をキャプチャします
  2. JSONL 形式でログファイルに追加します
  3. バックグラウンドでサイレントに実行します

ログエントリの例：

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"}
{"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"[email protected]","source":"whatsapp"}

ログを表示：

# 最近のコマンドを表示
tail -n 20 ~/.openclaw/logs/commands.log

# jq できれいに出力
cat ~/.openclaw/logs/commands.log | jq .

# アクションでフィルター
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

有効化：

openclaw hooks enable command-logger

soul-evil

パージウィンドウ中またはランダムチャンスで、注入された SOUL.md コンテンツを SOUL_EVIL.md に交換します。

イベント：agent:bootstrap

ドキュメント：SOUL Evil フック

出力：ファイルは書き込まれません。スワップはメモリ内でのみ発生します。

有効化：

openclaw hooks enable soul-evil

設定：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-evil": {
          "enabled": true,
          "file": "SOUL_EVIL.md",
          "chance": 0.1,
          "purge": { "at": "21:00", "duration": "15m" }
        }
      }
    }
  }
}

boot-md

gateway が起動したときに BOOT.md を実行します（チャネルが開始した後）。 これが実行されるには、内部フックを有効にする必要があります。

イベント：gateway:startup

要件：workspace.dir が設定されている必要があります

何をするか：

  1. ワークスペースから BOOT.md を読み取ります
  2. エージェントランナー経由で指示を実行します
  3. メッセージツール経由で要求されたアウトバウンドメッセージを送信します

有効化：

openclaw hooks enable boot-md

ベストプラクティス

ハンドラーを高速に保つ

フックはコマンド処理中に実行されます。軽量に保ってください：

// ✓ 良い - 非同期作業、すぐに返す
const handler: HookHandler = async (event) => {
  void processInBackground(event); // Fire and forget
};

// ✗ 悪い - コマンド処理をブロック
const handler: HookHandler = async (event) => {
  await slowDatabaseQuery(event);
  await evenSlowerAPICall(event);
};

エラーを優雅に処理

危険な操作は常にラップしてください：

const handler: HookHandler = async (event) => {
  try {
    await riskyOperation(event);
  } catch (err) {
    console.error('[my-handler] 失敗:', err instanceof Error ? err.message : String(err));
    // 投げない - 他のハンドラーを実行させる
  }
};

イベントを早期にフィルター

イベントが関連しない場合は早期に返します：

const handler: HookHandler = async (event) => {
  // 'new' コマンドのみを処理
  if (event.type !== 'command' || event.action !== 'new') {
    return;
  }

  // ここにロジックを追加
};

特定のイベントキーを使用

可能な場合はメタデータで正確なイベントを指定してください：

metadata: {"openclaw":{"events":["command:new"]}}  # 特定

以下よりも：

metadata: {"openclaw":{"events":["command"]}}      # 一般 - オーバーヘッドが大きい

デバッグ

フックロギングを有効化

gateway は起動時にフックのロードをログに記録します：

Registered hook: session-memory -> command:new
Registered hook: command-logger -> command
Registered hook: boot-md -> gateway:startup

検出を確認

検出されたすべてのフックをリスト：

openclaw hooks list --verbose

登録を確認

ハンドラーで呼び出されたときにログに記録します：

const handler: HookHandler = async (event) => {
  console.log('[my-handler] トリガーされました:', event.type, event.action);
  // ロジック
};

適格性を確認

フックが適格でない理由を確認：

openclaw hooks info my-hook

出力で不足している要件を探してください。

テスト

Gateway ログ

gateway ログを監視してフックの実行を確認します：

# macOS
./scripts/clawlog.sh -f

# その他のプラットフォーム
tail -f ~/.openclaw/gateway.log

フックを直接テスト

ハンドラーを分離してテストします：

import { test } from 'vitest';
import { createHookEvent } from './src/hooks/hooks.js';
import myHandler from './hooks/my-hook/handler.js';

test('my handler works', async () => {
  const event = createHookEvent('command', 'new', 'test-session', {
    foo: 'bar'
  });

  await myHandler(event);

  // 副作用をアサート
});

アーキテクチャ

コアコンポーネント

  • src/hooks/types.ts：型定義
  • src/hooks/workspace.ts：ディレクトリスキャンとロード
  • src/hooks/frontmatter.ts：HOOK.md メタデータ解析
  • src/hooks/config.ts：適格性チェック
  • src/hooks/hooks-status.ts：ステータスレポート
  • src/hooks/loader.ts：動的モジュールローダー
  • src/cli/hooks-cli.ts：CLI コマンド
  • src/gateway/server-startup.ts：gateway 起動時にフックをロード
  • src/auto-reply/reply/commands-core.ts：コマンドイベントをトリガー

検出フロー

Gateway 起動
    ↓
ディレクトリをスキャン（workspace → managed → bundled）
    ↓
HOOK.md ファイルを解析
    ↓
適格性をチェック（bins、env、config、os）
    ↓
適格なフックからハンドラーをロード
    ↓
イベントのハンドラーを登録

イベントフロー

ユーザーが /new を送信
    ↓
コマンド検証
    ↓
フックイベントを作成
    ↓
フックをトリガー（すべての登録済みハンドラー）
    ↓
コマンド処理が続行
    ↓
セッションリセット

トラブルシューティング

フックが検出されない

  1. ディレクトリ構造を確認：

    ls -la ~/.openclaw/hooks/my-hook/
# 表示されるはず：HOOK.md、handler.ts

  2. HOOK.md フォーマットを確認：

    cat ~/.openclaw/hooks/my-hook/HOOK.md
# name と metadata を含む YAML frontmatter が必要

  3. 検出されたすべてのフックをリスト：

    openclaw hooks list

フックが適格でない

要件を確認：

openclaw hooks info my-hook

不足しているものを探す：

  • バイナリ（PATH を確認）
  • 環境変数
  • 設定値
  • OS 互換性

フックが実行されない

  1. フックが有効になっていることを確認：

    openclaw hooks list
# 有効なフックの横に ✓ が表示されるはず

  2. gateway プロセスを再起動して、フックが再ロードされるようにします。

  3. gateway ログでエラーを確認：

    ./scripts/clawlog.sh | grep hook

ハンドラーエラー

TypeScript/インポートエラーを確認：

# インポートを直接テスト
node -e "import('./path/to/handler.ts').then(console.log)"

移行ガイド

レガシー設定から検出へ

以前：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "handlers": [
        {
          "event": "command:new",
          "module": "./hooks/handlers/my-handler.ts"
        }
      ]
    }
  }
}

以後：

  1. フックディレクトリを作成：

    mkdir -p ~/.openclaw/hooks/my-hook
mv ./hooks/handlers/my-handler.ts ~/.openclaw/hooks/my-hook/handler.ts

  2. HOOK.md を作成：

    ---
name: my-hook
description: "マイカスタムフック"
metadata: {"openclaw":{"emoji":"🎯","events":["command:new"]}}
---

# My Hook

便利なことをします。

  3. 設定を更新：

    {
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": { "enabled": true }
      }
    }
  }
}

  4. 確認して gateway プロセスを再起動：

    openclaw hooks list
# 表示されるはず：🎯 my-hook ✓

移行の利点：

  • 自動検出
  • CLI 管理
  • 適格性チェック
  • より良いドキュメント
  • 一貫した構造

関連項目

← ドキュメントに戻る