Skip to main content

Hooks

Hooks 提供一個可擴充的事件驅動系統,用於自動化 Agent 指令和事件的回應動作。Hooks 從目錄自動探索,並可透過 CLI 指令管理,類似於 OpenClaw 中技能的運作方式。

入門導引

Hooks 是當某件事發生時執行的小腳本。有兩種類型:
  • Hooks(本頁):當 Agent 事件觸發時在 Gateway 內部執行,例如 /new/reset/stop 或生命週期事件。
  • Webhooks:外部 HTTP webhooks,讓其他系統觸發 OpenClaw 中的工作。見 Webhook Hooks 或使用 openclaw webhooks 取得 Gmail 輔助指令。
Hooks 也可以打包在插件中;見 插件 常見用途:
  • 重置會話時儲存記憶快照
  • 保持指令稽核軌跡以供疑難排解或合規
  • 會話開始或結束時觸發後續自動化
  • 在事件觸發時將檔案寫入 Agent 工作區或呼叫外部 API
只要能寫一個小型 TypeScript 函式,就能寫一個 Hook。Hooks 自動探索,並透過 CLI 啟用或停用。

概述

Hooks 系統讓您可以:
  • 發出 /new 時將會話上下文儲存到記憶
  • 記錄所有指令以供稽核
  • 在 Agent 生命週期事件上觸發自訂自動化
  • 無需修改核心程式碼即可擴充 OpenClaw 的行為

快速開始

內建 Hooks

OpenClaw 隨附四個自動探索的內建 Hooks:
  • 💾 session-memory:在您發出 /new 時將會話上下文儲存到 Agent 工作區(預設 ~/.openclaw/workspace/memory/
  • 📎 bootstrap-extra-files:在 agent:bootstrap 期間從已設定的 glob/路徑模式注入額外的工作區 bootstrap 檔案
  • 📝 command-logger:將所有指令事件記錄到 ~/.openclaw/logs/commands.log
  • 🚀 boot-md:Gateway 啟動時執行 BOOT.md(需要啟用內部 hooks)
列出可用 hooks:
啟用 hook:
查看 hook 狀態:
取得詳細資訊:

引導設定

在引導設定(openclaw onboard)期間,系統會提示您啟用建議的 hooks。精靈自動探索符合條件的 hooks 並呈現供選擇。

Hook 探索

Hooks 自動從三個目錄探索(優先順序由高到低):
  1. 工作區 hooks<workspace>/hooks/(每 Agent,最高優先順序)
  2. 受管理 hooks~/.openclaw/hooks/(使用者安裝,跨工作區共用)
  3. 內建 hooks<openclaw>/dist/hooks/bundled/(隨 OpenClaw 附帶)
受管理的 hook 目錄可以是單一 hookhook 套件(套件目錄)。 每個 hook 是一個包含以下內容的目錄:

Hook 套件(npm/封存檔)

Hook 套件是標準 npm 套件,透過 package.json 中的 openclaw.hooks 匯出一或多個 hooks。使用以下方式安裝:
Npm 規格僅限於登錄(套件名稱 + 選填的精確版本或 dist-tag)。 Git/URL/file 規格和 semver 範圍會被拒絕。 裸規格和 @latest 保持在穩定軌道上。若 npm 解析其中之一為預發佈版, OpenClaw 會停止並要求您明確選擇加入,例如使用 @beta/@rc 或精確的預發佈版本。 範例 package.json
每個項目指向包含 HOOK.mdhandler.ts(或 index.ts)的 hook 目錄。 Hook 套件可附帶依賴項;它們將安裝在 ~/.openclaw/hooks/<id> 下。 每個 openclaw.hooks 項目在符號連結解析後必須保持在套件目錄內;超出範圍的項目會被拒絕。 安全注意事項:openclaw hooks install 使用 npm install --ignore-scripts 安裝依賴項 (無生命週期腳本)。保持 hook 套件依賴樹為「純 JS/TS」,避免依賴 postinstall 建置的套件。

Hook 結構

HOOK.md 格式

HOOK.md 檔案在 YAML frontmatter 中包含元資料,加上 Markdown 文件:

元資料欄位

metadata.openclaw 物件支援:
  • emoji:CLI 顯示表情符號(例如 "💾"
  • events:要監聽的事件陣列(例如 ["command:new", "command:reset"]
  • export:要使用的具名匯出(預設為 "default"
  • homepage:文件 URL
  • requires:選填需求
    • bins:PATH 上所需的執行檔(例如 ["git", "node"]
    • anyBins:至少一個這些執行檔必須存在
    • env:所需的環境變數
    • config:所需的設定路徑(例如 ["workspace.dir"]
    • os:所需的平台(例如 ["darwin", "linux"]
  • always:繞過資格檢查(布林值)
  • install:安裝方法(對內建 hooks:[{"id":"bundled","kind":"bundled"}]

處理器實作

handler.ts 檔案匯出一個 HookHandler 函式:

事件上下文

每個事件包含:

事件類型

指令事件

Agent 指令發出時觸發:
  • command:所有指令事件(通用監聽器)
  • command:new:發出 /new 指令時
  • command:reset:發出 /reset 指令時
  • command:stop:發出 /stop 指令時

會話事件

  • session:compact:before:壓縮摘要歷史記錄之前
  • session:compact:after:壓縮完成後,含摘要元資料
內部 hook 酬載以 type: "session" 搭配 action: "compact:before" / action: "compact:after" 發出;監聽器使用上述組合鍵訂閱。 特定處理器註冊使用字面鍵格式 ${type}:${action}。對這些事件,註冊 session:compact:beforesession:compact:after

Agent 事件

  • agent:bootstrap:工作區 bootstrap 檔案注入之前(hooks 可修改 context.bootstrapFiles

Gateway 事件

Gateway 啟動時觸發:
  • gateway:startup:頻道啟動且 hooks 載入後

訊息事件

訊息接收或傳送時觸發:
  • message:所有訊息事件(通用監聽器)
  • message:received:從任何頻道收到入站訊息時。在處理早期觸發,媒體解析前。內容可能包含尚未處理的媒體附件原始佔位符,例如 <media:audio>
  • message:transcribed:訊息已完全處理(包括音訊轉錄和連結解析)時。此時 transcript 包含音訊訊息的完整逐字稿文字。需要存取轉錄音訊內容時使用此 hook。
  • message:preprocessed:所有媒體 + 連結解析完成後對每則訊息觸發,讓 hooks 在 Agent 看到之前存取完整豐富化的內容(逐字稿、圖片說明、連結摘要)。
  • message:sent:出站訊息成功傳送時

訊息事件上下文

訊息事件包含豐富的訊息上下文:

範例:訊息記錄器 Hook

工具結果 Hooks(插件 API)

這些 hooks 不是事件串流監聽器;它們讓插件在 OpenClaw 持久化之前同步調整工具結果。
  • tool_result_persist:在工具結果寫入會話逐字稿之前轉換它們。必須同步;回傳更新後的工具結果酬載,或 undefined 以保持原樣。見 Agent 迴圈

插件 Hook 事件

透過插件 hook 執行器公開的壓縮生命週期 hooks:
  • before_compaction:壓縮前執行,含計數/Token 元資料
  • after_compaction:壓縮後執行,含壓縮摘要元資料

未來事件

計劃中的事件類型:
  • session:start:新會話開始時
  • session:end:會話結束時
  • agent:error:Agent 遇到錯誤時

建立自訂 Hooks

1. 選擇位置

  • 工作區 hooks<workspace>/hooks/):每 Agent,最高優先順序
  • 受管理 hooks~/.openclaw/hooks/):跨工作區共用

2. 建立目錄結構

3. 建立 HOOK.md

4. 建立 handler.ts

5. 啟用並測試

設定

新設定格式(建議)

每個 Hook 的設定

Hooks 可以有自訂設定:

額外目錄

從額外目錄載入 hooks:

舊版設定格式(仍受支援)

舊版設定格式仍可向後相容使用:
注意:module 必須是工作區相對路徑。拒絕絕對路徑和工作區外的路徑穿越。 遷移:新 hooks 使用新的探索機制。舊版處理器在目錄式 hooks 之後載入。

CLI 指令

列出 Hooks

Hook 資訊

檢查資格

啟用/停用

內建 Hook 參考

session-memory

在您發出 /new 時將會話上下文儲存到記憶。 事件command:new 需求:必須設定 workspace.dir 輸出<workspace>/memory/YYYY-MM-DD-slug.md(預設 ~/.openclaw/workspace 功能說明
  1. 使用重置前的會話記錄找到正確的逐字稿
  2. 擷取最後 15 行對話
  3. 使用 LLM 生成描述性的檔案名稱 slug
  4. 將會話元資料儲存到有日期的記憶檔案
輸出範例
檔案名稱範例
  • 2026-01-16-vendor-pitch.md
  • 2026-01-16-api-design.md
  • 2026-01-16-1430.md(slug 生成失敗時的回退時間戳記)
啟用

bootstrap-extra-files

agent:bootstrap 期間注入額外的 bootstrap 檔案(例如 monorepo 本地的 AGENTS.md / TOOLS.md)。 事件agent:bootstrap 需求:必須設定 workspace.dir 輸出:不寫入任何檔案;bootstrap 上下文僅在記憶體中修改。 設定
注意事項
  • 路徑相對於工作區解析。
  • 檔案必須保持在工作區內(realpath 檢查)。
  • 只載入已識別的 bootstrap 基礎名稱。
  • 子 Agent 允許清單被保留(僅 AGENTS.mdTOOLS.md)。
啟用

command-logger

將所有指令事件記錄到集中式稽核檔案。 事件command 需求:無 輸出~/.openclaw/logs/commands.log 功能說明
  1. 擷取事件詳情(指令動作、時間戳記、會話金鑰、傳送者 ID、來源)
  2. 以 JSONL 格式追加到日誌檔案
  3. 在背景靜默執行
範例日誌記錄
查看日誌
啟用

boot-md

Gateway 啟動時(頻道啟動後)執行 BOOT.md。 必須啟用內部 hooks 才能執行。 事件gateway:startup 需求:必須設定 workspace.dir 功能說明
  1. 從您的工作區讀取 BOOT.md
  2. 透過 agent runner 執行其中的指示
  3. 透過訊息工具傳送任何請求的出站訊息
啟用

最佳實踐

保持處理器快速

Hooks 在指令處理期間執行。保持輕量:

優雅地處理錯誤

始終包裝有風險的操作:

盡早篩選事件

若事件不相關則提早回傳:

使用特定的事件鍵

盡可能在元資料中指定精確的事件:
而非:

偵錯

啟用 Hook 記錄

Gateway 在啟動時記錄 hook 載入:

檢查探索

列出所有已探索的 hooks:

檢查註冊

在您的處理器中,記錄它被呼叫的時機:

確認資格

確認 hook 不符合資格的原因:
查看輸出中缺少的需求。

測試

Gateway 日誌

監控 gateway 日誌查看 hook 執行情況:

直接測試 Hooks

在隔離環境中測試您的處理器:

架構

核心元件

  • 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 啟動時載入 hooks
  • src/auto-reply/reply/commands-core.ts:觸發指令事件

探索流程

事件流程

疑難排解

Hook 未被探索

  1. 確認目錄結構:
  2. 確認 HOOK.md 格式:
  3. 列出所有已探索的 hooks:

Hook 不符合資格

檢查需求:
查看缺少的:
  • 執行檔(確認 PATH)
  • 環境變數
  • 設定值
  • 作業系統相容性

Hook 未執行

  1. 確認 hook 已啟用:
  2. 重啟您的 gateway 程序以重新載入 hooks。
  3. 查看 gateway 日誌中的錯誤:

處理器錯誤

確認 TypeScript/import 錯誤:

遷移指南

從舊版設定遷移到探索機制

之前
之後
  1. 建立 hook 目錄:
  2. 建立 HOOK.md:
  3. 更新設定:
  4. 確認並重啟您的 gateway 程序:
遷移的優點
  • 自動探索
  • CLI 管理
  • 資格檢查
  • 更好的文件
  • 一致的結構

參見