大多数钩子都是“发出即不管”的:它们在后台运行,不会阻塞 Enconvo。智能体运行期间,
PreToolUse、Stop 和 SubagentStop 是例外。智能体会等待它们完成,因此它们可以阻止一次工具调用,或让智能体返回继续工作。参见阻塞式钩子。快速开始
1
创建 hooks 文件夹
2
创建 ~/.enconvo/hooks.json
3
触发智能体
启动任意智能体或聊天命令。当它的状态变化时,Enconvo 会运行配置的命令,并向
/tmp/enconvo-hooks.log 追加一行。配置文件
钩子保存在:~/.config/enconvo/hooks.json。如果两个文件都存在,以 ~/.enconvo/hooks.json 为准。
每次触发事件时都会重新读取该文件,所以你可以在 Enconvo 运行时编辑钩子,无需重启。
在设置中管理钩子
打开 设置 → 钩子,可以看到~/.enconvo/hooks.json 中按事件分组的钩子。用开关开启或关闭某一项,或点击 打开 hooks.json 编辑文件。开启或关闭某一项时,会在该项上写入 enabled: false 或 enabled: true,不会改动它的命令或 webhook。
来自插件的钩子
Claude Code 和 Codex 插件(例如 context-mode)可以自带钩子。允许它们之后,它们会像在 Claude Code 中一样运行:在聊天开始时、每条消息前后、工具调用前后、上下文压缩前后,以及回复失败或智能体完成时触发。- 从 插件 安装插件,或在聊天中把插件的 GitHub 仓库、Git 地址、zip 或 npm 包提供给智能体。它会给出该插件的安装卡片。
- 安装前勾选 允许运行它的钩子。安装时未勾选的插件会显示其钩子处于关闭状态;之后可点击其页面上的 允许钩子 来开启。
钩子如何工作
事件触发时,Enconvo 会:- 加载
~/.enconvo/hooks.json。 - 仅当新文件不存在时,回退到
~/.config/enconvo/hooks.json。 - 在顶层
hooks对象中查找键名与事件名相符的条目。 - 应用可选的
matcher正则表达式。 - 跳过
enabled为false的条目。 - 并发运行所有已配置的钩子。
SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、Stop 和 SubagentStop。对于已有的安装,旧的 Enconvo 事件名和旧的扁平 JSON 结构仍然有效,但新写入的内容使用 Codex 风格的嵌套格式。
配置参考
命令钩子
命令钩子会运行一条 shell 命令。Enconvo 会把事件负载以 JSON 格式写入该命令的 stdin。HTTP 钩子
HTTP 钩子会把事件负载作为 JSON 请求正文发送。阻塞式钩子
在智能体或机器人运行期间,有三个事件以阻塞式钩子运行。智能体会等待所有匹配的钩子(它们并行运行)完成后再继续,并按照与 Claude Code 和 Codex 相同的方式读取它们的结果。
钩子有两种方式做出决定:
- 退出码 2 表示阻止。命令写入 stderr 的文本就是原因。
- 退出码 0,并在 stdout 输出 JSON。 其他任何输出、退出码、错误或超时都不做决定,运行会像没有该钩子一样继续。
HTTP 钩子通过 2xx 响应做出决定,响应正文为同样的 JSON。
当多个钩子匹配时,deny 优先于 ask,ask 优先于 allow。各个原因会合并在一起,并使用最后一个
updatedInput。
一个 Stop 钩子在一轮中最多可以让智能体返回 5 次。从第二次检查开始,stop_hook_active 为 true,这样钩子可以在其指令已被执行后让智能体停下。Stop 的阻塞只在智能体正常结束时生效;失败或被停止的运行仍会在后台触发 Stop。
阻塞式钩子会收到常规的事件负载,并在顶层附带 Claude Code 的字段:
Stop 和 SubagentStop 收到的是 stop_hook_active 和 last_assistant_message,而不是工具字段。命令钩子在智能体的工作目录中运行。
阻止危险命令
让智能体在结束前运行测试
事件负载
命令钩子从 stdin 收到这段 JSON。HTTP 钩子则把同样的 JSON 作为请求正文收到。
后台钩子也会收到 Claude Code 的字段:
hook_event_name、事件有会话时的 session_id,以及工具事件的 tool_name、tool_input 和 tool_use_id。
可用事件
run_status_changed、agent_tool_step_changed 等旧版 Enconvo 事件名仍然有效,因此现有的钩子文件不必立即迁移。
实用示例
智能体失败时发送 macOS 通知
记录智能体状态变化
记录智能体的工具调用
发送到 Slack
自定义脚本
创建一个从 stdin 读取事件负载的脚本:~/.enconvo/hooks.json 中引用它:
故障排除
手动测试脚本
把一段示例负载通过管道传给脚本:相关内容
智能体
了解 Enconvo 智能体和自定义机器人
扩展 API 参考
开发可以发出或监听事件的扩展