先说结论:
- 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 Code | Codex | Cursor |
|---|---|---|---|
| 用户级配置 | ~/.claude/settings.json | ~/.codex/hooks.json 或 config.toml | ~/.cursor/hooks.json |
| 项目级配置 | .claude/settings.json | .codex/hooks.json 或 config.toml | .cursor/hooks.json(需信任工作区) |
| 工具调用前 | PreToolUse | PreToolUse | preToolUse;壳命令也可用 beforeShellExecution |
| 工具调用后 | PostToolUse | PostToolUse | postToolUse / afterFileEdit 等 |
| Shell 工具名(matcher) | Bash | Bash | Shell(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」的否决权。
适用分工:
- 说明与偏好 → AGENTS.md / skills(解释意图、风格、流程)。
- 每次必须成立的规则 → hooks(拦危险命令、改写构建命令、审计、会话结束记一笔)。
- 不要把 hooks 当成唯一防线 → 有的路径会跳过 hooks(例如 Codex 文档写明:
write_stdin轮询已通过 PreToolUse 的命令时不会再跑一次 PreToolUse)。
最小脚本:拦一条危险 Bash(fail-open)
下面脚本对三端都适用:读 stdin JSON,取出命令;命中则拦,否则放行;解析失败则 exit 0(fail-open)。保存为可执行文件,例如 ~/.agents/hooks/block-rm-demo.sh。
#!/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:
{
"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:
{
"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:
{
"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。
- 放行路径:要求模型执行
echo hooks-allow-ok→ 输出hooks-allow-ok,约 8 秒。 - 拦截路径:要求模型执行
rm -rf /tmp/hooks-deny-me→ 返回 PreToolUse hook error,命令未执行,约 9 秒。报错片段:
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
- 单元级 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-closed | Claude Code:onFailure: "block";Cursor:failClosed: true;并自己测「脚本删掉后工具是否被拦」 |
| Codex 托管策略 | 按企业 requirements.toml / managed hooks | 见官方 Managed hooks;本地用户 hook 失败默认不硬拦 |
据 SwiftLee 文章:便利 hook 应 fail-open,免得坏掉的 hook 让你没法干活;挡危险操作的 hook 才应 fail-closed。
配置注意点(三端共通)
- 先读再启用:仓库或插件带来的 hooks 是本机脚本,权限等同你自己。Postman 一类插件曾自动装 SessionStart hooks——安装前先看清挂了什么。
- timeout 要短:agent 会等 hook;用户级便利 hook 常见 5 秒。
- Stop / stop 续跑要限环:Cursor 对
stop/subagentStop有loop_limit(默认 5);别让「结束后再跟一句」无限循环。 - matcher 名称别混:Claude Code / Codex 的 shell 工具叫
Bash;Cursor 通用工具匹配用Shell。 - 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)。
常见问题
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 → · 查看模型与接入文档 →



