OpenClaw Hooks: 完全な開発者ガイド (2026)

OpenClaw フック検出の仕組み

ゲートウェイが使用するのは、 自動ディレクトリスキャン フックを発見するために。起動時に、設定されたフック ディレクトリをスキャンし、見つかった有効なフック パッケージをロードします。

フックが有効になる前に、次の 2 つの重要な前提条件があります。

1. Hooks は次のとおりである必要があります 明示的に有効化 — フック ディレクトリだけでは十分ではありません
2. 少なくとも 1 つのフック エントリを設定する必要があります ゲートウェイ設定で

各フック パッケージには、次の 2 つのファイルが必要です。

• HOOK.md — フックの名前、バージョン、説明、ライフサイクル イベントのサブスクリプション、および必要な権限を宣言するメタデータ ファイル
• handler.ts (または handler.js) — イベントの発生時に実行される実際のロジックを含む実装ファイル

すべての開発者が知っておくべき 4 つのライフサイクル イベント

PreToolUse は最も強力です。それができる唯一のイベントです。 アボート 実行前のツール呼び出し。 PreToolUse 中にフックが拒否シグナルを返した場合、エージェントはツールを呼び出すことはありません。

PostToolUse 自動化の主力製品です。ファイルが書き込まれましたか?リンターを実行します。テストが変更されましたか?スイートを実行します。コードがコミットされましたか?ビルドをトリガーします。

ステップ別: 最初のカスタム フックを最初から作成する

ほとんどのドキュメントにはコマンドが記載されています。これにより、何もない状態から機能するフックまでの完全なパスが表示されます。

Step 1 — フック ディレクトリを作成する

mkdir -p .openclaw/hooks/auto-lint

ステップ 2 — HOOK.md メタデータを書き込む

# auto-lint

**Version:** 1.0.0
**Event:** PostToolUse
**Description:** Runs ESLint on any file written by the agent
**Tools:** write_file, edit_file

Tools フィールドは、フックの範囲を特定のツール呼び出しに設定します。それがないとフックが発火します 毎 PostToolUse イベント — 通常、必要なものではありません。

ステップ 3 — handler.ts を実装する

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const filePath = event.toolResult?.path;
  if (!filePath) return;

  try {
    execSync(`npx eslint --fix "${filePath}"`, { stdio: "inherit" });
  } catch (err) {
    console.error(`[auto-lint] ESLint failed on ${filePath}`);
  }
}

ステップ 4 — CLI 経由で有効にする

openclaw hooks enable auto-lint

Step 5 — ロードされたことを確認する

openclaw hooks list

auto-lint とステータス enabled が表示されるはずです。セッションを開始し、ファイルを書き込み、リンターが起動するのを観察します。

フック ハンドラーの JavaScript と TypeScript — 2026 年に何を選択するか

SDK には完全な TypeScript タイピングが同梱されており、2026 年の SDK リリースでは、 TypeScript が推奨されるデフォルトです 新しいフック用。

バージョン管理にコミットするか、チームと共有するフックを作成している場合は、TypeScript を使用してください。使い捨てのローカル ガードレールの場合は、プレーンな JavaScript で問題ありません。handler.js という名前を付けて、コンパイル手順をスキップするだけです。

OpenClaw フック CLI リファレンス

フック パックの管理 — インストール、更新、および --dry-run ワークフロー

フック パックは、複数の関連フックを 1 つのインストール可能なユニットとしてバンドルします。インストール ワークフローでは、 整合性ハッシュ ディスクに何かを書き込む前に。

# Preview what would be installed without committing
openclaw hooks install productivity-pack --dry-run

# Install non-interactively (for CI environments)
openclaw hooks install productivity-pack --yes

# Update all installed packs
openclaw hooks update --all

バンドルされたフックのリファレンス: OpenClaw に同梱されるもの

openclaw hooks inspect session-memory を実行して、その完全な構成オプションを確認します。ほとんどのバンドルされたフックは適切なデフォルトで出荷されますが、カスタマイズのために設定フィールドが公開されています。

実際のフックの使用例 (実例付き)

1. ファイル保護ガードレール (PreToolUse)

エージェントが .env ファイルに触れないようにします。

import { PreToolUseEvent } from "@openclaw/sdk";

export default function handler(event: PreToolUseEvent) {
  const target = event.toolInput?.path ?? "";
  if (target.includes(".env")) {
    return { abort: true, reason: "Modification of .env files is blocked by policy." };
  }
}

これを write_file と edit_file にスコープ設定された PreToolUse をサブスクライブする、一致する HOOK.md とともに .openclaw/hooks/protect-env/ にドロップします。エージェントはそのコンテキストで拒否理由を受け取り、再試行しません。

2. Slack セッション停止通知

import { StopEvent } from "@openclaw/sdk";

export default async function handler(event: StopEvent) {
  await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      text: `OpenClaw session ended. Files modified: ${event.session.filesModified ?? 0}`
    })
  });
}

このフックを Stop イベントにサブスクライブします。セッションが終了するたびに、概要を含む Slack メッセージが発行されます。外部サーバーは必要ありません。ゲートウェイ プロセスがアウトバウンド リクエストを直接作成します。

3. PostToolUse での自動フォーマット + テスト

import { PostToolUseEvent } from "@openclaw/sdk";
import { execSync } from "child_process";

export default function handler(event: PostToolUseEvent) {
  const file = event.toolResult?.path;
  if (!file?.endsWith(".ts")) return;

  execSync(`prettier --write "${file}"`);
  execSync("npm test -- --passWithNoTests", { stdio: "inherit" });
}

これは、TypeScript ファイルが書き込まれるたびに起動され、ファイルがフォーマットされてから、テスト スイートが実行されます。大規模なプロジェクトでは時間がかかります。HOOK.md の Tools フィールドを使用してスコープを厳密に設定します。

チーム向け Hooks — 共有プロジェクト全体にガードレールを適用する

.openclaw/hooks/ ディレクトリをバージョン管理にコミットします。リポジトリのクローンを作成するすべての開発者は、自動的に同じフック構成を持ちます。

• プロジェクト構成で重要なフックを enabled にロックする — チームメイトが誤ってファイルガードを無効にすることを防ぎます
• HOOK.md の説明を使用して意図を文書化する — コードコメントのように扱い、チームメイトが読みます
• Scope hooks to tool-level granularity — 広いフックによりすべてのエージェントの対話が遅くなり、チームメイトがエージェントを無効にする摩擦が生じます
• モノリポジトリでは、親ディレクトリ内のフックは、サブディレクトリ レベルでオーバーライドされない限り、ネストされたすべてのプロジェクトに適用されます。

CI/CD 統合 — OpenClaw フックを非対話的に実行する

GitHub アクションまたはその他のヘッドレス環境では、対話型の確認プロンプトによってパイプラインがハングします。 --yes を使用してスキップします。

- name: Install hooks non-interactively
  run: openclaw hooks install qa-pack --yes

- name: Run OpenClaw session
  env:
    OPENCLAW_HOOKS_ENABLED: "true"
    SLACK_WEBHOOK_URL: secrets.SLACK_WEBHOOK_URL
  run: openclaw run --task "audit dependencies" --yes

Hook Security: 実行されるもの、アクセスできるもの、安全を保つ方法

これは、ほとんどのドキュメントで完全に省略されている部分です。また、コミュニティ フック パックをインストールする場合は、最も重要なセクションです。

アクセスできるフック: フック スクリプトは ゲートウェイプロセスの完全な権限。ゲートウェイがユーザー アカウントとして実行されている場合、フックは、そのアカウントが読み取ることができる任意のファイルを読み取り、ネットワーク リクエストを実行し、サブプロセスを実行し、シークレットを含む環境変数にアクセスできます。

フックパック監査チェックリスト

サードパーティのパックをインストールする前に、これを実行してください。

openclaw hooks inspect コマンドは、インストールされているフックの完全なソース パスを表示します。これを使用して、更新後にハンドラー コードを再確認します。

OpenClaw フックのトラブルシューティング - フックが起動しない場合

よくある質問

最終的な考察 — ワークフローに適したフック戦略の選択

本当の問題を解決する 1 つのフック、つまりファイル ガードまたは書き込み後のリンターから始めます。さらに階層化する前に、エンドツーエンドで機能するようにしてください。フックの力は複合的です。スコープが適切に設定された 3 つのフックがスムーズに実行されるセッションは、スコープが不十分で信頼できない 10 個のフックが含まれるセッションよりも信頼性が大幅に高くなります。