hermes agent 的 hook 机制支持 pre-chat、post-skill、on-error、on-output 四类事件钩子，可通过配置文件全局注册、profile 级动态绑定或命令行实时管理，并要求脚本按 json 标准收发上下文。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在 Hermes Agent 中实现特定事件触发时自动执行定制化操作，例如在每次会话开始前加载用户偏好、在技能调用失败后启动回滚流程、或在模型输出含敏感词时自动拦截并重写，则需借助其内置的 Hook 机制。以下是配置与使用 Hook 的多种方式：
一、理解 Hook 机制的作用范围与触发时机
Hermes Agent 的 Hook 是一种轻量级事件监听器，嵌入于核心执行生命周期中，不修改主逻辑，但可在关键节点插入自定义行为。它支持 pre-chat、post-skill、on-error、on-output 四类标准钩子，每个钩子对应一个可执行的 Shell 脚本或 Python 模块路径，由 Hermes 在运行时动态加载并调用。
1、Hook 脚本必须具有可执行权限（Linux/macOS）或符合 Python 模块导入规范（如 __init__.py 存在）。
2、脚本返回非零退出码或抛出异常时，Hermes 将中断当前流程并进入错误处理分支。
3、所有 Hook 执行均在独立子进程沙盒中运行，与主 Agent 进程隔离，保障系统稳定性。
二、通过配置文件注册全局 Hook
该方法适用于对所有 Profile 统一启用的基础逻辑，如日志审计、输出脱敏等。配置项直接写入 ~/.hermes/.env 文件，无需重启 Agent 即可热生效（部分 Hook 需新会话生效）。
1、打开终端，执行命令编辑配置：vim ~/.hermes/.env。
2、在文件末尾新增以下行（以 post-output 脱敏为例）：HERMES_HOOK_POST_OUTPUT="/opt/hermes/hooks/sanitize_output.py"。
3、保存退出后，执行 hermes config reload 使配置立即加载。
4、验证是否注册成功：hermes config show | grep HOOK，应显示对应路径。
三、为单个 Profile 动态绑定 Hook
该方法适合差异化业务场景，例如为“finance” Profile 启用交易风控检查，而“marketing” Profile 启用文案合规校验。Hook 绑定仅对该 Profile 生效，切换 Profile 后自动切换逻辑。
1、确保已创建目标 Profile，例如：hermes profile create finance。
2、进入该 Profile 的配置目录：cd ~/.hermes/profiles/finance。
3、新建 hook.yaml 文件，内容如下：pre-skill: ./hooks/check_balance.sh\non-error: ./hooks/alert_finance_team.py。
4、将对应脚本放入 ./hooks/ 目录，并赋予执行权限：chmod +x ./hooks/check_balance.sh。
5、切换至该 Profile 并测试：hermes profile use finance && hermes chat "发起一笔转账"。
四、使用 /hook 命令行工具实时管理 Hook
该方法适用于调试阶段快速启停、替换或查看 Hook 状态，无需编辑文件或切换上下文，所有操作即时生效于当前会话。
1、列出当前会话已激活的 Hook：hermes hook list。
2、临时禁用某类 Hook（如屏蔽所有输出处理）：hermes hook disable post-output。
3、为当前会话注入一次性 Hook（仅本次 chat 有效）：hermes hook inject on-output "/tmp/debug_print.py"。
4、查看某 Hook 的最近三次执行日志：hermes hook log on-output --limit 3。
五、编写自定义 Hook 脚本的最小可行结构
无论 Shell 或 Python，Hermes 要求 Hook 脚本接收标准输入（stdin）传递的 JSON 上下文，并将处理结果以 JSON 格式写入标准输出（stdout）。输入结构包含 event_type、session_id、payload 等字段，输出必须含 status（success/error）和 optional message 字段。
1、Shell Hook 示例（/opt/hermes/hooks/log_session.sh）第一行必须为：#!/bin/bash。
2、读取输入：context=$(cat)；解析 session_id：sid=$(echo "$context" | jq -r '.session_id')。
3、执行业务逻辑（如记录到本地日志）：echo "$(date): $sid triggered $(echo "$context" | jq -r '.event_type')" >> /var/log/hermes/session.log。
4、输出标准响应：echo '{"status": "success", "message": "logged"}'。
