Skip to main content
钩子会在 Enconvo 中发生某些事件时运行 shell 命令或发送 HTTP 请求,例如智能体启动、完成、失败或使用工具时。钩子在一个 JSON 文件中配置,因此无需开发扩展,就能添加通知、日志、本地自动化或集成。
大多数钩子都是“发出即不管”的:它们在后台运行,不会阻塞 Enconvo。智能体运行期间,PreToolUse、Stop 和 SubagentStop 是例外。智能体会等待它们完成,因此它们可以阻止一次工具调用,或让智能体返回继续工作。参见阻塞式钩子。

快速开始

1

创建 hooks 文件夹

2

创建 ~/.enconvo/hooks.json

3

触发智能体

启动任意智能体或聊天命令。当它的状态变化时,Enconvo 会运行配置的命令,并向 /tmp/enconvo-hooks.log 追加一行。

配置文件

钩子保存在:
当新文件不存在时,Enconvo 也会读取旧版文件 ~/.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 中一样运行:在聊天开始时、每条消息前后、工具调用前后、上下文压缩前后,以及回复失败或智能体完成时触发。
  1. 从 插件 安装插件,或在聊天中把插件的 GitHub 仓库、Git 地址、zip 或 npm 包提供给智能体。它会给出该插件的安装卡片。
  2. 安装前勾选 允许运行它的钩子。安装时未勾选的插件会显示其钩子处于关闭状态;之后可点击其页面上的 允许钩子 来开启。
如果插件更新改动了它的钩子,这些钩子会停止运行,直到你重新检查并再次允许它们。Enconvo 无法运行的钩子会在卡片上列为不在 Enconvo 中运行。

钩子如何工作

事件触发时,Enconvo 会:
  1. 加载 ~/.enconvo/hooks.json。
  2. 仅当新文件不存在时,回退到 ~/.config/enconvo/hooks.json。
  3. 在顶层 hooks 对象中查找键名与事件名相符的条目。
  4. 应用可选的 matcher 正则表达式。
  5. 跳过 enabled 为 false 的条目。
  6. 并发运行所有已配置的钩子。
钩子事件名沿用 Claude Code 和 Codex 的生命周期事件: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。
智能体会等待阻塞式钩子,所以缓慢的 PreToolUse 钩子会拖慢每次工具调用,缓慢的 Stop 钩子会延迟本轮的结束。请让它们保持快速,设置较短的 timeout,或把耗时工作放到后台运行(command &)。
阻塞式钩子会收到常规的事件负载,并在顶层附带 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 参考

开发可以发出或监听事件的扩展