OpenClaw Hooks：完整開發人員指南 (2026)

OpenClaw Hook Discovery 的工作原理

網關使用 自動目錄掃描 發現鉤子。啟動時，它會掃描配置的鉤子目錄並加載它找到的任何有效的鉤子包。

在激活鉤子之前有兩個重要的先決條件：

1. Hooks 必須是 明確啟用 — 僅一個鉤子目錄是不夠的
2. 至少 必須配置一個鉤子條目 在您的網關設定中

每個鉤子包只需要兩個檔案：

• HOOK.md — 元資料文件，聲明鉤子的名稱、版本、描述、生命週期事件訂閱以及任何所需的權限
• handler.ts （或 handler.js） — 包含事件觸發時執行的實際邏輯的實作文件

每個開發人員都應該了解的四個生命週期事件

PreToolUse 是最強大的——這是唯一可以做到的事件 中止 执行之前的工具调用。如果您的掛鉤在 PreToolUse 期間傳回拒絕訊號，則代理程式永遠不會呼叫該工具。

PostToolUse 是自動化的主力。文件寫好了嗎？運行你的 linter。測試修改了？執行套件。代碼已提交？觸發建置。

步驟：從頭開始編寫您的第一個自訂 Hook

大多數文件都會向您顯示命令。這向您展示了從無到有的完整路徑。

步驟 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

第 5 步 — 驗證其已載入

OpenClaw hooks list

您應該會看到 auto-lint 的狀態為 enabled。啟動一個會話，寫入一個文件，然後觀察 linter 的觸發。

用於 Hook 處理程序的 JavaScript 與 TypeScript — 2026 年選擇什麼

該 SDK 附帶完整的 TypeScript 類型，從 2026 SDK 版本開始， TypeScript 是建議的預設值 用於新鉤子。

如果您正在編寫一個鉤子，您將致力於版本控製或與團隊共享，請使用 TypeScript。對於一次性的本地護欄，普通的 JavaScript 就可以了——只需將其命名為 handler.js 並跳過編譯步驟。

OpenClaw Hooks CLI 參考

管理 Hook Pack — 安裝、更新和 --dry-run 工作流程

Hook 套件將多個相關的 hook 捆綁為一個可安裝單元。安裝工作流程驗證 完整性哈希 在將任何內容寫入磁碟之前。

# 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

捆綁 Hook 參考：OpenClaw 附帶什麼

執行 OpenClaw hooks inspect session-memory 以查看其完整設定選項。大多數捆綁的鉤子都附帶合理的預設值，但會公開配置欄位以進行自訂。

真實世界的 Hook 用例（帶有工作範例）

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." };
  }
}

將其放入 .OpenClaw/hooks/protect-env/ 中，並與訂閱 PreToolUse 的匹配 HOOK.md 範圍為 write_file 和 edit_file。代理在其上下文中收到拒絕原因，並且不會重試。

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 欄位嚴格限制其範圍。

Teams 的掛鉤 — 在共享專案中實作護欄

將 .OpenClaw/hooks/ 目錄提交給版本控制。每個自動克隆存儲庫的開發人員都具有相同的鉤子配置。

• 將關鍵掛鉤鎖定到專案配置中的 enabled — 防止隊友意外禁用文件防護
• 使用 HOOK.md 描述來記錄意圖 — 將它們視為代碼註釋，隊友會閱讀它們
• Scope hooks to tool-level granularity - 寬鉤會減慢所有代理交互，產生摩擦，導致隊友禁用它們
• 在 monorepos 中，父目錄中的鉤子適用於所有巢狀項目，除非在子目錄層級覆蓋

CI/CD 整合 — 以非互動方式運行 OpenClaw Hooks

在 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 安全性：運行的內容、可存取的內容以及如何保持安全

這是大多數文件完全跳過的部分 - 如果您要安裝社區掛鉤包，這是最重要的部分。

哪些鉤子可以使用： Hook 腳本繼承 Gateway進程的全部權限。如果網關以您的使用者帳戶運行，您的掛鉤可以讀取該帳戶可以讀取的任何檔案、發出網路請求、執行子進程以及存取包括機密在內的環境變數。

鉤包審核清單

在安裝任何第三方包之前請執行此操作：

OpenClaw hooks inspect 指令顯示已安裝掛鉤的完整來源路徑 - 使用它在更新後重新檢視處理程序程式碼。

OpenClaw 鉤子不觸發時的故障排除

常見問題

最後的想法 - 為您的工作流程選擇正確的 Hook 策略

從解決真正難題的一個鉤子開始——文件保護或寫入後的 linter。在分層之前先讓它端到端地工作。鉤子的力量是複合的：具有三個範圍良好的鉤子的會話平穩運行比具有十個您不信任的範圍較小的鉤子的會話要可靠得多。