Hook 配置与发现

启用并选择内部钩子，以及 Gateway 如何跨来源发现它们。属于 钩子 指南的一部分。

配置¶

为了获得可预测的选择，请启用命名钩子，而不是开启广泛发现：

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

目录加载钩子的主开关和选择规则如下：

工作区钩子始终需要 entries.<hookKey>.enabled: true，即使处于开放式发现中。对于其他文件钩子，条目可以通过其名称或 hookKey 选择，但设置会在 hookKey 下读取。CLI 会解析名称并为你写入正确的键。添加第一个命名条目可能会缩小之前较宽泛的选择；在更改之前请检查现有钩子。

每个钩子的条目接受任意处理器定义的字段。核心类型包括 enabled 为布尔值，以及 env 为字符串到字符串的映射；它不会校验自定义处理器选项。例如：

{
  "hooks": {
    "internal": {
      "entries": {
        "my-hook": {
          "enabled": true,
          "env": { "MY_HOOK_LABEL": "example" }
        }
      }
    }
  }
}

每个钩子的 env 可满足资格检查，但不会修改 process.env。 在携带配置的事件中，处理器可以从 event.context.cfg?.hooks?.internal?.entries?.["my-hook"]?.env 读取它。其他事件不 保证提供 cfg 字段。不要记录完整的配置对象，也不要在示例中放入机密信息。

钩子发现¶

目录发现按名称合并钩子，规则如下：

内置、托管、工作区和插件钩子位置都是集合目录：发现过程会检查它们的直接子项，以查找钩子或在其 package.json 中声明 openclaw.hooks 的包。

每个显式的 hooks.internal.load.extraDirs 路径也可以是包根目录、 单钩子根目录或集合目录。包根目录只加载其声明的钩子路径，包括 ./hooks/my-hook 这样的嵌套路径。每个 路径必须直接指向一个钩子；发现过程不会递归进入另一个 包或集合。一个被识别但没有有效钩子的包会保持为空，而不是 扫描未列出的子项。单钩子根目录会加载其自身的 HOOK.md 和处理器。只有普通集合根目录才会执行直接子项扫描。

例如，若要直接选择 /opt/openclaw-hook-library/my-hook/HOOK.md，请添加该钩子的目录：

{
  "hooks": {
    "internal": {
      "load": {
        "extraDirs": ["/opt/openclaw-hook-library/my-hook"]
      }
    }
  }
}

若要改为扫描库的直接子项，请添加 /opt/openclaw-hook-library。仅添加受信任的目录：任何额外路径都会启用跨发现源、超出命名条目的钩子名称选择， 即使该路径只选择单个钩子或包。 处理器文件必须保留在其钩子目录内；包和插件钩子路径必须保留在其包根目录内。逃逸这些边界的 符号链接将被拒绝。钩子配置和已选择工作区的变更会在 hybrid 模式下重新加载发现，包括由新钩子包安装或链接写入的配置。钩子 文件和元数据不会被监视；在编辑它们或更新现有钩子代码后请重启，然后验证处理器的实际副作用。

钩子包¶

钩子包是一种在 package.json 的 openclaw.hooks 中声明钩子目录的包。通过统一安装器安装已审核的包或本地目录：

openclaw plugins install <path-or-spec>

安装和更新标志、npm 限制、链接根目录的行为和信任，以及已弃用的 hooks install / hooks update 别名，详见 安装和更新钩子包。