别再往框架源码里塞逻辑了！Hermes Hooks 钩子一招搞定安全拦截与日志审计
Hermes Agent Hooks 钩子使用教程
写了一个安全过滤逻辑，不知道往哪塞？每次 Agent 执行工具调用都想记录日志，难道要改框架源码？Hermes Agent Hooks（钩子）就是为解决这类问题而生的 生命周期回调系统，允许在智能体运行的关键节点注入自定义逻辑，实现日志审计、安全拦截、消息告警、上下文注入等扩展能力。本文从钩子类型、核心事件、开发流程、实战示例到最佳实践，带你全面掌握 Hooks 用法，灵活扩展 Agent 功能。
一、钩子系统总览
Hermes 提供两套独立钩子系统，覆盖网关与全会话场景，均为非阻塞设计—— 钩子报错不会导致 Agent 崩溃，仅记录日志。
1.1 网关钩子（Gateway Hooks）
-
运行环境：仅网关（TG/Discord/ 飞书等消息平台）生效。
-
注册方式：
~/.hermes/hooks/目录下创建HOOK.yaml+handler.py。 -
核心场景：网关启动、会话管理、命令监控、消息告警。
1.2 插件钩子（Plugin Hooks）
-
运行环境：CLI + 网关全场景生效。
-
注册方式：Python 插件中通过
ctx.register_hook()代码注册。 -
核心场景：工具拦截、LLM 上下文注入、会话生命周期管理。
1.3 核心价值
-
✅ 无侵入扩展：无需修改 Agent 核心代码，按需注入逻辑。
-
✅ 全链路可控：覆盖会话启动、工具调用、LLM 推理、会话结束全流程。
-
✅ 高稳定性：钩子异常自动捕获，不影响主流程。
-
✅ 灵活适配：支持日志、告警、安全、集成等多场景扩展。
图1：钩子系统架构图
graph TB
subgraph "钩子系统总览"
direction TB
GW[网关钩子 Gateway Hooks] -->|仅消息平台| TG[TG]
GW --> DC[Discord]
GW --> FS[飞书 / 钉钉]
PL[插件钩子 Plugin Hooks] -->|CLI + 网关全场景| SH[pre_tool_call 拦截]
PL --> PH[post_tool_call 审计]
PL --> LH[pre_llm_call 注入]
PL --> SH2[on_session_end 清理]
end
subgraph "注册方式"
R1[HOOK.yaml + handler.py<br/>~/.hermes/hooks/ 目录] --> GW
R2[ctx.register_hook<br/>Python 插件代码] --> PL
end
subgraph "设计特点"
N[非阻塞设计<br/>异常自动捕获 不影响主流程]
end
清楚了钩子的整体架构，先从网关钩子入手，看它如何在消息平台中发挥作用。
二、网关钩子（Gateway Hooks）
网关钩子仅在消息平台网关运行，适合监控网关级事件、发送平台告警。