OpenClaw Hook 机制详解

OpenClaw 的 Hook 机制 是其最强大的扩展性和可控性特性之一。它本质上是一个事件驱动的插件/拦截系统，允许你在 Agent 生命周期的各个关键点注入自定义逻辑，而无需修改核心代码。很多用户认为这是 OpenClaw 超越普通 Agent 框架的核心优势，能实现“强制干预”“主动注入”“自动化闭环”等高级玩法。

1. Hook 的基本概念

OpenClaw 有两种容易混淆的“Hook”：

Internal Hooks（内部钩子）
：运行在 Gateway 内部，响应本地事件（如命令、生命周期）。这是最常用的“Hook 机制”。
Webhooks（外部 Webhook）
：Gateway 暴露的 HTTP 端点，供外部服务（如 GitHub、Gmail、Cron）主动推送事件给 OpenClaw。

本文主要讲 Internal Hooks（文档中简称为 Hooks）。

Hooks 的核心思想：

OpenClaw 的各个子系统（Agent Loop、工具调用、Prompt 构建、会话管理等）在关键时刻会产生标准化事件。
Hooks 通过目录自动发现机制被加载，像“监听器”一样订阅特定事件。
当事件触发时，Hook 脚本在沙箱中执行，可以修改数据、拦截行为、记录日志、注入内容等。

2. 常见 Hook 点（Lifecycle Interception）

OpenClaw 在 Agent 执行流程中提供了多个拦截点，典型的有：

before_prompt_build
/ before_prompt：Prompt 构建前。常用于强制注入知识、规则、记忆片段，解决“Agent 记得但不使用”的问题。
after_prompt
：Prompt 处理后。
before_tool_call
：工具调用前。用于物理拦截、校验、修正 Agent 的工具选择（非常适合终结重复错误）。
on-stop
/ session_end / Stop Hook：会话结束或任务停止时。常用于回调通知、清理、日志。
/new
、/reset、/stop 等命令事件。
Gateway 启动、Cron 任务、心跳等生命周期事件。
插件级 Hook（Plugin Hooks）：更深层，如工具运行时钩子。

这些点让 Hook 可以做到“系统级干预”，远比单纯改 Prompt 更可靠。

3. 如何使用 Hook

发现 Hook：
Bash
```
openclaw hooks list
```
会列出内置、工作区、插件提供的 Hook（包括 eligible 只显示可用的）。
启用 Hook：
Bash
```
openclaw hooks enable <hook_name>
```
或直接编辑 ~/.openclaw/config.json 添加到 enabled hooks 列表。
注意：工作区（workspace）里的 Hook 默认禁用，必须手动启用；插件管理的 Hook 通过插件本身启用/禁用。
Hook 的结构：

每个 Hook 通常是一个独立目录，包含 HOOK.md（元数据、描述、事件类型）。
脚本可以是 JS/TS、Python 等（取决于执行环境），在沙箱中运行。
支持自动发现：放在指定目录（工作区、managed、extra、bundled）即可被识别。

内置示例 Hook：

session-memory
：执行 /new 时自动保存会话上下文到记忆。
command-logger
：记录所有命令事件到审计文件。
soul-evil
：示例性的随机/定时替换 SOUL 内容。

4. 实战应用举例

解决 Agent 重复犯错
：用 before_prompt_build 按阶段强制注入正确知识；用 before_tool_call 拦截并修正错误输出，实现“机械守卫”。结合 Cron 定时清洗日志、自动生成规则，形成闭环学习。
Claude Code 零轮询异步
：利用 Claude Code 的 Stop Hook + SessionEnd Hook 回调，任务完成后主动通知 OpenClaw，避免反复轮询消耗 Token。
自定义自动化
：新会话时注入特定上下文、工具调用前加权限检查、错误时自动重试或通知等。
多 Agent 协作
：在协作流程中注入 guardrail，降低规模化时的错误爆炸。

5. 与 Plugin 的关系

Hooks 常和 Plugins 结合使用：

Plugin 可以提供自己的 Hooks（显示为 plugin:<id>）。
Plugin Hooks 更侧重工具/运行时扩展，而普通 Hooks 更侧重事件响应。
安装 Hook 包现在统一通过 openclaw plugins 管理。

6. 优势与注意事项

优势
：高度可扩展、事件驱动、非侵入式、支持沙箱安全执行。让 OpenClaw 更像一个“Agent OS”，而非简单聊天机器人。
注意
：

Hook 执行是异步非阻塞的，但高频事件需注意性能。
自定义 Hook 建议先看官方文档的目录结构和示例。
生产环境建议结合日志、监控使用，避免 Hook 本身出错导致连锁问题。

想深入了解，推荐查看官方文档：

https://docs.openclaw.ai/automation/hooks （英文）
中文社区文档或 GitHub（如 openclaw-docs）也有详细源码剖析。

如果你有具体使用场景（如某个 Hook 点的代码示例、如何写自定义 Hook、或结合 Claude Code 的细节），可以提供更多信息，我可以帮你进一步细化！