Claude Code Hook 编写指南
Claude Code Hook 可以在特定生命周期事件发生时运行处理程序。处理程序可以是本地命令,也可以是 HTTP、提示词、子代理或 MCP 等类型。它能做什么,取决于运行环境、权限和触发事件。
下面用 UserPromptSubmit 演示如何读取用户输入,并选择放行、补充上下文或拦截。
1. 配置 Hook
在 ~/.claude/settings.json 中配置 Hook。将脚本路径替换为实际的绝对路径:
| |
如果 Hook 需要把结果返回给当前提示词,就不要启用 "async": true。异步 Hook 适合后台任务,但不能用来为当前这次提交注入结果。
2. Hook 的输入与输出
- Claude Code 将事件数据作为 JSON 写入脚本的标准输入(stdin);
UserPromptSubmit中可从prompt读取用户输入。 - Hook 的控制结果以 JSON 写到标准输出(stdout)。调试日志写到标准错误(stderr),避免破坏 JSON 输出。
hookSpecificOutput.additionalContext会补充上下文并继续处理提示词。decision: "block"会拦截当前提示词;reason用于说明拦截原因。- 不需要干预时,不输出控制 JSON,并以退出码
0正常结束。
3. 回声测试:拦截并显示结果
这个最小示例读取提示词,并返回 gemini: <输入>。这里用 decision: "block",因此提示词不会继续发送给模型。
保存为 echo_hook.py:
| |
先在终端模拟 Hook 输入,确认脚本输出:
| |
预期输出:
| |
4. 条件判断:为 1+1 注入答案
如果希望 Claude 继续回答,而不是拦截提示词,可以按条件返回 additionalContext。未命中条件时不输出内容,让提示词正常通过。
| |
输入 1+1 时,脚本向 Claude 提供附加上下文,Claude 再生成回答;输入其他内容时,脚本不输出控制信息,提示词正常继续。
5. 调用外部 API
例如,英语纠错可以按以下流程实现:
- 从 stdin 读取
prompt,先过滤中文、代码等不需要纠错的输入。 - 调用外部模型 API 获取建议。
- 如需保存结果,再将输入和建议发送到后端。
- 需要 Claude 在当前回复中使用建议时,输出
additionalContext;只需后台记录时,可以使用异步 Hook。
同步调用会增加提示词提交的等待时间,应设置合理的超时。API 密钥应通过环境变量或安全的凭据管理方式提供,不要硬编码到脚本中。
6. 多个 Hook 与退出码
同一事件下配置多个 Hook 时,不要依赖配置顺序来串行执行有依赖关系的逻辑。需要先后执行的步骤应放在同一个脚本中。
常见退出码:
| 退出码 | 含义 |
|---|---|
0 | Hook 正常结束;Claude Code 可处理 stdout 中符合格式的 JSON。 |
2 | Hook 报告阻断性错误;stderr 可作为错误原因显示。 |
| 其他非零值 | 普通错误;通常不会阻断主流程,stdout 中的 JSON 也不会按成功结果处理。 |
如果看到 Python 语法被 Shell 当作命令解析,检查 command 是否以 python3(或 Python 解释器的绝对路径)启动脚本。调试信息写入 stderr,例如 print("debug", file=sys.stderr)。
参考
- 原文链接:https://typonotes.com/posts/2026/11/18/claude-hook-writing-guide/
- 本文为原创文章,转载注明出处。
- 欢迎 扫码关注公众号
Go与云原生或 订阅网站 https://typonotes.com/ 。 - 第一时间看后续精彩文章。觉得好的话,请猛击文章右下角「在看」,感谢支持。


