openclaw hooks

管理 agent hooks（針對 /new、/reset 及 Gateway 啟動等指令的事件驅動自動化）。

相關資源：

• Hooks：Hooks
• 外掛程式 hooks：Plugins

列出所有 Hooks

openclaw hooks list

列出從工作區、受管理及內建目錄中探索到的所有 hooks。

選項：

• --eligible：只顯示合格的 hooks（已滿足需求條件）
• --json：以 JSON 輸出
• -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 command is issued

範例（詳細模式）：

openclaw hooks list --verbose

顯示不合格 hooks 缺少的需求條件。

範例（JSON）：

openclaw hooks list --json

回傳結構化 JSON 供程式使用。

取得 Hook 資訊

openclaw hooks info <name>

顯示特定 hook 的詳細資訊。

參數：

• <name>：Hook 名稱（例如 session-memory）

選項：

• --json：以 JSON 輸出

範例：

openclaw hooks info session-memory

輸出：

💾 session-memory ✓ Ready

Save session context to memory when /new 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

Requirements:
  Config: ✓ workspace.dir

檢查 Hooks 合格性

openclaw hooks check

顯示 hook 合格性狀態摘要（就緒與未就緒的數量）。

選項：

• --json：以 JSON 輸出

輸出範例：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

啟用 Hook

openclaw hooks enable <name>

透過將 hook 加入設定（~/.openclaw/config.json）來啟用特定 hook。

注意： 由外掛程式管理的 hooks 在 openclaw hooks list 中顯示為 plugin:<id>，無法在此啟用/停用。請改為啟用/停用該外掛程式。

參數：

• <name>：Hook 名稱（例如 session-memory）

範例：

openclaw hooks enable session-memory

輸出：

✓ Enabled hook: 💾 session-memory

執行內容：

• 檢查 hook 是否存在且合格
• 在設定中更新 hooks.internal.entries.<name>.enabled = true
• 將設定儲存至磁碟

啟用後：

• 重新啟動 Gateway 以重新載入 hooks（macOS 上重啟選單列 app，或重啟開發中的 Gateway 處理程序）。

停用 Hook

openclaw hooks disable <name>

透過更新設定來停用特定 hook。

參數：

• <name>：Hook 名稱（例如 command-logger）

範例：

openclaw hooks disable command-logger

輸出：

⏸ Disabled hook: 📝 command-logger

停用後：

• 重新啟動 Gateway 以重新載入 hooks

安裝 Hooks

openclaw hooks install <path-or-spec>
openclaw hooks install <npm-spec> --pin

從本地資料夾/封存檔或 npm 安裝 hook pack。

npm spec 僅限註冊表（套件名稱 + 選用的精確版本或 dist-tag）。Git/URL/檔案 spec 和 semver 範圍會被拒絕。依賴安裝會使用 --ignore-scripts 以確保安全。

無修飾的 spec 和 @latest 會追蹤穩定軌道。如果 npm 將其解析為預發布版本，OpenClaw 會停止並要求你以預發布 tag（如 @beta/@rc）或精確的預發布版本明確選擇加入。

執行內容：

• 將 hook pack 複製至 ~/.openclaw/hooks/<id>
• 在 hooks.internal.entries.* 中啟用已安裝的 hooks
• 在 hooks.internal.installs 中記錄安裝

選項：

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

支援的封存格式： .zip、.tgz、.tar.gz、.tar

範例：

# 本地目錄
openclaw hooks install ./my-hook-pack

# 本地封存檔
openclaw hooks install ./my-hook-pack.zip

# NPM 套件
openclaw hooks install @openclaw/my-hook-pack

# 連結本地目錄而不複製
openclaw hooks install -l ./my-hook-pack

更新 Hooks

openclaw hooks update <id>
openclaw hooks update --all

更新已安裝的 hook pack（僅限 npm 安裝）。

選項：

• --all：更新所有已追蹤的 hook pack
• --dry-run：顯示會有哪些變更但不實際寫入

當存在已儲存的完整性雜湊且擷取的成品雜湊不同時，OpenClaw 會列印警告並要求確認。在 CI/非互動式執行中使用全域 --yes 可跳過提示。

內建 Hooks

session-memory

當你發出 /new 時，將工作階段上下文儲存至記憶體。

啟用：

openclaw hooks enable session-memory

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

參閱： session-memory 文件

bootstrap-extra-files

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

啟用：

openclaw hooks enable bootstrap-extra-files

參閱： bootstrap-extra-files 文件

command-logger

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

啟用：

openclaw hooks enable command-logger

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

查看日誌：

# 最近的指令
tail -n 20 ~/.openclaw/logs/commands.log

# 格式化輸出
cat ~/.openclaw/logs/commands.log | jq .

# 依動作篩選
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

參閱： command-logger 文件

boot-md

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

事件： gateway:startup

啟用：

openclaw hooks enable boot-md

參閱： boot-md 文件