OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI 命令

Hooks

openclaw hooks

管理智能体 Hooks（由 /new、/reset 和 Gateway 网关启动等事件驱动的自动化）。不带参数的 openclaw hooks 等同于 openclaw hooks list。

相关：Hooks - 插件钩子

列出 Hooks

bash
openclaw hooks list [--eligible] [--json] [-v|--verbose]

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

  • --eligible：仅显示满足要求的 Hooks。
  • --json：结构化输出。
  • -v, --verbose：包含一列 Missing，显示未满足的要求。
Code
Hooks（4/5 已就绪） 已就绪：  🚀 boot-md ✓ - 在 Gateway 网关启动时运行 BOOT.md  📎 bootstrap-extra-files ✓ - 在智能体引导启动期间注入额外的工作区引导启动文件  📝 command-logger ✓ - 将所有命令事件记录到集中式审计文件  💾 session-memory ✓ - 发出 /new 或 /reset 命令时，将会话上下文保存到记忆

获取 Hook 信息

bash
openclaw hooks info <name> [--json]

<name> 是 Hook 名称或 Hook 键（例如 session-memory）。显示来源、文件/处理程序路径、主页、事件以及各项要求的状态（二进制文件、环境变量、配置、操作系统）。

检查可用性

bash
openclaw hooks check [--json]

输出已就绪/未就绪的数量摘要；如果存在未就绪的 Hooks，则逐一列出及其阻塞原因。

启用 Hook

bash
openclaw hooks enable <name>

在配置中添加或更新 hooks.internal.entries.<name>.enabled = true，同时打开 hooks.internal.enabled 总开关（在至少配置一个内部 Hook 之前，Gateway 网关不会加载任何内部 Hook 处理程序）。如果 Hook 不存在、由插件管理或不满足可用条件（缺少要求），则操作失败。

插件管理的 Hooks 会在 hooks list 中显示 plugin:<id>，无法在此处启用或禁用；请改为启用或禁用其所属插件。

启用后重启 Gateway 网关（重启 macOS 菜单栏应用，或在开发环境中重启 Gateway 网关进程），使其重新加载 Hooks。

禁用 Hook

bash
openclaw hooks disable <name>

设置 hooks.internal.entries.<name>.enabled = false。之后重启 Gateway 网关。

安装和更新 Hook 包

bash
openclaw plugins install <package>        # 默认使用 npmopenclaw plugins install npm:<package>    # 仅使用 npmopenclaw plugins install <package> --pin  # 固定解析后的版本openclaw plugins install <path>           # 本地目录或归档文件openclaw plugins install -l <path>        # 链接本地目录，而非复制 openclaw plugins update <id>openclaw plugins update --allopenclaw plugins update --dry-run

Hook 包通过统一的插件安装器/更新器进行安装；openclaw hooks install / openclaw hooks update 仍可作为已弃用的别名使用，它们会输出警告并转发到 plugins 命令。

  • Npm 说明符仅限注册表：包名加可选的精确版本或 dist-tag。不接受 Git/URL/文件说明符和 semver 范围。依赖项安装在项目本地运行，并使用 --ignore-scripts。
  • 不带版本的说明符和 @latest 保持在稳定通道；如果 npm 解析到预发布版本，OpenClaw 会停止并要求你明确选择加入（@beta、@rc 或精确的预发布版本）。
  • 支持的归档格式：.zip、.tgz、.tar.gz、.tar。
  • -l, --link 链接本地目录，而非复制该目录（将其添加到 hooks.internal.load.extraDirs）；链接的 Hook 包是来自操作员配置目录的托管 Hooks，而不是工作区 Hooks。
  • --pin 将 npm 安装以精确解析后的 name@version 形式记录在 hooks.internal.installs 中。
  • 安装操作会将 Hook 包复制到 ~/.openclaw/hooks/<id>，在 hooks.internal.entries.* 下启用其中的 Hooks，并将安装记录到 hooks.internal.installs。
  • 如果存储的完整性哈希与获取的产物不再匹配，OpenClaw 会发出警告并在继续前提示确认；传入全局 --yes 可跳过提示（例如在 CI 中）。

内置 Hooks

Hook 事件 功能
boot-md gateway:startup Gateway 网关启动时，为每个已配置的智能体作用域运行 BOOT.md
bootstrap-extra-files agent:bootstrap 在智能体引导启动期间注入额外的引导启动文件（例如 monorepo 中的 AGENTS.md/TOOLS.md）
command-logger command 将命令事件记录到 ~/.openclaw/logs/commands.log
compaction-notifier session:compact:before, session:compact:after 在会话压缩开始和完成时发送可见的聊天通知
session-memory command:new, command:reset 在执行 /new 或 /reset 时，将会话上下文保存到记忆

使用 openclaw hooks enable <hook-name> 启用任意内置 Hook。完整详情、配置键和默认值：内置 Hooks。

command-logger 日志文件

bash
tail -n 20 ~/.openclaw/logs/commands.log        # 最近的命令cat ~/.openclaw/logs/commands.log | jq .          # 美化输出grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .   # 按操作筛选

注意事项

  • hooks list --json、info --json 和 check --json 会将结构化 JSON 直接写入标准输出。

相关内容

Was this useful?
On this page

On this page