OpenClaw 钩子（Hooks）完整实战指南：openclaw hooks 命令详解与事件驱动自动化

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯

OpenClaw 的 Hooks 是一套内置于 Gateway 的事件驱动自动化系统，允许你在/new、/reset、/stop等命令事件和agent:bootstrap、gateway:startup等生命周期事件发生时，自动执行任意 TypeScript 小脚本。本文以 CLI 参考文档 为骨架，结合仓库内 Hooks 概念文档 与hooks/目录下的真实实现代码，完整讲解openclaw hooks的list/info/check/enable/disable/install/update全部命令、四个内置捆绑钩子（session-memory、bootstrap-extra-files、command-logger、boot-md）、钩子发现与优先级机制、HOOK.md 元数据格式、事件类型以及配置与调试方法。读完本文，你将能够熟练管理现有钩子、写出自己的钩子并接入 OpenClaw 的自动化流程。

一、Hooks 是什么：事件驱动的网关内自动化

在 OpenClaw 中，Hooks（钩子）是运行在 Gateway 进程内部的小型脚本，当特定 Agent 事件触发时被调用。它与外部 HTTP Webhook（见 Webhook Hooks）不同——Hook 直接内嵌在 Gateway 中，可以访问会话上下文，甚至能向用户推送消息。

常见的钩子用途包括：

• 在/new重置会话前，把会话上下文保存成记忆快照；
• 把所有命令事件写入集中审计日志，用于排查与合规；
• 在会话开始/结束时触发后续自动化动作；
• 在 Agent 启动时向工作区注入额外的引导文件。

从源码看，钩子的核心类型定义位于 hooks/internal-hooks.ts：事件类型为"command" | "session" | "agent" | "gateway" | "message"，每个事件包含type、action、sessionKey、timestamp、messages（向其中 push 内容即可发送给用户）以及携带上下文数据的context对象。

二、快速上手：四个捆绑钩子与核心命令

OpenClaw 随发行版自带四个自动发现的捆绑钩子（实现在 hooks/bundled/）：

最常用的三个操作：

# 列出所有已发现的钩子 openclaw hooks list # 启用一个钩子 openclaw hooks enable session-memory # 查看钩子状态汇总 openclaw hooks check

注意：启用或禁用钩子后必须重启 Gateway（macOS 上重启菜单栏应用，开发环境则重启网关进程），钩子才会重新加载。

三、openclaw hooks list：列出所有钩子

openclaw hooks list

该命令会列出从workspace 钩子目录、托管（managed）目录和捆绑（bundled）目录中发现的所有钩子。选项如下：

• --eligible：只显示满足资格（requirements 全部满足）的钩子；
• --json：以 JSON 结构化输出，便于程序化消费；
• -v, --verbose：显示详细信息，包括未满足的 requirements。

示例输出：

Hooks (4/4 ready) Ready: 🚀 boot-md ✓ - Run BOOT.md on gateway startup 📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap 📝 command-logger ✓ - Log all command events to a centralized audit file 💾 session-memory ✓ - Save session context to memory when /new command is issued

带--verbose时，输出表格会增加Missing列，显示未就绪钩子缺少哪些 requirements（如缺失的bins、env、config、os）。带--json时返回结构化数据，包含每个钩子的name、description、emoji、eligible、enabledByConfig、requirementsSatisfied、loadable、blockedReason、source、pluginId、events、homepage、missing等字段（对应 cli/hooks-cli.ts 中formatHooksList的 JSON 序列化逻辑）。

底层实现上，list命令通过buildHooksReport聚合三类钩子：从工作区加载的workspaceEntries、从插件状态中提取的pluginEntries，再经resolveHookEntries按优先级合并去重（见 cli/hooks-cli.ts）。

四、openclaw hooks info：查看单个钩子详情

openclaw hooks info <name>

显示某个具体钩子的详细信息。参数<name>为钩子名（例如session-memory），选项--json输出 JSON。

openclaw hooks info session-memory

示例输出：

💾 session-memory ✓ Ready Save session context to memory when /new command is issued Details: Source: openclaw-bundled Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts Homepage: https://docs.openclaw.ai/automation/hooks#session-memory Events: command:new Requirements: Config: ✓ workspace.dir

从实现看（cli/hooks-cli.ts），info会展示：来源（Source）、HOOK.md 路径（Path）、处理器路径（Handler）、文档主页（Homepage）、监听事件（Events）以及逐项核验的Requirements（Binaries/Any binary/Environment/Config/OS，每项以✓/✗标注是否满足）。如果钩子由插件管理，还会显示Managed by plugin; enable/disable via hooks CLI not available.提示。info是排查"钩子未就绪"的第一工具——输出中会明确列出缺失项。

五、openclaw hooks check：资格状态汇总

openclaw hooks check

显示钩子资格状态的汇总（多少个 ready、多少个 not ready），选项--json输出 JSON。

示例输出：

Hooks Status Total hooks: 4 Ready: 4 Not ready: 0

若有未就绪钩子，文本输出会列出"Hooks not ready"明细及其原因（bins: ...; env: ...; config: ...; os: ...）。JSON 模式下notEligible数组携带每个未就绪钩子的blockedReason与missing详情（cli/hooks-cli.ts）。

六、enable / disable：启用与禁用钩子

openclaw hooks enable <name> openclaw hooks disable <name>

enable通过把钩子写入配置（~/.openclaw/config.json）来启用它，执行流程是：

1. 检查钩子是否存在且满足资格（requireEligible: true，未满足 requirements 会直接报错Hook "<name>" is not eligible (missing requirements)）；
2. 更新配置中hooks.internal.entries.<name>.enabled = true；
3. 将配置保存到磁盘。

成功后输出✓ Enabled hook: 💾 session-memory；disable则把enabled置为false，输出⏸ Disabled hook: 📝 command-logger。实现细节见 cli/hooks-cli.ts：enableHook在写配置时还会把hooks.internal.enabled一并置为true（ensureHooksEnabled: true），确保内部钩子运行时整体开启。

两个关键限制：

• 由插件管理的钩子在openclaw hooks list中显示为plugin:<id>，无法通过 hooks CLI 启用/禁用，应去启用/禁用对应插件（见 插件钩子文档）；
• 启用/禁用后需要重启 Gateway才能生效。

七、钩子发现机制：workspace → managed → bundled 与优先级

钩子从三类目录自动发现，按优先级从低到高排列（hooks/workspace.ts）：

1. Bundled 钩子：<openclaw>/dist/hooks/bundled/，随 OpenClaw 发行版提供；
2. Managed 钩子：~/.openclaw/hooks/，用户安装、跨工作区共享（可以是单个钩子目录，也可以是 hook pack 包目录）；
3. Workspace 钩子：<workspace>/hooks/，按 Agent 隔离，优先级最高；
4. 另外还有插件钩子目录与配置的hooks.internal.load.extraDirs扩展目录。

同名钩子冲突时按HOOK_SOURCE_POLICIES决定去留（hooks/policy.ts）：优先级数值越大越优先——openclaw-bundled（10）<openclaw-plugin（20）<openclaw-managed（30）<openclaw-workspace（40）。例如 workspace 钩子可以覆盖 managed 和 bundled 的同名钩子，但 workspace 钩子的默认启用模式是explicit-opt-in，即必须显式配置enabled: true才会启用，而 bundled/plugin/managed 钩子默认default-on。

从源码还可看到，加载钩子时会做路径边界校验：HOOK.md 与 handler 都必须在钩子目录内部（resolveContainedDir使用 realpath 检查），读取文件也经由openBoundaryFileSync的边界防护（hooks/workspace.ts）。

八、钩子结构与 HOOK.md 元数据

每个钩子是一个目录，包含两个文件：

my-hook/ ├── HOOK.md # 元数据（YAML frontmatter）+ 文档 └── handler.ts # 处理器实现（默认导出）

handler 文件的候选名为handler.ts、handler.js、index.ts、index.js（hooks/workspace.ts）。若目录有 HOOK.md 但缺 handler 文件，该钩子会被跳过并记录警告。

HOOK.md的 frontmatter 是钩子的元数据来源（hooks/frontmatter.ts），完整格式：

--- name: my-hook description: "Short description of what this hook does" homepage: https://docs.openclaw.ai/automation/hooks#my-hook metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } --- # My Hook Detailed documentation goes here...

metadata.openclaw支持的字段（类型定义见 hooks/types.ts）：

以捆绑钩子的真实 frontmatter 为例，session-memory 的 HOOK.md 声明了emoji: "💾"、events: ["command:new", "command:reset"]、requires.config: ["workspace.dir"]，这解释了为什么info输出中会出现Config: ✓ workspace.dir这一行。

九、编写 Handler：事件上下文与事件类型

handler.ts导出一个HookHandler异步函数，接收完整的事件对象：

const myHandler = async (event) => { // 只在 'new' 命令时触发 if (event.type !== "command" || event.action !== "new") { return; } console.log(`[my-hook] New command triggered`); console.log(` Session: ${event.sessionKey}`); console.log(` Timestamp: ${event.timestamp.toISOString()}`); // 你的自定义逻辑 // 可选：向用户发送消息 event.messages.push("✨ My hook executed!"); }; export default myHandler;

每个事件包含（hooks/internal-hooks.ts 与 概念文档）：

{ type: 'command' | 'session' | 'agent' | 'gateway' | 'message', action: string, // e.g., 'new', 'reset', 'stop', 'received', 'sent' sessionKey: string, // 会话标识 timestamp: Date, // 事件发生时间 messages: string[], // 向此数组 push 内容即可发送给用户 context: { /* 事件类型相关的上下文 */ } }

事件类型总览

Command 事件（命令事件）：

• command：所有命令事件的通用监听；
• command:new：发出/new命令时；
• command:reset：发出/reset命令时；
• command:stop：发出/stop命令时。

Session 事件：

• session:compact:before：压缩开始总结历史之前；
• session:compact:after：压缩完成并生成摘要元数据之后。

Agent 事件：

• agent:bootstrap：工作区引导文件注入之前（钩子可修改context.bootstrapFiles）。

Gateway 事件：

• gateway:startup：频道启动、钩子加载完成后触发。

Message 事件（消息收发）：

• message：所有消息事件的通用监听；
• message:received：从任意频道收到入站消息时（早于媒体理解阶段，媒体占位符可能仍是<media:audio>原始形式）；
• message:transcribed：消息完成全部处理（含音频转写与链接理解）之后，此时transcript包含完整转写文本；
• message:preprocessed：每条消息在媒体+链接理解全部完成后触发，钩子可访问完全富集后的正文（转写、图片描述、链接摘要）；
• message:sent：出站消息成功发送后。

message 事件上下文非常丰富，例如message:received携带from、content、channelId、accountId、conversationId、messageId及metadata（provider 特定的to、provider、surface、threadId、senderId、senderName、senderE164等）；message:sent携带to、success、error、isGroup、groupId等（完整字段见 hooks/internal-hooks.ts 与 概念文档 Message Event Context 一节）。

计划中的未来事件：session:start、session:end、agent:error。

消息日志钩子示例

const isMessageReceivedEvent = (event: { type: string; action: string }) => event.type === "message" && event.action === "received"; const isMessageSentEvent = (event: { type: string; action: string }) => event.type === "message" && event.action === "sent"; const handler = async (event) => { if (isMessageReceivedEvent(event as { type: string; action: string })) { console.log(`[message-logger] Received from ${event.context.from}: ${event.context.content}`); } else if (isMessageSentEvent(event as { type: string; action: string })) { console.log(`[message-logger] Sent to ${event.context.to}: ${event.context.content}`); } }; export default handler;

十、安装与更新 Hook Pack（install / update）

Hook pack 是标准 npm 包，通过package.json中的openclaw.hooks字段导出一个或多个钩子：

{ "name": "@acme/my-hooks", "version": "0.1.0", "openclaw": { "hooks": ["./hooks/my-hook", "./hooks/other-hook"] } }

# 从本地目录/压缩包或 npm 安装 openclaw hooks install <path-or-spec> openclaw hooks install <npm-spec> --pin

npm spec 规则：仅支持 registry-only 形式（包名 + 可选的精确版本或 dist-tag）；Git/URL/file spec 与 semver 范围会被拒绝。裸 spec 和@latest保持在 stable 轨道上；若 npm 解析到预发布版本，OpenClaw 会停下来要求你显式用@beta/@rc或精确预发布版本确认。依赖安装使用--ignore-scripts（不执行生命周期脚本），因此应保持 hook pack 依赖树为"纯 JS/TS"，避免依赖依赖postinstall构建的包。支持的压缩包格式：.zip、.tgz、.tar.gz、.tar。

install 的完整动作（对应 hooks/install.ts 与 hooks/installs.ts）：

1. 把 hook pack 复制进~/.openclaw/hooks/<id>；
2. 在hooks.internal.entries.*中启用安装的钩子；
3. 在hooks.internal.installs中记录安装来源与解析信息。

选项：

• -l, --link：以链接方式引用本地目录而不复制（加入hooks.internal.load.extraDirs）；
• --pin：将 npm 安装记录为精确解析的name@version写入hooks.internal.installs。

安装前会做严格校验：openclaw.hooks数组非空、每个条目必须解析到包目录内部（realpath 检查，逃逸则拒绝）、钩子目录必须有 HOOK.md 与 handler 文件（hooks/install.ts），同时validateHookId会拒绝./..与含路径分隔符的 id 以防目录穿越。

更新已安装的 hook pack（仅限 npm 安装的记录）：

openclaw hooks update <id> openclaw hooks update --all

• --all：更新所有被追踪的 hook pack；
• --dry-run：只展示将要发生的变化，不实际写入。

当已存储的完整性哈希存在而拉取到的产物哈希发生变化时，OpenClaw 会打印警告并要求确认；CI/非交互环境可用全局--yes跳过提示（hooks/update.ts）。本地目录安装（source 非 npm）的钩子会被skipped。

重要提示（基于当前仓库源码）：在 cli/hooks-cli.ts 中，install与update子命令已标记为deprecated，运行时输出openclaw hooks installis deprecated; useopenclaw plugins install，并实际转发到runPluginInstallCommand/runPluginUpdateCommand。因此在新环境中安装/更新钩子包，建议直接使用openclaw plugins install/openclaw plugins update命令。

十一、配置详解：hooks.internal

钩子的启用状态与自定义配置都放在~/.openclaw/config.json（或openclaw.json）的hooks.internal节点中，类型定义见 config/types.hooks.ts。

新配置格式（推荐）

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

每钩子自定义配置

每个 entry 支持enabled、env（注入给该钩子的环境变量）以及任意自定义键：

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

扩展目录

通过hooks.internal.load.extraDirs从额外目录加载钩子（openclaw hooks install -l也是把目录加到这里）：

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

旧版格式（仍兼容）

{ "hooks": { "internal": { "enabled": true, "handlers": [ { "event": "command:new", "module": "./hooks/handlers/my-handler.ts", "export": "default" } ] } } }

注意：旧格式的module必须是工作区相对路径，绝对路径与逃逸出工作区的路径会被拒绝。旧版 handler 在目录式钩子之后加载（迁移指南见 概念文档 Migration Guide）。配置键的语义在 config/schema.help.ts 中有官方说明：hooks.internal.installs被定位为"安装来源与解析产物的操作溯源记录，避免手工漂移编辑"。

十二、四个捆绑钩子详解

12.1 💾 session-memory

在发出/new（或/reset）时把会话上下文保存到记忆文件。工作流程（见 HOOK.md）：

1. 用重置前的会话条目定位正确的 transcript；
2. 提取会话中最后 N 条用户/助手消息（默认 15 条，可配置）；
3. 用 LLM 依据对话内容生成描述性的文件名 slug（因此与任何 LLM provider 兼容）；
4. 写入<workspace>/memory/YYYY-MM-DD-slug.md（默认工作区~/.openclaw/workspace）。

前置要求：配置项workspace.dir必须已设置（onboarding 时自动配置）。可选配置：

{ "hooks": { "internal": { "entries": { "session-memory": { "enabled": true, "messages": 25 } } } } }

输出文件示例：

# Session: 2026-01-16 14:30:00 UTC - **Session Key**: agent:main:main - **Session ID**: abc123def456 - **Source**: telegram

文件名示例：2026-01-16-vendor-pitch.md、2026-01-16-api-design.md、2026-01-16-bug-fix.md；若 LLM slug 生成失败，则回退到时间戳格式2026-01-16-1430.md。

12.2 📎 bootstrap-extra-files

在agent:bootstrap阶段把额外引导文件（如 monorepo 局部的AGENTS.md/TOOLS.md）注入引导上下文。前置要求：workspace.dir。不写文件，仅内存中修改引导上下文。配置示例：

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

注意事项（来自 概念文档）：路径相对工作区解析；文件必须留在工作区内（realpath 校验）；仅加载被识别的引导 basename；子代理 allowlist 被保留（仅AGENTS.md与TOOLS.md）。

12.3 📝 command-logger

监听全部命令事件，把审计记录追加到集中日志文件（HOOK.md）。无任何 requirements，开箱即用。行为：

1. 捕获事件详情（命令 action、时间戳、sessionKey、senderId、source）；
2. 以 JSONL 格式追加到~/.openclaw/logs/commands.log；
3. 后台静默运行，不打扰用户。

日志条目示例：

{"timestamp":"2026-01-16T14:30:00.000Z","action":"new","sessionKey":"agent:main:main","senderId":"+1234567890","source":"telegram"} {"timestamp":"2026-01-16T15:45:22.000Z","action":"stop","sessionKey":"agent:main:main","senderId":"user@example.com","source":"whatsapp"}

查看与分析日志：

# 最近命令 tail -n 20 ~/.openclaw/logs/commands.log # 用 jq 美化输出 cat ~/.openclaw/logs/commands.log | jq . # 按 action 过滤 grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

该钩子不会自动轮转日志，可按需手动轮转或配置 logrotate。

12.4 🚀 boot-md

Gateway 启动（频道启动后）时，对每个已配置的 agent scope 执行其工作区中的BOOT.md（若文件存在）。前置要求：workspace.dir；另外必须启用内部钩子（hooks.internal.enabled: true）才会运行。执行流程：

1. 从工作区读取BOOT.md；
2. 通过 agent runner 执行其中的指令；
3. 通过 message 工具发送任何请求的外发消息。

十三、调试与故障排查

钩子未被发现

1. 检查目录结构：ls -la ~/.openclaw/hooks/my-hook/，应包含HOOK.md与handler.ts；
2. 检查 HOOK.md 的 YAML frontmatter 是否含name与metadata；
3. openclaw hooks list确认钩子出现在列表中。

钩子未就绪（not eligible）

运行openclaw hooks info <name>，检查输出中标注✗的缺失项：二进制（PATH）、环境变量、配置值、OS 平台。

钩子未执行

1. openclaw hooks list确认钩子旁显示✓（已启用且就绪）；
2. 重启 Gateway使钩子重新加载；
3. 检查 Gateway 日志中的报错，例如./scripts/clawlog.sh | grep hook（macOS），其他平台tail -f ~/.openclaw/gateway.log。

Gateway 启动时会在日志中打印钩子注册信息，正常时可见：

Registered hook: session-memory -> command:new Registered hook: bootstrap-extra-files -> agent:bootstrap Registered hook: command-logger -> command Registered hook: boot-md -> gateway:startup

Handler 报错

检查 TypeScript/import 错误，可先单独验证模块能否加载：node -e "import('./path/to/handler.ts').then(console.log)"。

十四、最佳实践

保持 Handler 轻量——钩子在命令处理流程中运行，阻塞式慢操作会影响命令处理：

// ✓ 好——异步执行、立即返回（fire and forget） const handler: HookHandler = async (event) => { void processInBackground(event); }; // ✗ 差——阻塞命令处理 const handler: HookHandler = async (event) => { await slowDatabaseQuery(event); await evenSlowerAPICall(event); };

优雅处理错误——用 try/catch 包裹风险操作，不要 throw 阻断其他 handler：

const handler: HookHandler = async (event) => { try { await riskyOperation(event); } catch (err) { console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err)); // 不要 throw，让其他 handler 继续执行 } };

尽早过滤事件——不相关的事件立即 return；使用具体事件键而非通用键（events: ["command:new"]优于events: ["command"]，后者开销更大）。

十五、源码架构速览

• cli/hooks-cli.ts：openclaw hooks全部子命令的注册与格式化实现（formatHooksList/formatHookInfo/formatHooksCheck/enableHook/disableHook）；
• hooks/workspace.ts：目录扫描与加载（bundled / managed / workspace / 插件 / extraDirs 五路发现）；
• hooks/frontmatter.ts：HOOK.md frontmatter 与metadata.openclaw解析；
• hooks/policy.ts：钩子来源优先级与同名覆盖策略、启用状态判定；
• hooks/config.ts：资格评估（shouldIncludeHook、isConfigPathTruthy）；
• hooks/hooks-status.ts：状态报告构建（buildWorkspaceHookStatus）；
• hooks/types.ts：Hook、OpenClawHookMetadata、HookEntry等核心类型；
• hooks/internal-hooks.ts：事件类型定义与钩子运行时（registerHook/triggerHook等）；
• hooks/install.ts / hooks/update.ts / hooks/installs.ts：hook pack 安装、更新与安装记录；
• hooks/bundled/：四个捆绑钩子的 HOOK.md 与 handler 实现；
• 配置类型：config/types.hooks.ts，配置语义说明见 config/schema.help.ts。

事件流示意（以/new为例）：

用户发送 /new ↓ 命令校验 ↓ 创建 hook 事件 ↓ 触发所有已注册 handler ↓ 命令处理继续 ↓ 会话重置（session-memory 等钩子已保存上下文）

十六、补充：Hooks 与 Webhooks / 插件钩子的关系

• Hooks（本文主题）：运行在 Gateway 内部，响应 Agent 命令与生命周期事件；
• Webhooks：外部 HTTP webhook，让其他系统触发 OpenClaw 中的工作（见 docs/automation/webhook.md，Gmail 辅助命令用openclaw webhooks）；
• 插件钩子（Plugin Hooks）：插件可通过api.registerHook(...)在运行时注册钩子，无需单独安装 hook pack；它们显示为plugin:<id>，不能通过 hooks CLI 单独开关，而是随插件整体启用/禁用（docs/tools/plugin.md）。钩子资格规则（OS/bins/env/config）对插件钩子同样生效。

• 人工智能
• 大模型
• LLM 网关
• AI Agent
• 即时通讯