很多人准备 Claude 相关认证或走上 AI 工程化这条路时都会在同一个地方卡住网页对话框里聊天很顺一旦要把 Claude 接进真实系统就不知道代码该怎么写、AI 的执行行为该怎么控制。本文是“Zero to Claude Certified Architect”系列的第六部分主题就是 SDK 和 Hooks。我不打算只罗列概念而是把这两个东西放到真实的工程场景里去讲SDK 解决的是“程序怎么稳定地调用 Claude”Hooks 解决的是“AI 在执行过程中怎么被审计、被拦截、被约束”。读完这篇文章你至少能亲手跑通三件事第一用 Python SDK 发起一次带上下文的对话第二用 Claude Code 的 Hooks 拦截一条危险 Bash 命令第三把一次工具调用的审计日志落到本地文件里。这套能力不是锦上添花。企业级的 Claude 应用几乎都要求可审计、可回滚、可限定权限。没有这套机制模型能力越强失控风险越大。顺便说一句如果你搜过“claude code 安装”“claude 无法识别为 cmdlet”“hooks 是什么动作”“什么是 sdk”这些问题说明你正好卡在真实工程入口。这些问题本文都会逐一展开并且会给出一个可以照着做的排错思路。1. 为什么认证路线里要单独讲 SDK 和 Hooks先说一个误区。很多人以为考 Claude 相关认证或者做“Claude 架构师”核心是背 Prompt、懂对话技巧、会用网页版聊天。这最多算“用户”称不上“架构师”。真正的架构师要回答的问题是如果企业要把 Claude 接入现有系统你怎么设计调用链路怎么控制它能访问什么怎么在它做错事的时候能拦住怎么记录它做过什么这些问题的答案落在工程层面就是两个接口SDK程序与 Claude 模型之间的编程接口。HooksClaude Code 在执行工具调用前后、请求权限时、会话结束时的扩展点。换句话说SDK 负责“能不能调用”Hooks 负责“能不能控制”。两者合在一起才能构成一个可交付、可运维、可审计的 AI 工程系统。从认证备考的角度看理解这两块能帮你打通很多题目。单独问“Messages API 怎么传参”考的是记忆但问“如何设计一个带审计能力的 Agent 工作流”考的才是架构能力。后者需要你同时理解 SDK 的调用方式、Hooks 的触发时机、外部脚本的退出码语义以及安全边界的取舍。所以这篇文章的读者画像也比较明确你在准备 Claude 认证或者正在做 AI 应用落地再或者只是想搞清楚 claude code 里 hooks 到底能干什么。如果你属于这三类人这篇内容值得收藏。2. 基础概念SDK 是什么和普通 API 调用有什么区别“什么是 SDK” 是一个搜索热词。很多新手把 SDK 和 API 混为一谈这是第一个需要掰开的概念。SDK 的全称是 Software Development Kit软件开发工具包。它不是一个单一接口而是包含客户端封装、类型定义、错误处理、重试逻辑、流式处理能力在内的一整套工具。你可以把它理解为一个“工具箱”里面不仅有“插座”还备好了螺丝刀、电笔和绝缘胶带。API 则更像“插座规格”。它定义了你怎么请求、传什么参数、拿什么响应。用 SDK 调 API比直接拼 HTTP 请求安全得多也省得多。以 Claude 官方 SDK 为例主要包含几类能力能力说明典型场景Messages API 封装一次性发送多轮消息返回模型回复聊天机器人、知识问答流式输出边生成边返回降低首字延迟长文总结、流式对话工具调用让模型输出结构化工具参数再由程序执行自主 Agent、任务编排Token 统计统计输入输出 Token 数量成本核算、配额控制错误处理内置限流重试、异常分类生产环境稳定调用为什么认证路线里要考 SDK因为通过 SDK 是否有能力直接反映你能不能把模型嵌进自己的代码库。网页对话框没法接你内部的用户体系没法控制超时没法统计成本。SDK 可以。很多人在这个阶段的第二个误区是我直接用 requests 库写 HTTP 请求是不是就不用学 SDK 了能跑通但不推荐。官方 SDK 帮你处理了认证头、重试、网络抖动、流式解析这些脏活。而且在实际项目里同事看你的代码时会默认你用了官方 SDK因为它更好维护。从架构师视角看SDK 学习的重点不是记住每个参数而是理解一个完整调用链路的生命周期创建客户端、组装消息、发起请求、处理响应、处理异常、统计用量。这个生命周期会在你未来写的每一个 Claude 集成代码里反复出现。3. Hooks 是什么从 Git Hooks 到 Claude Code 的流程控制“hooks 是什么动作” 在搜索热词里出现了不止一次。先打个比方。你上飞机前会经过安检安检不是飞行员想不想做的问题而是航司强制设在那里的检查点。开发流程里也需要这种“强制检查点”Hooks 就是干这个的。这个概念其实不新。Git Hooks 让你在 commit 前跑测试GitHub Actions 让你在 push 时触发流水线这些都是“钩子”思想在某个动作发生前或发生后执行一段自定义逻辑。Claude Code 的 Hooks 机制是把同样的思想引入 AI Agent 的执行链路。Claude Code 在执行工具调用、请求权限、会话结束等时机会触发你配置的外部脚本。这些脚本可以读取上下文、修改输入、拦截行为、记录日志。常见的 Hooks 类型和触发时机如下Hooks 类型触发时机典型用途PreToolUse某个工具被调用之前检查命令合法性、阻断危险操作PostToolUse某个工具执行完成后记录结果、统计成功率、触发后续流程PermissionRequestAgent 请求执行敏感操作时自动批准白名单命令、拒绝高危操作Notification需要通知外部系统时发消息、更新状态Stop会话结束时汇总会话数据、清理临时文件一看就明白PreToolUse 的核心价值是“拦截”PostToolUse 的核心价值是“审计”PermissionRequest 的核心价值是“权限自动化”。这里要强调一个判断如果你只把 Claude Code 当聊天工具用Hooks 对你确实没什么用。但你想让它跑在团队公共环境里或者让它自动执行写文件、跑命令、改代码这类操作Hooks 就不是可选优化而是安全底线。很多人都搜过 “claude code skill” 或 “claude code 桌面版”希望给 Claude Code 扩展能力。Skill 和 Hooks 不是一个层面的东西。Skill 改变的是模型“用哪些指令和流程完成任务”Hooks 改变的是工程侧“哪些行为允许发生”。Skill 像给员工发操作手册Hooks 像给工位装门禁。如果你之前用过 Codex 的 Hooks 思路或者接触过别的 Agent 工具的钩子配置理解 Claude Code 的这套机制会很快。核心心智模型是一样的在 Agent 执行外部效果的操作前永远有机会插一段由你自己掌控的代码。4. 环境准备与前置条件从安装到打通 API在实际动手之前先把环境准备好。下面以最常见的开发环境为例Windows、macOS、Linux 均可差异主要在路径和终端命令上。需要准备的基础环境Node.js 16 及以上版本Claude Code 的命令行工具依赖 Node。Python 3.8 及以上版本用于运行官方 Python SDK 和示例脚本。一个有效的 Claude API Key或者能正常登录 Claude Code 的账号凭证。一个适合跑测试的空目录建议不要直接在业务项目里试。第一步安装 Claude Code 命令行工具。在终端执行npm install -g anthropic-ai/claude-code安装完成后验证是否成功claude --version在 Windows 上如果提示“claude 不是内部或外部命令也不是可运行的程序”原因是 npm 的全局安装目录没有加入 PATH。这个问题很常见我们会在第 8 节专门讲排查方法。第二步配置 API Key。在终端设置环境变量export ANTHROPIC_API_KEYsk-ant-你的密钥在 Windows PowerShell 中则使用$env:ANTHROPIC_API_KEYsk-ant-你的密钥第三步安装 Python SDKpip install anthropic验证安装是否成功python -c import anthropic; print(anthropic.__version__)第四步创建项目目录。本文所有示例都建议放在同一个目录下便于理解文件之间的引用关系mkdir claude-architect-demo cd claude-architect-demo这个步骤里有几个需要特别提醒的点。第一API Key 是敏感凭证不要写进代码仓库。设置环境变量是最简单的做法团队项目建议用密钥管理服务。第二版本细节请以你实际安装的版本为准。不同版本可能在某些 API 参数和 Hooks 字段上有差异但核心流程不会变。第三如果在安装或导入时遇到网络问题先检查本机网络环境再检查包镜像配置不要一上来就怀疑代码。5. SDK 最小示例用 Python 完成一次上下文对话环境准备完成后先用 SDK 写一个最小示例把整个调用链路跑通。这个示例虽然简单但它包含了一个完整的 SDK 调用生命周期创建客户端、组装消息、发起请求、解析响应。在项目目录下创建文件demo_sdk.py# 文件路径claude-architect-demo/demo_sdk.py import anthropic # 客户端创建SDK 会自动读取环境变量 ANTHROPIC_API_KEY client anthropic.Anthropic() # 发起一次多轮对话 messages [ {role: user, content: 请用一句话解释 Hooks 在 AI Agent 中的作用。} ] response client.messages.create( # 注意模型 ID 请以官方文档和你的账号权限为准 modelclaude-3-5-sonnet-latest, max_tokens512, messagesmessages, ) # 解析输出 print(response.content[0].text)运行方式python demo_sdk.py这段代码里最核心的是client.messages.create()。它接受模型名、最大 Token 数、消息列表三个关键参数。消息列表采用role加content的结构role可以是user、assistant。真正做多轮对话时只要把历史消息依次放进messages列表即可。max_tokens是架构师必须关注的参数。它控制单次回复的最大长度直接影响成本。一个常见的错误是把max_tokens设得过大导致请求超时或成本飙升。实际项目中应该根据场景需要设置合理上限而不是无脑给大值。运行成功后终端会输出一段对 Hooks 的解释。看到输出代表你的 SDK 通路已经打通。此时可以进阶一步在messages中追加一条assistant回复再追加一条新的user问题模拟真正的上下文对话。这个阶段的重点是建立“程序调用模型”的心智模型。你写的每一行代码最终都会成为架构设计的一部分。先跑通最小示例再逐步加复杂度是稳妥的路线。6. Hooks 完整示例搭建一个可审计、可拦截的 Claude 工作流这是全文的核心实操部分。我们用一个贴近真实团队的场景来演示你给团队搭建了一个公共的 Claude Code 环境希望做到两件事。第一任何人让 Claude 执行 Bash 命令时系统先检查这条命令是否危险。比如rm -rf /、mkfs这类命令直接拦截。第二每次工具调用后自动记录一条审计日志包含工具名称和退出码方便事后追溯。这个场景同时用到了 PreToolUse 和 PostToolUse 两种 Hooks正好覆盖“拦截”和“审计”两个能力。6.1 项目目录结构在claude-architect-demo下创建如下结构claude-architect-demo/ ├── .claude/ │ └── settings.json ├── scripts/ │ ├── audit.py │ └── record.py └── demo_sdk.py.claude/settings.json是 Claude Code 的 Hooks 配置文件。scripts目录存放被 Hooks 调用的 Python 脚本。6.2 编写 PreToolUse 拦截脚本创建scripts/audit.py# 文件路径claude-architect-demo/scripts/audit.py #!/usr/bin/env python3 PreToolUse 钩子示例 在 Bash 工具执行前检查命令是否包含危险关键字。 退出码为 2 时Claude Code 会阻断该工具调用。 import json import os import sys tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) tool_input_raw os.environ.get(CLAUDE_TOOL_INPUT, {}) dangerous_keywords [ rm -rf /, mkfs, dd if, :(){ :|: };:, ] if tool_name Bash: try: command json.loads(tool_input_raw).get(command, ) except json.JSONDecodeError: command tool_input_raw for keyword in dangerous_keywords: if keyword in command: print(fBLOCKED: dangerous command detected - {command}) sys.exit(2) print(fALLOWED: {command}) sys.exit(0)这个脚本的逻辑很清楚通过环境变量读到当前要执行的工具名称和输入解析出具体命令然后在危险关键字列表里做匹配。一旦命中就输出告警并以退出码 2 结束。在 Claude Code 的 Hooks 约定中退出码 2 表示“阻断本次工具调用”。6.3 编写 PostToolUse 审计脚本创建scripts/record.py# 文件路径claude-architect-demo/scripts/record.py #!/usr/bin/env python3 PostToolUse 钩子示例 在每次工具调用结束后把工具名称和退出码写入审计日志。 import os from datetime import datetime tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) exit_code os.environ.get(CLAUDE_EXIT_CODE, 0) log_file os.path.expanduser(~/.claude/hooks_audit.log) log_dir os.path.dirname(log_file) os.makedirs(log_dir, exist_okTrue) line f{datetime.now().isoformat()} | {tool_name} | exit{exit_code}\n with open(log_file, a, encodingutf-8) as f: f.write(line) print(flogged: {line.strip()}) sys.exit(0)注意这个脚本开头需要导入sys模块但我在上面没有写。补齐后的完整代码如下# 文件路径claude-architect-demo/scripts/record.py #!/usr/bin/env python3 PostToolUse 钩子示例 在每次工具调用结束后把工具名称和退出码写入审计日志。 import os import sys from datetime import datetime tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) exit_code os.environ.get(CLAUDE_EXIT_CODE, 0) log_file os.path.expanduser(~/.claude/hooks_audit.log) log_dir os.path.dirname(log_file) os.makedirs(log_dir, exist_okTrue) line f{datetime.now().isoformat()} | {tool_name} | exit{exit_code}\n with open(log_file, a, encodingutf-8) as f: f.write(line) print(flogged: {line.strip()}) sys.exit(0)6.4 编写 Hooks 配置创建.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/audit.py, timeout: 10 } ] } ], PostToolUse: [ { matcher: *, hooks: [ { type: command, command: python3 scripts/record.py, timeout: 10 } ] } ] } }matcher用于指定这个 Hook 监听哪种工具。Bash表示只拦截 Bash 工具*表示匹配所有工具。command是要执行的命令。timeout是超时时间单位秒避免脚本卡死导致 Agent 停摆。在 Windows 环境下python3可能无法识别需要把命令改为python或者直接写 Python 可执行文件的绝对路径。这个细节在团队配置里经常被忽略。6.5 测试 Hooks 是否生效进入claude-architect-demo目录启动 Claude Codeclaude在 Claude Code 中让它执行一条安全命令请运行 echo hello正常情况是命令被允许执行。然后再让它执行一条危险命令比如请你运行rm -rf /。此时 PreToolUse 钩子应该拦截这条命令并在对话中给出BLOCKED提示。接着查看审计日志文件cat ~/.claude/hooks_audit.log如果日志里出现了Bash | exit0或Bash | exit2之类的记录说明 PostToolUse 钩子也正常工作。这个例子虽然小但架构意义不小。它本质上是一个“可观测、可管控的 AI 执行环境”。将来你可以在这个基础上扩展接入企业微信通知、同步日志到 Elasticsearch、把危险命令列表放到配置管理平台等等。7. 运行结果与效果验证怎么确定 Hooks 真生效了很多人配置完 Hooks 后最担心的问题是“它到底有没有跑”。下面给出明确的验证路径。第一验证 PreToolUse。在 Claude Code 对话框中输入请执行命令rm -rf /tmp/test_dir如果配置生效你会看到类似这样的反馈BLOCKED: dangerous command detected - rm -rf /tmp/test_dir与此同时对话界面会提示工具调用被阻断。此时回到终端输入echo $?在 Claude Code 中不一定能直接看到这个退出码但脚本里print的内容会出现在调试信息中。如果看到了BLOCKED说明 PreToolUse 正常。第二验证 PostToolUse。执行完任意一条安全命令后检查审计日志cat ~/.claude/hooks_audit.log预期输出类似2025-01-15T10:23:45.123456 | Bash | exit0如果日志文件不存在可能原因有三个脚本路径不对、Python 不是用对的解释器运行、sys.exit(0)之前抛了异常。先把脚本单独拿出来跑一遍确认它能正常写文件再放回 Hooks 配置里。第三判断“是否生效”的标准不是“没报错”而是“行为符合预期”。这听起来像一句废话但实际项目里很多人只看日志没报错就认为没问题。更严谨的做法是设计一个对照实验不配置 Hooks 时运行一次危险命令观察系统反应配置 Hooks 后运行同样的命令确认行为不同。第四注意 Hooks 的失败模式。如果脚本因为语法错误或路径问题退出Claude Code 的行为取决于退出码。退出码为零时系统会认为 Hook 执行成功这可能导致你的拦截脚本形同虚设。所以在正式环境里脚本要写得非常简单并且要单独测试。8. 常见问题与排查思路下面这张表汇总了从搜索热词和实际工程经验中提炼出的常见问题按“现象、可能原因、排查方式、解决方案”四列给出。问题现象可能原因排查方式解决方案Windows 提示 “claude 不是内部或外部命令”npm 全局安装目录未加入 PATH执行npm config get prefix查看全局目录执行where claude确认是否存在将 npm prefix 目录加入 PATH重新打开终端或改用npx claude临时调用SDK tools 里没有 HAXM新版 Android SDK 已用 AEHD 替代 HAXM打开 SDK Manager搜索 Emulator 相关组件安装 Android Emulator Hypervisor Driver或使用虚拟化平台自带的加速方案在 Claude Code 中指定模型后提示 “model … is not a model this version recognizes”模型 ID 在当前版本中不可用或第三方 API 兼容层不支持该模型查看当前 Claude Code 版本支持模型列表检查模型名拼写使用官方支持的模型 ID涉及第三方模型映射时以兼容层文档为准新用户登录时提示 “Claude is not available to new users”账号地区或使用策略受限确认账号状态和官方公告等待账号解禁或使用已获授权的企业账号Hooks 配置后不触发配置文件路径不对或 matcher 不匹配检查.claude/settings.json是否位于项目根目录确认 matcher 名称将配置文件放到正确目录临时把所有 matcher 改成*验证脚本执行报错但看不到错误信息脚本异常被 Hooks 框架吞掉单独在终端运行脚本检查环境变量取值给脚本增加 try/except把异常信息输出到 stderrAPI Key 配置了但请求返回 401环境变量未正确读取或 Key 无效在脚本里打印os.environ.get(ANTHROPIC_API_KEY)重新设置环境变量重启终端后再运行安装了 SDK 但 import 报错Python 环境混用装到了不同的解释器执行which python和pip show anthropic核对位置使用虚拟环境安装依赖这里面有几个值得展开的点。第一个是 PATH 问题。Windows 上这类报错非常典型不只是 Claude很多 Node 全局工具都会遇到。解决办法是手动把 npm 的全局目录加进系统 PATH。你可以用npm config get prefix拿到路径在“系统环境变量”里追加C:\Users\你的用户名\AppData\Roaming\npm然后重启终端。如果不想改系统变量临时用npx claude也能跑只是每次都要加npx。第二个是 Hooks 不触发。最常见的原因是配置文件放错了位置。Claude Code 的 Hooks 配置是分层的项目级配置放在项目根目录的.claude/settings.json用户级配置放在用户目录下。如果你在项目 A 配置了 Hooks却在项目 B 里启动 Claude Code那项目配置就不会生效。排查时先确认当前项目根目录下确实有.claude/settings.json。第三个是第三方模型接入的问题。很多人想把 Claude Code 接到其他模型服务上比如搜索热词里出现的 deepseek 相关讨论。这里要提醒一句如果你使用的是第三方兼容层它支持的模型名和参数格式可能与官方不完全一致。错误信息里如果出现某个模型 ID 不被当前版本识别优先找兼容层的文档而不是 Claude 官方文档。还有一个经常被忽视的问题Hooks 脚本的执行权限。macOS 和 Linux 下如果脚本被直接执行而不是通过python3 xxx.py调用需要先给脚本加执行权限chmod x scripts/audit.py scripts/record.py如果忘记加权限脚本会报 permission deniedHooks 也就不会正常工作。9. 最佳实践与工程建议跑通示例只是第一步。真正要在团队或生产环境里使用 Claude Code 和 Hooks下面的工程建议会帮你少踩很多坑。第一安全边界遵循最小权限原则。Hooks 能够拦截命令但这不代表你应该把所有命令都放行。更稳妥的做法是维护一个白名单而不是黑名单。黑名单总有遗漏白名单的覆盖面更可控。审计脚本里的危险关键字列表只是一个演示真实项目应该根据团队的使用场景做精细化配置。第二所有 Hooks 脚本都要可观测、可调试。脚本的输入输出要清晰不要吞掉异常。建议在脚本开头将关键环境变量写到日志里方便事后追溯。生产环境的 Hooks 脚本越简单越好复杂逻辑应该放到独立的服务里通过 API 调用而不是塞进一个命令行脚本。第三Hooks 配置要纳入版本管理。.claude/settings.json应该提交到 Git 仓库和代码一起评审一起回滚。这样当某次改动导致工具行为异常时可以快速定位是配置变化引起的。相反审计日志文件不要提交到仓库它属于运行时产物。第四注意成本和资源控制。SDK 调用时要设置合理的max_tokens同时考虑在应用层做配额的兜底。Hooks 脚本的超时时间也要设置比如 10 秒。如果某个 Hook 脚本卡住了它会影响整个 Claude Code 的执行流不能掉以轻心。第五不要把认证备考变成背题。从架构师认证的思路上看更重要的是你能不能完成一个完整的闭环设计用户输入进来系统怎么鉴权模型要调工具系统怎么校验工具执行完系统怎么记录发生异常系统怎么回滚。Hooks 和 SDK 只是你的工具你真正的价值是把这个链路设计得稳健。第六快速试错时用最小配置起步。不要一开始就配置一大堆 Hooks 和复杂的脚本。先跑通一个 PreToolUse再逐步加 PostToolUse、Notification。每加一个 Hook都要验证它是不是真的在按预期工作。第七关注版本变化。Claude SDK、Claude Code 和 Hooks 的具体字段可能在不同版本中有调整。你不必记住每一个版本的差异但要在升级依赖时重新验证你的 Hooks 配置。最稳妥的方式是升级后先跑一遍完整的对照测试再让团队成员正式使用。10. 下一步用 30 分钟跑通第一个可审计工作流如果你今天看完文章后只做一件事我建议做这个把第 6 节的三个文件完整地创建出来跑一遍拦截和审计流程。30 分钟足够了。你不需要理解每一个 API 细节只需要体验一次“在 AI 执行前插入一道可控检查”的感觉。跑通之后再回到第 5 节的 SDK 示例试着把一次调用封装成一个函数加上日志和超时处理。然后你会慢慢理解为什么这个系列会把 SDK 和 Hooks 放在同一篇文章里它们是同一枚硬币的两面一面解决“如何调用模型”一面解决“如何控制模型”。接下来的学习方向可以沿着三条线继续深入。第一条是 SDK 的工具调用能力让模型返回结构化工具参数再由程序执行这背后是 Agent 设计的基础。第二条是 Notification 和更细粒度的 PermissionRequest 控制把 Hooks 从“命令行脚本”升级成“团队治理体系”。第三条是生产环境的监控和成本治理把 Token 消耗、请求延迟、失败率接入现有监控系统。技术学习最忌讳只收藏不实践。建议你现在就打开终端创建今天的第一个文件。后面如果遇到问题再回头看这篇第 8 节的排查表你会觉得每一步都有回应。
很多人准备 Claude 相关认证或走上 AI 工程化这条路时都会在同一个地方卡住网页对话框里聊天很顺一旦要把 Claude 接进真实系统就不知道代码该怎么写、AI 的执行行为该怎么控制。本文是“Zero to Claude Certified Architect”系列的第六部分主题就是 SDK 和 Hooks。我不打算只罗列概念而是把这两个东西放到真实的工程场景里去讲SDK 解决的是“程序怎么稳定地调用 Claude”Hooks 解决的是“AI 在执行过程中怎么被审计、被拦截、被约束”。读完这篇文章你至少能亲手跑通三件事第一用 Python SDK 发起一次带上下文的对话第二用 Claude Code 的 Hooks 拦截一条危险 Bash 命令第三把一次工具调用的审计日志落到本地文件里。这套能力不是锦上添花。企业级的 Claude 应用几乎都要求可审计、可回滚、可限定权限。没有这套机制模型能力越强失控风险越大。顺便说一句如果你搜过“claude code 安装”“claude 无法识别为 cmdlet”“hooks 是什么动作”“什么是 sdk”这些问题说明你正好卡在真实工程入口。这些问题本文都会逐一展开并且会给出一个可以照着做的排错思路。1. 为什么认证路线里要单独讲 SDK 和 Hooks先说一个误区。很多人以为考 Claude 相关认证或者做“Claude 架构师”核心是背 Prompt、懂对话技巧、会用网页版聊天。这最多算“用户”称不上“架构师”。真正的架构师要回答的问题是如果企业要把 Claude 接入现有系统你怎么设计调用链路怎么控制它能访问什么怎么在它做错事的时候能拦住怎么记录它做过什么这些问题的答案落在工程层面就是两个接口SDK程序与 Claude 模型之间的编程接口。HooksClaude Code 在执行工具调用前后、请求权限时、会话结束时的扩展点。换句话说SDK 负责“能不能调用”Hooks 负责“能不能控制”。两者合在一起才能构成一个可交付、可运维、可审计的 AI 工程系统。从认证备考的角度看理解这两块能帮你打通很多题目。单独问“Messages API 怎么传参”考的是记忆但问“如何设计一个带审计能力的 Agent 工作流”考的才是架构能力。后者需要你同时理解 SDK 的调用方式、Hooks 的触发时机、外部脚本的退出码语义以及安全边界的取舍。所以这篇文章的读者画像也比较明确你在准备 Claude 认证或者正在做 AI 应用落地再或者只是想搞清楚 claude code 里 hooks 到底能干什么。如果你属于这三类人这篇内容值得收藏。2. 基础概念SDK 是什么和普通 API 调用有什么区别“什么是 SDK” 是一个搜索热词。很多新手把 SDK 和 API 混为一谈这是第一个需要掰开的概念。SDK 的全称是 Software Development Kit软件开发工具包。它不是一个单一接口而是包含客户端封装、类型定义、错误处理、重试逻辑、流式处理能力在内的一整套工具。你可以把它理解为一个“工具箱”里面不仅有“插座”还备好了螺丝刀、电笔和绝缘胶带。API 则更像“插座规格”。它定义了你怎么请求、传什么参数、拿什么响应。用 SDK 调 API比直接拼 HTTP 请求安全得多也省得多。以 Claude 官方 SDK 为例主要包含几类能力能力说明典型场景Messages API 封装一次性发送多轮消息返回模型回复聊天机器人、知识问答流式输出边生成边返回降低首字延迟长文总结、流式对话工具调用让模型输出结构化工具参数再由程序执行自主 Agent、任务编排Token 统计统计输入输出 Token 数量成本核算、配额控制错误处理内置限流重试、异常分类生产环境稳定调用为什么认证路线里要考 SDK因为通过 SDK 是否有能力直接反映你能不能把模型嵌进自己的代码库。网页对话框没法接你内部的用户体系没法控制超时没法统计成本。SDK 可以。很多人在这个阶段的第二个误区是我直接用 requests 库写 HTTP 请求是不是就不用学 SDK 了能跑通但不推荐。官方 SDK 帮你处理了认证头、重试、网络抖动、流式解析这些脏活。而且在实际项目里同事看你的代码时会默认你用了官方 SDK因为它更好维护。从架构师视角看SDK 学习的重点不是记住每个参数而是理解一个完整调用链路的生命周期创建客户端、组装消息、发起请求、处理响应、处理异常、统计用量。这个生命周期会在你未来写的每一个 Claude 集成代码里反复出现。3. Hooks 是什么从 Git Hooks 到 Claude Code 的流程控制“hooks 是什么动作” 在搜索热词里出现了不止一次。先打个比方。你上飞机前会经过安检安检不是飞行员想不想做的问题而是航司强制设在那里的检查点。开发流程里也需要这种“强制检查点”Hooks 就是干这个的。这个概念其实不新。Git Hooks 让你在 commit 前跑测试GitHub Actions 让你在 push 时触发流水线这些都是“钩子”思想在某个动作发生前或发生后执行一段自定义逻辑。Claude Code 的 Hooks 机制是把同样的思想引入 AI Agent 的执行链路。Claude Code 在执行工具调用、请求权限、会话结束等时机会触发你配置的外部脚本。这些脚本可以读取上下文、修改输入、拦截行为、记录日志。常见的 Hooks 类型和触发时机如下Hooks 类型触发时机典型用途PreToolUse某个工具被调用之前检查命令合法性、阻断危险操作PostToolUse某个工具执行完成后记录结果、统计成功率、触发后续流程PermissionRequestAgent 请求执行敏感操作时自动批准白名单命令、拒绝高危操作Notification需要通知外部系统时发消息、更新状态Stop会话结束时汇总会话数据、清理临时文件一看就明白PreToolUse 的核心价值是“拦截”PostToolUse 的核心价值是“审计”PermissionRequest 的核心价值是“权限自动化”。这里要强调一个判断如果你只把 Claude Code 当聊天工具用Hooks 对你确实没什么用。但你想让它跑在团队公共环境里或者让它自动执行写文件、跑命令、改代码这类操作Hooks 就不是可选优化而是安全底线。很多人都搜过 “claude code skill” 或 “claude code 桌面版”希望给 Claude Code 扩展能力。Skill 和 Hooks 不是一个层面的东西。Skill 改变的是模型“用哪些指令和流程完成任务”Hooks 改变的是工程侧“哪些行为允许发生”。Skill 像给员工发操作手册Hooks 像给工位装门禁。如果你之前用过 Codex 的 Hooks 思路或者接触过别的 Agent 工具的钩子配置理解 Claude Code 的这套机制会很快。核心心智模型是一样的在 Agent 执行外部效果的操作前永远有机会插一段由你自己掌控的代码。4. 环境准备与前置条件从安装到打通 API在实际动手之前先把环境准备好。下面以最常见的开发环境为例Windows、macOS、Linux 均可差异主要在路径和终端命令上。需要准备的基础环境Node.js 16 及以上版本Claude Code 的命令行工具依赖 Node。Python 3.8 及以上版本用于运行官方 Python SDK 和示例脚本。一个有效的 Claude API Key或者能正常登录 Claude Code 的账号凭证。一个适合跑测试的空目录建议不要直接在业务项目里试。第一步安装 Claude Code 命令行工具。在终端执行npm install -g anthropic-ai/claude-code安装完成后验证是否成功claude --version在 Windows 上如果提示“claude 不是内部或外部命令也不是可运行的程序”原因是 npm 的全局安装目录没有加入 PATH。这个问题很常见我们会在第 8 节专门讲排查方法。第二步配置 API Key。在终端设置环境变量export ANTHROPIC_API_KEYsk-ant-你的密钥在 Windows PowerShell 中则使用$env:ANTHROPIC_API_KEYsk-ant-你的密钥第三步安装 Python SDKpip install anthropic验证安装是否成功python -c import anthropic; print(anthropic.__version__)第四步创建项目目录。本文所有示例都建议放在同一个目录下便于理解文件之间的引用关系mkdir claude-architect-demo cd claude-architect-demo这个步骤里有几个需要特别提醒的点。第一API Key 是敏感凭证不要写进代码仓库。设置环境变量是最简单的做法团队项目建议用密钥管理服务。第二版本细节请以你实际安装的版本为准。不同版本可能在某些 API 参数和 Hooks 字段上有差异但核心流程不会变。第三如果在安装或导入时遇到网络问题先检查本机网络环境再检查包镜像配置不要一上来就怀疑代码。5. SDK 最小示例用 Python 完成一次上下文对话环境准备完成后先用 SDK 写一个最小示例把整个调用链路跑通。这个示例虽然简单但它包含了一个完整的 SDK 调用生命周期创建客户端、组装消息、发起请求、解析响应。在项目目录下创建文件demo_sdk.py# 文件路径claude-architect-demo/demo_sdk.py import anthropic # 客户端创建SDK 会自动读取环境变量 ANTHROPIC_API_KEY client anthropic.Anthropic() # 发起一次多轮对话 messages [ {role: user, content: 请用一句话解释 Hooks 在 AI Agent 中的作用。} ] response client.messages.create( # 注意模型 ID 请以官方文档和你的账号权限为准 modelclaude-3-5-sonnet-latest, max_tokens512, messagesmessages, ) # 解析输出 print(response.content[0].text)运行方式python demo_sdk.py这段代码里最核心的是client.messages.create()。它接受模型名、最大 Token 数、消息列表三个关键参数。消息列表采用role加content的结构role可以是user、assistant。真正做多轮对话时只要把历史消息依次放进messages列表即可。max_tokens是架构师必须关注的参数。它控制单次回复的最大长度直接影响成本。一个常见的错误是把max_tokens设得过大导致请求超时或成本飙升。实际项目中应该根据场景需要设置合理上限而不是无脑给大值。运行成功后终端会输出一段对 Hooks 的解释。看到输出代表你的 SDK 通路已经打通。此时可以进阶一步在messages中追加一条assistant回复再追加一条新的user问题模拟真正的上下文对话。这个阶段的重点是建立“程序调用模型”的心智模型。你写的每一行代码最终都会成为架构设计的一部分。先跑通最小示例再逐步加复杂度是稳妥的路线。6. Hooks 完整示例搭建一个可审计、可拦截的 Claude 工作流这是全文的核心实操部分。我们用一个贴近真实团队的场景来演示你给团队搭建了一个公共的 Claude Code 环境希望做到两件事。第一任何人让 Claude 执行 Bash 命令时系统先检查这条命令是否危险。比如rm -rf /、mkfs这类命令直接拦截。第二每次工具调用后自动记录一条审计日志包含工具名称和退出码方便事后追溯。这个场景同时用到了 PreToolUse 和 PostToolUse 两种 Hooks正好覆盖“拦截”和“审计”两个能力。6.1 项目目录结构在claude-architect-demo下创建如下结构claude-architect-demo/ ├── .claude/ │ └── settings.json ├── scripts/ │ ├── audit.py │ └── record.py └── demo_sdk.py.claude/settings.json是 Claude Code 的 Hooks 配置文件。scripts目录存放被 Hooks 调用的 Python 脚本。6.2 编写 PreToolUse 拦截脚本创建scripts/audit.py# 文件路径claude-architect-demo/scripts/audit.py #!/usr/bin/env python3 PreToolUse 钩子示例 在 Bash 工具执行前检查命令是否包含危险关键字。 退出码为 2 时Claude Code 会阻断该工具调用。 import json import os import sys tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) tool_input_raw os.environ.get(CLAUDE_TOOL_INPUT, {}) dangerous_keywords [ rm -rf /, mkfs, dd if, :(){ :|: };:, ] if tool_name Bash: try: command json.loads(tool_input_raw).get(command, ) except json.JSONDecodeError: command tool_input_raw for keyword in dangerous_keywords: if keyword in command: print(fBLOCKED: dangerous command detected - {command}) sys.exit(2) print(fALLOWED: {command}) sys.exit(0)这个脚本的逻辑很清楚通过环境变量读到当前要执行的工具名称和输入解析出具体命令然后在危险关键字列表里做匹配。一旦命中就输出告警并以退出码 2 结束。在 Claude Code 的 Hooks 约定中退出码 2 表示“阻断本次工具调用”。6.3 编写 PostToolUse 审计脚本创建scripts/record.py# 文件路径claude-architect-demo/scripts/record.py #!/usr/bin/env python3 PostToolUse 钩子示例 在每次工具调用结束后把工具名称和退出码写入审计日志。 import os from datetime import datetime tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) exit_code os.environ.get(CLAUDE_EXIT_CODE, 0) log_file os.path.expanduser(~/.claude/hooks_audit.log) log_dir os.path.dirname(log_file) os.makedirs(log_dir, exist_okTrue) line f{datetime.now().isoformat()} | {tool_name} | exit{exit_code}\n with open(log_file, a, encodingutf-8) as f: f.write(line) print(flogged: {line.strip()}) sys.exit(0)注意这个脚本开头需要导入sys模块但我在上面没有写。补齐后的完整代码如下# 文件路径claude-architect-demo/scripts/record.py #!/usr/bin/env python3 PostToolUse 钩子示例 在每次工具调用结束后把工具名称和退出码写入审计日志。 import os import sys from datetime import datetime tool_name os.environ.get(CLAUDE_TOOL_NAME, unknown) exit_code os.environ.get(CLAUDE_EXIT_CODE, 0) log_file os.path.expanduser(~/.claude/hooks_audit.log) log_dir os.path.dirname(log_file) os.makedirs(log_dir, exist_okTrue) line f{datetime.now().isoformat()} | {tool_name} | exit{exit_code}\n with open(log_file, a, encodingutf-8) as f: f.write(line) print(flogged: {line.strip()}) sys.exit(0)6.4 编写 Hooks 配置创建.claude/settings.json{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: python3 scripts/audit.py, timeout: 10 } ] } ], PostToolUse: [ { matcher: *, hooks: [ { type: command, command: python3 scripts/record.py, timeout: 10 } ] } ] } }matcher用于指定这个 Hook 监听哪种工具。Bash表示只拦截 Bash 工具*表示匹配所有工具。command是要执行的命令。timeout是超时时间单位秒避免脚本卡死导致 Agent 停摆。在 Windows 环境下python3可能无法识别需要把命令改为python或者直接写 Python 可执行文件的绝对路径。这个细节在团队配置里经常被忽略。6.5 测试 Hooks 是否生效进入claude-architect-demo目录启动 Claude Codeclaude在 Claude Code 中让它执行一条安全命令请运行 echo hello正常情况是命令被允许执行。然后再让它执行一条危险命令比如请你运行rm -rf /。此时 PreToolUse 钩子应该拦截这条命令并在对话中给出BLOCKED提示。接着查看审计日志文件cat ~/.claude/hooks_audit.log如果日志里出现了Bash | exit0或Bash | exit2之类的记录说明 PostToolUse 钩子也正常工作。这个例子虽然小但架构意义不小。它本质上是一个“可观测、可管控的 AI 执行环境”。将来你可以在这个基础上扩展接入企业微信通知、同步日志到 Elasticsearch、把危险命令列表放到配置管理平台等等。7. 运行结果与效果验证怎么确定 Hooks 真生效了很多人配置完 Hooks 后最担心的问题是“它到底有没有跑”。下面给出明确的验证路径。第一验证 PreToolUse。在 Claude Code 对话框中输入请执行命令rm -rf /tmp/test_dir如果配置生效你会看到类似这样的反馈BLOCKED: dangerous command detected - rm -rf /tmp/test_dir与此同时对话界面会提示工具调用被阻断。此时回到终端输入echo $?在 Claude Code 中不一定能直接看到这个退出码但脚本里print的内容会出现在调试信息中。如果看到了BLOCKED说明 PreToolUse 正常。第二验证 PostToolUse。执行完任意一条安全命令后检查审计日志cat ~/.claude/hooks_audit.log预期输出类似2025-01-15T10:23:45.123456 | Bash | exit0如果日志文件不存在可能原因有三个脚本路径不对、Python 不是用对的解释器运行、sys.exit(0)之前抛了异常。先把脚本单独拿出来跑一遍确认它能正常写文件再放回 Hooks 配置里。第三判断“是否生效”的标准不是“没报错”而是“行为符合预期”。这听起来像一句废话但实际项目里很多人只看日志没报错就认为没问题。更严谨的做法是设计一个对照实验不配置 Hooks 时运行一次危险命令观察系统反应配置 Hooks 后运行同样的命令确认行为不同。第四注意 Hooks 的失败模式。如果脚本因为语法错误或路径问题退出Claude Code 的行为取决于退出码。退出码为零时系统会认为 Hook 执行成功这可能导致你的拦截脚本形同虚设。所以在正式环境里脚本要写得非常简单并且要单独测试。8. 常见问题与排查思路下面这张表汇总了从搜索热词和实际工程经验中提炼出的常见问题按“现象、可能原因、排查方式、解决方案”四列给出。问题现象可能原因排查方式解决方案Windows 提示 “claude 不是内部或外部命令”npm 全局安装目录未加入 PATH执行npm config get prefix查看全局目录执行where claude确认是否存在将 npm prefix 目录加入 PATH重新打开终端或改用npx claude临时调用SDK tools 里没有 HAXM新版 Android SDK 已用 AEHD 替代 HAXM打开 SDK Manager搜索 Emulator 相关组件安装 Android Emulator Hypervisor Driver或使用虚拟化平台自带的加速方案在 Claude Code 中指定模型后提示 “model … is not a model this version recognizes”模型 ID 在当前版本中不可用或第三方 API 兼容层不支持该模型查看当前 Claude Code 版本支持模型列表检查模型名拼写使用官方支持的模型 ID涉及第三方模型映射时以兼容层文档为准新用户登录时提示 “Claude is not available to new users”账号地区或使用策略受限确认账号状态和官方公告等待账号解禁或使用已获授权的企业账号Hooks 配置后不触发配置文件路径不对或 matcher 不匹配检查.claude/settings.json是否位于项目根目录确认 matcher 名称将配置文件放到正确目录临时把所有 matcher 改成*验证脚本执行报错但看不到错误信息脚本异常被 Hooks 框架吞掉单独在终端运行脚本检查环境变量取值给脚本增加 try/except把异常信息输出到 stderrAPI Key 配置了但请求返回 401环境变量未正确读取或 Key 无效在脚本里打印os.environ.get(ANTHROPIC_API_KEY)重新设置环境变量重启终端后再运行安装了 SDK 但 import 报错Python 环境混用装到了不同的解释器执行which python和pip show anthropic核对位置使用虚拟环境安装依赖这里面有几个值得展开的点。第一个是 PATH 问题。Windows 上这类报错非常典型不只是 Claude很多 Node 全局工具都会遇到。解决办法是手动把 npm 的全局目录加进系统 PATH。你可以用npm config get prefix拿到路径在“系统环境变量”里追加C:\Users\你的用户名\AppData\Roaming\npm然后重启终端。如果不想改系统变量临时用npx claude也能跑只是每次都要加npx。第二个是 Hooks 不触发。最常见的原因是配置文件放错了位置。Claude Code 的 Hooks 配置是分层的项目级配置放在项目根目录的.claude/settings.json用户级配置放在用户目录下。如果你在项目 A 配置了 Hooks却在项目 B 里启动 Claude Code那项目配置就不会生效。排查时先确认当前项目根目录下确实有.claude/settings.json。第三个是第三方模型接入的问题。很多人想把 Claude Code 接到其他模型服务上比如搜索热词里出现的 deepseek 相关讨论。这里要提醒一句如果你使用的是第三方兼容层它支持的模型名和参数格式可能与官方不完全一致。错误信息里如果出现某个模型 ID 不被当前版本识别优先找兼容层的文档而不是 Claude 官方文档。还有一个经常被忽视的问题Hooks 脚本的执行权限。macOS 和 Linux 下如果脚本被直接执行而不是通过python3 xxx.py调用需要先给脚本加执行权限chmod x scripts/audit.py scripts/record.py如果忘记加权限脚本会报 permission deniedHooks 也就不会正常工作。9. 最佳实践与工程建议跑通示例只是第一步。真正要在团队或生产环境里使用 Claude Code 和 Hooks下面的工程建议会帮你少踩很多坑。第一安全边界遵循最小权限原则。Hooks 能够拦截命令但这不代表你应该把所有命令都放行。更稳妥的做法是维护一个白名单而不是黑名单。黑名单总有遗漏白名单的覆盖面更可控。审计脚本里的危险关键字列表只是一个演示真实项目应该根据团队的使用场景做精细化配置。第二所有 Hooks 脚本都要可观测、可调试。脚本的输入输出要清晰不要吞掉异常。建议在脚本开头将关键环境变量写到日志里方便事后追溯。生产环境的 Hooks 脚本越简单越好复杂逻辑应该放到独立的服务里通过 API 调用而不是塞进一个命令行脚本。第三Hooks 配置要纳入版本管理。.claude/settings.json应该提交到 Git 仓库和代码一起评审一起回滚。这样当某次改动导致工具行为异常时可以快速定位是配置变化引起的。相反审计日志文件不要提交到仓库它属于运行时产物。第四注意成本和资源控制。SDK 调用时要设置合理的max_tokens同时考虑在应用层做配额的兜底。Hooks 脚本的超时时间也要设置比如 10 秒。如果某个 Hook 脚本卡住了它会影响整个 Claude Code 的执行流不能掉以轻心。第五不要把认证备考变成背题。从架构师认证的思路上看更重要的是你能不能完成一个完整的闭环设计用户输入进来系统怎么鉴权模型要调工具系统怎么校验工具执行完系统怎么记录发生异常系统怎么回滚。Hooks 和 SDK 只是你的工具你真正的价值是把这个链路设计得稳健。第六快速试错时用最小配置起步。不要一开始就配置一大堆 Hooks 和复杂的脚本。先跑通一个 PreToolUse再逐步加 PostToolUse、Notification。每加一个 Hook都要验证它是不是真的在按预期工作。第七关注版本变化。Claude SDK、Claude Code 和 Hooks 的具体字段可能在不同版本中有调整。你不必记住每一个版本的差异但要在升级依赖时重新验证你的 Hooks 配置。最稳妥的方式是升级后先跑一遍完整的对照测试再让团队成员正式使用。10. 下一步用 30 分钟跑通第一个可审计工作流如果你今天看完文章后只做一件事我建议做这个把第 6 节的三个文件完整地创建出来跑一遍拦截和审计流程。30 分钟足够了。你不需要理解每一个 API 细节只需要体验一次“在 AI 执行前插入一道可控检查”的感觉。跑通之后再回到第 5 节的 SDK 示例试着把一次调用封装成一个函数加上日志和超时处理。然后你会慢慢理解为什么这个系列会把 SDK 和 Hooks 放在同一篇文章里它们是同一枚硬币的两面一面解决“如何调用模型”一面解决“如何控制模型”。接下来的学习方向可以沿着三条线继续深入。第一条是 SDK 的工具调用能力让模型返回结构化工具参数再由程序执行这背后是 Agent 设计的基础。第二条是 Notification 和更细粒度的 PermissionRequest 控制把 Hooks 从“命令行脚本”升级成“团队治理体系”。第三条是生产环境的监控和成本治理把 Token 消耗、请求延迟、失败率接入现有监控系统。技术学习最忌讳只收藏不实践。建议你现在就打开终端创建今天的第一个文件。后面如果遇到问题再回头看这篇第 8 节的排查表你会觉得每一步都有回应。
