openclaw hooks¶
检查并配置内部钩子：用于命令、
消息、会话和 Gateway 事件的处理程序。单独运行 openclaw hooks 会执行与
openclaw hooks list 相同的报告。这些命令不会管理 HTTP
Webhooks，也不会管理插件钩子中的类型化 api.on(...) 钩子目录。
目标与范围¶
只读报告（hooks、list、info、check）会先在所选 Gateway 上调用 hooks.status。已配置的远程 Gateway 和显式指定的
OPENCLAW_GATEWAY_URL 目标具有权威性：远程 URL 缺失、
连接/身份验证失败以及不支持的方法会直接失败，而不是
显示客户端本地钩子。隐式选择的本地 Gateway 在不可用或其钩子报告方法/agent
参数不受支持时，可以回退到本地发现。其他错误不会被静默替换为本地
清单。
启用、禁用、安装和更新会修改本地文件/配置/状态。 它们不会
通过 RPC 更改远程 Gateway。若要更改服务器，请在该主机上运行命令，并使用其 profile/配置。由新安装或链接写入的启用、禁用和配置可以在默认 hybrid
重载模式中立即生效。off 需要手动
重启。钩子文件和元数据不会被监视。编辑它们或更新现有钩子代码后，请重启。
--agent <id> 选择用于检查的 agent 工作区。当已配置的 agent 没有隐式所有者时，它是必需的。空白或未知 ID
会失败。该选项可以在 list、info、check、enable 和
disable 之前或之后使用。它不会将持久化的钩子条目限定到该 agent，并且不支持在 install/update 中使用。参见
本地、远程和 agent 范围
了解工作区清单与 Gateway 加载之间的区别。
列出钩子¶
openclaw hooks [--agent <id>] [--json]
openclaw hooks list [--agent <id>] [--eligible] [--json] [-v|--verbose]
发现包括捆绑钩子、活动插件钩子、受管钩子、额外 目录以及所选工作区。钩子名称冲突遵循 源策略。
| 选项 | 含义 |
|---|---|
--agent <id> |
选择要检查的工作区。 |
--eligible |
仅显示 loadable 钩子：按每个钩子/源策略启用、满足要求，并且至少声明了一个事件。 |
--json |
将结构化 JSON 直接写入 stdout。父级 hooks 命令也接受该选项。 |
-v, --verbose |
在人类可读表格中添加 Missing 列。 |
人类可读输出是一个包含 Status、Hook、Description 和 Source 列的表格，
前面带有 Hooks (<ready>/<total> ready)。插件管理的源显示为
plugin:<id>。
Note
ready、eligible 和 loadable 是清单结果，而不是实时处理程序
注册检查。该报告不会应用 Gateway 的主开关或
配置名称选择，不会导入处理程序以证明其可用，也不会验证
事件是否已运行。即使内部钩子
系统处于关闭状态，捆绑钩子也可能显示为 ready。启用目标钩子并
验证其真实副作用。
列出 JSON¶
根对象包含 workspaceDir、managedHooksDir 和 hooks。
每个钩子包括：
- 标识/显示：
name、description、source、可选pluginId、emoji、homepage和managedByPlugin。 - 状态：
enabledByConfig、requirementsSatisfied、loadable、可选blockedReason，以及兼容性别名eligible（loadable）和disabled（!enabledByConfig）。 - 事件/要求：
events、unknownEvents和missing，其数组 为bins、anyBins、env、config和os。
blockedReason 可以是 disabled in config、workspace hook (disabled by default)、
missing requirements 或 no events defined。未知事件是
建议性的：它们本身不会使钩子无法加载。
获取钩子信息¶
接受钩子名称或其元数据 hookKey。精确的钩子名称优先于
匹配的键。一个键必须标识单个钩子。显示源、描述符
和处理程序路径、主页、事件、未知事件警告、阻止原因以及
每个要求的状态。缺失或歧义的钩子以代码 1 退出。歧义选择器会列出候选项，以便你选择唯一的名称或键。
JSON 包含列表字段，外加 filePath、baseDir、handlerPath、
hookKey、always、requirements、configChecks 和规范化后的 install
选项。每个配置检查具有 path 和 satisfied。每个安装选项具有
id、kind、label 和 bins。安装选项是描述性元数据，而不是
自动安装依赖项的命令。
检查资格¶
打印 ready/not-ready 钩子的总数，并列出阻止原因。JSON 包含
total、eligible、notEligible 和 hooks，其中包含一个 eligible 名称
数组和一个 notEligible 数组，数组元素为 { name, blockedReason?, missing } 对象。
即使钩子未就绪，成功报告也会以代码 0 退出。对于 自动化资格检查，应检查 JSON 计数，而不是将 退出代码视为所有钩子均已就绪的结果。这仍然不会测试实际加载。
启用钩子¶
在本地发现钩子，然后在本地配置中写入
hooks.internal.entries.<hookKey>.enabled = true 和
hooks.internal.enabled = true。该条目中的其他字段会
保留。精确的钩子名称优先于匹配的键。歧义的键
匹配会失败且不写入。
对于缺失的钩子、插件托管的钩子或未满足的运行时要求，启用操作会失败。它可以启用当前已禁用的工作区钩子。这并不证明存在有效的模块导出或事件订阅。也请检查 info 和 Gateway 日志。
该条目是全局的，即使使用 --agent：无论在哪里发现该键，它都会生效。添加命名条目可以缩小先前开放式目录选择的范围。参见配置。
运行中的 Gateway 会在 hybrid 模式下重新加载选择。如果选定的钩子无法加载，它会保留之前的处理器。请检查 Gateway 日志。重新加载不会重放 gateway:startup，因此 boot-md 会在下次 Gateway 启动时运行。
禁用钩子¶
写入 hooks.internal.entries.<hookKey>.enabled = false。它不会删除钩子文件，也不会更改主开关。缺失/不明确的钩子和插件托管的钩子会被拒绝。缺少运行时要求不会阻止禁用操作。在 hybrid 模式下，后续事件会使用更新后的选择。已运行的事件会使用其原始处理器完成。
插件托管的钩子不能通过这些命令切换。请通过 openclaw plugins 启用或禁用所属插件。
安装和更新钩子包¶
使用统一的插件安装程序来安装经过审核的钩子包：
openclaw plugins install npm:<package>
openclaw plugins install npm:<package>@<version> --pin
openclaw plugins install ./my-hook-pack
openclaw plugins install ./my-hook-pack.tgz
openclaw plugins update <id> --dry-run
openclaw plugins update <id>
包在 package.json 的 openclaw.hooks 下声明钩子目录。没有 package.json 的本地目录可以包含单个 HOOK.md 和处理器。复制的钩子包会安装到 <stateDir>/hooks/<id>。它们的钩子会在配置中启用，安装来源记录在共享的 SQLite 状态中。该配置可以立即在 hybrid 模式下激活钩子。不要在 openclaw.json 中编写 hooks.internal.installs。
对于 npm 钩子包路径，spec 仅限 registry：包名加上可选的精确版本或 dist-tag。Git/URL/文件 spec、npm 别名和 semver 范围不属于 npm registry spec。裸 spec 和 @latest 保持在稳定轨道上。预发布解析需要显式的预发布版本或非 latest 标签，例如 @beta 或 @rc。使用 npm: 显式选择 npm。统一安装程序支持 openclaw plugins 中描述的其他插件来源。
支持的本地存档格式有 .zip、.tgz、.tar.gz 和 .tar。复制的钩子包会从 dependencies 和 optionalDependencies 中解析运行时包，包括仅包含可选依赖的包。仅列在 devDependencies 中的包会被省略。npm pack 和依赖安装使用 --ignore-scripts。这不会对已安装的处理器进行沙箱隔离。无论 npm 的 dry-run 或 pack-destination 设置如何，下载始终会在 OpenClaw 的临时工作区中创建存档。
安装选项与信任¶
| 选项 | 对钩子包的效果 |
|---|---|
-l, --link |
将确切的本地钩子或包根目录添加到 hooks.internal.load.extraDirs，而不是复制它。支持单个钩子和嵌套包布局。 |
--pin |
在可用时将解析出的精确 npm name@version 记录到安装状态中；不适用于本地路径。 |
--force |
确认非 ClawHub 来源，并允许替换现有的已复制安装。对于链接，它确认来源但不进行复制。 |
--acknowledge-install-policy-warning |
确认操作员的 security.installPolicy 警告，无需提示。阻止安装和策略失败仍会停止安装。 |
交互式非 ClawHub 安装会要求您确认信任。非交互式安装需要 --force。plugins install 和 hooks install 别名都不接受 --yes 标志。--force 也不能替代确认安装策略警告。在提供任一确认之前，请先审查来源。
Warning
链接的钩子直接从提供的路径运行。链接不会复制它或创建符号链接。单个钩子根目录会加载自己的 HOOK.md 和处理器。包只会加载 openclaw.hooks 中列出的钩子目录，包括 ./hooks/my-hook 等嵌套路径。声明的路径必须保持在包内部，并直接指向钩子。发现机制不会递归到嵌套包或集合中，也不会扫描未列出的子项，即使所有声明的路径都被拒绝。
只链接受信任的代码。额外的目录仍然会使目录钩子名称选择跨发现来源保持开放式，而不仅仅是在链接的包内。链接可以立即在 hybrid 模式下激活钩子。编辑现有钩子代码或元数据后请重新启动，检查 hooks list，并验证处理器的实际副作用。
更新行为¶
更新使用跟踪的 npm 安装记录。已跟踪的钩子包 ID 使用其存储的 spec。匹配的 npm 包 spec 可以选择新版本/标签。本地路径和存档记录不会被 npm 钩子更新程序刷新。
--dry-run 会报告将要更改的内容，而不会安装或重写配置。--all 在统一更新程序中选择插件和钩子包，包括通过已弃用的别名访问时。它不是仅限钩子的批量命令。
当适用的存储完整性哈希与下载的工件不同时，更新程序会发出警告并在终端中要求确认。没有 CLI 标志可以回答该提示：plugins update 和 hooks update 别名都不接受 --yes，而 --acknowledge-install-policy-warning 仅涵盖安装策略警告。--dry-run 会在不提示的情况下报告差异。
弃用别名¶
这些命令会打印一条弃用警告，并转发到统一的 owners：
openclaw hooks install <path-or-spec> [-l|--link] [--pin] [--force] [--acknowledge-install-policy-warning]
openclaw hooks update [id] [--all] [--dry-run] [--acknowledge-install-policy-warning]
对于 update，请提供 id 或 --all。这些别名不接受 --agent，也不是新自动化的首选接口。
内置钩子¶
维护的目录、事件订阅、选项和验证说明位于 内置钩子。其中包括 boot-md、bootstrap-extra-files、command-logger、compaction-notifier 和 session-memory（手动和自动重置捕获）。
command-logger 日志文件¶
在 Gateway 主机上，使用默认状态目录：
tail -n 20 ~/.openclaw/logs/commands.log
jq . ~/.openclaw/logs/commands.log
jq 'select(.action == "new")' ~/.openclaw/logs/commands.log
对于自定义状态目录，请使用 <stateDir>/logs/commands.log。这些记录包含会话和发送者标识符。请保护访问权限，并安排保留或轮转。该钩子不会轮转这些日志。
备注¶
报告命令支持 --json。成功的 JSON 会直接输出到 stdout。失败时使用标准的 CLI JSON 失败封装，缺失的钩子信息还会包含所请求的 hook 名称。报告命令不会将钩子作为测试执行。
隐藏的 hooks relay 命令保留用于生成的原生 harness 集成。它不是内部钩子测试命令，也不是手动事件触发命令。
相关¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw