bot/docs/zh-CN/cli/hooks.md

read_when, summary, title, x-i18n

read_when	summary	title	x-i18n
你想管理智能体钩子 你想安装或更新钩子	CLI 参考：`bot hooks`（智能体钩子）	hooks	generated_at model provider source_hash source_path workflow 2026-02-03T10:04:32Z claude-opus-4-5 pi e2032e61ff4b9135cb2708d92eb7889ac627b85a5fc153e3d5b84265f7bd7bc6 cli/hooks.md 15

bot hooks

管理智能体钩子（针对 /new、/reset 等命令以及 Gateway 网关启动的事件驱动自动化）。

相关内容：

• 钩子：钩子
• 插件钩子：插件

列出所有钩子

bot hooks list

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

选项：

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

示例输出：

Hooks (3/3 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

示例（详细模式）：

bot hooks list --verbose

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

示例（JSON）：

bot hooks list --json

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

获取钩子信息

bot hooks info <name>

显示特定钩子的详细信息。

参数：

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

选项：

• --json：以 JSON 格式输出

示例：

bot hooks info session-memory

输出：

💾 session-memory ✓ Ready

Save session context to memory when /new command is issued

Details:
  Source: bot-bundled
  Path: /path/to/bot/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/bot/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.hanzo.bot/automation/hooks#session-memory
  Events: command:new

Requirements:
  Config: ✓ workspace.dir

检查钩子资格

bot hooks check

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

选项：

• --json：以 JSON 格式输出

示例输出：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

启用钩子

bot hooks enable <name>

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

注意： 由插件管理的钩子在 bot hooks list 中显示 plugin:<id>， 无法在此处启用/禁用。请改为启用/禁用该插件。

参数：

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

示例：

bot hooks enable session-memory

输出：

✓ Enabled hook: 💾 session-memory

执行操作：

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

启用后：

• 重启 Gateway 网关以重新加载钩子（macOS 上重启菜单栏应用，或在开发环境中重启 Gateway 网关进程）。

禁用钩子

bot hooks disable <name>

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

参数：

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

示例：

bot hooks disable command-logger

输出：

⏸ Disabled hook: 📝 command-logger

禁用后：

• 重启 Gateway 网关以重新加载钩子

安装钩子

bot hooks install <path-or-spec>

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

执行操作：

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

选项：

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

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

示例：

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

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

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

# 链接本地目录而不复制
bot hooks install -l ./my-hook-pack

更新钩子

bot hooks update <id>
bot hooks update --all

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

选项：

• --all：更新所有已跟踪的钩子包
• --dry-run：显示将要进行的更改，但不写入

内置钩子

session-memory

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

启用：

bot hooks enable session-memory

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

参见： session-memory 文档

command-logger

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

启用：

bot hooks enable command-logger

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

查看日志：

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

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

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

参见： command-logger 文档

boot-md

在 Gateway 网关启动时（渠道启动后）运行 BOOT.md。

事件：gateway:startup

启用：

bot hooks enable boot-md

参见： boot-md 文档