openclaw hooks

管理 Agent Hooks（事件驱动自动化，用于 /new、/reset 命令和 Gateway 启动等事件）。

相关文档：

• Hooks 概念：Hooks
• 插件 Hooks：Plugin hooks

列出所有 Hooks

openclaw hooks list

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

选项：

• --eligible：只显示符合条件的 Hooks（满足所有要求）
• --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 or /reset command is issued

详细模式：

openclaw hooks list --verbose

显示不符合条件的 Hooks 缺少哪些要求。

JSON 模式：

openclaw hooks list --json

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

查看 Hook 详情

openclaw hooks info <name>

显示特定 Hook 的详细信息。

参数：

• <name>：Hook 名称（例如 session-memory）

选项：

• --json：以 JSON 格式输出

示例：

openclaw hooks info session-memory

输出：

💾 session-memory ✓ Ready

Save session context to memory when /new or /reset 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, command:reset

Requirements:
  Config: ✓ workspace.dir

检查 Hooks 就绪状态

openclaw hooks check

显示 Hook 就绪状态摘要（有多少已就绪，有多少未就绪）。

选项：

• --json：以 JSON 格式输出

示例输出：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

启用 Hook

openclaw hooks enable <name>

通过将其添加到配置（~/.openclaw/config.json）来启用特定 Hook。

注意： 工作区 Hooks 默认禁用，需在此处或在配置中启用。由插件管理的 Hooks 在 openclaw hooks list 中显示 plugin:<id>，无法在此处启用/禁用，请改为启用/禁用对应插件。

参数：

• <name>：Hook 名称（例如 session-memory）

示例：

openclaw hooks enable session-memory

输出：

✓ Enabled hook: 💾 session-memory

执行内容：

• 检查 Hook 是否存在且符合条件
• 在配置中将 hooks.internal.entries.<name>.enabled = true
• 将配置保存到磁盘

如果 Hook 来自 <workspace>/hooks/，必须先完成这个启用步骤，Gateway 才会加载它。

启用后：

• 重启 Gateway 使 Hooks 重新加载（macOS 上重启菜单栏应用，或在开发模式下重启 gateway 进程）。

禁用 Hook

openclaw hooks disable <name>

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

参数：

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

示例：

openclaw hooks disable command-logger

输出：

⏸ Disabled hook: 📝 command-logger

禁用后：

• 重启 Gateway 使 Hooks 重新加载。

安装 Hook 包

openclaw plugins install <package>        # 先从 ClawHub 查找，再从 npm 查找
openclaw plugins install <package> --pin  # 锁定版本
openclaw plugins install <path>           # 从本地路径安装

通过统一的插件安装器安装 Hook 包。

openclaw hooks install 仍然可用，作为兼容性别名，但会打印废弃警告并转发给 openclaw plugins install。

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

裸规范和 @latest 保持在稳定版轨道。如果 npm 将两者解析为预发布版本，OpenClaw 会停止并要求你通过预发布标签（如 @beta/@rc）或精确的预发布版本号明确确认。

执行内容：

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

选项：

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

支持的归档格式： .zip、.tgz、.tar.gz、.tar

示例：

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

# 本地归档
openclaw plugins install ./my-hook-pack.zip

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

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

链接的 Hook 包被视为来自操作员配置目录的托管 Hooks，而非工作区 Hooks。

更新 Hook 包

openclaw plugins update <id>
openclaw plugins update --all

通过统一的插件更新器更新跟踪的基于 npm 的 Hook 包。

openclaw hooks update 仍然可用，作为兼容性别名，但会打印废弃警告并转发给 openclaw plugins update。

选项：

• --all：更新所有跟踪的 Hook 包
• --dry-run：显示将会发生什么变化，但不写入

当存储的完整性哈希与获取的构件哈希不匹配时，OpenClaw 会打印警告并在继续之前请求确认。在 CI/非交互式运行中使用全局 --yes 绕过提示。

内置 Hooks

session-memory

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

启用：

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

养龙虾小技巧：给你的龙虾装上 session-memory Hook，它就会在每次对话结束时自动总结上下文，下次开对话时记忆不丢失——老龙虾才记得住事儿。