Claude Code 钩子：以确定性方式控制智能体的行为

钩子的组成

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }
        ]
      }
    ]
  }
}

包含三个部分：事件、匹配器（对于工具事件，它是匹配工具名称的正则表达式；省略则匹配所有工具）以及一个或多个命令。命令通过标准输入接收描述事件的 JSON 对象，对于工具事件，其中包含 tool_name 和 tool_input，上面的示例正是通过它找到刚编辑的文件。将配置放入 .claude/settings.json 即可在仓库中共享，放入 ~/.claude/settings.json 供自己使用，或者运行 /hooks 让 Claude Code 写入配置。

事件

• PreToolUse — 在工具运行之前。这是唯一可以 阻止工具调用的事件：退出码 2 会取消调用，Claude 会读取你的标准错误输出作为原因。
• PostToolUse — 在工具成功执行之后。可对编辑过的文件运行格式化工具、代码检查工具和类型检查。
• UserPromptSubmit — 在你发送提示词时；可以注入上下文或拒绝提示词。
• Stop / SubagentStop — 在智能体（或子智能体）即将结束时。此处退出码 2 表示“尚未完成”，经典用法是在测试失败时拒绝停止。
• PreCompact — 在执行 /compact之前；保存完整对话记录中你需要的任何内容。
• SessionStart — 在会话开始或恢复时；加载环境、输出提醒。
• Notification — 在 Claude Code 需要你关注时（权限提示、空闲状态）；可将其接入桌面通知或 Slack 通知。

阻止危险命令

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

退出码 2 是约定：工具调用不会执行，钩子输出到标准错误的内容会成为 Claude 看到的说明，让它能够选择其他方法，而不是重试同一操作。其他任何非零退出码都会被记录，但不会阻止调用。

“测试通过之前不要停止”

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

在无界面运行时，将其与 --max-turns 上限配合使用，避免确实无法修复的失败导致无限循环。

钩子、CLAUDE.md 与权限的对比

CLAUDE.md 是模型读取的建议； /permissions 列出了它无需询问即可执行的操作；钩子则是无论如何都会运行的代码。用 CLAUDE.md 提供风格要求和上下文，用权限界定允许直接执行和需要询问的范围，用钩子保证每次都必须满足的要求，例如格式化、密钥扫描、测试门禁和审计日志。它们可以组合使用：权限允许 Bash(git *) 运行，PreToolUse 钩子仍然可以阻止 git push --force.

钩子与网关

钩子在本地运行，完全不涉及 API，因此当 Claude Code 指向 ANTHROPIC_BASE_URL=https://aiprimetech.io时，无需更改。一个实用的组合是：使用 Stop 钩子，从你自己的日志中输出 /cost风格的用量信息，让使用按量付费额度的团队在每次会话结束时看到该会话的费用。

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

常见问题

AI Prime Tech 是独立的 API 网关，与 Anthropic 无关联，也未获得其认可或赞助。“Claude”和“Claude Code”是 Anthropic 的商标。此处介绍的 Claude Code 功能以撰写时 Anthropic 的公开文档为依据，且经常发生变化；本页面的价格和模型列表读取自此网关的实时设置。