openclaw hooks

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

相关：

  • 钩子（Hooks）：钩子
  • 插件钩子（Plugin hooks）：插件

列出所有钩子（List All Hooks）

openclaw hooks list

列出从工作区、管理和捆绑目录发现的所有钩子。

选项：

  • --eligible：仅显示符合条件的钩子（满足要求）
  • --json：输出为 JSON
  • -v, --verbose：显示详细信息，包括缺失的要求

示例输出：

Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new command is issued
  😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance

示例（详细）：

openclaw hooks list --verbose

显示不符合条件的钩子的缺失要求。

示例（JSON）：

openclaw hooks list --json

返回结构化 JSON 供程序化使用。

获取钩子信息（Get Hook Information）

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/hooks#session-memory
  Events: command:new

Requirements:
  Config: ✓ workspace.dir

检查钩子资格（Check Hooks Eligibility）

openclaw hooks check

显示钩子资格状态摘要（有多少就绪与未就绪）。

选项：

  • --json：输出为 JSON

示例输出：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

启用钩子（Enable a Hook）

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 进程）。

禁用钩子（Disable a Hook）

openclaw hooks disable <name>

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

参数：

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

示例：

openclaw hooks disable command-logger

输出：

⏸ Disabled hook: 📝 command-logger

禁用后：

  • 重启 gateway 以便钩子重新加载

安装钩子（Install Hooks）

openclaw hooks install <path-or-spec>

从本地文件夹/归档或 npm 安装钩子包。

它的作用：

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

选项：

  • -l, --link：链接本地目录而不是复制（将其添加到 hooks.internal.load.extraDirs）

支持的归档： .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

更新钩子（Update Hooks）

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

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

选项：

  • --all：更新所有跟踪的钩子包
  • --dry-run：显示将要更改的内容而不写入

捆绑钩子（Bundled Hooks）

session-memory

当您发出 /new 时保存会话上下文到内存。

启用：

openclaw hooks enable session-memory

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

参见： session-memory 文档

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 文档

soul-evil

在清除窗口期间或通过随机机会将注入的 SOUL.md 内容替换为 SOUL_EVIL.md。

启用：

openclaw hooks enable soul-evil

参见： SOUL Evil Hook

boot-md

当 gateway 启动时运行 BOOT.md（在渠道启动后）。

事件：gateway:startup

启用：

openclaw hooks enable boot-md

参见： boot-md 文档

← 返回文档首页