鉤子

Hooks 是在 Gateway 內部發生某些事件時執行的小型指令碼。它們可以從目錄中被發現，並透過 openclaw hooks 檢查。只有在你啟用 hooks，或設定至少一個 hook 項目、hook pack、legacy handler 或額外 hook 目錄之後，Gateway 才會載入 internal hooks。

OpenClaw 中有兩種 hooks：

• Internal hooks（本頁）：當 agent 事件觸發時在 Gateway 內部執行，例如 /new、/reset、/stop 或生命週期事件。
• Webhooks：外部 HTTP 端點，讓其他系統觸發 OpenClaw 中的工作。請參閱 Webhooks。

Hooks 也可以封裝在 plugins 內。openclaw hooks list 會同時顯示獨立 hooks 和 plugin 管理的 hooks。

快速開始

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

事件類型

撰寫 hooks

Hook 結構

每個 hook 是一個包含兩個檔案的目錄：

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

HOOK.md 格式

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

Metadata 欄位（metadata.openclaw）：

Handler 實作

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send message to user  event.messages.push("Hook executed!");}; export default handler;

每個事件都包含：type、action、sessionKey、timestamp、messages（push 以傳送給使用者），以及 context（事件特定資料）。Agent 和 tool plugin hook contexts 也可以包含 trace，這是一個唯讀、相容 W3C 的診斷 trace context，plugins 可將其傳入 structured logs 以進行 OTEL 關聯。

事件 context 重點

Command events（command:new、command:reset）：context.sessionEntry、context.previousSessionEntry、context.commandSource、context.workspaceDir、context.cfg。

Message events（message:received）：context.from、context.content、context.channelId、context.metadata（provider-specific data including senderId、senderName、guildId）。context.content 會優先使用類似指令訊息中的非空 command body，接著 fallback 到原始 inbound body 和 generic body；它不包含 agent-only enrichment，例如 thread history 或 link summaries。

Message events（message:sent）：context.to、context.content、context.success、context.channelId。

Message events（message:transcribed）：context.transcript、context.from、context.channelId、context.mediaPath。

Message events（message:preprocessed）：context.bodyForAgent（最終 enriched body）、context.from、context.channelId。

Bootstrap events（agent:bootstrap）：context.bootstrapFiles（可變陣列）、context.agentId。

Session patch events（session:patch）：context.sessionEntry、context.patch（僅變更的欄位）、context.cfg。只有特權 clients 可以觸發 patch events。

Compaction events：session:compact:before 包含 messageCount、tokenCount。session:compact:after 會新增 compactedCount、summaryLength、tokensBefore、tokensAfter。

command:stop 觀察使用者發出 /stop；它是 cancellation/command 生命週期，而不是 agent-finalization gate。需要檢查自然 final answer 並要求 agent 再執行一次 pass 的 plugins，應改用 typed plugin hook before_agent_finalize。請參閱 Plugin hooks。

Gateway 生命週期事件：gateway:shutdown 包含 reason 和 restartExpectedMs，並在 gateway shutdown 開始時觸發。gateway:pre-restart 包含相同 context，但只會在 shutdown 是預期 restart 的一部分，且提供有限的 restartExpectedMs 值時觸發。在 shutdown 期間，每個 lifecycle hook wait 都是 best-effort 並有邊界，因此即使 handler 停滯，shutdown 仍會繼續。

在 gateway:shutdown（或 gateway:pre-restart）事件與 shutdown 序列其餘部分之間，gateway 也會對 process 停止時仍處於 active 的每個 session 觸發 typed session_end plugin hook。對一般 SIGTERM/SIGINT stop，事件的 reason 是 shutdown；若 close 是預期 restart 的一部分，則為 restart。此 drain 有邊界，因此緩慢的 session_end handler 無法阻擋 process exit；已透過 replace / reset / delete / compaction finalize 的 sessions 會被略過，以避免重複觸發。

Hook discovery

Hooks 會依 override precedence 遞增順序，從以下目錄中被發現：

1. Bundled hooks：隨 OpenClaw 出貨
2. Plugin hooks：封裝在已安裝 plugins 內的 hooks
3. Managed hooks：~/.openclaw/hooks/（使用者安裝、跨 workspaces 共用）。來自 hooks.internal.load.extraDirs 的額外目錄共享此 precedence。
4. Workspace hooks：<workspace>/hooks/（per-agent，預設停用直到明確啟用）

Workspace hooks 可以新增 hook 名稱，但無法覆寫同名的 bundled、managed 或 plugin-provided hooks。

Gateway 在 internal hooks 尚未設定前，會在啟動時略過 internal hook discovery。使用 openclaw hooks enable <name> 啟用 bundled 或 managed hook、安裝 hook pack，或設定 hooks.internal.enabled=true 以 opt in。當你啟用一個具名 hook 時，Gateway 只會載入該 hook 的 handler；hooks.internal.enabled=true、額外 hook 目錄，以及 legacy handlers 會 opt into broad discovery。

Hook packs

Hook packs 是 npm packages，透過 package.json 中的 openclaw.hooks export hooks。使用以下方式安裝：

openclaw plugins install <path-or-spec>

Npm specs 僅限 registry（package name + optional exact version or dist-tag）。Git/URL/file specs 和 semver ranges 會被拒絕。

Bundled hooks

啟用任何 bundled hook：

openclaw hooks enable <hook-name>

session-memory 詳細資料

擷取最後 15 則 user/assistant messages，並使用 host local date 儲存到 <workspace>/memory/YYYY-MM-DD-HHMM.md。Memory capture 會在背景執行，因此 /new 和 /reset acknowledgements 不會因 transcript reads 或 optional slug generation 而延遲。設定 hooks.internal.entries.session-memory.llmSlug: true，即可使用 configured model 產生描述性 filename slugs。需要已設定 workspace.dir。

bootstrap-extra-files config

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

Paths 會相對於 workspace 解析。只會載入已識別的 bootstrap basenames（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、MEMORY.md）。

command-logger 詳細資料

將每個 slash command 記錄到 ~/.openclaw/logs/commands.log。

compaction-notifier 詳細資料

當 OpenClaw 開始和完成 compacting session transcript 時，會將簡短狀態訊息傳送到目前 conversation。這能降低 chat surfaces 上長回合的困惑，因為使用者可以看到 assistant 正在摘要 context，並會在 compaction 後繼續。

boot-md 詳細資料

在 gateway 啟動時，從 active workspace 執行 BOOT.md。

Plugin hooks

Plugins 可以透過 Plugin SDK 註冊 typed hooks，以進行更深入的整合： intercepting tool calls、modifying prompts、controlling message flow 等。 當你需要 before_tool_call、before_agent_reply、 before_install 或其他 in-process lifecycle hooks 時，請使用 plugin hooks。

完整的 plugin hook 參考請參閱 Plugin hooks。

設定

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

Per-hook 環境變數：

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

額外 hook 目錄：

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

CLI 參考

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

最佳實務

• 讓處理常式保持快速。 掛鉤會在命令處理期間執行。使用 void processInBackground(event) 以觸發後即不等待的方式處理繁重工作。
• 妥善處理錯誤。 將有風險的操作包在 try/catch 中；不要擲出例外，讓其他處理常式可以執行。
• 及早篩選事件。 如果事件類型/動作不相關，請立即返回。
• 使用特定的事件鍵。 偏好使用 "events": ["command:new"]，而不是 "events": ["command"]，以降低開銷。

疑難排解

未探索到掛鉤

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

掛鉤不符合資格

openclaw hooks info my-hook

檢查是否缺少二進位檔（PATH）、環境變數、設定值或作業系統相容性。

掛鉤未執行

1. 確認掛鉤已啟用：openclaw hooks list
2. 重新啟動你的 Gateway 行程，讓掛鉤重新載入。
3. 檢查 Gateway 記錄：./scripts/clawlog.sh | grep hook

相關內容

• CLI 參考：掛鉤
• Webhook
• Plugin 掛鉤 — 行程內 Plugin 生命週期掛鉤
• 設定