钩子（Hook）是 TraeCode 提供的自动化扩展机制。通过 Hook，你可以在智能体执行过程中的特定事件节点运行自定义 Shell 命令，用于补充上下文、执行校验、记录日志、拦截高风险操作等。
支持的 Hook 事件
TraeCode 支持以下六类 Hook 事件。关于每个事件的输入、输出等详细信息，参考 Hook 事件。
| 事件名 | 触发时机 | 主要用途 |
|---|---|---|
SessionStart | 创建 Session 后、发起第一个对话前。 | 初始化环境、注入环境变量或补充上下文。 |
UserPromptSubmit | 用户发送 Query 后、智能体开始处理前。 | 拦截不允许的请求，或向模型附加上下文。 |
PreToolUse | 智能体发起工具调用后、实际执行前。 | 校验、拦截、修改工具参数，或要求用户确认。 |
PostToolUse | 工具调用实际执行完成后。 | 检查工具执行结果，并向模型附加上下文。 |
Stop | 智能体完成输出、准备结束当前 Query 时。 | 检查产出是否达标。必要时阻断停止并让智能体继续执行。 |
Notification | 工具调用执行等待用户确认时，或智能体完成任务时。 该事件异步触发，不阻塞主流程。 |
Hook 的生命周期
Hook 在会话的特定节点触发。事件触发并命中所配置的条件后，TraeCode 会将该事件的 JSON 上下文传递给你的 Hook 处理程序，由该程序根据返回结果决定是否附加上下文、拦截请求或继续执行。Hook 的生命周期示意图如下：
<svg xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" viewBox="-0.5 -0.5 840 765">
智能体执行工具调用前，可通过 Hooks 校验、拦截、修改工具参数，或要求用户确认。
适用场景
| 场景 | 描述 | 建议事件 |
|---|---|---|
| 安全合规 | 拦截敏感请求、保护关键文件、阻止高风险命令。 | UserPromptSubmit、PreToolUse |
| 研发流程自动化 | 在代码变更后，调用脚本进行代码格式化或校验；在工具调用前后，调用脚本来记录日志或审计。 | PreToolUse、PostToolUse |
| 上下文增强 | 会话开始时，注入环境变量、工程约束或背景信息。 | SessionStart |
| 任务验收 | 任务结束前，检查产出质量。若质量不达标，则阻断停止，让智能体继续优化其输出。 | Stop |
| 工具链联动 | 将智能体的行为接入现有脚本、审查机制或规范检查流程。 | 根据实际需求选择。 |
Hook 类型
TraeCode 支持全局和项目 Hook：
| Hook 类型 | 生效范围 | 建议配置 |
|---|---|---|
| 全局 Hook | 对本机当前用户下的所有工作区生效。 | 通用安全策略、统一上下文注入或跨项目校验规则。 |
| 项目 Hook | 仅对当前项目或工作区生效。 | 与具体项目强相关的脚本、测试和格式化流程。 |
关于两类 Hook 的配置文件路径，参考 Hook 配置文件位置。
在 TraeCode 中管理 Hook
新建 Hook
你可以在 TraeCode 中创建 Hook 配置文件，并在文件中配置具体事件和命令。步骤如下：
- 前往 设置 > Hooks。
- 在 配置 部分，选择需创建的 Hook 类型：全局 或 项目。
- 在 已配置的 Hooks 处，点击 创建 按钮。
- 在弹出的安全警示面板中，阅读提示信息。确认无风险后，点击 启用 按钮。
根据你选的 Hook 类型，TraeCode 会在相应目录下创建
hooks.json配置文件，并默认启用该 Hook 配置。 - 在
hooks.json文件中，配置 Hook。配置格式和字段说明参考 Hook 配置。 - 保存配置。
管理 Hook 的配置
在 TraeCode 中新建 Hook 后，你后续可以根据实际需要修改这些 Hook 的配置，或禁用 Hook。
- 前往 设置 > Hooks。
- 在 配置 部分，选择需修改的 Hook 类型：全局 或 项目。
- 在 已配置的 Hooks 处，按需完成以下操作：
- 点击齿轮图标，在编辑器内打开
hooks.json编辑文件，然后修改 Hook 配置。 - 打开或关闭 Hook 的开关，从而启用或禁用相关 Hook。
- 点击齿轮图标，在编辑器内打开
导入 Claude Code 中的 Hook
提示
TraeCode 与 Claude Code 中同名 Hook 事件的输入参数和输出参数可能存在差异。导入 Claude Code Hook 后，建议根据 TraeCode 的 Hook 事件规范检查并调整相关配置，确保 Hook 命令能正确解析输入并返回符合预期的输出。
TraeCode 支持读取 Claude Code 的 Hook 配置。关于 Claude Code 配置文件路径和合并执行规则，参考 Hook 配置文件位置。
- 前往 设置 > Hooks。
- 在 配置 部分，选择需导入的 Hook 类型：全局 或 项目。
- 打开 导入 CLAUDE 中的 Hooks 配置 开关。
- 在弹出的安全警示面板中，阅读提示信息。确认无风险后，点击 启用 按钮。
设置 Hook 命令的运行方式
你可以控制 Hook 命令的运行方式。
- 前往 设置 > Hooks。
- 在 运行方式 部分，选择 Hook 命令的运行方式。可选项如下：
方式 描述 沙箱运行 在沙箱中自动执行 Hook 命令。更多关于沙箱的信息，参考沙箱。 本地自动运行 始终在沙箱外自动执行 Hook 命令。该方式存在风险，请谨慎选择。
查看 Hook 的运行日志
你可以查看 Hook 的完整运行日志。
- 前往 设置 > Hooks。
- 在 运行方式 部分，点击 运行日志 处的 查看日志 按钮。
TraeCode 将打开 输出 面板，并展示 “Agent Hooks” 类型的日志。
提示
退出 TraeCode 后，Hook 在当前周期的运行日志将被清空。
