Claude Code / Codex / Cursor Agent Hooks 怎么配?PreToolUse 对照、最小脚本与 fail-open 实测

Instructions、AGENTS.md、skills 都是模型可忽略的建议;hooks 是 harness 在固定时机跑的确定性脚本。本文对照 Claude Code、Codex、Cursor 的 PreToolUse(或等价事件)配置路径、事件名、exit 2 / deny、fail-open 与 fail-closed,并给出一份在 Claude Code 上实测过的最小拦截脚本。

6 分钟阅读
Claude Code / Codex / Cursor Agent Hooks 怎么配?PreToolUse 对照、最小脚本与 fail-open 实测

先说结论:

  • AGENTS.md / skills / 系统说明是建议:模型会读,也可以忘或绕开。
  • Hooks 是 harness 跑的脚本:在工具调用前、后等固定时机执行,不依赖模型是否「记得」规则。
  • 三端都能拦工具调用:Claude Code / Codex 用 PreToolUse;Cursor 用 preToolUse(或更窄的 beforeShellExecution)。拦法常见是 exit code 2,或返回 JSON 的 deny。
  • 默认多为 fail-open:脚本崩了、超时、非 0/2 退出时,工具调用往往仍会继续;安全策略要显式改成 fail-closed(Claude Code:onFailure: "block";Cursor:failClosed: true)。Codex 官方文档对 hook 失败会报 hook failure,默认不把失败当硬拦。
  • 我们实测了 Claude Code:匹配 rm -rf /tmp/hooks-deny-me 的 Bash 被 PreToolUse 拦截(exit 2);echo hooks-allow-ok 正常通过。Cursor 无法在本机无界面环境做同等实测,配置按官方文档整理,不宣称 Cursor 实测。

据 SwiftLee / Antoine van der Lee 2026-11-02 文章,以及 @peterfriese 在 X 上的转发:hooks 比把规则写进 AGENTS.md 可靠得多。下文以各家官方文档为准;与第三方文章不一致处,以官方为准,并标明出处。

相关背景:插件可能悄悄挂上 SessionStart hooks(见 Postman 插件检查与移除);AGENTS.md 也可能被目录上下文带偏(见 Downloads 目录劫持)。Hooks 不能替代「别在 Downloads 里开 agent」,但能执行 markdown 管不住的硬规则。MCP 与权限边界另见 Codex Playwright MCP 安全指南;skills 与 hooks 的分工见 如何在 AI Agent 里用 Skills。

一分钟对照表

项Claude CodeCodexCursor
用户级配置~/.claude/settings.json~/.codex/hooks.json 或 config.toml~/.cursor/hooks.json
项目级配置.claude/settings.json.codex/hooks.json 或 config.toml.cursor/hooks.json(需信任工作区)
工具调用前PreToolUsePreToolUsepreToolUse;壳命令也可用 beforeShellExecution
工具调用后PostToolUsePostToolUsepostToolUse / afterFileEdit 等
Shell 工具名(matcher)BashBashShell(beforeShellExecution 则按命令文本匹配)
拦截exit 2,或 JSON permissionDecision: "deny"exit 2,或 JSON permissionDecision: "deny" / 旧式 decision: "block"exit 2,或 JSON permission: "deny"
Hook 失败默认多数事件继续(fail-open);可设 onFailure: "block"报 hook failure,不把失败当硬拦(据官方 Hooks 页)默认 fail-open;可设 failClosed: true
信任 / 审查工作区信任影响项目 hooks非托管 hooks 需 /hooks 审查并 trust;可用 --dangerously-bypass-hook-trust(一次性)项目 hooks 仅在受信任工作区加载

官方入口:Claude Code Hooks · Codex Hooks · Cursor Hooks。

为什么不只写 AGENTS.md

据 SwiftLee 文章的经验:把「过滤 xcodebuild 输出」写进全局说明后,agent 仍经常把原始日志塞进上下文。说明文字进入 prompt,模型决定要不要遵守;hook 在 harness 层跑,模型没有「是否执行 hook」的否决权。

适用分工:

  1. 说明与偏好 → AGENTS.md / skills(解释意图、风格、流程)。
  2. 每次必须成立的规则 → hooks(拦危险命令、改写构建命令、审计、会话结束记一笔)。
  3. 不要把 hooks 当成唯一防线 → 有的路径会跳过 hooks(例如 Codex 文档写明:write_stdin 轮询已通过 PreToolUse 的命令时不会再跑一次 PreToolUse)。

最小脚本:拦一条危险 Bash(fail-open)

下面脚本对三端都适用:读 stdin JSON,取出命令;命中则拦,否则放行;解析失败则 exit 0(fail-open)。保存为可执行文件,例如 ~/.agents/hooks/block-rm-demo.sh。

bash
#!/bin/bash
# fail-open: jq 缺失或 JSON 异常 → exit 0,不挡工作
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)

if [[ -z "$command" ]]; then
  exit 0
fi

if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
  # Cursor:有 cursor_version 字段时用 JSON deny(据官方 Cursor Hooks + SwiftLee 文章写法)
  if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
    jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
    exit 0
  fi
  # Claude Code / Codex:stderr + exit 2
  echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
  exit 2
fi

exit 0

chmod +x 之后再挂配置。

Claude Code 注册

写在 ~/.claude/settings.json 或项目 .claude/settings.json:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

用户级可用绝对路径。安全策略 hook 建议加上 "onFailure": "block"(需较新版本,官方说明见 Hooks reference),避免脚本路径写错时整段策略失效。

Codex 注册

形状与 Claude Code 接近,放进 ~/.codex/hooks.json 或项目 .codex/hooks.json:

json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
            "timeout": 5,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

注意:Codex 要求非托管 hooks 先在 CLI 里 /hooks 审查并 trust;项目层 hooks 还要求项目 .codex/ 被信任。一次性自动化可用官方文档中的 --dangerously-bypass-hook-trust。可用 [features] hooks = false 全局关掉。

Cursor 注册

Cursor 的 hooks.json 更扁,且需要 version:

json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "~/.agents/hooks/block-rm-demo.sh",
        "matcher": "Shell",
        "timeout": 5
      }
    ]
  }
}

项目级路径相对仓库根,例如 .cursor/hooks/block-rm-demo.sh。安全关键 hook 加 "failClosed": true。也可改用 beforeShellExecution,matcher 直接匹配命令文本(如 rm\\s+-rf)。

实测:Claude Code PreToolUse(本站 Key)

环境:Claude Code CLI 2.1.319,项目内 .claude/settings.json 挂上上面的 fail-open 脚本,经 aicodewith 兼容接口跑非交互 -p。

  1. 放行路径:要求模型执行 echo hooks-allow-ok → 输出 hooks-allow-ok,约 8 秒。
  2. 拦截路径:要求模型执行 rm -rf /tmp/hooks-deny-me → 返回 PreToolUse hook error,命令未执行,约 9 秒。报错片段:
text
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
  1. 单元级 fail-open:stdin 喂非法 JSON → 脚本 exit 0(不挡后续)。

Cursor 未在本机无界面环境做同等实测;上表 Cursor 列依据 Cursor 官方 Hooks 文档。Codex 配置形状已按官方文档核对;本次集成实测选 Claude Code 一条链路,避免重复消耗。

若你用 Codex,把同一脚本挂到 PreToolUse + matcher Bash,先 /hooks trust,再让它跑一条匹配命令与一条不匹配命令即可自测。

fail-open 还是 fail-closed

场景建议怎么配
便利类(过滤构建日志、自动 format)fail-open默认即可;脚本里解析失败也 exit 0
安全 / 合规(禁删、禁外传、禁改密钥文件)fail-closedClaude Code:onFailure: "block";Cursor:failClosed: true;并自己测「脚本删掉后工具是否被拦」
Codex 托管策略按企业 requirements.toml / managed hooks见官方 Managed hooks;本地用户 hook 失败默认不硬拦

据 SwiftLee 文章:便利 hook 应 fail-open,免得坏掉的 hook 让你没法干活;挡危险操作的 hook 才应 fail-closed。

配置注意点(三端共通)

  1. 先读再启用:仓库或插件带来的 hooks 是本机脚本,权限等同你自己。Postman 一类插件曾自动装 SessionStart hooks——安装前先看清挂了什么。
  2. timeout 要短:agent 会等 hook;用户级便利 hook 常见 5 秒。
  3. Stop / stop 续跑要限环:Cursor 对 stop / subagentStop 有 loop_limit(默认 5);别让「结束后再跟一句」无限循环。
  4. matcher 名称别混:Claude Code / Codex 的 shell 工具叫 Bash;Cursor 通用工具匹配用 Shell。
  5. Hooks ≠ skills:skills 是按名或描述调用的能力包;hooks 是事件触发、无人点名也会跑。

用 aicodewith Key 跑 Claude Code / Codex(可选)

测 hooks 不依赖特定模型供应商。若你通过 aicodewith 调模型:

  • Claude Code:按站点文档设置兼容 Base URL 与 Key。
  • Codex:全局 ~/.codex/config.toml 使用 experimental_bearer_token,name = "aicodewith",base_url = "https://api.aicodewith.ai/chatgpt/v1"(注意是 /chatgpt/v1,不是裸 /v1)。

Create API Key →

常见问题

Hooks 和 AGENTS.md 有什么区别?

AGENTS.md 进入上下文,模型可忽略;hooks 由 Claude Code / Codex / Cursor 在生命周期事件上直接执行。意图写进 markdown,硬约束写成 hook。

Exit code 2 和 JSON deny 选哪个?

两者都能拦。Claude Code / Codex 常用 stderr + exit 2;需要结构化原因或改写输入时用 JSON(如 permissionDecision / updatedInput)。Cursor 对 permission hooks 更偏向 stdout JSON 的 permission 字段;exit 2 也等价于 deny。

为什么我的项目 hooks 不跑?

检查:工作区 / 项目是否已信任;Codex 是否已 /hooks trust;路径是否相对正确(Cursor 项目 hooks 相对仓库根);matcher 是否写对工具名;Claude Code 可用 /hooks 菜单核对来源。

Hooks 能完全替代安全策略吗?

不能。官方文档承认部分路径不走 hook;插件与 SessionStart 脚本本身也可能是风险面。Hooks 是 deterministic 的一层护栏,需与权限模式、密钥管理、目录选择一起用。

Cursor 的 ask 在 preToolUse 上可靠吗?

据 Cursor 官方文档:preToolUse 的输出里 "ask" 目前不会强制执行;要挡操作请用 "deny" 或 exit 2。beforeShellExecution 等事件支持 allow / deny / ask。

小结

把「模型应该记得」的规则升格为「harness 每次都会跑」的 hooks。先从一条 PreToolUse / preToolUse 最小脚本开始:matcher 对准 Bash 或 Shell,命中 exit 2 / deny,默认 fail-open,安全场景再 fail-closed。Claude Code、Codex、Cursor 配置文件与事件名不同,但事件 → matcher → 脚本 → 决策 这一套是一样的。

Create API Key → · 查看模型与接入文档 →

来源

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。