什么是 Hooks
Hooks（钩子）是 OpenClaw 的事件驱动扩展系统。当特定事件发生时（如新建会话、执行命令、网关启动），对应的钩子会自动触发，执行预定义的操作。
Hooks 从指定目录自动发现，可以通过 CLI 管理，无需修改核心配置。
事件类型
命令事件
当用户执行特定命令时触发：
/new：创建新会话/reset：重置会话/stop：停止代理
代理事件
代理生命周期中的关键节点：
- Bootstrap：代理初始化阶段，工作区文件注入之前
网关事件
网关自身的生命周期事件：
- Startup：网关启动完成、所有频道加载之后
内置钩子
OpenClaw 自带三个实用钩子：
session-memory
当你执行 /new 创建新会话时，这个钩子会自动保存当前对话的上下文快照到 ~/.openclaw/workspace/memory/ 目录。这样即使开始了新会话，之前的对话记忆也不会丢失。
command-logger
将所有命令事件以 JSONL 格式记录到集中审计文件中。适合需要追踪操作历史的场景，每条记录包含时间戳、命令类型和执行上下文。
boot-md
在网关启动时自动执行 BOOT.md 文件中的指令。你可以在 BOOT.md 中定义启动时需要执行的初始化任务。
钩子目录结构
Hooks 按以下优先级从三个位置加载：
- 工作区钩子：
<workspace>/hooks/— 项目级别 - 托管钩子：
~/.openclaw/hooks/— 用户级别 - 内置钩子：随 OpenClaw 安装 — 系统级别
每个钩子是一个包含以下文件的目录：
my-hook/
├── HOOK.md # 元数据和文档说明
└── handler.ts # TypeScript 实现
HOOK.md 示例
---
name: my-custom-hook
event: command
commands: ["/new"]
enabled: true
---
这个钩子在创建新会话时执行自定义逻辑。
handler.ts 示例
import type { HookHandler } from "openclaw/hooks";
export const handler: HookHandler = async (context) => {
// 在新会话创建时执行的逻辑
console.log(`新会话创建: ${context.sessionId}`);
// 可以执行文件操作、发送通知等
};
管理 Hooks
# 查看所有可用钩子
openclaw hooks list
# 启用钩子
openclaw hooks enable session-memory
# 检查钩子状态
openclaw hooks check
实用场景
对话记忆持久化
启用 session-memory 钩子后，每次 /new 都会保存上下文：
openclaw hooks enable session-memory
保存的记忆文件可以在后续会话中被 AI 引用，实现跨会话的长期记忆。
操作审计
启用 command-logger 实现完整的操作审计追踪：
openclaw hooks enable command-logger
审计日志对于团队使用场景特别有价值，可以追踪谁在什么时间执行了什么操作。
自定义启动流程
在 BOOT.md 中定义网关启动时的初始化任务：
## 启动检查
1. 验证所有 API 密钥是否有效
2. 检查工作区目录权限
3. 发送启动通知到 Discord
自定义钩子开发
创建自己的钩子只需两步：
- 在
~/.openclaw/hooks/下创建钩子目录 - 编写
HOOK.md和handler.ts
钩子可以访问完整的 OpenClaw 上下文，包括会话信息、代理配置和工具调用能力，让你能够构建强大的自动化工作流。