内置 hooks

OpenClaw 随附的钩子，以及每个钩子的行为和选项。本指南是 钩子 指南的一部分。

内置钩子¶

使用 openclaw hooks enable <hook-name> 启用其中一个，并验证其副作用。 仅启动时运行的钩子（例如 boot-md）会等待下一次 Gateway 启动。

boot-md 详情¶

在每个已配置代理的已解析工作区中运行非空的 BOOT.md。 由多个代理共享的工作区只运行一次，且在该工作区选中的第一个代理下运行。启动任务按顺序运行；失败的任务会被记录，并且不会阻止后续任务。

这会通过代理运行来执行指令，而不是作为 shell 脚本，也不是作为引导文件注入。每次运行都会使用一个全新的临时 agent:<id>:boot:<run-id> 会话，并在成功或失败后清理。现有会话及其历史记录会被保留。正常的最终响应投递会被禁用；如果指令需要通知某人，必须为消息工具指定频道和目标。缺失或空文件会被跳过。

保持启动指令简短，并确保每次重启时重复执行都是安全的。它们可以使用模型和工具能力，因此启用此钩子可能会导致模型调用和出站副作用。

bootstrap-extra-files 配置¶

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

优先使用 paths。如果为空，处理器会尝试 patterns，然后尝试 files；这些是替代项，而不是合并后的列表。如果没有 patterns，钩子不会执行任何操作。

路径相对于事件的工作区解析，并且必须始终位于其中，包括符号链接解析之后。仅加载以下基名：AGENTS.md、SOUL.md、IDENTITY.md、USER.md、BOOTSTRAP.md 和 MEMORY.md。

额外文件会经过正常的引导过滤和注入限制。每个文件的读取上限为 2 MiB。注入默认每个文件 20,000 个字符，总计 60,000 个字符，由代理默认值或覆盖项中的 bootstrapMaxChars 和 bootstrapTotalMaxChars 控制；USER.md 有单独的 4,000 个字符上限。重复路径会被移除。子代理仅保留 AGENTS.md；cron 和非私密对话具有额外的上下文/隐私过滤器。使用 /context detail 检查实际注入结果；参见 上下文。

TOOLS.md 不是受支持的运行时引导基名。 openclaw doctor --fix 会归档工作区根目录中的 TOOLS.md，并将自定义内容合并到 AGENTS.md 的 ## Tools 部分。由 patterns 指定的其他 TOOLS.md 文件不会被迁移；请将这些 patterns 指向 AGENTS.md。

command-logger 详情¶

为每个发出的命令事件向 <stateDir>/logs/commands.log 追加一行 JSON。字段包括 timestamp、action、sessionKey、senderId 和 source；缺失的 sender/source 值会变成 unknown。核心会发出 /new、/reset 和 /stop，而不是每个斜杠命令。

处理器会等待追加完成，记录写入错误，并且不发送聊天确认。它不会轮转日志。请为它记录的会话和发送者标识设置适当的访问权限和保留策略。参见 日志检查。

compaction-notifier 详情¶

在压缩前添加一条简短通知，并在压缩成功后添加完成通知。通知可以包含消息数量以及可用时的压缩前/后 token 数量。它们通过压缩调用方的通知回调传递；如果没有能够投递它们的回调，启用钩子并不能保证出现可见消息。只有 before 通知而没有 after 通知，可能表示压缩被跳过、失败或中断，而不是钩子卡住。手动 /compact 不会提供此钩子消息投递回调，因此它不是测试这些通知的可靠方式。

session-memory 详情¶

在 /new、/reset（包括软重置）或自动每日/空闲轮换时，保存已结束会话最近的用户/助手文本。自动轮换会发出 session:auto-reset，而不是合成命令事件。过期检查会在后续回合被接受时进行；这不是一个在会话空闲时于每日边界写入记忆的定时器。

默认产物为 <workspace>/memory/YYYY-MM-DD-HHMM.md，如果该文件名已存在，则添加数字后缀。日期使用 agents.defaults.userTimezone；如果未设置用户时区，则使用进程 TZ；最后回退到主机时区。该文件会记录会话标识以及命令来源或自动重置原因。

该钩子会在重置关闭其活动窗口之前捕获即将结束的对话，然后在后台写入快照。捕获范围限制为 4,096 条已扫描消息和 8 MiB。隐身会话不会创建 memory 工件，包括在手动或自动重置时。 手动重置不会等待文件写入或可选的 slug 模型调用；自动重置分发也会独立于后续轮次运行。在日志中等待 Session context saved to ... 后再预期文件存在。

这是一个经过过滤的摘录，而不是完整转录或模型编写的摘要。它会省略斜杠命令文本、工具消息、跨会话用户输入、 静默回复标记以及重复的投递镜像文本。如果读取转录失败，工件可以记录该内容不可用。工作区从事件/代理配置中解析；你无需添加 workspace.dir 键。

当 llmSlug: true 时，对话文本会发送到已配置的模型以命名文件。失败时会回退到时间戳 slug。如果你不想为命名进行额外的模型调用，请保持关闭。