Hooks
Hooksは、Gateway内で何かが起きたときに実行される小さなスクリプトです。ディレクトリから自動的に検出され、openclaw hooksで確認できます。
OpenClawには2種類のhooksがあります。
- 内部hooks（このページ）:
/new、/reset、/stop、またはライフサイクルイベントのようなエージェントイベントが発生したときにGateway内で実行されます。
- Webhooks: 他のシステムがOpenClaw内で処理をトリガーできるようにする外部HTTPエンドポイントです。Webhooksを参照してください。
Hooksはplugins内に同梱することもできます。openclaw hooks listには、スタンドアロンhooksとplugin管理hooksの両方が表示されます。
クイックスタート
# 利用可能なhooksを一覧表示
openclaw hooks list
# hookを有効化
openclaw hooks enable session-memory
# hookのステータスを確認
openclaw hooks check
# 詳細情報を取得
openclaw hooks info session-memory
イベントの種類
| Event | 発火するタイミング |
|---|
command:new | /newコマンドが実行されたとき |
command:reset | /resetコマンドが実行されたとき |
command:stop | /stopコマンドが実行されたとき |
command | 任意のコマンドイベント（汎用リスナー） |
session:compact:before | compactionが履歴を要約する前 |
session:compact:after | compactionの完了後 |
session:patch | セッションのプロパティが変更されたとき |
agent:bootstrap | ワークスペースのbootstrapファイルが注入される前 |
gateway:startup | channelsが起動し、hooksが読み込まれた後 |
message:received | 任意のchannelから受信した受信メッセージ |
message:transcribed | 音声文字起こしの完了後 |
message:preprocessed | すべてのメディア処理とリンク理解の完了後 |
message:sent | 送信メッセージが配信されたとき |
hooksの作成
hookの構成
各hookは、2つのファイルを含むディレクトリです。
my-hook/
├── HOOK.md # メタデータ + ドキュメント
└── handler.ts # ハンドラー実装
HOOK.md形式
---
name: my-hook
description: "このhookが行うことの短い説明"
metadata:
{ "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---
# My Hook
詳細なドキュメントをここに記述します。
metadata.openclaw）:
| Field | 説明 |
|---|
emoji | CLIに表示する絵文字 |
events | 監視するイベントの配列 |
export | 使用する名前付きexport（デフォルトは"default"） |
os | 必要なプラットフォーム（例: ["darwin", "linux"]） |
requires | 必須のbins、anyBins、env、またはconfigパス |
always | 適格性チェックをバイパスするかどうか（boolean） |
install | インストール方法 |
ハンドラー実装
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;
type、action、sessionKey、timestamp、messages（ユーザーに送信するにはpush）、およびcontext（イベント固有のデータ）。
イベントコンテキストの主な項目
コマンドイベント（command:new、command:reset）: context.sessionEntry、context.previousSessionEntry、context.commandSource、context.workspaceDir、context.cfg。
メッセージイベント（message:received）: context.from、context.content、context.channelId、context.metadata（senderId、senderName、guildIdを含むプロバイダー固有データ）。
メッセージイベント（message:sent）: context.to、context.content、context.success、context.channelId。
メッセージイベント（message:transcribed）: context.transcript、context.from、context.channelId、context.mediaPath。
メッセージイベント（message:preprocessed）: context.bodyForAgent（最終的に拡張された本文）、context.from、context.channelId。
Bootstrapイベント（agent:bootstrap）: context.bootstrapFiles（変更可能な配列）、context.agentId。
セッションpatchイベント（session:patch）: context.sessionEntry、context.patch（変更されたフィールドのみ）、context.cfg。patchイベントをトリガーできるのは特権クライアントのみです。
Compactionイベント: session:compact:beforeにはmessageCount、tokenCountが含まれます。session:compact:afterにはさらにcompactedCount、summaryLength、tokensBefore、tokensAfterが追加されます。
hookの検出
Hooksは、上書き優先度が低い順から高い順に、次のディレクトリから検出されます。
- 同梱hooks: OpenClawに同梱されるもの
- Plugin hooks: インストール済みplugins内に同梱されるhooks
- Managed hooks:
~/.openclaw/hooks/（ユーザーがインストールし、ワークスペース間で共有されるもの）。hooks.internal.load.extraDirsの追加ディレクトリもこの優先度を共有します。
- Workspace hooks:
<workspace>/hooks/（エージェントごと。明示的に有効化するまでデフォルトでは無効）
Workspace hooksは新しいhook名を追加できますが、同じ名前の同梱、managed、またはplugin提供hookを上書きすることはできません。
hookパック
hookパックは、package.json内のopenclaw.hooksを通じてhooksを公開するnpmパッケージです。次のようにインストールします。
openclaw plugins install <path-or-spec>
同梱hooks
| Hook | Events | 動作内容 |
|---|
| session-memory | command:new, command:reset | セッションコンテキストを<workspace>/memory/に保存 |
| bootstrap-extra-files | agent:bootstrap | globパターンから追加のbootstrapファイルを注入 |
| command-logger | command | すべてのコマンドを~/.openclaw/logs/commands.logに記録 |
| boot-md | gateway:startup | gatewayの起動時にBOOT.mdを実行 |
openclaw hooks enable <hook-name>
session-memoryの詳細
直近15件のユーザー/assistantメッセージを抽出し、LLMで説明的なファイル名スラッグを生成して、<workspace>/memory/YYYY-MM-DD-slug.mdに保存します。workspace.dirが設定されている必要があります。
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、MEMORY.md）。
Plugin hooks
Pluginsは、より深い統合のためにPlugin SDKを通じてhooksを登録できます。これには、ツール呼び出しのインターセプト、プロンプトの変更、メッセージフローの制御などが含まれます。Plugin SDKは、モデル解決、エージェントライフサイクル、メッセージフロー、ツール実行、subagent協調、gatewayライフサイクルをカバーする28個のhooksを公開しています。
before_tool_call、before_agent_reply、before_install、およびその他すべてのplugin hooksを含む完全なplugin hookリファレンスについては、Plugin Architectureを参照してください。
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true },
"command-logger": { "enabled": false }
}
}
}
}
{
"hooks": {
"internal": {
"entries": {
"my-hook": {
"enabled": true,
"env": { "MY_CUSTOM_VAR": "value" }
}
}
}
}
}
{
"hooks": {
"internal": {
"load": {
"extraDirs": ["/path/to/more/hooks"]
}
}
}
}
従来のhooks.internal.handlers配列設定形式も後方互換性のため引き続きサポートされていますが、新しいhooksでは検出ベースのシステムを使用してください。
CLIリファレンス
# すべてのhooksを一覧表示（--eligible、--verbose、または--jsonを追加可能）
openclaw hooks list
# hookの詳細情報を表示
openclaw hooks info <hook-name>
# 適格性の概要を表示
openclaw hooks check
# 有効化/無効化
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>
ベストプラクティス
- ハンドラーは高速に保つ。 Hooksはコマンド処理中に実行されます。重い処理は
void processInBackground(event)でfire-and-forgetにしてください。
- エラーは適切に処理する。 危険な処理はtry/catchで囲み、他のハンドラーが実行できるようにthrowしないでください。
- 早い段階でイベントを絞り込む。 イベントのtype/actionが関係ない場合はすぐにreturnしてください。
- 具体的なイベントキーを使う。 オーバーヘッドを減らすため、
"events": ["command"]より"events": ["command:new"]を優先してください。
トラブルシューティング
hookが検出されない
# ディレクトリ構造を確認
ls -la ~/.openclaw/hooks/my-hook/
# 表示されるべきもの: HOOK.md, handler.ts
# 検出されたすべてのhooksを一覧表示
openclaw hooks list
hookが適格でない
openclaw hooks info my-hook
hookが実行されない
- hookが有効になっていることを確認します:
openclaw hooks list
- hooksが再読み込みされるようにgatewayプロセスを再起動します。
- gatewayログを確認します:
./scripts/clawlog.sh | grep hook
