openclaw hooks

管理 Agent 钩子（针对 /new、/reset 等命令和 Gateway 启动的事件驱动自动化）。

相关文档：

列出所有钩子

openclaw hooks list

列出从工作区、托管和内置目录中发现的所有钩子。

选项：

  • --eligible：只显示满足条件的钩子
  • --json：以 JSON 格式输出
  • -v, --verbose：显示详细信息，包括缺失的依赖

输出示例：

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

详细模式示例：

openclaw hooks list --verbose

显示不满足条件的钩子缺少哪些依赖。

JSON 输出示例：

openclaw hooks list --json

返回结构化 JSON，方便程序化使用。

查看钩子信息

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

检查钩子就绪状态

openclaw hooks check

显示钩子就绪状态的汇总（多少已就绪 vs. 未就绪）。

选项：

  • --json：以 JSON 格式输出

输出示例：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

启用钩子

openclaw hooks enable <name>

通过将钩子添加到配置中（~/.openclaw/config.json）来启用它。

注意： 由插件管理的钩子在 openclaw hooks list 中显示为 plugin:<id>，不能在这里启用/禁用。请改为启用/禁用对应的插件。

参数：

  • <name>：钩子名称（如 session-memory）

示例：

openclaw hooks enable session-memory

输出：

✓ Enabled hook: 💾 session-memory

具体行为：

  • 检查钩子是否存在且满足条件
  • 在配置中更新 hooks.internal.entries.<name>.enabled = true
  • 保存配置到磁盘

启用后：

  • 重启 Gateway 让钩子生效（macOS 上重启菜单栏应用，或重启你的 Gateway 进程）。

禁用钩子

openclaw hooks disable <name>

通过更新配置来禁用特定钩子。

参数：

  • <name>：钩子名称（如 command-logger）

示例：

openclaw hooks disable command-logger

输出：

⏸ Disabled hook: 📝 command-logger

禁用后：

  • 重启 Gateway 让变更生效

安装钩子

openclaw hooks install <path-or-spec>
openclaw hooks install <npm-spec> --pin

从本地文件夹/压缩包或 npm 安装钩子包。

npm 规格仅限注册表（包名 + 可选的精确版本或 dist-tag）。Git/URL/文件规格和语义版本范围会被拒绝。依赖安装使用 --ignore-scripts 以确保安全。

裸规格和 @latest 走稳定轨道。如果 npm 将它们解析为预发布版本，OpenClaw 会停下来要求你用预发布标签（如 @beta/@rc）或精确的预发布版本号来显式确认。

具体行为：

  • 将钩子包复制到 ~/.openclaw/hooks/<id>
  • 在 hooks.internal.entries.* 中启用已安装的钩子
  • 在 hooks.internal.installs 中记录安装信息

选项：

  • -l, --link：链接本地目录而不是复制（添加到 hooks.internal.load.extraDirs）
  • --pin：将 npm 安装记录为精确解析的 name@version 到 hooks.internal.installs

支持的压缩格式： .zip、.tgz、.tar.gz、.tar

示例：

# 本地目录
openclaw hooks install ./my-hook-pack

# 本地压缩包
openclaw hooks install ./my-hook-pack.zip

# NPM 包
openclaw hooks install @openclaw/my-hook-pack

# 链接本地目录（不复制）
openclaw hooks install -l ./my-hook-pack

更新钩子

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

更新已安装的钩子包（仅限 npm 安装）。

选项：

  • --all：更新所有已跟踪的钩子包
  • --dry-run：显示会发生什么变更但不实际写入

当存在已存储的完整性哈希且获取的包哈希发生变化时，OpenClaw 会打印警告并请求确认后再继续。在 CI/非交互式运行中可以用全局 --yes 跳过提示。

内置钩子

session-memory

在你执行 /new 时将会话上下文保存到记忆中。

启用：

openclaw hooks enable session-memory

输出： ~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md

参见： session-memory 文档

bootstrap-extra-files

在 agent:bootstrap 期间注入额外的引导文件（例如 monorepo 本地的 AGENTS.md / TOOLS.md）。

启用：

openclaw hooks enable bootstrap-extra-files

参见： bootstrap-extra-files 文档

command-logger

将所有命令事件记录到一个集中的审计文件中。

启用：

openclaw hooks enable command-logger

输出： ~/.openclaw/logs/commands.log

查看日志：

# 最近的命令
tail -n 20 ~/.openclaw/logs/commands.log

# 格式化输出
cat ~/.openclaw/logs/commands.log | jq .

# 按操作过滤
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

参见： command-logger 文档

boot-md

Gateway 启动时（频道启动之后）运行 BOOT.md。

事件：gateway:startup

启用：

openclaw hooks enable boot-md

参见： boot-md 文档

arrow_back
上一页
Health
下一页
Logs
arrow_forward