Source: https://aiprimetech.io/zh/claude-code/hooks/

[首页](/zh/) › [Claude Code](/claude-code/zh/) › 钩子

[概览](/claude-code/zh/)[安装](/claude-code/zh/install/)[CLI 参考文档](/zh/claude-code/cli/)[定价与限制](/claude-code/zh/pricing/)[Agent SDK](/zh/claude-code/sdk/)[技能与插件](/zh/claude-code/skills/)[GitHub](/zh/claude-code/github/)[网页、桌面与 IDE](/zh/claude-code/web-and-desktop/)[模型](/zh/claude-code/models/)[错误](/zh/claude-code/errors/)[是否开源？](/zh/claude-code/open-source/)[教程](/claude-code/zh/tutorial/)[学生指南](/zh/claude-code/for-students/)[QA 自动化](/zh/claude-code/qa-automation/)[与 Cursor 对比](/zh/claude-code/vs-cursor/)[与 Codex 和 OpenCode 对比](/zh/claude-code/vs-codex/)[子智能体](/zh/claude-code/subagents/)[钩子](/zh/claude-code/hooks/)[MCP](/zh/claude-code/mcp/)[生态系统](/zh/claude-code/ecosystem/)[VS Code](/zh/claude-code/vscode/)[OpenRouter](/zh/claude-code/openrouter/)[速率限制](/zh/claude-code/rate-limits/)[中文指南](/claude-code/zh/)

最后更新：2026 年 11 月

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

钩子是 Claude Code 在其循环的固定节点运行的 shell 命令，例如工具调用前、工具调用后、提交提示词时以及任务完成时。模型可能遵循也可能不遵循 CLAUDE.md 中的指令，而钩子始终会运行。通过钩子，你可以制定始终生效的规则。

## TLDR
- 配置位置： .claude/settings.json （项目级）或 ~/.claude/settings.json （用户级），也可以使用 /hooks.
- 事件：PreToolUse、PostToolUse、UserPromptSubmit、Notification、Stop、SubagentStop、PreCompact、SessionStart。
- 钩子通过标准输入接收 JSON（工具名称、输入、会话）；退出码 0 表示允许，退出码 2 表示阻止，并将标准错误输出反馈给 Claude。
- 典型用途：每次编辑后格式化、阻止危险命令、要求停止前通过测试、发送桌面通知。

## 钩子的组成 

```
{
  "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风格的用量信息，让使用按量付费额度的团队在每次会话结束时看到该会话的费用。

## 先免费试用

新账户可获得 $5 免费 API 额度 使用优惠码 CLAUDECODE — 足够用 Sonnet 运行 Claude Code 一晚，之后可获得面值 7.69231 倍的额度。

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

[使用优惠码 CLAUDECODE 创建账户](/register?promo=CLAUDECODE)

## 常见问题

什么是 Claude Code 钩子？

它们是 Claude Code 在循环中的各类事件发生时自动运行的 shell 命令，例如工具调用前后、提交提示词时以及停止时。与 CLAUDE.md 中的指令不同，它们的执行是确定的。如何用钩子阻止命令？

使用匹配器为 Bash 的 PreToolUse 钩子，从标准输入中检查 tool_input.command，并以退出码 2 退出；标准错误文本会作为原因显示给 Claude。钩子应放在哪里？

放在项目中的 .claude/settings.json（共享）或 ~/.claude/settings.json（个人）的 hooks 键下；可通过 /hooks 交互式编辑。

## 通过网关运行 Claude Code

相同的模型，两个环境变量，面值 7.69231 倍的额度，或固定费率不限量方案。 新账户：使用优惠码 CLAUDECODE 可获得 $5 免费 API 额度。[获取 API 密钥](/register?promo=CLAUDECODE) [查看不限量方案](/zh/plans/)

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

## 更多 Claude Code 指南

[Claude Code：完整指南](/claude-code/zh/)[如何安装 Claude Code](/claude-code/zh/install/)[Claude Code CLI 文档：命令与参数](/zh/claude-code/cli/)[Claude Code 定价与限制详解](/claude-code/zh/pricing/)[Claude Code SDK，现已更名为 Claude Agent SDK](/zh/claude-code/sdk/)[Claude Code 技能与插件](/zh/claude-code/skills/)[在 GitHub 中使用 Claude Code：App、Action 和 @claude](/zh/claude-code/github/)[Claude Code 有网页界面吗？网页、桌面与 IDE 版本详解](/zh/claude-code/web-and-desktop/)[Claude Code 使用哪个模型，以及如何更改](/zh/claude-code/models/)[Claude Code 错误及修复方法](/zh/claude-code/errors/)[Claude Code 开源吗？](/zh/claude-code/open-source/)[Claude Code 教程：您的首次实际会话](/claude-code/zh/tutorial/)[学生使用 Claude：Claude Code、API，以及教育优惠实际提供什么](/zh/claude-code/for-students/)[如何使用 Claude Code 实现 QA 自动化](/zh/claude-code/qa-automation/)[Claude Code 与 Cursor 对比：如何选择、何时使用，以及如何同时使用两者](/zh/claude-code/vs-cursor/)[Claude Code、Codex 与 OpenCode：终端智能体对比](/zh/claude-code/vs-codex/)[Claude Code 子智能体：工作原理、定义方法与智能体团队](/zh/claude-code/subagents/)[Claude Code MCP：连接服务器、作用域、远程 MCP 与实际示例](/zh/claude-code/mcp/)[Claude Code 生态系统：路由器、框架、插件及收录它们的清单](/zh/claude-code/ecosystem/)[在 VS Code 中使用 Claude Code：扩展、终端方式与常见错误](/zh/claude-code/vscode/)[如何在 Claude Code 中使用 OpenRouter（以及何时不宜使用）](/zh/claude-code/openrouter/)[Claude 速率限制错误：“API error: rate limit reached”的含义与解决方法](/zh/claude-code/rate-limits/)[Claude Code 怎么用：从安装到日常使用](/claude-code/zh/)