概念

Hooks 讓你在 OpenClaw 的各種事件發生時執行自訂邏輯。例如：訊息進來時、session 開始時、agent 回覆前。

核心檔案

src/plugins/
├── hooks.ts               # Hook 型別定義
├── hook-runner.ts         # Hook 執行器
├── hook-runner-global.ts  # Global hook runner
└── internal-hooks/        # 內建 hooks
    ├── memory-flush.ts
    ├── session-start.ts
    └── ...

~/.openclaw/hooks/         # 用戶自訂 hooks

Hook 類型

檔案：src/plugins/hooks.ts

export type HookType =
  | "session:start"        // Session 開始
  | "session:end"          // Session 結束
  | "message:inbound"      // 收到訊息
  | "message:outbound"     // 發送訊息前
  | "reply:before"         // Agent 回覆前
  | "reply:after"          // Agent 回覆後
  | "tool:before"          // Tool 執行前
  | "tool:after"           // Tool 執行後
  | "compaction:before"    // Compaction 前
  | "compaction:after";    // Compaction 後

export type Hook = {
  type: HookType;
  name: string;
  handler: HookHandler;
  priority?: number;       // 越小越先執行
};

export type HookHandler = (params: {
  ctx: HookContext;
  payload: unknown;
}) => Promise<HookResult>;

Hook 執行器

檔案：src/plugins/hook-runner.ts

export class HookRunner {
  private hooks: Map<HookType, Hook[]> = new Map();
  
  register(hook: Hook): void {
    const existing = this.hooks.get(hook.type) ?? [];
    existing.push(hook);
    // 按 priority 排序
    existing.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
    this.hooks.set(hook.type, existing);
  }
  
  async run(type: HookType, payload: unknown): Promise<HookRunResult> {
    const hooks = this.hooks.get(type) ?? [];
    
    for (const hook of hooks) {
      const result = await hook.handler({ ctx: this.ctx, payload });
      
      // 如果 hook 要求中斷，停止執行
      if (result.abort) {
        return { aborted: true, reason: result.reason };
      }
      
      // 如果 hook 修改了 payload，傳遞給下一個
      if (result.payload !== undefined) {
        payload = result.payload;
      }
    }
    
    return { aborted: false, payload };
  }
}

Global Hook Runner

檔案：src/plugins/hook-runner-global.ts

let globalHookRunner: HookRunner | null = null;

export function getGlobalHookRunner(): HookRunner {
  if (!globalHookRunner) {
    globalHookRunner = new HookRunner();
    loadInternalHooks(globalHookRunner);
  }
  return globalHookRunner;
}

export async function runHook(type: HookType, payload: unknown): Promise<HookRunResult> {
  const runner = getGlobalHookRunner();
  return await runner.run(type, payload);
}

內建 Hooks

Session Start Hook：

// src/plugins/internal-hooks/session-start.ts
export const sessionStartHook: Hook = {
  type: "session:start",
  name: "session-start-log",
  priority: 10,
  
  async handler({ ctx, payload }) {
    const { sessionId, agentId } = payload as SessionStartPayload;
    
    log.info(`Session started: ${sessionId} (agent: ${agentId})`);
    
    // 可以做額外初始化
    await initializeSessionResources(sessionId);
    
    return { abort: false };
  },
};

Memory Flush Hook：

// src/plugins/internal-hooks/memory-flush.ts
export const memoryFlushHook: Hook = {
  type: "compaction:before",
  name: "memory-flush",
  priority: 1,  // 最先執行
  
  async handler({ ctx, payload }) {
    const { session, cfg } = payload as CompactionPayload;
    
    // 觸發 memory flush
    if (cfg.compaction?.memoryFlush?.enabled) {
      await triggerMemoryFlush(session);
    }
    
    return { abort: false };
  },
};

自訂 Hooks

在 ~/.openclaw/hooks/ 放置 JavaScript 檔案：

// ~/.openclaw/hooks/my-hook.js
export default {
  type: "message:inbound",
  name: "my-custom-hook",
  priority: 50,
  
  async handler({ ctx, payload }) {
    const { body, from } = payload;
    
    // 自訂邏輯
    console.log(`Message from ${from}: ${body}`);
    
    // 可以修改 payload
    return {
      abort: false,
      payload: {
        ...payload,
        body: body.toLowerCase(), // 把訊息轉小寫
      },
    };
  },
};

設定

// openclaw.json
{
  "hooks": {
    "enabled": true,
    "paths": ["~/.openclaw/hooks"],
    "internal": {
      "memoryFlush": { "enabled": true },
      "sessionLog": { "enabled": true }
    }
  }
}

Hook 執行時機

Message arrives
    ↓
[hook: message:inbound]
    ↓
Session resolved
    ↓
[hook: session:start] (if new session)
    ↓
[hook: reply:before]
    ↓
LLM processes
    ↓
[hook: tool:before] → Tool executes → [hook: tool:after]
    ↓
[hook: reply:after]
    ↓
[hook: message:outbound]
    ↓
Message sent

💡 關鍵洞察

Hooks 可以修改流程
- 修改 payload 影響後續處理
- abort: true 可以中斷流程
Priority 控制順序
- 數字越小越先執行
- 內建 hooks 通常用 1-10
自訂 hooks 很強大
- 可以 log、filter、transform
- 可以整合外部服務
小心效能
- Hook 在 hot path 上
- 避免做太重的事

🔗 核心檔案

功能	檔案
Hook 型別	`src/plugins/hooks.ts`
Hook 執行器	`src/plugins/hook-runner.ts`
Global runner	`src/plugins/hook-runner-global.ts`
內建 hooks	`src/plugins/internal-hooks/`

明天： Logging 與 Debug — 追蹤問題

Day 15: Hooks 系統