OpenClaw Hooks 是在 Gateway 内部事件触发时自动运行的小脚本，支持 /new、/reset、/stop 及 agent 生命周期事件。本页涵盖两类 Hook（内部 Hook 与 Webhook）的编写、发现机制、内置 Hook 启用方式、插件 Hook 集成、完整配置格式及常见故障排查。

Hooks 事件驱动自动化

Hooks 是在 Gateway 内部发生特定事件时自动运行的小脚本。它们从目录中自动发现，可通过 openclaw hooks 命令查看。

OpenClaw 有两类 Hook：

• 内部 Hook（本页）：在 agent 事件触发时在 Gateway 内部运行，如 /new、/reset、/stop 或生命周期事件。
• Webhook：让外部系统通过 HTTP 触发 OpenClaw 工作的外部端点。参见 Webhooks（定时任务页）。

Hook 也可以打包在插件内。openclaw hooks list 会同时显示独立 Hook 和插件管理的 Hook。

快速开始

# 列出可用 Hooks
openclaw hooks list

# 启用某个 Hook
openclaw hooks enable session-memory

# 检查 Hook 状态
openclaw hooks check

# 获取详细信息
openclaw hooks info session-memory

事件类型

事件	触发时机
command:new	执行 /new 命令时
command:reset	执行 /reset 命令时
command:stop	执行 /stop 命令时
command	任意命令事件（通用监听）
session:compact:before	压缩历史记录之前
session:compact:after	压缩完成之后
session:patch	session 属性被修改时
agent:bootstrap	workspace bootstrap 文件注入之前
gateway:startup	频道启动、Hooks 加载完成之后
message:received	从任意频道收到消息时
message:transcribed	音频转录完成后
message:preprocessed	所有媒体和链接理解完成后
message:sent	出站消息送达时

编写 Hook

Hook 目录结构

每个 Hook 是一个包含两个文件的目录：

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

HOOK.md 格式

---
name: my-hook
description: "这个 Hook 做什么的简短描述"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

详细文档写在这里。

元数据字段（metadata.openclaw）：

字段	说明
emoji	CLI 显示用的 emoji
events	要监听的事件数组
export	使用的命名导出（默认 "default"）
os	要求的平台（如 ["darwin", "linux"]）
requires	需要的 bins、anyBins、env 或 config 路径
always	绕过资格检查（布尔值）
install	安装方式

处理器实现

const handler = async (event) => {
  if (event.type !== "command" || event.action !== "new") {
    return;
  }

  console.log(`[my-hook] 触发了 New 命令`);
  // 你的业务逻辑

  // 可选：向用户发送消息
  event.messages.push("Hook 已执行！");
};

export default handler;

每个事件包含：type、action、sessionKey、timestamp、messages（推送到此数组即可向用户发送消息）和 context（事件特定数据）。

事件上下文说明

命令事件（command:new、command:reset）：context.sessionEntry、context.previousSessionEntry、context.commandSource、context.workspaceDir、context.cfg。

消息事件（message:received）：context.from、context.content、context.channelId、context.metadata（含 senderId、senderName、guildId 等提供商特定数据）。

消息事件（message:sent）：context.to、context.content、context.success、context.channelId。

消息事件（message:transcribed）：context.transcript、context.from、context.channelId、context.mediaPath。

消息事件（message:preprocessed）：context.bodyForAgent（最终富化后的正文）、context.from、context.channelId。

Bootstrap 事件（agent:bootstrap）：context.bootstrapFiles（可修改的数组）、context.agentId。

Session patch 事件（session:patch）：context.sessionEntry、context.patch（仅变更字段）、context.cfg。只有特权客户端能触发 patch 事件。

压缩事件：session:compact:before 包含 messageCount、tokenCount；session:compact:after 额外包含 compactedCount、summaryLength、tokensBefore、tokensAfter。

Hook 发现机制

Hook 按照以下顺序从目录中发现，后面的优先级更高：

1. 内置 Hook：随 OpenClaw 一起发布
2. 插件 Hook：已安装插件内打包的 Hook
3. 托管 Hook：~/.openclaw/hooks/（用户安装，跨 workspace 共享）。hooks.internal.load.extraDirs 中的额外目录也属于这个优先级。
4. Workspace Hook：<workspace>/hooks/（每个 agent 独立，默认禁用，需显式启用）

Workspace Hook 可以新增新 Hook 名称，但不能覆盖同名的内置、托管或插件 Hook。

Hook 包

Hook 包是通过 package.json 中的 openclaw.hooks 导出 Hook 的 npm 包。安装命令：

openclaw plugins install <path-or-spec>

npm 规格只支持注册表（包名 + 可选的精确版本或 dist-tag）。Git/URL/文件规格和语义化版本范围会被拒绝。

内置 Hooks

Hook	事件	功能
session-memory	command:new、command:reset	将 session 上下文保存到 <workspace>/memory/
bootstrap-extra-files	agent:bootstrap	从 glob 模式注入额外的 bootstrap 文件
command-logger	command	将所有命令记录到 ~/.openclaw/logs/commands.log
boot-md	gateway:startup	Gateway 启动时运行 BOOT.md

启用任意内置 Hook：

openclaw hooks enable <hook-name>

session-memory 详解

提取最近 15 条用户/助手消息，通过 LLM 生成描述性文件名 slug，保存到 <workspace>/memory/YYYY-MM-DD-slug.md。需要配置 workspace.dir。

bootstrap-extra-files 配置

{
  "hooks": {
    "internal": {
      "entries": {
        "bootstrap-extra-files": {
          "enabled": true,
          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]
        }
      }
    }
  }
}

路径相对于 workspace 解析。只会加载识别到的 bootstrap 基础名（AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md、BOOTSTRAP.md、MEMORY.md）。

插件 Hooks

插件可以通过 Plugin SDK 注册 Hook，实现更深度的集成：拦截工具调用、修改提示词、控制消息流等。Plugin SDK 提供了 28 个 Hook，覆盖模型解析、agent 生命周期、消息流、工具执行、子代理协调和 gateway 生命周期。

完整插件 Hook 参考（含 before_tool_call、before_agent_reply、before_install 等），请参见 插件架构。

配置

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": { "enabled": true },
        "command-logger": { "enabled": false }
      }
    }
  }
}

每个 Hook 的环境变量：

{
  "hooks": {
    "internal": {
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": { "MY_CUSTOM_VAR": "value" }
        }
      }
    }
  }
}

额外 Hook 目录：

{
  "hooks": {
    "internal": {
      "load": {
        "extraDirs": ["/path/to/more/hooks"]
      }
    }
  }
}

旧版 hooks.internal.handlers 数组配置格式仍然支持（向后兼容），但新 Hook 应使用基于发现的系统。

CLI 参考

# 列出所有 Hooks（可加 --eligible、--verbose 或 --json）
openclaw hooks list

# 显示某个 Hook 的详细信息
openclaw hooks info <hook-name>

# 显示资格摘要
openclaw hooks check

# 启用/禁用
openclaw hooks enable <hook-name>
openclaw hooks disable <hook-name>

最佳实践

• 保持处理器快速。 Hook 在命令处理期间运行。对耗时操作使用 void processInBackground(event) 异步触发。
• 优雅处理错误。 用 try/catch 包裹风险操作；不要抛出异常，让其他处理器也能运行。
• 尽早过滤事件。 如果事件类型/动作不相关，立即返回。
• 使用精确的事件键。 优先用 "events": ["command:new"] 而非 "events": ["command"]，减少不必要的开销。

故障排查

Hook 未被发现

# 验证目录结构
ls -la ~/.openclaw/hooks/my-hook/
# 应该显示：HOOK.md, handler.ts

# 列出所有已发现的 Hooks
openclaw hooks list

Hook 不符合资格

openclaw hooks info my-hook

检查是否缺少必要的可执行文件（PATH）、环境变量、配置值或 OS 兼容性。

Hook 未执行

1. 确认 Hook 已启用：openclaw hooks list
2. 重启 Gateway 进程以重新加载 Hooks。
3. 检查 Gateway 日志：./scripts/clawlog.sh | grep hook

常见问题

Q: Hook 和 Webhook 有什么区别？

A: 内部 Hook 在 Gateway 内部事件（如 /new 命令）触发时运行；Webhook 是对外暴露的 HTTP 端点，让外部系统（如 GitHub、Gmail）主动触发 OpenClaw 执行任务。

Q: 能在 Hook 里直接发消息给用户吗？

A: 可以。在处理器中向 event.messages 数组推送字符串即可，Gateway 会在命令响应里把这些消息带给用户。

Q: Workspace Hook 能不能覆盖内置 Hook？

A: 不能。Workspace Hook 只能新增新的 Hook 名称，无法覆盖同名的内置、托管或插件 Hook。

相关链接

• CLI 参考：hooks
• Webhooks
• 插件架构 — 完整插件 Hook 参考
• 配置参考