《Cursor文档》-第三方钩子

Cursor 支持加载第三方工具的钩子，并兼容其他 AI 编程助手现有的钩子配置。

Claude Code 钩子¶

Cursor 可以加载并执行为 Claude Code 配置的钩子，让您可以在两个工具中使用相同的钩子脚本。

要求¶

要启用 Claude Code 钩子兼容性：

1. 在 Cursor 设置 → 规则、技能、子智能体 → 包含第三方插件、技能和其他配置中，启用第三方技能
2. 此功能必须已为你的账户启用

配置位置¶

Claude Code 钩子会从以下位置加载 (按优先级排序) ：

优先级顺序¶

当钩子配置在多个位置时，将按以下优先级顺序合并 (从高到低) ：

1. 企业版 钩子 (托管部署)
2. 团队 钩子 (在仪表盘中配置)
3. 项目 钩子 (.cursor/hooks.json)
4. 用户 钩子 (~/.cursor/hooks.json)
5. Claude 项目本地配置 (.claude/settings.local.json)
6. Claude 项目配置 (.claude/settings.json)
7. Claude 用户配置 (~/.claude/settings.json)

来自所有来源的匹配钩子都会运行。响应发生冲突时，合并时以优先级较高的来源为准。

企业版托管的 钩子 和仪表盘分发功能需要企业版方案。联系销售了解更多。

Claude Code 钩子格式¶

Claude Code 钩子使用相似但略有不同的格式。Cursor 会自动将 Claude 钩子名称映射为 Cursor 中对应的名称。

Claude Code settings.json 示例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Shell",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/validate-shell.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/audit.sh"
          }
        ]
      }
    ]
  }
}

响应格式兼容性¶

Cursor 同时支持 Claude Code 的嵌套 hookSpecificOutput 响应格式和较早的扁平响应格式。为 Claude Code 编写的钩子脚本无论采用哪种格式，均可在 Cursor 中正常运行。

PreToolUse 响应格式¶

嵌套格式 (Claude Code 风格) ：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by policy",
    "updatedInput": { "command": "npm ci" }
  }
}

扁平格式 (Cursor 原生风格) ：

{
  "permission": "deny",
  "user_message": "Blocked by policy",
  "updated_input": { "command": "npm ci" }
}

两种格式等效。嵌套的 permissionDecision 对应 permission，permissionDecisionReason 对应 user_message，updatedInput 对应 updated_input。

Stop / SubagentStop 响应格式¶

嵌套格式 (Claude Code 风格) ：

{
  "hookSpecificOutput": {
    "decision": "block",
    "reason": "Tasks incomplete, continue working"
  }
}

扁平格式 (Claude Code 旧版风格) ：

{
  "decision": "block",
  "reason": "Tasks incomplete, continue working"
}

Cursor 原生格式：

{
  "followup_message": "Tasks incomplete, continue working"
}

对于 Stop 和 SubagentStop 钩子，decision 为带有 reason 的 "block" 时，会被视为自动跟进，等同于在 Cursor 原生格式中提供 followup_message。

钩子步骤映射¶

Claude Code 钩子名称会自动映射为对应的 Cursor 钩子名称：

退出码行为¶

Cursor 和 Claude Code 钩子均支持通过退出码 2 阻止操作，从而确保在不同工具间共享钩子时行为一致：

#!/bin/bash
# 阻止危险命令
if [[ "$COMMAND" == *"rm -rf"* ]]; then
  echo '{"permission": "deny", "user_message": "Destructive command blocked"}'
  exit 2
fi
echo '{"permission": "allow"}'
exit 0

• 退出码 0：钩子执行成功，使用 JSON 输出
• 退出码 2：阻止该操作 (等同于 permission: "deny")
• 其他退出码：钩子执行失败，操作仍会继续执行 (失败时放行)

从 Claude Code 迁移¶

如果您已有 Claude Code 钩子，可以：

1. 继续使用 Claude Code 配置文件：启用第三方技能后，现有 .claude/settings.json 中的钩子会自动生效
2. 迁移到 Cursor 格式：按照 Cursor 格式将钩子复制到 .cursor/hooks.json，即可获得完整功能支持

对应的 Cursor 格式：

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "./hooks/validate-shell.sh",
        "matcher": "Shell"
      }
    ],
    "postToolUse": [
      {
        "command": "./hooks/audit.sh"
      }
    ]
  }
}

支持的功能¶

在 Cursor 中使用 Claude Code 钩子时，支持以下功能：

其他支持的功能：

工具名称映射¶

Claude Code 工具名称与 Cursor 工具名称的映射如下：

限制¶

以下功能仅在使用 Cursor 原生格式时可用：

• subagentStart 钩子 (Claude Code 仅支持 SubagentStop)
• 循环限制配置 (loop_limit)
• 通过仪表盘分发团队/企业版钩子

疑难排查¶

Claude Code 钩子未加载

1. 确认已在 Cursor 设置中启用“第三方技能”
2. 检查 .claude/settings.json 文件是否为有效的 JSON
3. Cursor 会监视配置文件并自动重新加载。如果钩子仍未加载，请重启 Cursor。

钩子正在运行但未阻止操作

1. 确保钩子脚本以退出代码 2 退出，以阻止操作
2. 检查 JSON 输出格式是否符合预期的 schema
3. 在 Cursor 中查看 Hooks 输出通道，获取错误详情

Cursor 与 Claude Code 的行为差异

由于执行环境不同，二者的行为可能存在差异。请在两个工具中测试钩子，以确保兼容性。

企业版钩子部署¶

通过仪表盘使用托管的企业版钩子并向团队分发。