跳轉到主要內容

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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:patchsession 屬性被修改時
agent:bootstrap在 workspace bootstrap 檔案被注入之前
gateway:startupchannels 啟動且 hooks 載入之後
gateway:shutdowngateway shutdown 開始時
gateway:pre-restart在預期的 gateway restart 之前
message:received來自任何 channel 的入站訊息
message:transcribedaudio transcription 完成之後
message:preprocessedmedia 和 link preprocessing 完成或被略過之後
message:sentoutbound 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）：
欄位說明
emojiCLI 顯示用 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-memorycommand:new、command:reset將 session context 儲存到 <workspace>/memory/
bootstrap-extra-filesagent:bootstrap從 glob patterns 注入 additional bootstrap files
command-loggercommand將所有 commands 記錄到 ~/.openclaw/logs/commands.log
compaction-notifiersession:compact:before、session:compact:after在 session compaction 開始/結束時傳送可見 chat notices
boot-mdgateway: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

​
相關內容