之前做 Claude 集成时我一度把“能用 Claude API 返回一段文本”等同于“会调用 Claude API”结果在准备架构类题目和搭建智能体时反复踩坑。真正要从零搭起一个可用、可靠、可扩展的 Claude 应用核心不是某个 SDK 方法而是理解 Claude 技术栈里反复出现的“模式Mode”概念——它既指 Claude Code 里的工作模式也指 API 调用层面的请求、流式、工具调用与智能体循环模式。本文会围绕“Claude Certified Architect Prerequisite Building with the Claude API Part 6 Mode”这个主题把两套 Mode 体系串联讲解先用整套可运行示例讲 Claude API 的调用模式再延伸到 Claude Code 的常见模式最后解决高频报错比如自签名证书错误、等待 API 响应卡住等。如果你是准备 Claude 认证、正在做智能体应用或者只是被unable to connect to api: self-signed certificate折腾过这篇文章都可以当作一份完整实操笔记。1. 背景与核心概念1.1 什么是 Claude API为什么要关注“Mode”Claude API 是 Anthropic 提供的模型调用接口。开发者可以通过 HTTP 请求把文本、系统提示词、工具定义发送给 Claude 模型让模型生成回复或者通过工具调用完成更复杂的任务。在 Claude 的官方资料、认证课程和工程文档里“Mode”这个词会出现在两个层面使用工具层面Claude Code 等 CLI 产品中用户可以在不同工作模式之间切换比如默认模式、计划模式Plan Mode、架构模式Architect Mode。调用 API 层面开发者可以按不同方式组织和消费模型能力比如同步请求、流式输出、工具调用、智能体循环。很多初学者容易把这两个层面的“模式”搞混。本文会先讲清楚 API 层面的模式再讲 Claude Code 的工作模式最后统一到工程实践里。1.2 Claude API 的用途和常见场景Claude API 的典型场景包括对话助手基于 Messages API 构建多轮问答。内容生成生成文档、代码、摘要并支持流式输出。工具调用让模型根据用户意图选择调用搜索、计算、数据库查询等外部函数。智能体Agent循环模型在不断调用工具、接收工具结果的过程中自主完成多步任务。一个即将参加 Claude 认证架构师考试的开发者至少要能回答这几个问题不同模式有什么区别什么场景选流式工具调用如何闭环连接错误如何处理本文的章节顺序基本就是围绕这些问题设计的。2. 环境准备与版本说明开始写代码之前先把本机环境准备好。以下是一些基础环境示例具体版本请根据你的实际项目调整。2.1 安装 Python 与 Claude SDK操作系统的差异在这里影响不大Windows、macOS、Linux 都可以。推荐使用 Python 3.9 及以上版本并创建独立虚拟环境。python -m venv venv source venv/bin/activate # Windows 系统执行venv\Scripts\activate pip install --upgrade pip pip install anthropic httpxanthropic是官方 Python SDKhttpx用于自定义 HTTP 客户端在后面解决证书问题时非常有用。2.2 获取 API Key 并配置环境变量在 Anthropic 控制台创建 API Key 后把它放到环境变量中不要在代码里硬编码。export ANTHROPIC_API_KEYsk-ant-xxxxxx建议项目根目录使用.env管理密钥但不要把.env提交到 Git。如果团队协作给一个.env.example模板即可。2.3 准备 Claude Code可选如果你需要体验 Claude Code 的工作模式可以通过 npm 安装npm install -g anthropic-ai/claude-code claude安装后首次运行会引导你完成登录或 API Key 配置。如果你不需要命令行工具只想学习 API 模式可以跳过这一步。2.4 验证基础连通性配置完成后先用下面的 Python 脚本验证能否正常连上官方 APIfrom anthropic import Anthropic client Anthropic() resp client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens100, messages[ {role: user, content: 请回答连接成功} ] ) print(resp.content[0].text)如果顺利你会看到模型回复。如果出现网络错误、证书错误或 401先不要继续往下看优先解决连接问题。因为后面的所有模式示例都建立在“能连通 API”的基础上。模型名称请按你的账号实际可用模型调整示例中使用了claude-3-5-sonnet-latest这类别名。3. 理解 Claude Code 的工作模式很多人在准备 Claude 认证时会把注意力完全放在 API 上忽略了 Claude Code。实际上Claude Code 正在成为架构师日常工作中最常见的 Claude 交互工具而它的“Mode 系统”是官方认证考试中经常出现的概念。3.1 默认模式与计划模式Claude Code 的默认模式是最直接的模式你可以让 Claude 读写代码、执行命令、完成修改任务。适合日常开发和调试。计划模式Plan Mode则适合“先分析后动手”。在计划模式下Claude 会先阅读项目、搜索代码、分析影响范围然后输出一份完整计划而不是直接修改文件。对架构师来说这是做代码评审、重构方案、迁移方案时的首选模式。通过/mode命令可以在不同模式之间切换。不同版本的 Claude Code 对模式切换的快捷键和命令支持略有差异建议以你当前安装版本的帮助信息为准。3.2 Architect Mode 与自定义模式Architect Mode 是 Claude Code 中非常受架构师欢迎的一种模式。在这种模式下Claude 会偏向输出系统设计、技术方案、模块划分和接口设计而不是立即写业务代码。它通常只读项目文件不执行修改操作。这个模式与“Claude Certified Architect”这一概念高度相关。除了内置模式Claude Code 还支持自定义模式。自定义模式通常通过 Markdown 文件定义可以指定模式名称、描述、可用工具以及 System Prompt。例如你可以定义一个“API 审查模式”专门检查 Claude API 集成代码是否遵循官方最佳实践。自定义模式的具体字段在不同版本中可能存在差异建议参考官方文档中关于 modes 的说明来编写。3.3 为什么架构师要关注 Mode从考试和实际工作两个角度看Mode 都很重要。考试会考察你是否理解不同 Mode 的边界与适用场景实际工作中正确选择合适的 Mode 能显著减少误操作。架构评审阶段用计划模式或 Architect Mode实施阶段用默认模式复杂多步任务再考虑结合 API 的智能体模式这是一套比较成熟的实践。4. 深入拆解 Claude API 的调用模式Claude Code 的 Mode 是产品层面的工作流而 Claude API 的“调用模式”是更底层的工程能力。接下来进入本文的核心从代码角度理解四种调用模式。4.1 Messages API 基础模式Messages API 是当前 Claude API 的主要接口路径是/v1/messages。无论请求是普通对话、流式响应还是工具调用底层都走这个接口。基础模式其实就是一个“请求-响应”模型客户端发送消息列表Claude 返回完整响应。from anthropic import Anthropic client Anthropic() resp client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, system你是一名经验丰富的架构师回答要简洁专业。, messages[ {role: user, content: 什么是 API 的流式调用} ] ) print(resp.content[0].text)关键参数说明model指定使用的模型需要根据账号权限选择。max_tokens限制生成的最大 token 数防止长文本超出预算。system设置系统提示词影响模型行为。messages多轮对话的消息列表role分为user和assistant。基础模式的优点是简单、稳定适合非实时场景比如离线批量生成、异步任务处理。缺点也很明显必须等整个响应生成完才能拿到结果长文本场景下用户体验会比较差。4.2 流式响应模式流式模式在用户感知上比基础模式好很多。Claude 一边生成一边把内容推给客户端用户在终端看到的是逐渐输出的文字类似打字机效果。from anthropic import Anthropic client Anthropic() with client.messages.stream( modelclaude-3-5-sonnet-latest, max_tokens1024, messages[ {role: user, content: 帮我写一段 300 字关于分层架构的说明。} ] ) as stream: for text in stream.text_stream: print(text, end, flushTrue)这里的stream.text_stream会迭代输出文本片段。底层事件还包括message_start、content_block_delta、message_stop等如果你要实现更精细的控制可以手动遍历事件。流式模式适合聊天助手、实时翻译、代码补全等场景。在工程上流式响应还能让用户更早发现结果方向是否有问题节省等待时间。4.3 工具调用模式工具调用Tool Use是 Claude API 构建智能体的关键能力。模型本身不直接执行外部动作但它可以决定“需要调用哪个工具”并输出结构化的工具调用参数。真正的执行发生在你的程序里。下面定义一个天气查询工具from anthropic import Anthropic client Anthropic() tools [ { name: get_weather, description: 查询指定城市的天气情况, input_schema: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } ] resp client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, toolstools, messages[ {role: user, content: 北京今天天气怎么样} ] ) print(stop_reason:, resp.stop_reason) for block in resp.content: if block.type tool_use: print(工具名:, block.name) print(参数:, block.input)当模型认为需要调用工具时stop_reason会是tool_use响应内容里会有tool_use类型的 block。你的程序需要读取block.id、block.name、block.input执行对应工具再把结果作为新的用户消息回传给 Claude模型才能继续回答。工具调用模式适合需要外部数据、执行动作的任务比如查询数据库、调用业务接口、搜索文档等。4.4 智能体循环模式工具调用如果加上一个循环就变成了智能体模式。流程是用户提问 → 模型决定调工具或直接回答 → 程序执行工具 → 把工具结果返回模型 → 模型继续决策直到不再需要工具为止。def run_agent(user_input, max_steps5): messages [{role: user, content: user_input}] for _ in range(max_steps): resp client.messages.create( modelclaude-3-5-sonnet-latest, max_tokens1024, toolstools, messagesmessages ) messages.append({role: assistant, content: resp.content}) if resp.stop_reason ! tool_use: break for block in resp.content: if block.type tool_use: result execute_tool(block.name, block.input) messages.append({ role: user, content: [ { type: tool_result, tool_use_id: block.id, content: str(result) } ] }) return messages这里的execute_tool是你的工具执行函数。智能体循环有几个关键风险点循环必须有最大步数限制防止模型陷入死循环。工具执行结果要做合法性校验不能直接信任模型输出。每次循环都会增加 token 消耗需要监控成本。智能体模式适合多步骤任务比如查询订单 → 检查库存 → 生成发货单 → 调用通知服务。单次工具调用无法完成这类完整流程。5. 完整实战一个多模式命令行助手现在把前面讲的 API 模式整合成一个完整项目。这个项目叫claude_mode_demo通过命令行参数切换basic、stream、agent三种模式适合作为你自己的实验脚手架。5.1 项目结构claude_mode_demo/ ├── venv/ ├── .env ├── requirements.txt └── mode_demo.pyrequirements.txt内容anthropic httpx python-dotenv5.2 完整代码创建mode_demo.pyimport sys from dotenv import load_dotenv from anthropic import Anthropic load_dotenv() client Anthropic() MODEL claude-3-5-sonnet-latest tools [ { name: get_city_weather, description: 获取指定城市的天气概况, input_schema: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } ] def execute_tool(name, args): if name get_city_weather: city args.get(city, 未知城市) return f{city}晴25 摄氏度东南风 3 级 return 未知工具 def basic_mode(prompt): resp client.messages.create( modelMODEL, max_tokens1024, messages[{role: user, content: prompt}] ) print(resp.content[0].text) def stream_mode(prompt): with client.messages.stream( modelMODEL, max_tokens1024, messages[{role: user, content: prompt}] ) as stream: for text in stream.text_stream: print(text, end, flushTrue) print() def agent_mode(prompt): messages [{role: user, content: prompt}] last_text for _ in range(5): resp client.messages.create( modelMODEL, max_tokens1024, toolstools, messagesmessages ) messages.append({role: assistant, content: resp.content}) for block in resp.content: if block.type text: last_text block.text if resp.stop_reason ! tool_use: break for block in resp.content: if block.type tool_use: result execute_tool(block.name, block.input) messages.append({ role: user, content: [ { type: tool_result, tool_use_id: block.id, content: result } ] }) print(last_text if last_text else 执行完成请查看工具调用结果。) if __name__ __main__: mode sys.argv[1] if len(sys.argv) 1 else basic prompt sys.argv[2] if len(sys.argv) 2 else 你好请做个自我介绍 if mode basic: basic_mode(prompt) elif mode stream: stream_mode(prompt) elif mode agent: agent_mode(prompt) else: print(用法: python mode_demo.py [basic|stream|agent] [提示词])5.3 运行与验证先运行基础模式python mode_demo.py basic 用一句话介绍 Claude API再运行流式模式观察输出是否逐字出现python mode_demo.py stream 写一段 200 字的 API 设计原则最后运行智能体模式python mode_demo.py agent 北京和上海哪个城市适合穿短袖请分别查询两个城市的天气。智能体模式中Claude 会先发起get_city_weather工具调用程序执行工具回传天气模型再基于工具结果给出建议。5.4 结果说明这个示例把三种模式封装在同一个入口里方便你对比差异。实际项目中建议把客户端初始化、提示词管理、工具注册、日志记录拆分成独立模块而不是像示例一样全放在一个文件里。示例的核心价值是让你直观感受基础模式适合简单问答流式模式适合实时输出智能体模式适合需要外部信息的多步决策。6. 常见问题与排查思路API 调用不会总是顺利。结合网上高频报错这里整理一份排查清单。6.1 自签名证书错误报错形式常为api error: unable to connect to api: self-signed certificate这个报错意味着客户端在建立 HTTPS 连接时无法信任服务端返回的证书。常见原因是使用了代理工具、企业内网 HTTPS 拦截、或自定义网关使用了自签名证书。在中国开发者环境里调试代理、API 网关、本地兼容服务都容易出现这个问题。排查步骤确认是否设置了HTTPS_PROXY或ANTHROPIC_BASE_URL环境变量。如果是代理导致检查代理证书是否已安装到系统信任库。如果是自建网关把网关的 CA 证书加入系统信任链。解决方案一通过环境变量指定自定义 CA 证书。export SSL_CERT_FILE/path/to/your-ca.pem export NODE_EXTRA_CA_CERTS/path/to/your-ca.pemNODE_EXTRA_CA_CERTS对基于 Node.js 的 Claude Code 尤其有效。设置后重启claude命令再试。解决方案二仅在本地调试时临时跳过证书校验。生产环境绝对不要这么做。import httpx from anthropic import Anthropic client Anthropic( http_clienthttpx.Client(verifyFalse) )这个写法只适合本地联调一旦上生产必须恢复证书校验并正确配置 CA 证书。6.2 Claude Code 长时间等待 API 响应在 Claude Code 中有时会看到waiting for api response卡住不动。可能原因包括网络不稳定或代理连接正在建立。请求内容特别长模型生成时间比较久。当前模型服务端繁忙出现延迟。请求发出后返回超时但 CLI 没有及时提示。排查方式先用curl测试 API 连通性排除网络问题。尝试一个非常短的提示词比如“你好”。如果短提示正常、长提示卡住说明是生成耗时或上下文过长问题。检查代理日志确认请求是否真的发送成功。更新 Claude Code 到最新版本。curl -v https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-latest, max_tokens: 20, messages: [{role: user, content: ping}] }如果 curl 正常而 Claude Code 卡住可以试试自定义端点或代理配置是否正确。6.3 认证失败与其他 HTTP 错误问题现象常见原因解决思路HTTP 401 认证失败API Key 不正确、已过期、环境变量未生效检查.env是否加载重新生成 KeyHTTP 429 请求过多触发速率限制退避重试降低并发HTTP 529 服务过载Anthropic 服务端繁忙等待后重试设置指数退避连接超时网络不通、代理未生效、DNS 解析失败检查网络确认代理配置使用 curl 测试值得一提的是遇到 429 和 529 时不要立即无限重试建议采用指数退避策略例如第一次等 1 秒第二次等 2 秒第三次等 4 秒并设置最大重试次数。7. 最佳实践与工程建议7.1 API Key 与配置安全API Key 必须放在环境变量或密钥管理服务中不能提交到代码仓库。团队项目里可以约定使用.env管理本地配置但要在.gitignore中排除。对生产环境建议使用专门的密钥管理工具并定期轮换密钥。7.2 超时、重试与并发控制给所有 Claude API 请求设置合理的超时时间。SDK 一般支持timeout参数实际值需要根据业务容忍度调整。调用外部 API 时超时太短会导致误判失败太长会阻塞请求线程。重试策略要区分错误类型网络错误可以重试认证错误不需要重试速率限制则必须退避。7.3 流式优先凡是面向用户实时交互的场景优先考虑流式模式。流式输出不仅提升用户体验还能在输出方向错误时尽早发现。批量离线场景则用同步模式代码更简洁也便于日志记录和任务编排。7.4 上下文与成本控制Claude API 按 token 计费system prompt、历史对话、工具定义都会消耗上下文空间。建议保持 system prompt 精简。多轮对话中做历史裁剪只保留最近的若干轮关键消息。工具定义只放当前任务可能用到的工具不要一股脑全塞进去。对长文档采用分段处理或摘要方式而不是全部塞进 messages。7.5 可观测性与日志生产环境一定要记录请求元数据。至少记录请求时间、模型名称、提示词摘要、响应耗时、token 使用量、错误码。Anthropic 响应头中带有请求 ID排障时提供这个 ID 会非常有帮助。不要把完整的提示词和响应都打进日志避免泄露敏感数据。7.6 自定义端点与本地环境如果你使用的是本地兼容服务、企业网关或第三方 Claude 兼容端点可以通过ANTHROPIC_BASE_URL指向该地址export ANTHROPIC_BASE_URLhttp://localhost:8000使用自定义端点时要特别注意协议兼容性和证书配置。环境切换建议按dev、test、prod分离配置避免在测试环境调试时误连生产 API。8. 总结与学习建议这篇文章从“Mode”这个关键词出发完整梳理了 Claude 技术栈中的两层模式Claude Code 的工作模式以及 Claude API 的调用模式。我建议你先跑通最基础的模式再逐步叠加流式和工具调用。工具调用和智能体循环虽然代码量不大但设计复杂度很高最好从一个小范围的天气查询工具开始逐步扩展为真实业务工具。下一步可以继续深入研究 Anthropic 官方提供的 Cookbook 示例和工具调用文档学习函数设计、多工具编排、评测方法等内容。对于准备认证考试的同学重点理解 Plan Mode、Architect Mode 的定位以及 API 模式下工具调用与智能体循环的适用边界。如果你在本地调试时遇到自签名证书错误或 API 等待卡住的问题直接翻到第 6 节按清单排查即可。希望这篇文章能帮你减少一些摸黑试错的成本。