Claude Code settings.json 详解（三）：hooks 钩子全解析
hooks 是什么
Claude 每次执行工具（读文件、写文件、运行命令……）都会经历几个固定的生命周期节点：执行前、执行后、会话结束时。hooks 让你在这些节点上挂载自己的脚本——在 Claude 动手之前检查一遍，或者在它写完代码后自动跑一次 lint。
这是 Claude Code 配置里自动化程度最高的部分，也是最能体现”按你的规矩办事”的地方。
配置结构
hooks 是 settings.json 的顶层字段，与 permissions 平级：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo '即将执行 Bash 命令' >> /tmp/claude.log"
}
]
}
],
"PostToolUse": [...],
"Stop": [...],
"Notification": [...]
}
}结构是三层嵌套：
hooks
└── 事件名（如 PreToolUse）
└── [] HookMatcher 数组
├── matcher: 匹配规则（可选）
└── hooks: [] HookCommand 数组每个事件下可以挂多个 matcher，每个 matcher 下可以挂多条命令。
四种 HookCommand 类型
| 类型 | 说明 | 适用场景 |
|---|---|---|
command | 执行 shell 命令 | 日志、lint、通知、阻断检查 |
prompt | 调用 LLM 做判断 | 智能审查、语义检查 |
agent | 启动子代理处理 | 复杂自动化流程 |
http | 向指定 URL 发送 HTTP POST | Webhook、外部系统集成 |
日常使用最多的是 command，其他三种适合更高级的场景。
command 类型的完整字段：
{
"type": "command",
"command": "your-shell-command",
"shell": "bash",
"timeout": 30,
"statusMessage": "正在检查...",
"async": false,
"asyncRewake": false,
"once": false
}timeout：超时秒数statusMessage：执行时显示的 spinner 提示文字async: true：后台异步执行，不阻塞 ClaudeasyncRewake: true：后台执行，若 exit code 为 2 则唤醒模型once: true：只执行一次后自动移除
核心事件详解
Claude Code 共有 26 个以上的 hook 事件，以下是日常最实用的四个。
PreToolUse — 工具执行前
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "/path/to/check.sh" }]
}
]何时触发：Claude 即将调用某个工具，尚未执行时。
stdin 收到的 JSON：
{
"hook_event_name": "PreToolUse",
"session_id": "...",
"cwd": "/your/project",
"transcript_path": "/tmp/transcript.jsonl",
"tool_name": "Bash",
"tool_input": { "command": "rm -rf dist/" },
"tool_use_id": "..."
}stdout 可输出的 JSON：
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"additionalContext": "禁止删除 dist 目录"
}
}permissionDecision 支持 "allow" / "deny" / "ask" 三个值。
exit code 语义：
| exit code | 效果 |
|---|---|
0 | 正常，不显示任何输出 |
2 | 阻断工具执行，将 stderr 内容告知模型 |
| 其他 | 仅将 stderr 显示给用户，工具继续执行 |
关键能力：exit code 2 配合 JSON output 的 permissionDecision: "deny" 可以完全阻断工具调用，比 permissions 规则更灵活，因为可以在脚本里写任意逻辑。
PostToolUse — 工具执行后
"PostToolUse": [
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "pnpm lint --fix" }]
}
]何时触发：工具成功执行完毕之后。
stdin 收到的 JSON：
{
"hook_event_name": "PostToolUse",
"tool_name": "Write",
"inputs": { "file_path": "src/foo.ts", "content": "..." },
"response": { "type": "text", "text": "文件写入成功" },
"tool_use_id": "..."
}stdout 可输出的 JSON：
{
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"additionalContext": "lint 已自动修复"
}
}exit code 语义：
| exit code | 效果 |
|---|---|
0 | 正常，输出显示在 transcript 模式中 |
2 | 将 stderr 立即告知模型 |
| 其他 | 仅将 stderr 显示给用户 |
Stop — 会话结束前
"Stop": [
{
"hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude 已完成\"'" }]
}
]何时触发：Claude 即将结束本轮回复时。
stdin 收到的 JSON：
{
"hook_event_name": "Stop",
"stop_hook_active": false,
"last_assistant_message": "好的，我已经完成了修改。"
}exit code 为 2 时：Claude 会读取 stderr 内容并继续对话，适合实现”Claude 停止前自动检查，发现问题就继续”的效果。
Stop 事件没有 matcher，对所有停止事件都生效。
Notification — 通知事件
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Ping.aiff" }]
}
]何时触发：Claude 发出权限请求、认证提示等通知时。
matcher 匹配 notification_type，常见值有 permission_prompt、auth_success 等。
这个事件是即发即忘的，不阻塞执行，适合做声音提醒、系统通知等副作用操作。
stdin/stdout 协议
每个 hook 脚本通过标准 IO 与 Claude Code 通信：
- stdin：收到一行 JSON，包含事件名、session_id、cwd、transcript_path 以及事件特有字段
- stdout：可以输出 JSON 来控制行为，也可以输出纯文本（会被记录到 transcript）
如果脚本第一行输出 {"async":true}，则立即后台化，Claude 不等待结果继续执行。
可用的环境变量
hook 脚本执行时，可以访问以下环境变量：
| 变量 | 说明 |
|---|---|
CLAUDE_PROJECT_DIR | 稳定的项目根目录（非 worktree 路径） |
CLAUDE_ENV_FILE | 可写入 export VAR=val 的 .sh 文件（仅 bash） |
CLAUDE_PLUGIN_ROOT | 插件/skill 目录路径 |
matcher 格式
matcher 复用 permissions 里的规则语法，可以是：
"Write"— 精确匹配 Write 工具"Bash(git *)"— 匹配带 git 命令的 Bash 调用"Bash(npm:*)"— 旧式前缀匹配- 留空或省略 — 匹配所有调用
实用配置示例
写文件后自动 lint：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && pnpm lint --fix",
"timeout": 30
}
]
}
]
}
}阻断危险 Bash 命令：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash /path/to/guard.sh"
}
]
}
]
}
}guard.sh 里读取 stdin JSON，判断 tool_input.command 是否包含危险操作，危险则 exit 2 并向 stderr 输出原因。
Claude 完成时发送系统通知（macOS）：
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude 已完成任务\" with title \"Claude Code\"'"
}
]
}
]
}
}记录所有 Bash 命令到日志：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> /tmp/claude-bash.log",
"async": true
}
]
}
]
}
}async: true 让日志写入在后台进行，不影响 Claude 的执行速度。
注意事项
- 工作区信任：所有 hook 都需要工作区处于受信任状态才会执行，在不信任的工作区中 hook 会被跳过
- 来源优先级：
policySettings（企业策略）>projectSettings>userSettings>localSettings> 插件 hooks；各层的 hooks 会合并执行，而不是互相覆盖 - 超时控制：建议给每个 hook 设置合理的
timeout，避免因脚本卡住而阻塞 Claude
小结
hooks 是 Claude Code 配置体系里最强大的扩展点：
- 四种类型（
command/prompt/agent/http）覆盖从简单脚本到复杂自动化的需求 PreToolUse+ exit code2可以在 Claude 动手之前做任意检查和阻断PostToolUse可以在工具执行后触发自动修复或验证Stop可以在 Claude 结束前插入额外逻辑，或触发通知- stdin/stdout JSON 协议让 hook 脚本可以精确控制 Claude 的下一步行为
下一篇将介绍 settings.json 中的 env 和其他杂项字段。
相关推荐
AI-first 创业公司，为什么只需要一种编程语言？
技术架构越简单 = AI Coding 效率越高。从 Java 的"防人"设计到 TypeScript 全栈通吃，聊聊 AI 时代创业公司的编程语言选择。
cc-ping：一行命令 Ping 所有 Claude Code 配置
用多个 Claude Code API Key 或中继？cc-ping 帮你管理配置、一键切换，还能并行 Ping 所有节点比速度。
震惊！程序员用这个工具，4分钟干完95分钟的活！效率暴涨24倍
躺床上发3条消息，4分钟搞定3个项目。传统方式需要95分钟，这就是冷兵器和热兵器的差距。
CCBot - 研发提效 24 倍
通过 IM 机器人控制 Claude Code，3 个项目 4 分钟全部搞定。传统编程需要 95 分钟，效率提升 24 倍。
Claude Code /add-dir：被低估的 Monorepo 神器
Claude Code 默认只能看到当前目录。/add-dir 打破这个限制——分享我每天跨 5 个仓库使用的经验。
Claude Code 省 Token 小技巧：感叹号的妙用
一个简单却容易被忽略的技巧——用感叹号直接执行命令，省 token、提速度、更可控。
我做了个机器人，让团队在飞书里用 Claude Code
CCBot 让你的团队在飞书群聊里直接用 Claude Code——不需要终端、不需要 SSH。开源、自部署、五分钟搞定。
Claude Code /btw 命令详解：不打扰主线的快问快答
详细介绍 Claude Code 的 /btw 命令——它是什么、怎么用、什么时候该用，以及它和子代理、/compact 的区别。
Claude Code /compact：释放上下文，不丢进度
任务做到一半上下文满了？/compact 帮你压缩对话继续干活——和 /clear、/rewind 的区别一次讲清。
Claude Code /config：一文搞懂所有可调设置
用 Claude Code 却从没打开过 /config？这篇带你逐项拆解——从权限模式到自动压缩，从主题切换到通知配置，帮你打造最顺手的 AI 编程环境。
Claude Code /context：你的上下文都被什么吃了？
对话到一半 Claude Code 说上下文不够了？/context 用一张可视化网格告诉你：上下文被什么占了、占了多少、怎么优化。
Claude Code /diff：这次对话改了什么，一目了然
Claude Code 帮你改了一堆文件，但你不确定到底改了什么？/diff 用交互式界面展示所有改动——既有 git 视角的全量 diff，也有按对话轮次拆分的逐步 diff。
Claude Code /fast：同样的 Opus，两倍速——值不值？
/fast 不会降级模型，还是 Opus，只是更快。什么时候该开、什么时候该关，以及实际体验差异。
Claude Code 引用外部知识的最佳实践：GitHub MCP + Context7
用 GitHub MCP 和 Context7 MCP 两个工具组合，解决 Claude Code 知识过时导致的代码错误问题。
Claude Code /hooks：让 AI 按你的规矩办事
想在 Claude Code 执行命令前自动检查？想在任务完成后自动通知？/hooks 让你用脚本、AI 甚至 HTTP 请求，在关键节点插入自定义逻辑。
Claude Code /init：10 秒自动生成 CLAUDE.md
别再手写 CLAUDE.md 了。看看 /init 自动生成的效果、怎么自定义输出，以及一个让 Claude Code 效率翻倍的小技巧。
Claude Code MCP：让 AI 连接 GitHub、数据库等一切工具
MCP 把 Claude Code 从代码阅读器升级为全栈 Agent。哪些 MCP 服务器值得装、配置怎么写，实测分享。
Claude Code /memory 详解：让 AI 真正记住你的项目
详细介绍 Claude Code 的 /memory 命令和记忆系统——CLAUDE.md 手动指令、Auto Memory 自动记忆、模块化规则，让 Claude 跨会话记住项目规范和个人偏好。
Claude Code /model：Opus、Sonnet、Haiku 怎么选？
不是每个任务都需要 Opus。怎么切换模型、哪个场景用哪个、怎么省 token 又不掉质量。
Claude Code /permissions：谁能干什么，你说了算
每次 Claude Code 要跑命令都弹窗问你？嫌烦又不敢全放开？/permissions 帮你精细控制每个工具的权限——该放的放，该拦的拦。
Claude Code /plan 详解：先想清楚再动手
详细介绍 Claude Code 的 /plan 命令和 Plan Mode——只读规划模式，让 Claude 先分析代码、制定方案，确认后再动手，避免复杂任务翻车。
Claude Code + Playwright MCP：AI 终于能"看见"页面了
一个 Modal 溢出的 bug，Claude Code 反复修了 5 次都没搞定。直到接入 Playwright MCP 让它真正看到页面，一次定位，一次修复。
Claude Code /resume 命令详解：别让对话白聊
详细介绍 Claude Code 的 /resume 命令——恢复历史对话、管理会话、实用技巧，让你的每一轮对话都不浪费。
Claude Code /review：让 AI 帮你做 Code Review
提了 PR 没人看？想在合并前多一道把关？/review 让 Claude Code 像一个资深开发者一样审查你的代码——还有 /ultrareview 和 /security-review 两个进阶选择。
Claude Code Skills 详解：打造你的专属命令库
详细介绍 Claude Code 的 Skills 功能——创建自定义斜杠命令、复用提示词模板、共享团队最佳实践，让 AI 编程更高效更一致。
Claude Code /stats：看看 AI 到底帮你写了多少代码
好奇 Claude Code 到底写了多少行代码？/stats 给你完整数据——token、编辑次数、工具调用，教你怎么看。
Claude Code /status 命令详解：一眼看清会话全貌
详细介绍 Claude Code 的 /status 命令——它是什么、怎么用、能看到哪些信息，以及它在日常工作流中的实际价值。
Claude Code /tasks 命令详解：后台任务尽在掌控
详细介绍 Claude Code 的 /tasks 命令——查看后台任务、管理并行 Agent、掌控长时间运行的进程，让多任务开发井井有条。
Claude Code /usage 命令详解：你的额度还剩多少
详细介绍 Claude Code 的 /usage 命令——查看用量、了解限额、避免突然被限速，让你对自己的额度心中有数。
Claude Code /vim：在 AI 编程助手里用 Vim 键位
习惯了 Vim 的操作方式？/vim 让你在 Claude Code 的输入框里用 hjkl 移动、dd 删行、ciw 替换单词——不用改变肌肉记忆。
Claude Code 使用指南：从安装到实战，一篇就够（2026）
用了半年 Claude Code 的经验总结——5 分钟安装配置、最常用的命令、CLAUDE.md 编写技巧，以及没人告诉你的实战心得。
Claude 全家桶：从聊天到写代码到自动办公，一文讲清楚
一篇文章带你了解 Anthropic 的 Claude 全家桶——Claude.ai、Claude Code、Claude Cowork，以及 Opus、Sonnet、Haiku 三大模型家族。
Claude Code /agents 详解：自定义 AI 子代理，各司其职
详细介绍 Claude Code 的 /agents 命令——查看、管理和创建自定义 Agent，让不同任务由专门的 AI 角色来执行，从代码探索到架构规划各司其职。
Claude Code /doctor 详解：一键诊断你的开发环境
详细介绍 Claude Code 的 /doctor 命令——自动检测安装状态、API 连接、MCP 配置、上下文用量等问题，帮你快速定位和修复环境故障。
Claude Code /effort 详解：控制 AI 思考的深度
详细介绍 Claude Code 的 /effort 命令——调节 Claude 的推理努力程度，在速度和质量之间找到最佳平衡点，让每一次对话都恰到好处。
Claude Code /cost 详解：你的 AI 编程到底花了多少钱
详细介绍 Claude Code 的 /cost 命令——实时查看会话 API 成本，了解各模型定价和 Token 消耗明细，让每一分钱都花得明明白白。
Claude Code /export 详解：把 AI 对话带走
详细介绍 Claude Code 的 /export 命令——将对话导出为文件或复制到剪贴板，方便分享、存档和复盘，让每一次有价值的对话都不浪费。
Claude Code /rewind 详解：AI 改错了？一键回退
详细介绍 Claude Code 的 /rewind 命令——将代码和对话回退到任意历史节点，支持只回退代码、只回退对话、或两者同时回退，是你和 AI 协作时的后悔药。
Claude Code /plugin 详解：给你的 AI 编程助手装插件
详细介绍 Claude Code 的 /plugin 命令——管理插件的安装、启用、禁用和更新，通过插件扩展 Claude Code 的命令、技能、Agent 和 Hook，打造你专属的 AI 编程工具链。
Claude Code /theme 详解：给你的终端换个好看的皮肤
详细介绍 Claude Code 的 /theme 命令——6 种预设主题 + 自动模式，支持深色/浅色、色盲友好、ANSI 兼容，60+ 色值覆盖终端全部 UI 元素。
Claude Code /insights 详解：用 AI 分析你自己用 AI 的方式
详细介绍 Claude Code 的 /insights 命令——五阶段数据分析流水线、七大洞察章节、多维度会话统计，用 Claude Opus 生成专属 HTML 使用报告。
Claude Code /rename 详解：给你的会话取个有意义的名字
详细介绍 Claude Code 的 /rename 命令——手动命名、AI 自动生成（Haiku 模型）、启动参数命名、Plan 模式自动命名，以及双标题系统与 Bridge 同步机制。
Claude Code settings.json 详解（一）：配置文件在哪里、谁说了算
全面介绍 Claude Code 的配置文件体系——五个配置来源的路径、优先级规则、数组合并与单值覆盖的区别、企业管理设置的多种下发方式。
Claude Code settings.json 详解（二）：permissions 权限系统全解析
深入解析 Claude Code 的 permissions 配置——allow/deny/ask 三类规则、通配符语法、MCP 工具权限、defaultMode 各模式含义，以及 additionalDirectories 的作用。
Claude Code settings.json 详解（四）：env、模型、认证与其他实用字段
全面介绍 Claude Code settings.json 中的 env 环境变量注入、模型配置、身份认证辅助、Git 提交署名、会话清理、语言与界面、思考深度、自动更新、记忆系统等实用字段。
Claude Code Agent Loop：拆解 AI 编程助手的心脏
Claude Code 是怎么一步步理解你的需求、调用工具、自我修复的？从源码角度拆解 Agent Loop 的核心架构——流式响应、并行工具执行、自动压缩、错误恢复，一次讲透。