鉤子

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 hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

​

事件類型

事件	觸發時機
command:new	發出 /new 指令
command:reset	發出 /reset 指令
command:stop	發出 /stop 指令
command	任何指令事件（一般監聽器）
session:compact:before	在 compaction 摘要歷史記錄之前
session:compact:after	在 compaction 完成之後
session:patch	session 屬性被修改時
agent:bootstrap	在 workspace bootstrap 檔案被注入之前
gateway:startup	channels 啟動且 hooks 載入之後
gateway:shutdown	gateway shutdown 開始時
gateway:pre-restart	在預期的 gateway restart 之前
message:received	來自任何 channel 的入站訊息
message:transcribed	audio transcription 完成之後
message:preprocessed	media 和 link preprocessing 完成或被略過之後
message:sent	outbound message 已送達

​

撰寫 hooks

​

Hook 結構

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

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

​

HOOK.md 格式

---
name: my-hook
description: "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）：

欄位	說明
emoji	CLI 顯示用 emoji
events	要監聽的事件陣列
export	要使用的具名 export（預設為 "default"）
os	必要平台（例如 ["darwin", "linux"]）
requires	必要的 bins、anyBins、env 或 config 路徑
always	略過資格檢查（boolean）
install	安裝方法

​

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

Hook	事件	作用
session-memory	command:new、command:reset	將 session context 儲存到 <workspace>/memory/
bootstrap-extra-files	agent:bootstrap	從 glob patterns 注入 additional bootstrap files
command-logger	command	將所有 commands 記錄到 ~/.openclaw/logs/commands.log
compaction-notifier	session:compact:before、session:compact:after	在 session compaction 開始/結束時傳送可見 chat notices
boot-md	gateway:startup	在 gateway 啟動時執行 BOOT.md

啟用任何 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"]
      }
    }
  }
}

舊版 hooks.internal.handlers 陣列設定格式仍支援向後相容性，但新的掛鉤應使用以探索為基礎的系統。

​

CLI 參考

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

​

最佳實務

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

​

疑難排解

​

未探索到掛鉤

# Verify directory structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw 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 生命週期掛鉤
• 設定