钩子 - Devin Docs

钩子让你能够在 Agent 生命周期中的特定事件发生时运行自定义逻辑。你可以使用钩子来强制执行策略、添加上下文、记录操作、修改权限，或与外部系统集成。钩子使用 JSON 格式进行配置。请将它们放在你项目的 .devin/ 目录 (或用户级配置) 中，Devin CLI 会在匹配的生命周期事件发生时运行它们。.claude/ 目录中的现有钩子也会被自动识别——请参阅 Where Hooks Live。

Hooks 有什么作用？

执行策略

阻止危险命令、要求对特定操作进行确认，或限制文件访问。

添加上下文

在调用特定工具时注入额外指示或信息。

触发副作用

在事件发生时执行脚本、发送通知或记录日志。

修改权限

根据具体情况动态授予或限制权限。

快速示例

在你的项目中创建 .devin/hooks.v1.json：

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}

这会在每次执行 shell 命令前运行 ./scripts/check-command.sh。该脚本会通过 stdin 接收事件数据，并可通过返回非零退出码来阻止该操作。

Hook 事件

Hook 可以响应以下生命周期事件：

事件	触发时机
`PreToolUse`	工具执行前
`PostToolUse`	工具完成后
`PermissionRequest`	需要做出权限决策时
`UserPromptSubmit`	用户提交消息时
`Stop`	Agent 想要停止时
`SessionStart`	会话开始时
`SessionEnd`	会话结束时

有关各个事件及其可用数据的详细信息，请参阅生命周期 Hook。

钩子格式

每个钩子都有一个类型 (command 或 prompt) 、一个可选的匹配器 (用于匹配钩子事件 tool_name 的正则表达式) ，以及配置：

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Field	说明
`matcher`	用于匹配 hook 事件 `tool_name` 的正则表达式。空字符串或省略 `matcher` 时，会匹配所有工具名称。
`type`	`"command"` 表示运行 shell 命令，`"prompt"` 表示评估 LLM 提示。
`command`	要运行的 shell 命令 (用于 `command` 类型) 。
`prompt`	要评估的 LLM 提示 (用于 `prompt` 类型) 。
`timeout`	超时时间 (以秒为单位，可选) 。

命令钩子

命令钩子会执行 shell 命令。事件数据会以 JSON 格式通过 stdin 传入，命令也可以通过 stdout 返回 JSON 来控制执行结果 (请参阅下方的输出格式) 。输入 (stdin) ：

{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}

DEVIN_PROJECT_DIR 环境变量会自动设置为项目根目录。内置工具名称以及可匹配的 MCP 工具名称格式，请参阅使用 Matcher。

输出格式

命令钩子可以将 JSON 对象打印到 stdout，以控制执行结果。要批准或阻止某个 action，请返回顶层的 decision (可选附带 reason) ：

{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}

要向 Agent 的上下文中注入文本，请在以该事件名称标记的 hookSpecificOutput 对象中返回 additionalContext：

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}

要在某个工具执行前以透明方式重写其输入，请在 PreToolUse 的 hookSpecificOutput 中返回 updatedInput。updatedInput 中的字段会合并到该工具的参数中，因此你可以只更新其中的一部分 (例如仅更新 command) ：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

输出字段	说明
`decision`	用 `"approve"` 允许该操作，或用 `"block"` 阻止该操作
`reason`	显示给 Agent 的解释
`hookSpecificOutput.hookEventName`	该输出适用的事件 (例如 `UserPromptSubmit`、`SessionStart`、`PreToolUse`、`PostToolUse`)
`hookSpecificOutput.additionalContext`	注入到 Agent 上下文中的文本 (用于 `UserPromptSubmit`、`SessionStart`、`PostToolUse`)
`hookSpecificOutput.updatedInput`	在执行前合并到工具参数中的对象 (用于 `PreToolUse`)

退出代码

代码	含义
0	成功——hook 正常继续执行
2	阻止——操作被拒绝
其他	错误——会被记录，但不会阻止

Hooks 的存放位置

Devin CLI 会从以下位置读取 hooks。它们都使用相同的 JSON 格式。

项目级

位置	说明
`.devin/hooks.v1.json`	独立的 hooks 文件 (推荐)
`.devin/config.json`	配置文件中的 `"hooks"` 键
`.devin/config.local.json`	`"hooks"` 键 (本地覆盖，已加入 gitignore)
`.claude/settings.json`	`"hooks"` 键 (Claude Code 格式)
`.claude/settings.local.json`	`"hooks"` 键 (Claude Code 格式)

用户级 (全局)

位置	说明
`~/.config/devin/config.json` (Windows 上为 `%APPDATA%\devin\config.json`)	用户配置中的 `"hooks"` 密钥
`~/.claude.json`	`"hooks"` 密钥 (Claude Code 格式)
`~/.claude/settings.json`	`"hooks"` 密钥 (Claude Code 格式)
`~/.claude/settings.local.json`	`"hooks"` 密钥 (Claude Code 格式)

在 .devin/hooks.v1.json 中，hooks 对象就是整个文件 (无需外层包装密钥) 。在其他所有位置，hooks 都位于设置文件中的 "hooks" 密钥下。

启用 read_config_from.claude 时 (默认启用) ，会加载来自 .claude/ 路径的 hooks。如有需要，你可以在用户配置中禁用此功能。

检查 Hooks

使用 /hooks 斜杠命令，查看当前已加载的所有 Hooks 及其源文件：

/hooks

钩子

Hooks 有什么作用？

执行策略

添加上下文

触发副作用

修改权限

快速示例

Hook 事件

钩子格式

命令钩子

输出格式

退出代码

Hooks 的存放位置

项目级

用户级 (全局)

检查 Hooks

后续步骤

生命周期钩子

配置

​Hooks 有什么作用？

执行策略

添加上下文

触发副作用

修改权限

​快速示例

​Hook 事件

​钩子格式

​命令钩子

​输出格式

​退出代码

​Hooks 的存放位置

​项目级

​用户级 (全局)

​检查 Hooks

​后续步骤

生命周期钩子

配置

Hooks 有什么作用？

快速示例

Hook 事件

钩子格式

命令钩子

输出格式

退出代码

Hooks 的存放位置

项目级

用户级 (全局)

检查 Hooks

后续步骤