钩子 (Hooks) - 事件驱动自动化系统

Hooks（钩子）是 OpenClaw 的可扩展事件驱动系统，允许你在 Agent（智能体）生命周期的各个阶段自动触发自定义逻辑。通过监听特定事件，Hooks 可以实现消息预处理、日志记录、会话管理等丰富的自动化能力。

基本概念

每个 Hook 由两部分组成：

• HOOK.md：元数据文件，包含 YAML Frontmatter（YAML 前置元数据）和文档说明
• handler.ts：处理函数，接收事件对象并执行逻辑

my-hook/
├── HOOK.md        # 元数据 + 文档
└── handler.ts     # 事件处理逻辑

发现位置 (Discovery Locations)

OpenClaw 按以下优先级顺序发现 Hooks，同名 Hook 高优先级覆盖低优先级：

优先级	位置	路径	说明
1（最高）	Workspace Hooks（工作区钩子）	/hooks/	项目级别自定义
2	Managed Hooks（托管钩子）	~/.openclaw/hooks/	用户级别共享
3（最低）	Bundled Hooks（内置钩子）	随 OpenClaw 发布	系统默认

内置钩子

OpenClaw 自带两个 Bundled Hooks：

• session-memory：自动管理会话记忆的持久化与恢复
• command-logger：记录所有命令执行的日志

Hook Packs

Hook Packs 是通过 npm 包分发的钩子集合。在 package.json 中声明导出路径即可：

{
  "name": "openclaw-hooks-productivity",
  "openclaw": {
    "hooks": ["./hooks/auto-tag", "./hooks/smart-notify"]
  }
}

安装后自动被 OpenClaw 发现和加载。

事件触发器 (Event Triggers)

Command Events（命令事件）

事件名	触发时机
command:new	用户发起新命令时
command:reset	会话重置时
command:stop	命令被终止时

Agent Events（代理事件）

事件名	触发时机
agent:bootstrap	Agent 初始化启动时

Gateway Events（网关事件）

事件名	触发时机
gateway:startup	Gateway 服务启动时

Message Events（消息事件）

事件名	触发时机
message:received	收到用户原始消息时
message:transcribed	语音消息转写完成时
message:preprocessed	消息预处理完成时
message:sent	消息发送完成时

Tool Events（工具事件）

事件名	触发时机	特殊说明
tool_result_persist	工具执行结果持久化时	同步执行，阻塞后续流程

同步钩子

tool_result_persist 是唯一的同步事件。处理函数必须尽快返回，否则会阻塞整个 Agent 执行管线。

Hook 结构详解

HOOK.md 示例

---
name: auto-summarize
version: 1.0.0
events:
  - message:sent
description: 自动为每轮对话生成摘要
---

# 自动摘要钩子

在每条消息发送后，自动提取关键信息生成摘要，
存储到会话记忆中，方便后续检索。

handler.ts 示例

import type { HookContext, MessageSentEvent } from "@openclaw/sdk";

export default async function handler(ctx: HookContext<MessageSentEvent>) {
  const { message, session } = ctx.event;

  // 过滤：仅处理 Agent 回复
  if (message.role !== "assistant") return;

  // 生成摘要
  const summary = await ctx.agent.summarize(message.content, {
    maxLength: 100,
  });

  // 存储到会话记忆
  await session.memory.append({
    type: "summary",
    content: summary,
    timestamp: Date.now(),
  });
}

配置管理

在 openclaw.json 中管理 Hooks：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": true }
      }
    },
    "workspace": {
      "enabled": true,
      "entries": {
        "auto-summarize": {
          "enabled": true,
          "config": {
            "maxSummaryLength": 200
          }
        }
      }
    }
  }
}

CLI 命令

查看所有钩子

openclaw hooks list

输出示例：

NAME              SOURCE      EVENTS                  STATUS
session-memory    bundled     message:sent            enabled
command-logger    bundled     command:new,command:stop enabled
auto-summarize    workspace   message:sent            enabled

启用/禁用钩子

openclaw hooks enable auto-summarize
openclaw hooks disable command-logger

查看钩子详情

openclaw hooks info session-memory

最佳实践

开发建议

1. 保持处理函数轻量：Hook 处理函数应尽快完成，避免长时间阻塞
2. 尽早过滤事件：在函数开头检查事件条件，不符合的直接 return
3. 优雅处理错误：使用 try/catch 包裹核心逻辑，防止单个 Hook 的异常影响整体
4. 避免副作用累积：注意幂等性（Idempotency），同一事件重复处理不应产生额外影响
5. 善用 Workspace Hooks：项目特定逻辑放在工作区，通用逻辑放在托管目录

🇨🇳 中国用户须知

• Hook Packs 通过 npm 安装，建议配置国内镜像源加速：npm config set registry https://registry.npmmirror.com
• 如果在钩子中调用国内 API，注意处理网络超时和重试逻辑