OpenClaw Hooks活用ガイド：イベント駆動で自動化を実装する

開発中に「特定のイベントが発生したタイミングで自動的に処理を実行したい」と考えたことはありませんか？手動での操作を繰り返すのは手間ですし、ミスも起きやすくなります。そんな時に役立つのが OpenClaw の Hooks 機能です。

OpenClaw の Hooks を活用すれば、Gateway 内で発生するイベントをトリガーにして、カスタムスクリプトを自動実行できます。これにより、ワークフローの自動化や機能拡張がスムーズに行えるようになります。

快速開始

まずは、現在利用可能な Hooks を確認し、必要なものを有効化してみましょう。

1. 利用可能な Hooks を一覧表示します。

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

2. 特定の Hook を有効化します。

   # Enable a hook
   openclaw hooks enable session-memory

3. Hook の状態を確認します。

   # Check hook status
   openclaw hooks check

4. 詳細情報を取得します。

   # Get detailed information
   openclaw hooks info session-memory

事件類型

Gateway 内で発生するさまざまなイベントに対して、Hooks をフックさせることが可能です。

Event	When it fires
command:new	/new command issued
command:reset	/reset command issued
command:stop	/stop command issued
command	Any command event (general listener)
session:compact:before	Before compaction summarizes history
session:compact:after	After compaction completes
session:patch	When session properties are modified
agent:bootstrap	Before workspace bootstrap files are injected
gateway:startup	After channels start and hooks are loaded
message:received	Inbound message from any channel
message:transcribed	After audio transcription completes
message:preprocessed	After all media and link understanding completes
message:sent	Outbound message delivered

撰寫 Hooks

独自の Hook を作成するには、ディレクトリ内にメタデータファイルと実装ファイルを用意します。

Hook 結構

各 Hook は以下の2つのファイルを含むディレクトリで構成されます。

my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

HOOK.md 格式

---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.

Handler 實作

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

  console.log(`[my-hook] New command triggered`);
  // Your logic here

  // Optionally send message to user
  event.messages.push("Hook executed!");
};

export default handler;

Hook 探索

Hooks は以下のディレクトリから優先順位に従って読み込まれます。

1. Bundled hooks: OpenClaw に同梱されているもの
2. Plugin hooks: インストールされたプラグインに含まれるもの
3. Managed hooks: ~/.openclaw/hooks/ (ユーザーインストール済み)
4. Workspace hooks: <workspace>/hooks/ (エージェントごとの設定)

Hook 套件

Hook パックは、package.json の openclaw.hooks でエクスポートされる npm パッケージです。以下のコマンドでインストールします。

openclaw plugins install <path-or-spec>

捆綁的 Hooks

OpenClaw には最初から便利な Hooks がいくつか同梱されています。

Hook	Events	What it does
session-memory	command:new, command:reset	Saves session context to <workspace>/memory/
bootstrap-extra-files	agent:bootstrap	Injects additional bootstrap files from glob patterns
command-logger	command	Logs all commands to ~/.openclaw/logs/commands.log
boot-md	gateway:startup	Runs BOOT.md when the gateway starts

session-memory 詳細

直近のメッセージを要約し、ファイルとして保存します。workspace.dir の設定が必要です。

bootstrap-extra-files 設定

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

command-logger 詳細

すべてのスラッシュコマンドを ~/.openclaw/logs/commands.log に記録します。

boot-md 詳細

Gateway 起動時にアクティブなワークスペースの BOOT.md を実行します。

插件 Hooks

プラグインは Plugin SDK を通じて、より深いレベルで Hooks を登録できます。ツール呼び出しのインターセプトやプロンプトの変更など、28種類以上の Hooks が利用可能です。詳細は Plugin Architecture を参照してください。

設定

JSON 形式で Hooks の有効・無効や環境変数を細かく制御できます。

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

各 Hook ごとの環境変数設定：

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

追加の Hook ディレクトリ指定：

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

CLI 參考

コマンドラインから Hooks を管理するための主要なコマンドです。

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

最佳實踐

効率的で安定した Hooks を作成するために、以下の点に注意してください。

1. 処理を高速に保つ: 重い処理はバックグラウンドで実行するようにしてください。
2. エラーハンドリング: try/catch を使用し、他のハンドラーに影響を与えないようにします。
3. 早期フィルタリング: 不要なイベントは即座に return します。
4. 具体的なイベントキーの指定: パフォーマンス向上のため、可能な限り具体的なイベントを指定してください。

疑難排解

Hook が動作しない場合は、以下の手順で確認を行ってください。

Hook が検出されない場合

# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw hooks list

Hook が利用不可の場合

openclaw hooks info my-hook

Hook が実行されない場合

1. Hook が有効になっているか確認します：openclaw hooks list
2. Gateway プロセスを再起動して再読み込みさせます。
3. ログを確認します：./scripts/clawlog.sh | grep hook

相關文檔

• CLI Reference: hooks
• Webhooks
• Plugin Architecture
• Configuration

さらなるサポートが必要な場合は、AI Setup Assistant をご利用ください。

openclaw hooks enable <hook-name>