Hooks 是 OpenClaw 的事件驱动扩展机制——当 Agent 命令和生命周期事件触发时，自动执行你写的小脚本。
两种类型
- Hooks（本文）：在 Gateway 内部运行，响应 Agent 命令和事件
- Webhooks：外部 HTTP 端点，让其他系统触发 OpenClaw 操作
内置 Hooks（开箱即用）
OpenClaw 自带 4 个内置 Hook：
| Hook | 触发时机 | 作用 |
|---|---|---|
| 💾 session-memory | /new 命令 | 将会话上下文保存到工作区记忆 |
| 📎 bootstrap-extra-files | agent:bootstrap | 注入额外工作区文件 |
| 📝 command-logger | 所有命令 | 记录命令日志到文件 |
| 🚀 boot-md | Gateway 启动 | 运行 BOOT.md 指令 |
bash
openclaw hooks list
openclaw hooks enable session-memory
openclaw hooks info session-memoryHook 发现顺序
- Workspace Hooks：
<workspace>/hooks/（每个 Agent 专属，优先级最高） - Managed Hooks：
~/.openclaw/hooks/（共享） - Bundled Hooks：内置
目录结构
my-hook/
├── HOOK.md # 元数据 + 文档（YAML frontmatter）
└── handler.ts # Handler 实现
HOOK.md 格式
yaml
---
name: my-hook
description: "执行某操作"
metadata:
{
"openclaw": {
"emoji": "🎯",
"events": ["command:new"],
"requires": { "bins": ["node"] }
}
}
---handler.ts 实现
typescript
const myHandler = async (event) => {
if (event.type !== "command" || event.action !== "new") {
return;
}
console.log(`[my-hook] Session: ${event.sessionKey}`);
event.messages.push("Hook 执行成功！");
};
export default myHandler;事件类型
命令事件
command:new、command:reset、command:stop
Session 事件
session:compact:before、session:compact:after
Agent 事件
agent:bootstrap（可修改 bootstrapFiles）
Gateway 事件
gateway:startup
消息事件
message:received（媒体处理前）message:transcribed（音频转写完成后）message:preprocessed（Agent 看到之前的完整消息）message:sent
消息 Context 结构
typescript
// message:received
{
from: string,
content: string,
channelId: string,
accountId?: string,
conversationId?: string,
messageId?: string,
}
// message:sent
{
to: string,
content: string,
success: boolean,
channelId: string,
isGroup?: boolean,
}创建自定义 Hook（5 步）
bash
# 1. 创建目录
mkdir -p ~/.openclaw/hooks/my-hook
# 2. 创建 HOOK.md 和 handler.ts（见上）
# 3. 验证发现
openclaw hooks list
# 4. 启用
openclaw hooks enable my-hook
# 5. 重启 Gateway内置 Hooks 详解
session-memory
/new 时保存最近 15 行对话到带日期记忆文件：
~/.openclaw/workspace/memory/2026-03-11-api-design.md
bootstrap-extra-files
自动注入 monorepo 各包的文件：
json
{
"hooks": {
"internal": {
"entries": {
"bootstrap-extra-files": {
"enabled": true,
"paths": ["packages/*/AGENTS.md"]
}
}
}
}
}command-logger
日志格式（JSONL）：
json
{"timestamp":"2026-03-11T00:00:00.000Z","action":"new","sessionKey":"agent:main:main"}boot-md
Gateway 启动时运行 <workspace>/BOOT.md 中的指令。
配置
json
{
"hooks": {
"internal": {
"enabled": true,
"entries": {
"session-memory": { "enabled": true },
"command-logger": { "enabled": true }
}
}
}
}最佳实践
保持 Handler 快速（异步处理，不阻塞命令）；优雅捕获异常（不要 throw，让其他 Handler 继续运行）；使用精确事件键（command:new 而非 command）。
故障排查
bash
openclaw hooks list # 检查发现状态
openclaw hooks list --verbose # 查看缺少的依赖
openclaw hooks info my-hook # 查看资格检查
tail -f ~/.openclaw/gateway.log | grep hook原文：Hooks - OpenClaw | 来源：OpenClaw 官方文档