Hooks (Automation)

事件驱动脚本，在 Gateway 内部事件触发时运行。

两种钩子

• Internal hooks（本页）：Gateway 内部事件触发（/new//reset//stop/生命周期）
• Webhooks：外部 HTTP 端点触发 OpenClaw 工作 → concepts/automation-cron
• Plugin hooks：进程内工具调用拦截 → concepts/plugin-hooks

快速开始

openclaw hooks list          # 列出可用钩子
openclaw hooks enable session-memory  # 启用钩子
openclaw hooks check         # 检查钩子状态
openclaw hooks info session-memory    # 详细信息

事件类型

事件	触发时机
command:new	/new 命令
command:reset	/reset 命令
command:stop	/stop 命令
session:compact:before	压缩前
session:compact:after	压缩后
session:patch	会话属性修改
agent:bootstrap	工作区引导文件注入前
gateway:startup	Gateway 启动后
gateway:shutdown	Gateway 关闭时
gateway:pre-restart	预期重启前
message:received	收到入站消息
message:transcribed	音频转录完成
message:preprocessed	媒体/链接预处理完成
message:sent	出站消息投递

钩子结构

my-hook/
├── HOOK.md          # 元数据 + 文档
└── handler.ts       # 处理器实现

HOOK.md 格式

---
name: my-hook
description: "Short description"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

注意事项

• Gateway 仅在启用钩子或配置至少一个钩子条目后才加载内部钩子
• 钩子可以打包在插件内，openclaw hooks list 同时显示独立钩子和插件管理的钩子

相关

• concepts/automation-overview — 自动化机制选择
• concepts/plugin-hooks — 插件钩子系统
• concepts/cli-hooks — openclaw hooks CLI 参考