---
title: "钩子（hooks）是什么"
description: "钩子在固定生命周期点自动执行命令或校验，不经过模型决策。它用于格式化、拦截危险操作与审计留痕；失败时阻断还是放行要提前设计，它和工具权限、沙箱也不是一回事。"
updated: 2026-11-13
canonical: https://docai.cc/concepts/hooks/
markdown_mirror: https://docai.cc/concepts/hooks.md
---
## 它是什么

钩子（hooks）是在固定生命周期点自动执行的命令或校验。比如工具调用之前、工具调用之后、会话开始、代理准备停止时，宿主按配置运行你指定的脚本，不需要模型同意，也不由模型决定是否跳过。

它解决的是「每次都别忘了做某件事」。格式化、跑检查、拦截危险命令、记录审计日志、发通知，这些动作适合交给钩子，而不是写进提示里指望模型记住。

钩子不是模型能力，是你自己的代码。它跑在你的机器上，用的是你的权限。

## 怎么工作

以 [Claude Code](/concepts/claude-code/) 为例，钩子配置里主要包含事件、匹配条件与要执行的命令。事件决定时机，匹配条件用来限定工具或范围，命令拿到一份 JSON 输入，里面有会话、工具名和参数。

执行结果通常看退出码：

- 正常退出，动作继续；
- 特定退出码表示阻断，错误信息会回传给模型，让它知道为什么被拦；
- 其他非零退出码一般只提示错误，不阻断。

所以「失败时阻断还是放行」要提前设计。拦截危险操作的钩子应该阻断，并给出可执行的替代建议；格式化、日志这类钩子失败时通常放行，避免因为一个辅助脚本挂掉整个流程。还要设超时，钩子卡住会拖住整个回合。

钩子适合放在这些位置：

- 写文件后自动格式化、跑 lint；
- 执行命令前检查是否碰到生产环境、是否包含删除操作；
- 每次工具调用后追加审计记录，留下谁在什么时候改了什么；
- 会话结束时汇总本次改动。

它和[工具调用](/concepts/tool-use/)互补：工具调用是模型发起的动作，钩子是宿主在动作前后加的固定关卡。它和权限系统也不是一回事：权限回答「这个工具能不能用」，钩子回答「这一次具体操作要不要额外检查、做完之后要做什么」。权限是边界，钩子是边界上的检查和副作用。钩子本身不是沙箱，写得不好会误放行，也会误拦截。在[Agent](/concepts/agent/) 循环里，这种确定性尤其重要：模型可以改变计划，但改变不了钩子的运行时机。

## 常见误解

- **「钩子是提示词」**：不是。它不进入模型的对话，模型也无法说服它跳过。
- **「加了钩子就安全」**：钩子只能检查你想到的情况；它降低误操作概率，不保证隔离。
- **「钩子能撤销操作」**：工具执行后的钩子只能做事后处理，已经发生的写入不会自动回滚。
- **「所有事件都能阻断」**：不同生命周期点能力不同，有的只能观察和记录，设计前先查清楚。