跳转到主要内容
钩子 让你能够在 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用户提交消息时
StopAgent 想要停止时
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."
  }
}
输出字段说明
decision用 "approve" 允许该操作，或用 "block" 阻止该操作
reason显示给 Agent 的解释
hookSpecificOutput.hookEventName该输出适用的事件 (例如 UserPromptSubmit、SessionStart、PostToolUse)
hookSpecificOutput.additionalContext注入到 Agent 上下文中的文本 (用于 UserPromptSubmit、SessionStart、PostToolUse)

​
退出代码

代码含义
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

​
后续步骤

生命周期钩子

深入了解各类事件及其可用数据。

配置

控制 Devin CLI 从哪些配置位置读取钩子配置。