Claude Code Hook 可以在特定生命周期事件发生时运行处理程序。处理程序可以是本地命令,也可以是 HTTP、提示词、子代理或 MCP 等类型。它能做什么,取决于运行环境、权限和触发事件。

下面用 UserPromptSubmit 演示如何读取用户输入,并选择放行、补充上下文或拦截。

1. 配置 Hook

在 ~/.claude/settings.json 中配置 Hook。将脚本路径替换为实际的绝对路径:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 /absolute/path/to/echo_hook.py",
            "timeout": 15
          }
        ]
      }
    ]
  }
}

如果 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import json
import sys

data = json.load(sys.stdin)
prompt = data.get("prompt", "").strip()

print(json.dumps({
    "decision": "block",
    "reason": f"gemini: {prompt}",
}, ensure_ascii=False))

先在终端模拟 Hook 输入,确认脚本输出:

1
printf '{"prompt":"hello"}\n' | python3 /absolute/path/to/echo_hook.py

预期输出:

1
{"decision": "block", "reason": "gemini: hello"}

4. 条件判断:为 1+1 注入答案

如果希望 Claude 继续回答,而不是拦截提示词,可以按条件返回 additionalContext。未命中条件时不输出内容,让提示词正常通过。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import json
import sys

data = json.load(sys.stdin)
prompt = data.get("prompt", "").strip()

if "1+1" in prompt:
    output = {
        "hookSpecificOutput": {
            "hookEventName": "UserPromptSubmit",
            "additionalContext": "计算结果是 2。请在回答时告诉用户:1+1=2。",
        }
    }
    print(json.dumps(output, ensure_ascii=False))

输入 1+1 时,脚本向 Claude 提供附加上下文,Claude 再生成回答;输入其他内容时,脚本不输出控制信息,提示词正常继续。

5. 调用外部 API

例如,英语纠错可以按以下流程实现:

  1. 从 stdin 读取 prompt,先过滤中文、代码等不需要纠错的输入。
  2. 调用外部模型 API 获取建议。
  3. 如需保存结果,再将输入和建议发送到后端。
  4. 需要 Claude 在当前回复中使用建议时,输出 additionalContext;只需后台记录时,可以使用异步 Hook。

同步调用会增加提示词提交的等待时间,应设置合理的超时。API 密钥应通过环境变量或安全的凭据管理方式提供,不要硬编码到脚本中。

6. 多个 Hook 与退出码

同一事件下配置多个 Hook 时,不要依赖配置顺序来串行执行有依赖关系的逻辑。需要先后执行的步骤应放在同一个脚本中。

常见退出码:

退出码含义
0Hook 正常结束;Claude Code 可处理 stdout 中符合格式的 JSON。
2Hook 报告阻断性错误;stderr 可作为错误原因显示。
其他非零值普通错误;通常不会阻断主流程,stdout 中的 JSON 也不会按成功结果处理。

如果看到 Python 语法被 Shell 当作命令解析,检查 command 是否以 python3(或 Python 解释器的绝对路径)启动脚本。调试信息写入 stderr,例如 print("debug", file=sys.stderr)。

参考