钩子¶

内部钩子是小型 JavaScript 或 TypeScript 处理器，当 OpenClaw 发出事件时，在 Gateway 进程中运行。使用它们来保存会话上下文、记录重置命令，或在消息和会话生命周期事件期间执行短暂的副作用。OpenClaw 包含用于常见任务的捆绑钩子；你无需编写插件即可使用它们。

选择正确的接口¶

你想要…	使用
在 `/new` 时保存上下文、记录命令，或响应会话和消息事件	内部钩子（`HOOK.md` 加一个处理器），本文描述
修改 Prompt、拦截工具、控制回复，或使用带优先级和返回值的生命周期契约	通过 `api.on(...)` 使用插件钩子
让另一个服务通过 HTTP 请求开始工作	Webhooks
导出遥测数据而不是更改行为	诊断事件

这些是相互独立的系统。hooks.internal 配置本页的事件处理器；hooks.enabled 配置 HTTP 入口。内部事件名称（如 message:received）不是类型化插件名称（如 message_received）。

Warning

内部钩子是受信任的代码，而不是沙箱脚本。它们以 Gateway 进程的文件系统、网络和环境访问权限运行。在启用钩子代码之前请审查它，尤其是来自工作区或下载的包的代码。

快速开始¶

从 command-logger 开始：它不需要额外的二进制文件或模型调用，并给你一个可检查的具体文件。在 Gateway 主机 上运行以下命令，并使用与该 Gateway 相同的配置档和配置：

openclaw hooks list
openclaw hooks info command-logger
openclaw hooks enable command-logger

默认 hybrid 重载模式会在不重启的情况下应用钩子配置更改。如果重载模式为 off，请运行 openclaw gateway restart，或自行重启前台 Gateway。当你的配置包含多个代理且没有隐式所有者时，添加 --agent <id>。

在可以安全重置的对话中，以授权用户身份发送 /new 或 /reset。然后在 Gateway 主机上检查日志：

tail -n 5 ~/.openclaw/logs/commands.log

查找一条新的 JSON 行，其中包含 "action":"new" 或 "action":"reset"、最近的 timestamp，以及该对话的 sessionKey。如果使用自定义状态目录，请改为读取 <stateDir>/logs/commands.log。这可以证明某个处理器已运行；仅运行 openclaw hooks check 不能证明。

日志包含会话和发送者标识符。如果你不想保留这些记录，请在试用后禁用该钩子：

openclaw hooks disable command-logger

符合条件、已启用和已加载¶

保持这三项检查相互独立：

要求已满足：钩子的 OS、二进制文件、环境和配置要求在执行检查的主机上通过。
由配置启用：每个钩子/来源的策略允许它。工作区钩子需要显式选择加入；当启用广泛发现时，捆绑钩子和托管钩子不需要该每个钩子的标志。
已加载：正在运行的 Gateway 已选择该钩子、导入其处理器并注册其事件。这也要求主开关和已配置的名称选择允许它。

CLI 的 ready、eligible 和 loadable 字段描述前两项检查以及非空事件列表。它们不能证明 Gateway 已导入处理器、全局选择包含它，或其事件已触发。更改后，请检查实际副作用或特定于钩子的日志。

配置重载会先准备所选处理器，再一起替换它们。如果某个所选处理器无法加载，则之前的处理器保持活动状态。已经运行的事件会以其原始处理器完成；后续事件使用新选择。重载不会重放 gateway:startup。

本地、远程和代理范围¶

hooks list、info 和 check 请求所选 Gateway 的清单。隐式本地 Gateway 在不可用或缺少报告方法时，可以回退到本地发现。已配置的远程 Gateway 或显式 OPENCLAW_GATEWAY_URL 在失败时不会回退到你笔记本电脑上的钩子。

hooks enable 和 hooks disable 始终检查并修改本地配置。它们不会通过 RPC 更新远程 Gateway。请在 Gateway 主机上运行它们，以更改该主机的钩子。

--agent <id> 选择要检查的工作区，而不是一个隔离的钩子注册表。保存的 hooks.internal.entries.<hookKey> 条目是全局的。Gateway 会将其所选工作区中的目录钩子加载到进程范围的注册表中；它不会仅仅因为你检查了某个代理的 hooks/ 目录就加载每个代理的 hooks/ 目录。当已加载的处理器只应对某个特定代理生效时，它必须过滤事件的代理或会话。参见钩子发现。

插件钩子¶

插件管理的内部钩子在 hooks list 中显示为 plugin:<id>。它们参与此事件系统，但你启用或禁用的是所属插件，而不是使用 hooks enable 或 hooks disable 切换它们。目录加载器的已配置名称选择不是类型化 api.on 钩子的策略门，也不是插件激活的替代。

旧版 api.registerHook API 注册内部事件。它不会调用类型化生命周期名称，例如 before_tool_call、message_received 或 session_start；注册这些名称会发出警告，引导作者使用 api.on(...)。对于需要类型化生命周期控制的新集成，请使用插件钩子参考。

最佳实践¶

同一事件的处理程序按顺序运行：先运行 family 监听器，再运行 exact 监听器，每组内按注册顺序运行。调度器会等待每个处理程序，捕获并记录抛出的错误，然后继续后续处理程序。目录钩子没有优先级选项。

这种顺序执行不会串行化不同事件。消息通知、补丁通知和自动重置工作可能与其他事件及代理处理重叠。没有通用的处理程序超时、取消信号、持久事件队列、自动重试或恰好一次保证。重启或进程退出可能丢失进行中的工作。

保持副作用简短且有界。等待属于该处理程序的工作完成，为网络调用设置超时，限制数据大小，并使可重复操作具备幂等性。不要将 void doHeavyWork(event) 作为通用解决方案：该工作会脱离处理程序的等待/错误边界，并可能比其会话或进程存活更久。如果工作需要持久的作业生命周期，请使用拥有它的自动化或服务。

尽早过滤无关事件，并避免记录消息正文、完整配置对象或凭据。消息和会话数据可能是私密的。仅保留副作用所需的最小数据，保护输出文件，并设置保留策略。长生命周期定时器、监视器、套接字和客户端应属于具有明确关闭生命周期的插件服务，而不是请求/事件处理程序。

CLI 参考¶

有关所有公开报告和切换选项、JSON 输出字段、退出行为以及安装/更新别名，请参阅 openclaw hooks。

详细主题¶

这些页面包含参考和指南材料，它们此前位于本页的快速入门之后。

页面	阅读时机
编写钩子	你正在编写钩子，需要文件布局、处理程序契约或 `HOOK.md` 字段。
钩子配置与发现	你正在启用钩子、缩小选择范围，或跨来源追踪发现过程。
内置钩子	你想要一个随附钩子，并需要其行为、选项和检查。
钩子事件类型与上下文	你需要某个事件键的触发条件、等待行为或上下文字段。
钩子故障排查	钩子未被发现、不符合条件或未执行。

各章节迁移位置¶

前一版单页版本中的每个章节标题都在此处保留其锚点，因此诸如 /automation/hooks#session-memory 之类的现有链接仍然可以解析。每个条目指向现在承载该内容的页面。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw

钩子¶