OpenClaw 的 Hooks钩子系统

OpenClaw 的 Hooks（钩子）是一种简单而强大的自动化机制，让你在不修改核心代码的情况下，轻松扩展 AI Agent 的行为。它本质上是小型脚本，当特定事件发生时，会在 Gateway（网关）进程内部自动运行。

简单来说：

• 你发出一条命令（如 /new 创建新会话），或者系统内部发生某些变化（如会话压缩、消息接收）时，Hooks 就能自动执行你预设的操作。
• 它属于事件驱动（event-driven）系统。

注意：Hooks 和 Webhooks 是两回事。Webhooks 是外部系统通过 HTTP 调用 OpenClaw，而这里的 Hooks 是 OpenClaw 内部响应事件的小脚本。

Hooks 的常见用途

• 当你输入 /new 或 /reset 时，自动保存当前会话的上下文记忆到文件。
• 记录所有命令操作，用于审计或排查问题。
• 在 Agent 启动时，自动注入额外文件到工作区（如 AGENTS.md、TOOLS.md）。
• Gateway 启动时，执行 BOOT.md 中的初始化指令。
• 监听消息收发、会话属性修改等，实现自定义自动化（如日志记录、外部 API 调用）。

OpenClaw 自带的四个内置 Hooks

OpenClaw 默认会自动发现并提供这四个常用钩子，可以直接启用它们：

1. session-memory：在 /new 或 /reset 时，把会话上下文保存到默认路径 ~/.openclaw/workspace/memory/，方便后续恢复记忆。
2. bootstrap-extra-files：在 Agent 初始化（bootstrap）阶段，根据配置的路径或 glob 模式，自动注入额外文件到工作区。
3. command-logger：把所有命令事件记录成 JSONL 格式日志，保存到 ~/.openclaw/logs/commands.log。
4. boot-md：Gateway 启动后，自动执行工作区中的 BOOT.md 文件（需要启用内部钩子）。

这些内置钩子非常实用，推荐从它们开始上手。

如何管理和使用 Hooks

OpenClaw 提供了专门的 CLI 命令来管理 Hooks：

• openclaw hooks list：列出所有已发现的钩子（包括内置、插件、托管和工作区钩子）。
• openclaw hooks enable <hook名称>：启用某个钩子（例如 openclaw hooks enable session-memory）。
• openclaw hooks check：检查钩子状态。
• openclaw hooks info <hook名称>：查看某个钩子的详细信息。
• 在首次安装（openclaw onboard）过程中，系统会引导你选择并启用推荐的钩子。

重要安全规则：

• 内置和插件/托管钩子是可信的，可以直接使用。
• 工作区内的钩子（放在 <workspace>/hooks/ 目录下）默认被禁用，必须手动启用后才能运行，防止意外执行不可信代码。

Hooks 的发现和安装方式

Hooks 会按照以下优先级自动发现（后面的可以覆盖前面的同名钩子，但工作区钩子除外）：

1. OpenClaw 内置钩子。
2. 插件（Plugins）中打包的钩子。
3. 托管钩子（放在 ~/.openclaw/hooks/，支持额外目录配置）。
4. 工作区钩子（每个 Agent 自己的 <workspace>/hooks/，优先级最低，不能覆盖其他钩子）。

你还可以安装 Hook Packs（钩子包），它们其实是标准的 npm 包：

• 通过 openclaw plugins install <包名或路径> 安装。
• 包的 package.json 中需要声明 "openclaw": { "hooks": [...] } 来指定钩子目录。
• 支持依赖安装，但会忽略脚本执行以保证安全。

一个 Hook 的基本结构（如果你想自己写）

每个 Hook 是一个文件夹，里面至少包含两个文件：

• HOOK.md：元数据文件（YAML 前置 + Markdown 文档），描述名称、功能、触发事件、所需环境等。
  • 关键元数据包括：events（监听哪些事件，如 ["command:new"]）、emoji、requires（所需二进制或配置）等。
• handler.ts：核心处理函数，用 TypeScript 编写。
  • 函数签名通常是 async (event) => { ... }。
  • 里面先判断事件类型和动作（如 if (event.type === "command" && event.action === "new")），再执行你的逻辑。
  • 可以读取 event.sessionKey、event.timestamp 等信息，还可以往 event.messages 推送消息给用户。

示例逻辑（伪代码）：

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") return;
  console.log(`新会话创建：${event.sessionKey}`);
  // 这里可以保存文件、调用 API 等
};

Hooks 的主要类型和触发时机

OpenClaw 的 Hooks 按事件类型分为几大类，每类有具体的触发时机和传入参数（event 对象）：

1. Command Events（命令事件）

   • 触发命令：/new、 /reset、 /stop 等用户发出的命令。
   • 具体事件键：command:new、command:reset、command:stop、command（通用）。
   • 适合做：日志记录、记忆保存、会话初始化等。
   • 参数包含：sessionKey、timestamp、action、context（会话信息、来源如 WhatsApp 等）。

2. Session Events（会话事件）

   • 触发时机：会话压缩前后（session:compact:before/after）、会话属性修改（session:patch，如改模型、工具、策略等）。
   • 适合做：审计配置变更、压缩前后的额外处理。
   • 注意：session:patch 通常只允许特权客户端触发。

3. Agent Events（Agent 事件）

   • 主要触发：agent:bootstrap（工作区 bootstrap 文件注入前）。
   • 适合做：额外注入文件（如自定义文档）。
   • 可以修改 context.bootstrapFiles 来添加文件（仅限允许的文件名，如 AGENTS.md）。

4. Gateway Events（网关事件）

   • 触发：gateway:startup（Gateway 启动且通道、钩子加载完成后）。
   • 适合做：全局初始化任务。

5. Message Events（消息事件）

   • 触发阶段：消息接收（message:received）、转录后（message:transcribed）、预处理后（message:preprocessed）、发送成功（message:sent）。
   • 适合做：消息日志、内容增强、自动回复逻辑。
   • 不同阶段的参数丰富度不同（例如 preprocessed 阶段已包含完整媒体理解和转录）。

此外，还有插件 API 中的 Tool Result Hooks（用于修改工具执行结果），适合高级扩展。

使用建议和最佳实践

• 从内置钩子开始：先用 openclaw hooks list 查看，然后 enable 需要的几个，观察效果。
• 保持简单快速：钩子运行时会同步阻塞流程，所以不要放耗时操作，避免影响 Agent 响应速度。
• 早过滤事件：在 handler 中尽快检查 event.type 和 event.action，减少不必要的计算。
• 错误处理：优雅处理异常，不要让钩子抛错影响其他流程。
• 安全第一：工作区钩子必须手动启用；Hook Packs 安装时会安全地忽略脚本。
• 调试：用 openclaw hooks info 查看详情，多用 console.log 输出日志。
• 如果你想自定义钩子，从复制一个内置钩子的结构开始修改即可。

总之，Hooks 是 OpenClaw 让 AI Agent “活起来”和高度可定制的核心功能之一。掌握它后，你可以轻松实现个性化自动化，而不需要深入修改底层代码。