OpenClaw Hooks 指南：管理自動化事件與指令觸發機制

身為開發者，我們經常會遇到需要處理重複性任務或是想在特定事件觸發時自動執行邏輯的困擾。手動管理這些自動化流程不僅耗時，還容易因為配置分散而導致維護困難，這時候你需要一套更聰明的解決方案。

透過 OpenClaw 的 hook 管理功能，你可以輕鬆處理 agent 的事件驅動自動化，無論是 /new、/reset 指令還是 Gateway 啟動時的自動化任務，都能透過簡單的指令完成。

列出所有 Hooks

你可以透過這個指令查看目前工作區、受管理目錄以及內建目錄中所有被發現的 hooks。請注意，除非至少設定了一個內部 hook，否則 Gateway 啟動時不會載入內部的 hook 處理器。

openclaw hooks list

選項：

1. --eligible：僅顯示符合條件的 hooks（已滿足需求）。
2. --json：以 JSON 格式輸出。
3. -v, --verbose：顯示詳細資訊，包含缺少的必要條件。

輸出範例：

Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued

範例（詳細模式）：

openclaw hooks list --verbose

範例（JSON 格式）：

openclaw hooks list --json

取得 Hook 詳細資訊

如果你想深入了解某個特定 hook 的運作方式或需求，可以使用這個指令來查看詳細內容。

openclaw hooks info <name>

參數：

1. <name>：Hook 的名稱或 key（例如 session-memory）。

選項：

1. --json：以 JSON 格式輸出。

範例：

openclaw hooks info session-memory

輸出：

💾 session-memory ✓ Ready

Save session context to memory when /new or /reset command is issued

Details:
  Source: openclaw-bundled
  Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

檢查 Hooks 適用性

這個指令能讓你快速掌握目前有多少 hooks 準備就緒，以及有多少尚未準備好。

openclaw hooks check

選項：

1. --json：以 JSON 格式輸出。

輸出範例：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

啟用 Hook

當你決定使用某個 hook 時，可以透過此指令將其加入你的設定檔（預設為 ~/.openclaw/openclaw.json）。

openclaw hooks enable <name>

注意： 工作區的 hooks 預設為停用狀態，必須在此處或設定檔中手動啟用。由插件管理的 hooks 會顯示為 plugin:<id>，這類 hooks 無法在此啟用或停用，請改為管理該插件本身。

參數：

1. <name>：Hook 的名稱（例如 session-memory）。

範例：

openclaw hooks enable session-memory

輸出：

✓ Enabled hook: 💾 session-memory

執行動作：

1. 檢查 hook 是否存在且符合條件。
2. 更新設定檔中的 hooks.internal.entries.<name>.enabled = true。
3. 將設定儲存至磁碟。

若 hook 來自 <workspace>/hooks/，在 Gateway 載入前，這個啟用步驟是必須的。

啟用後：

1. 重啟 Gateway 以重新載入 hooks（在 macOS 上重啟選單列應用程式，或在開發環境中重啟你的 Gateway 程序）。

停用 Hook

如果你不再需要某個 hook，可以透過此指令更新設定檔將其停用。

openclaw hooks disable <name>

參數：

1. <name>：Hook 的名稱（例如 command-logger）。

範例：

openclaw hooks disable command-logger

輸出：

⏸ Disabled hook: 📝 command-logger

停用後：

1. 重啟 Gateway 以重新載入 hooks。

注意事項

這裡有一些關於 hook 管理的小撇步，幫助你更有效率地使用 OpenClaw。

1. openclaw hooks list --json、info --json 以及 check --json 會直接將結構化的 JSON 寫入標準輸出（stdout）。
2. 由插件管理的 hooks 無法在此處啟用或停用；請直接啟用或停用該插件。

安裝 Hook 套件

你可以透過統一的插件安裝器來安裝 hook 套件，這讓流程變得非常一致。

openclaw plugins install <package>        # ClawHub first, then npm
openclaw plugins install <package> --pin  # pin version
openclaw plugins install <path>           # local path

openclaw hooks install 指令目前仍可作為相容性別名使用，但會顯示棄用警告並轉發至 openclaw plugins install。

npm 規格僅限於 registry（套件名稱 + 可選的精確版本或 dist-tag）。不支援 Git/URL/檔案規格及 semver 範圍。為了安全起見，相依套件安裝時會執行 --ignore-scripts。

裸規格與 @latest 會保持在穩定版本軌道。若 npm 將其解析為預發布版本，OpenClaw 會停止並要求你明確選擇，例如使用 @beta/@rc 或精確的預發布版本。

執行動作：

1. 將 hook 套件複製到 ~/.openclaw/hooks/<id>。
2. 在 hooks.internal.entries.* 中啟用已安裝的 hooks。
3. 在 hooks.internal.installs 下記錄安裝資訊。

選項：

1. -l, --link：連結本地目錄而非複製（將其加入 hooks.internal.load.extraDirs）。
2. --pin：將 npm 安裝記錄為 hooks.internal.installs 中解析出的精確 name@version。

支援的壓縮檔： .zip、.tgz、.tar.gz、.tar

範例：

# Local directory
openclaw plugins install ./my-hook-pack

# Local archive
openclaw plugins install ./my-hook-pack.zip

# NPM package
openclaw plugins install @openclaw/my-hook-pack

# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack

連結的 hook 套件會被視為由操作者設定目錄管理的 hooks，而非工作區 hooks。

更新 Hook 套件

使用統一的插件更新器來更新已追蹤的 npm hook 套件。

openclaw plugins update <id>
openclaw plugins update --all

openclaw hooks update 指令目前仍可作為相容性別名使用，但會顯示棄用警告並轉發至 openclaw plugins update。

選項：

1. --all：更新所有已追蹤的 hook 套件。
2. --dry-run：顯示變更內容而不實際寫入。

當存在儲存的完整性雜湊值（integrity hash）且獲取的構件雜湊值發生變更時，OpenClaw 會顯示警告並要求確認。在 CI 或非互動式執行環境中，可使用全域 --yes 來略過提示。

內建 Hooks

以下是 OpenClaw 內建的一些實用 hooks，你可以根據需求啟用它們。

session-memory

當你發出 /new 或 /reset 指令時，此 hook 會將對話上下文儲存至記憶體。

啟用：

openclaw hooks enable session-memory

輸出： ~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md

參考： session-memory documentation

bootstrap-extra-files

在 agent:bootstrap 期間注入額外的引導檔案（例如 monorepo 本地的 AGENTS.md / TOOLS.md）。

啟用：

openclaw hooks enable bootstrap-extra-files

參考： bootstrap-extra-files documentation

command-logger

將所有指令事件記錄到集中的審核檔案中。

啟用：

openclaw hooks enable command-logger

輸出： ~/.openclaw/logs/commands.log

檢視日誌：

# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

參考： command-logger documentation

boot-md

當 Gateway 啟動時（在頻道啟動後）執行 BOOT.md。

事件：gateway:startup

啟用：

openclaw hooks enable boot-md

參考： boot-md documentation

---

相關文件

• Hooks
• Plugin hooks

如果你在設定過程中遇到任何問題，歡迎使用 AI Setup Assistant 進行諮詢。