> ## Documentation Index > Fetch the complete documentation index at: https://docs.trae.cn/llms.txt > Use this file to discover all available pages before exploring further. 钩子（Hook）是 TRAE IDE 提供的自动化扩展机制。通过 Hook，你可以在智能体执行过程中的特定事件节点运行自定义 Shell 命令，用于补充上下文、执行校验、记录日志、拦截高风险操作等。 ## 支持的 Hook 事件 {#ea4a633c} TRAE 支持以下六类 Hook 事件。关于每个事件的输入、输出等详细信息，参考 [Hook 事件](/ide/reference-for-hooks-configuration#6a3a90e4)。 | | | | \ |**事件名** |**触发时机** |**主要用途** | |---|---|---| | | | | \ |`SessionStart` |创建 Session 后、发起第一个对话前。 |初始化环境、注入环境变量或补充上下文。 | | | | | \ |`UserPromptSubmit` |用户发送 Query 后、智能体开始处理前。 |拦截不允许的请求，或向模型附加上下文。 | | | | | \ |`PreToolUse` |智能体发起工具调用后、实际执行前。 |校验、拦截、修改工具参数，或要求用户确认。 | | | | | \ |`PostToolUse` |工具调用实际执行完成后。 |检查工具执行结果，并向模型附加上下文。 | | | | | \ |`Stop` |智能体完成输出、准备结束当前 Query 时。 |检查产出是否达标。必要时阻断停止并让智能体继续执行。 | | | | | \ |`Notification` |工具调用执行等待用户确认时，或智能体完成任务时。 |\ | | |\ | |该事件异步触发，不阻塞主流程。 |向用户发送通知。 | ## Hook 的生命周期 {#ee0d2af5} Hook 在会话的特定节点触发。事件触发并命中所配置的条件后，TRAE 会将该事件的 JSON 上下文传递给你的 Hook 处理程序，由该程序根据返回结果决定是否附加上下文、拦截请求或继续执行。Hook 的生命周期示意图如下： ## 适用场景 {#691ec078} | | | | \ |**场景** |**描述** |**建议事件** | |---|---|---| | | | | \ |安全合规 |拦截敏感请求、保护关键文件、阻止高风险命令。 |`UserPromptSubmit`、`PreToolUse` | | | | | \ |研发流程自动化 |在代码变更后，调用脚本进行代码格式化或校验；在工具调用前后，调用脚本来记录日志或审计。 |`PreToolUse`、`PostToolUse` | | | | | \ |上下文增强 |会话开始时，注入环境变量、工程约束或背景信息。 |`SessionStart` | | | | | \ |任务验收 |任务结束前，检查产出质量。若质量不达标，则阻断停止，让智能体继续优化其输出。 |`Stop` | | | | | \ |工具链联动 |将智能体的行为接入现有脚本、审查机制或规范检查流程。 |根据实际需求选择。 | ## Hook 类型 {#9ff979ee} TRAE IDE 支持全局和项目 Hook： | | | | \ |**Hook 类型** |**生效范围** |**建议配置** | |---|---|---| | | | | \ |全局 Hook |对本机当前用户下的所有工作区生效。 |通用安全策略、统一上下文注入或跨项目校验规则。 | | | | | \ |项目 Hook |仅对当前项目或工作区生效。 |与具体项目强相关的脚本、测试和格式化流程。 | 关于两类 Hook 的配置文件路径，参考 [Hook 配置文件位置](/ide/reference-for-hooks-configuration#342af89c)。 ## 在 TRAE IDE 中管理 Hook {#6d07ca9d} ### 新建 Hook {#edf9cdd6} 你可以在 TRAE IDE 中创建 Hook 配置文件，并在文件中配置具体事件和命令。步骤如下： 1. 前往 **设置** > **Hooks**。 2. 在 **配置** 部分，选择需创建的 Hook 类型：**全局** 或 **项目**。 3. 在 **已配置的 Hooks** 处，点击 **创建** 按钮。 ![Image=600x209](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/25af4054bfe84a988c500315b1a3bcb0~tplv-goo7wpa0wc-image.image) 4. 在弹出的安全警示面板中，阅读提示信息。确认无风险后，点击 **启用** 按钮。根据你选的 Hook 类型，TRAE IDE 会在相应目录下创建 `hooks.json` 配置文件，并默认启用该 Hook 配置。 5. 在 `hooks.json` 文件中，配置 Hook。配置格式和字段说明参考 [Hook 配置](/ide/reference-for-hooks-configuration#9bf733cf)。 6. 保存配置。 ### 管理 Hook 的配置 {#30f3135b} 在 TRAE 中新建 Hook 后，你后续可以根据实际需要修改这些 Hook 的配置，或禁用 Hook。 1. 前往 **设置** > **Hooks**。 2. 在 **配置** 部分，选择需修改的 Hook 类型：**全局** 或 **项目**。 3. 在 **已配置的 Hooks** 处，按需完成以下操作： * 点击齿轮图标，在编辑器内打开 `hooks.json` 编辑文件，然后修改 Hook 配置。 * 打开或关闭 Hook 的开关，从而启用或禁用相关 Hook。 ![Image=600x208](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/6fd90622df0a4e8699b76bc74c67bfd6~tplv-goo7wpa0wc-image.image) ### 导入 Claude Code 中的 Hook {#4c6238cd} :::tip 提示 TRAE IDE 与 Claude Code 中同名 Hook 事件的输入参数和输出参数可能存在差异。导入 Claude Code Hook 后，建议根据 TRAE IDE 的 Hook 事件规范检查并调整相关配置，确保 Hook 命令能正确解析输入并返回符合预期的输出。 ::: TRAE IDE 支持读取 Claude Code 的 Hook 配置。关于 Claude Code 配置文件路径和合并执行规则，参考 [Hook 配置文件位置](/ide/reference-for-hooks-configuration#342af89c)。 1. 前往 **设置** > **Hooks**。 2. 在 **配置** 部分，选择需导入的 Hook 类型：**全局** 或 **项目**。 3. 打开 **导入 CLAUDE 中的 Hooks 配置** 开关。 ![Image=600x213](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/09aebd5d5c2a4065b9f959a4e509d813~tplv-goo7wpa0wc-image.image) 4. 在弹出的安全警示面板中，阅读提示信息。确认无风险后，点击 **启用** 按钮。 ### 设置 Hook 命令的运行方式 {#bb41f71f} 你可以控制 Hook 命令的运行方式。 1. 前往 **设置** > **Hooks**。 2. 在 **运行方式** 部分，选择 Hook 命令的运行方式。可选项如下： | | | \ |**方式** |**描述** | |---|---| | | | \ |沙箱运行 |在沙箱中自动执行 Hook 命令。更多关于沙箱的信息，参考[沙箱](/ide/sandbox)。 | | | | \ |本地自动运行 |始终在沙箱外自动执行 Hook 命令。该方式存在风险，请谨慎选择。 | ### 查看 Hook 的运行日志 {#eab4efe8} 你可以查看 Hook 的完整运行日志。 1. 前往 **设置** > **Hooks**。 2. 在 **运行方式** 部分，点击 **运行日志** 处的 **查看日志** 按钮。 TRAE IDE 将打开 **输出** 面板，并展示 “Agent Hooks” 类型的日志。 ![Image=2330x439](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/9ae3d2d9787d4d4a8b16104780f85ec8~tplv-goo7wpa0wc-image.image) :::tip 提示退出 TRAE IDE 后，Hook 在当前周期的运行日志将被清空。 :::