什么是 Claude Code hooks
Anthropic 的定义:“Hooks 是用户定义的 shell 命令、HTTP 端点、MCP 工具调用、LLM 提示词或子代理(subagents),它们在 Claude Code 生命周期的特定点自动执行。”
它们不仅在终端中运行。“无论在哪里运行,Claude Code 都会触发相同的 hook 事件:终端会话、IDE 扩展、桌面应用和云端会话。”
每个 hook 都附加到一个事件上。参考文档列出了数十个事件,从会话开始或恢复时的 SessionStart,到工具调用运行前的 PreToolUse,再到压缩前后的 PreCompact 和 PostCompact,以及会话终止时的 SessionEnd。
hooks 还可以执行副作用操作,例如在编辑后格式化文件、拦截高风险命令或发送通知。本指南重点讨论将文本放入 Claude 上下文的子集,因为这些文本的行为类似于记忆,并有一套自己的规则。
Hooks 在哪里定义
定义 hook 的位置决定了它的作用域。参考文档列出了以下位置:
~/.claude/settings.json:适用于你机器上的所有项目。.claude/settings.json:适用于单个项目,可以提交到代码库。.claude/settings.local.json:适用于单个项目,不共享。- 托管策略设置:适用于组织,由管理员控制。
- 插件的
hooks/hooks.json:在插件启用时生效。 - Skill 或子代理的前置配置(frontmatter):在该 skill 或子代理使用时生效。
hook 条目是合并而非替换的。“Hook 条目跨设置层级合并,而不是相互替换:用户、项目和本地设置会添加自己的 hooks,而不会移除托管的 hooks”。
对于远程工作,有一点限制值得注意:“云端会话不会读取你本地的 ~/.claude/settings.json。”除非在云端会话能读取的地方定义,否则你本地依赖的 hook 不会在云端会话中运行。
要查看已配置的内容,请输入 /hooks。Anthropic 将其描述为“已配置 hooks 的只读浏览器”,它会标记每个 hook 的来源。
哪些 hooks 可以为 Claude 添加上下文
并非每个 hook 都能与 Claude 对话。能够对话的 hooks 使用一个名为 additionalContext 的字段。Anthropic 解释道:“additionalContext 字段将 hook 中的字符串传递到 Claude 的上下文窗口中。”
文本出现的位置取决于事件:
SessionStart和SubagentStart:“在对话开始时,第一个提示词之前”UserPromptSubmit和UserPromptExpansion:“与提交的提示词一起”PreToolUse、PostToolUse、PostToolUseFailure和PostToolBatch:“在工具结果旁边”Stop和SubagentStop:在轮次结束时,以便 Claude 可以根据反馈采取行动PostModelSwitch:“在切换后的下一次请求中”
对于 UserPromptSubmit,普通输出也有效。参考文档描述了两个通道:普通标准输出(stdout)和 additionalContext,并指出:“这两个通道都不会产生可见的转录条目。”
这是让人感到意外的地方。Claude Code 将文本包装在系统提醒中:“Claude 在下一次模型请求时读取提醒,但它不会作为聊天消息出现在界面中。”Claude 能看到它,但聊天界面不显示它。
如果你想查看 hooks 添加了什么,转录视图(transcript view)显示的会话内容比聊天界面更多。我们在关于 Claude Code 中转录视图显示的内容 的指南中涵盖了这一点。
Hook 可以添加多少上下文
存在大小限制。“如果值超过 10,000 个字符,Claude Code 会将文本写入会话目录中的文件,并向 Claude 传递文件路径以及最多前 2,000 个字符的预览。Claude 可以读取该文件,但 Claude Code 不会主动要求它这么做。”
因此,转储长报告的 hook 不会将整个报告放在 Claude 面前。它会提供预览和路径,至于 Claude 是否打开文件取决于 Claude 自己。
当多个 hooks 在同一个事件上触发时,所有 hooks 都会被计算在内。“当多个 hooks 为同一个事件返回 additionalContext 时,Claude 会收到所有的值。”
如何编写 hook 添加的上下文
Anthropic 对措辞给出了具体建议:“将文本写成事实陈述,而不是命令式的系统指令。”
原因是安全性。听起来像来自对话外部命令的文本可能看起来像提示词注入。Anthropic 警告说,这种框架“可能会触发 Claude 的提示词注入防御,导致 Claude 向你展示该文本,而不是将其视为上下文”。
它给出的示例读起来像是纯粹的事实:“部署目标是生产环境”或“此仓库使用 bun test”。它还列出了 hooks 适合处理的信息类型:
- 环境状态:当前分支、部署目标或功能标志(feature flags)
- 条件性项目规则:哪个测试命令适用于刚编辑的文件,工作树中哪些目录是只读的
- 外部数据:未解决的问题(issues)、最近的 CI 结果、来自内部服务的内容
这些信息的共同点是它们会发生变化。这就是使用 hook 而不是文件的原因。
为什么恢复的会话会重放旧的 hook 输出
这是引言中提到的行为的完整解释。“Claude Code 将注入的文本保存在会话转录中。”
当你回到一个会话时,过去的轮次不会重新运行。“对于会话中期事件(如 PostToolUse 或 UserPromptSubmit),当你使用 --continue 或 --resume 恢复时,Claude Code 会重放保存的文本,而不是为过去的轮次重新运行 hook,因此时间戳或提交 SHA 等值会变得陈旧。”
实际上,Claude 看到的是你的 hooks 当时所说的话。如果 hook 昨天报告了 CI 状态、分支或问题列表,那么这些内容就会出现在恢复对话的历史记录中,紧挨着它触发时的轮次。
SessionStart 是个例外。Anthropic 表示,SessionStart hooks 在恢复时会再次运行,source 字段会被设置为 resume(如果你添加了 --fork-session 则为 fork),“以便它们可以刷新上下文”。
因此,如果你想在恢复的会话中获得新鲜的值,带有 resume 匹配器的 SessionStart hook 是文档中建议的地方。旧值仍然存在于历史记录中,因此新文本说明什么是当前状态会很有帮助。
压缩时 hook 上下文会发生什么
压缩(Compaction)会总结对话的早期部分以释放空间。Anthropic 的 hooks 指南直接指出了风险:“这可能会丢失重要细节。”
Hook 文本位于对话历史记录中,而压缩正是对历史记录进行总结。Hooks 为你提供了两种管理方式。
压缩后重新注入。 SessionStart 有一个 compact 匹配器,它在自动或手动压缩后触发。指南的建议是:“使用带有 compact 匹配器的 SessionStart hook,在每次压缩后重新注入关键上下文。”
塑造摘要本身。 PreCompact 在压缩前运行,其输出具有特殊作用。“当 PreCompact hook 以 0 状态退出且未阻塞时,Claude Code 使用其标准输出作为压缩摘要的指令。”同样的 10,000 字符上限也适用,超过上限的输出会被截断。
PreCompact 也可以阻塞压缩,根据时机产生不同的结果。如果压缩是主动触发的,阻塞它意味着对话将以未压缩的状态继续。如果是为了从上下文限制错误中恢复而触发的,“底层错误会浮现,当前请求将失败”。
PostCompact 会在一个名为 compact_summary 的字段中接收生成的摘要,这对于在 Claude Code 外部记录日志或更新笔记很有用。参考文档将其列为无决策控制,仅用于日志记录等副作用。
SessionStart 匹配器
因为 SessionStart 是 hooks 刷新上下文的主要方式,它的匹配器值得了解。参考文档列出了五个:
startup:用于新会话resume:用于--resume、--continue或/resumeclear:用于/clearcompact:用于自动或手动压缩fork:用于从现有会话分叉出的新会话
还有一个时间细节。在启动和 /clear 之后,SessionStart hooks 在后台运行,以便你可以立即输入,但“Claude 的第一次响应仍会等待 hooks 完成,以便它们的上下文能到达 Claude。”参考文档还提到,如果你在后台 hooks 仍在运行时执行 /clear 或切换对话,它们返回的任何内容都不会应用于该会话。
何时 CLAUDE.md 是更好的选择
Anthropic 在参考文档中直接回答了这个问题:“对于永不改变的指令,首选 CLAUDE.md。它无需运行脚本即可加载,是存放静态项目规范的标准位置。”
SessionStart 部分也提到了同样的一点:“对于不需要脚本的静态上下文,请改用 CLAUDE.md。”
一个简单的测试:如果文本在每次 hook 运行时都相同,那么它属于 CLAUDE.md。如果它取决于时刻,例如分支、时间或最新的构建,那么 hook 就是正确的工具。
CLAUDE.md 在压缩方面有其自身的行为。参考文档指出,InstructionsLoaded 的加载原因是 compact,它在压缩后重新加载指令文件时触发。如果你一直为了让静态规则在压缩中幸存而将其放入 hook 中,CLAUDE.md 才是它们文档化的归宿。要检查你的 CLAUDE.md 文件如何加载以及它们的成本,请参阅我们的指南:Claude Code 中 /doctor 检查的内容。
关闭 hooks
要移除 hook,请从设置文件中删除其条目。要临时关闭所有 hooks,参考文档描述了一个 disableAllHooks 设置,它遵循设置优先级。管理员拥有更强大的版本:通过在托管设置中使用 allowManagedHooksOnly,用户、项目、本地和插件 hooks 都会被拦截。
如果 hook 的上下文似乎消失了,在调试脚本之前请先检查这两个设置。
人们首先尝试的做法
信任恢复会话中的值。 会话中期的 hook 输出是从转录中重放的,因此时间戳和提交 SHA 可能是陈旧的。
在聊天中寻找 hook 输出。 添加的上下文不会作为聊天消息出现。
将静态规则放入 hook。 Anthropic 建议将永不改变的指令放入 CLAUDE.md。
将 hook 文本写成命令。 命令式框架可能会触发提示词注入防御。
返回长报告。 超过 10,000 个字符后,Claude 只会得到预览和文件路径。
期望在云端会话中使用本地 hooks。 云端会话不会读取你本地的用户设置。
解决方案:为 Claude 提供当前上下文而不留陈旧残余
第 1 步:将静态规则移至 CLAUDE.md
如果一个 hook 总是说同样的话,请将该文本放入 CLAUDE.md。
第 2 步:在恢复和压缩后刷新
对于会变化的值,使用带有 resume 和 compact 匹配器的 SessionStart。
第 3 步:编写事实,保持简短
将 hook 输出表述为事实陈述,标记什么是当前的,并保持在 10,000 个字符以内。
第 4 步:记录原因
将规范背后的决策(例如为什么某个目录是只读的,或者为什么测试命令不同)记录在不会在每个会话中重新生成的地方。
在 MemoryLake 中设置
Hooks 擅长处理现在时:你当前在哪个分支,CI 现在的状态。CLAUDE.md 擅长处理固定规范。两者都不适合处理那些变化缓慢且需要触达多个工具的决策,例如团队为什么选择某种迁移顺序,或者哪种方法已经被排除。
MemoryLake 是此类项目上下文(如决策、约束和规范)的记忆层,它保存在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。
你用自己的语言编写条目。不会从你的 hooks、设置文件、CLAUDE.md 文件、会话转录、压缩摘要或任何供应商的存储中读取、写入或删除任何内容。Hooks、压缩和恢复仍按 Anthropic 描述的方式工作。
第 1 步:创建 API 密钥
登录并从仪表板生成密钥。将其存储在代码库之外和 hook 脚本之外,就像任何其他凭据一样。

第 2 步:上传你的第一条记忆
从你在解决方案第 4 步中写下的内容开始:规范背后的原因以及你的 hooks 所假设的决策。每个条目对应一个决策。

第 3 步:连接你的 AI 和代理
连接 Claude Code 和你使用的任何其他助手。Hooks 继续提供当前状态,而背后的推理也随之可用。

这在实践中改变了什么
第一个区别是更清晰的分离。Hooks 承载每分钟都在变化的内容,CLAUDE.md 承载固定规范,而变化较慢的决策则有自己的归宿。
第二个区别是更少陈旧的上下文。决策不会在 hook 触发的那一刻被冻结在转录中。
第三个区别是跨工具的连续性。在同一个仓库上工作的 Codex 或其他助手可以使用相同的决策,而无需自己的 hook 设置。
Claude Code hooks 最佳实践
将 hooks 用于变化的内容。 分支、构建和问题列表,而不是固定规则。
将固定规则放入 CLAUDE.md。 它无需运行脚本即可加载。
在恢复时刷新。 只有 SessionStart 会在恢复时重新运行。
为压缩做计划。 使用 compact 匹配器重新注入重要内容,或使用 PreCompact 引导摘要。
编写事实,而非命令。 这能防止 hook 文本看起来像注入攻击。
保持在大小限制内。 长输出会变成文件路径和预览。
当内容缺失时检查 /hooks。 它会显示每个 hook 的来源。
结论
Claude Code hooks 在会话生命周期的特定点自动运行,其中几个可以通过 additionalContext 为 Claude 添加上下文:SessionStart、SubagentStart、UserPromptSubmit、工具事件、Stop 和 PostModelSwitch 等。这些文本作为系统提醒到达 Claude,不会作为聊天消息出现。
Claude Code 将 hook 文本保存在转录中,并在恢复过去轮次时重放,因此值可能会变陈旧,且只有 SessionStart 会再次运行。使用 SessionStart 匹配器和 PreCompact 来管理跨恢复和压缩的上下文,将静态规则保留在 CLAUDE.md 中,并将设置背后的决策保存在不会在每个会话中重新生成的地方。