Documentation Index
Fetch the complete documentation index at: https://mintlify.com/zhcndoc/openclaw/llms.txt
Use this file to discover all available pages before exploring further.
Hooks
Hooks 提供了一个可扩展的事件驱动系统，用于响应代理命令和事件来自动执行操作。Hooks 会从指定目录中自动发现，并且可以通过 CLI 命令进行管理。
入门导览
Hooks 是在某些事件发生时运行的小脚本。主要有两种类型：
- Hooks（本页内容）：当代理事件触发时，在网关内部运行
- Webhooks：外部 HTTP webhook，允许其他系统触发 OpenClaw 中的工作
快速开始
列出可用 Hooks
启用 Hook
openclaw hooks enable session-memory
检查 Hook 状态
获取详细信息
openclaw hooks info session-memory
内置 Hooks
OpenClaw 自带四个自动发现的内置 hooks：
💾 session-memory
当执行 /new 时将会话上下文保存到代理工作区。
openclaw hooks enable session-memory
~/.openclaw/workspace/memory/
文件名示例：
2026-01-16-vendor-pitch.md2026-01-16-api-design.md
在 agent:bootstrap 阶段注入额外的启动文件。
openclaw hooks enable bootstrap-extra-files
{
hooks: {
internal: {
enabled: true,
entries: {
"bootstrap-extra-files": {
enabled: true,
paths: ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
}
}
}
}
}
📝 command-logger
将所有命令事件记录到集中审计文件。
openclaw hooks enable command-logger
~/.openclaw/logs/commands.log
查看日志：
tail -n 20 ~/.openclaw/logs/commands.log
cat ~/.openclaw/logs/commands.log | jq .
🚀 boot-md
网关启动时运行 BOOT.md。
openclaw hooks enable boot-md
事件类型
命令事件
command:new — 发出 /new 命令时command:reset — 发出 /reset 命令时command:stop — 发出 /stop 命令时
会话事件
session:compact:before — 压缩历史摘要之前session:compact:after — 压缩完成
代理事件
agent:bootstrap — 在注入工作区 bootstrap 文件之前
网关事件
gateway:startup — 频道启动及 hooks 加载后
消息事件
message:received — 收取任一渠道入站消息message:transcribed — 消息已全解析（包含音频转录）message:preprocessed — 所有媒体和链接解析完毕后触发message:sent — 出站消息发送成功时
创建自定义 Hooks
1. 选择位置
- 工作区 hooks：
<workspace>/hooks/
- 管理 hooks：
~/.openclaw/hooks/
2. 创建目录结构
mkdir -p ~/.openclaw/hooks/my-hook
cd ~/.openclaw/hooks/my-hook
3. 创建 HOOK.md
---
name: my-hook
description: "执行一些有用操作"
metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } }
---
# 我的自定义 Hook
当你执行 `/new` 时，本 hook 会做一些有用的事情。
4. 创建 handler.ts
const handler = async (event) => {
if (event.type !== "command" || event.action !== "new") {
return;
}
console.log("[my-hook] 运行中！");
// 您的逻辑写这里
};
export default handler;
5. 启用并测试
# 确认 hook 是否被发现
openclaw hooks list
# 启用 hook
openclaw hooks enable my-hook
# 重启网关
openclaw gateway restart
新配置格式（推荐）
{
hooks: {
internal: {
enabled: true,
entries: {
"session-memory": { enabled: true },
"command-logger": { enabled: false }
}
}
}
}
针对某个 Hook 的配置
{
hooks: {
internal: {
enabled: true,
entries: {
"my-hook": {
enabled: true,
env: {
MY_CUSTOM_VAR: "value"
}
}
}
}
}
}
Hook 发现机制
Hooks 会自动从三个目录中发现（优先级按顺序）：
- 工作区 hooks：
<workspace>/hooks/
- 管理 hooks：
~/.openclaw/hooks/
- 内置 hooks：
<openclaw>/dist/hooks/bundled/
CLI 命令
列出 Hooks
openclaw hooks list
openclaw hooks list --eligible # 只显示合格的
openclaw hooks list --verbose # 详细显示
openclaw hooks list --json # JSON 输出
查看 Hook 信息
openclaw hooks info session-memory
openclaw hooks info session-memory --json
检查条件
openclaw hooks check
openclaw hooks check --json
启用 / 禁用
openclaw hooks enable session-memory
openclaw hooks disable command-logger
故障排查
Hook 未被发现
-
检查目录结构：
ls -la ~/.openclaw/hooks/my-hook/
# 应包含 HOOK.md，handler.ts
-
验证 HOOK.md 格式
-
列出所有已发现的 hook：
Hook 不合格
openclaw hooks info my-hook
- 二进制程序（检查 PATH）
- 环境变量
- 配置
- OS 兼容性
Hook 不执行
-
确认 hook 已启用：
-
重启网关进程
-
查看网关日志：
openclaw logs --follow | grep hook
相关文档
