企业官网建设流程全解析

最近与 Anthropic、Claude 和 Claude Code 相关的技术讨论热度很高，许多标题把它形容为“AI 领地战争”。在一线开发者眼中，真正印象更深的反而不是某家大模型能力又提升了多少，而是大量项目在接入 Anthropic 服务或兼容网关时，集中出现两类报错：一类是unable to connect to anthropic services failed to connect to api.anthropic.com: status 403，另一类是doesn't look like an anthropic model: expected a gateway model route reference。前者说明请求没有到达模型，后者说明请求虽然到达了某个网关或模型服务，但服务返回的模型信息与客户端预期不一致。

这篇文章不讨论厂商之间的商业模式，而是把这两类报错当作模型接入层的排障入口。全文会围绕 Anthropic API 的访问链路、鉴权 Header、模型名与网关路由机制、Claude Code 和 Spring AI 接入方式展开，依次说明“连接失败”“鉴权失败”“模型路由错误”应该如何定位。读完以后，你可以自己做一次从官方 API 到自建模型网关的最小联调，并且能根据返回状态码、响应 body 和日志，判断问题出在网络出口、密钥权限、Base URL 路径还是网关路由映射。

1. 模型接入层的三个关键问题，决定了你看到的报错类型

1.1 生态竞争不一定发生在模型层，更多发生在开发者入口层

模型层竞争关注的是推理能力、上下文长度、多模态效果和响应速度。到了工程侧，这些差距在大多数业务场景里并不明显，真正影响开发效率的是开发者到底用哪个入口把模型接进代码：是直接调官方 API，还是通过 Claude Code、Cursor 等 AI 编程工具，又或者是基于 Spring AI 这类抽象框架写一套应用代码。

一旦多个工具和框架同时接入同一个模型服务，问题就从“调用一个模型”变成“让多个客户端和多个模型协议互相兼容”。你面对的不只是api.anthropic.com这一个域名，还包括：

• Claude Code 采用的 Anthropic Messages API 协议。
• Spring AI 这类框架对 Anthropic 模型做的封装。
• 企业内部为了统一管理密钥、日志和成本而部署的模型网关。
• 网关后面可能不止 Claude 模型，还有自研模型或其他合规模型供应商。

这也是为什么最近很多讨论给人“AI 领地战争”的感觉：不同工具都想成为开发者默认入口，底层协议则变成一条重要边界。但从工程实践看，与其关心谁占住入口，不如先把手上的请求到底经过了哪些层弄清楚。

1.2 连接、鉴权、路由是三个阶段的问题

一次模型调用可以拆成三段：

第一段是客户端与 API 服务建立连接。DNS 解析、TCP 建连、TLS 握手、网络出口 IP 是否被允许访问，任何一个环节失败，都会表现为超时、连接重置或 403。

第二段是服务端完成鉴权。Anthropic API 需要识别客户端身份，校验 API Key 是否有权限、是否过期、账户是否有配额。这个阶段的错误也会返回 403，但响应 body 里通常会包含更精确的错误类型。

第三段是模型服务根据请求里的model字段进行路由。官方 API 内部会把自己支持的模型名映射到真实模型，如果请求里的模型名不存在，返回的错误会是“model not found”。如果请求发给的不是 Anthropic 官方 API，而是一个兼容 Anthropic 协议的第三方网关，情况会更复杂：网关需要把 Claude Code 发送的模型名映射到自己的后端模型服务，这种映射关系通常称为模型路由或 gateway model route。

实际项目里，三种问题的表现常常混在一起。比如你配置了自建网关，结果 API Key 填了网关生成的 Key，却把 Base URL 写成了官方地址；或者你填了正确的官方 Key，但网络出口被限制；又或者你用了第三方兼容服务，网关把模型名原样透传，下游模型服务却完全不认识这个名称。只有先把错误归类，后面的排查顺序才有意义。

1.3 用一份报错清单串起整篇实践

为了让你后续阅读时有方向，先把常见的报错和对应的排查章节放在一起：

下面的实践会先从 Anthropic API 的完整访问链路讲起，因为大多数排查手段都依赖对链路的理解。

2. 接入前，先把 Anthropic 模型调用的访问链路理清

2.1 一条完整请求会经过哪些节点

以 Claude Code 为例，一条请求从本地终端到最终回答，通常经过这些节点：

1. Claude Code 客户端读取配置，拿到 API Key、Base URL 和模型名。
2. 客户端向 Anthropic Messages API 的POST /v1/messages发送 JSON 请求。
3. API 服务先做网络层接入检查，再做鉴权。
4. 鉴权通过后，服务根据请求体里的model字段选择模型，并把 prompt 交给推理服务。
5. 推理结果通过 HTTP 响应返回，官方 API 默认支持流式和非流式两种方式，Claude Code 一般使用 SSE 流式响应。

如果请求不是直接发给官方 API，而是发给企业网关，链路会多一层。网关在收到 Claude Code 的请求后，需要先按 Anthropic 协议解析，再把模型名转换成真正负责推理的后端服务地址。推理后，网关还要把后端返回的结果包装成 Claude Code 能识别的协议格式。

看链路的时候，要记住一个原则：工具报错信息不一定来自最终推理模型。很多看起来像“模型错误”的提示，其实来自中间网关或协议转换层。

2.2 Anthropic API 的鉴权与 Header

请求 Anthropic API 时，核心 Header 有三个：

• x-api-key：携带 API Key。
• anthropic-version：声明客户端支持的 API 版本。
• content-type：声明请求体格式，通常是application/json。

部分场景还会用到Authorization: Bearer ...，例如通过 OAuth token 访问。这里要注意，很多框架在底层会自动加上这些 Header，但如果你是自己封装 HTTP 请求，很容易漏掉anthropic-version。

anthropic-version的作用不只是“过时检查”，它决定服务端对某些字段、工具调用方式和响应格式的解释方式。协议演进过程中，同一个字段的含义可能发生变化。比如工具调用参数、图片输入格式、系统提示的结构，在不同版本下可能存在细微差异。所以排查鉴权问题时，不要只检查 API Key，还要确认anthropic-version是否已经携带。

2.3 第三方网关与模型路由：理解 gateway model route

Anthropic 官方 API 内部也有模型路由，但官方服务会把普通开发者从路由细节中隔离出去。你只需要传一个模型名，服务端自己知道这个名字对应哪一版权重、哪个推理集群。

自建网关的时候，模型路由必须明确出现。网关里通常会维护一张路由表，把“客户端传来的模型名”映射到“实际被调用的模型服务”。比如客户端传来的模型名是claude-3-5-sonnet-latest，网关需要把它映射成实际部署的精确版本，或者是某个内部别名。

有些网关产品把这种映射称为 route，有些称为 provider/model 映射。Claude Code 等客户端发出的模型名可能还会带上前缀，例如anthropic/claude-3-5-sonnet-20241022。这不是 Anthropic API 原生格式，但它经常出现在 AI 编程工具和网关配合使用的场景里。

如果网关只做 HTTP 转发，不修改模型名，也不检查自己的路由表，就会出现这样的结果：Claude Code 发送一个带命名空间的模型名，网关把请求原样转给后端，后端看到这个模型名后返回“不存在这个模型”，或者返回一次不能被 Claude Code 识别的模型描述。doesn't look like an anthropic model: expected a gateway model route reference这类错误，往往就发生在这个节点。

2.4 官方 API、兼容网关、私有化服务的差异

同一个 Claude Code 客户端，在三种模式下，配置差异很小，行为差异却很大：

差异集中在 Base URL、API Key 和模型名三处。很多联调失败，是因为三者没有对齐：Base URL 指向网关，API Key 却是官方 Key；或者 API Key 是网关的，模型名却写成了某个不存在于路由表中的名称。

3. 最小环境准备：用 Claude Code 和 Spring AI 各跑一次调用

3.1 本地环境要求

先准备一个可以复现联调的最小环境。如果你是做 Java 应用集成，建议准备 JDK 17 以上和一个 Spring Boot 工程；如果你主要是使用 AI 编程工具，那么准备 Node.js 环境即可，因为 Claude Code 通常依赖 Node.js 运行。

建议环境要求如下：

第一次实践不要求把生产该做的事都做齐，但建议先单独建一个测试账号或测试 API Key。不要直接用生产 Key 做连通性测试，因为一些错误的重试会把限流触发的概率放大。

3.2 准备 API Key 与基础连通性验证

拿到 API Key 后，先用环境变量保存，不要写进代码仓库：

export ANTHROPIC_API_KEY="这里填写你的测试Key" export ANTHROPIC_BASE_URL="https://api.anthropic.com" export ANTHROPIC_MODEL="claude-3-5-sonnet-latest"

这里用claude-3-5-sonnet-latest只是示例。落地前一定要去 Anthropic 控制台确认当前账号可用的模型名，因为模型 ID 可能随版本调整。不要假设某个名字一定长期存在。

先做一次最原始的 curl 请求，绕过所有客户端框架，确认网络和密钥本身没有问题：

curl -sS -o /tmp/anthropic_response.json -w "%{http_code}\n" \ 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": 32, "messages": [ { "role": "user", "content": "ping" } ] }'

命令执行后，第一行输出的是 HTTP 状态码。如果输出200，说明网络和密钥链路正常；如果输出403，需要继续排查。查看响应体可以用：

cat /tmp/anthropic_response.json

后端返回的 JSON 里通常会包含error.type和error.message，这些信息比 HTTP 状态码更有排查价值。

3.3 Claude Code 接入 Anthropic API

在终端中安装并进入 Claude Code 后，它会读取当前环境变量。如果只在终端里执行过 export，请确认启动 Claude Code 的终端窗口和保存环境变量的窗口是同一个，否则变量不会生效。

常见配置方式是：

export ANTHROPIC_API_KEY="..." export ANTHROPIC_BASE_URL="https://api.anthropic.com" export ANTHROPIC_MODEL="claude-3-5-sonnet-latest" claude

如果 Claude Code 已经启动，修改环境变量后需要重启进程。很多“改了不生效”的问题，都是改了.env或 shell 配置后忘记重启。

在这个阶段，不建议直接用 Claude Code 连自建网关。正确顺序是：先确保 Claude Code 能直连官方 API 并正常回答一次，再切换 Base URL 到网关。否则同时出现网络和协议问题，你很难定位根因。

3.4 用 Spring AI 写一个最小调用

Spring AI 是对模型 API 做抽象的上层框架。在 Spring Boot 工程中，常见做法是在pom.xml中加入 Spring AI 的 Anthropic Starter，然后在application.yml里配置：

spring: ai: anthropic: api-key: ${ANTHROPIC_API_KEY} base-url: ${ANTHROPIC_BASE_URL:https://api.anthropic.com} chat: options: model: ${ANTHROPIC_MODEL:claude-3-5-sonnet-latest} max-tokens: 1024 temperature: 0.7

不同 Spring AI 版本的配置路径并不完全一致，例如有的版本要求spring.ai.anthropic.chat.options.model，有的版本可能采用不同的属性前缀。上面配置用于说明思路，正式项目里要以你使用的 Spring AI 版本文档为准。

Java 代码可以保持简单，先把一次请求跑通：

import org.springframework.ai.chat.client.ChatClient; import org.springframework.stereotype.Service; @Service public class AnthropicChatService { private final ChatClient chatClient; public AnthropicChatService(ChatClient.Builder builder) { this.chatClient = builder.build(); } public String ask(String question) { return chatClient.prompt(question).call().content(); } }

这段代码只是用来验证 Spring AI 是否完成了密钥注入、模型名选择和 HTTP 调用。如果返回结果为空或抛异常，优先回退到第 3.2 节的 curl，确认是否 API 侧已经在报错。

3.5 验证成功后要先看什么数据

一次请求成功后，不要急着写业务逻辑。建议把下面几个信息记录下来：

• 使用的模型名，精确到服务端返回的最终模型名。
• 请求耗时和 token 消耗。
• HTTP 状态码与错误类型。
• 使用的 API Key 后缀标识。
• 请求发出的出口 IP 或网关节点。

这些数据在后续排查 Agent 多次调用切换模型时很有用。很多线上问题不是第一天集成就发生的，而是某个模型改名、Key 扩容或网关路由调整之后才出现。如果没有基础数据，你很难判断变化从哪里开始。

4. 处理 403：unable to connect to anthropic services 的排查链路

4.1 先判断错误发生在网络层还是业务层

unable to connect to anthropic services failed to connect to api.anthropic.com: status 403这类提示，写法上容易让人以为“连接不上”，但实际上status 403说明 TCP 连接已经建立，HTTP 请求已经到达服务器，是服务端拒绝请求，而不是网络不通。

这是排查中最关键的分岔路口。如果你看到的是connect timed out、Connection refused、Could not resolve host，那属于网络层；如果你看到的是status 403，必须先停止纠缠 DNS 和网络，转向鉴权和访问策略。

可以先用一条简单命令判断：

curl -sS -o /dev/null -w "%{http_code}\n" \ https://api.anthropic.com/v1/models \ -H "x-api-key: ${ANTHROPIC_API_KEY}" \ -H "anthropic-version: 2023-06-01"

如果这条也返回 403，那么问题大概率出在 API Key 或账号权限；如果这条返回不同状态码，再结合你的完整请求对比 Header 和路径。

4.2 排查网络出口与访问策略

虽然 403 多半不是“网络不通”，但在少数情况下，网络策略层也会返回 403。常见场景包括：

• 企业防火墙或云安全组拦截了对该域名的 HTTP 请求。
• API 服务要求调用方出口 IP 在白名单内，而当前服务器 IP 未加入白名单。
• 网关节点所在地的网络策略不允许访问目标域名。

这类问题在本地开发时表现不明显，但在 CI/CD 服务器、容器环境或自建网关机器上容易出现。排查方式是在相同的网络出口下直接执行 curl，观察是否能拿到 200。如果 curl 能通过而 Claude Code 报 403，则问题在客户端配置或 Header；如果 curl 也报 403，则需要修改网络出口或联系平台管理员确认访问策略。

注意：自建网关上出现 403，不一定来自模型服务，也可能来自网关自身的安全策略。网关需要检查调用方是否携带有效凭据、请求头是否符合预期、请求路径是否在白名单中。

4.3 排查 API Key 与配额

收到 403 后，优先查看响应 JSON 里的错误类型。下面是一些常见原因：

这些错误可能与 403 一起出现。不要只记录状态码，要把error.message一并记录。很多网关监控里只保留了状态码，缺少错误消息，导致事后无法复盘。

4.4 排查 Header 与端点路径

确认 Key 没问题后，再检查请求本身。

第一，Base URL 是否重复带有/v1。有些 SDK 的 Base URL 只要求填到域名，框架会补上/v1；有些网关要求完整填到/v1。如果你两者混用，可能出现https://api.anthropic.com/v1/v1/messages这类路径，服务端可能返回 404，也可能因为路径不匹配而拒绝，表现为 403。

第二，是否携带了正确的anthropic-version。服务端如果无法识别版本，可能导致鉴权策略无法匹配。最好显式设置一个明确的版本，不要依赖框架默认值。

第三，是否误用了其他平台的 Key。Anthropic API 与一些网关、云平台提供的 Anthropic 兼容服务并不完全共享同一套 Key。用错了 Key 之后，请求同样能建立连接，但服务器校验身份时会拒绝。

检查方式仍然是最小化：先用自己的 Key 通过 curl 访问官方 API，然后在同样的命令里逐步替换 Base URL、Header 和模型名。哪一步开始出现 403，问题就在哪一步。

4.5 错误响应格式留给排查的线索

Anthropic API 的错误响应通常有相对固定的结构。一个简化的示例：

{ "type": "error", "error": { "type": "permission_error", "message": "Your API key does not have permission to access this resource." } }

你的网关可能返回类似的错误结构，也可能不一致。遇到第三方网关时，要重点看错误有没有透传原始上游错误。有些网关会把上游 403 吞掉，只返回一个笼统的upstream error。遇到这种情况，必须检查网关日志，找到网关真正请求上游时使用的 URL、Key、Header 和收到的状态码。

实际项目里，我建议用「排除变量」的方式处理 403：

1. 使用官方域名、官方 Key、最小模型名跑通一次，作为基线。
2. 只修改 Base URL，指向网关，其余不变。
3. 只修改 API Key，使用网关 Key，其余不变。
4. 只修改模型名，使用网关路由表的模型名，其余不变。
5. 每次只改一个变量，同时观察 curl 返回和网关日志。

这样最多五轮请求，基本就能定位问题在哪一层。

5. 模型路由错误：doesn’t look like an anthropic model 的根因与解决

5.1 这条错误通常不是模型不存在，而是路由概念不一致

doesn't look like an anthropic model: expected a gateway model route reference从字面看很像“模型不存在”，但实际排障中经常不是这样。更准确的解读是：客户端发送的模型名需要被网关解释成一个路由条目，但网关没有找到或者返回了一个客户端无法理解的模型对象。

出现这种错误时，要理解一个差异：

• 官方 API 内部处理模型名，但不会把一个“路由引用”返回给客户端。
• 第三方网关需要暴露模型名到后端模型的显式映射。如果网关设计不够规范，模型路由可能只存在于管理页面，没有同步到请求处理逻辑。

因此，模型名能不能被识别，取决于网关的路由配置，而不只是模型服务是否启停。你甚至可能在后端已经部署了模型，但网关路由表里没有为这个模型添加对应条目，于是客户端仍然收到路由错误。

5.2 Claude Code 发送的 model 字段如何被网关解析

Claude Code 在发送请求时，model字段会被放到 JSON body 顶层。一个简化后的请求片段如下：

{ "model": "anthropic/claude-3-7-sonnet-20250219", "max_tokens": 2048, "messages": [ { "role": "user", "content": "帮我检查这段代码" } ] }

这个model值可能带有供应商前缀，例如anthropic/。当服务端是官方 API 时，官方能识别这个名称；但当你把请求发给自己的模型网关时，网关必须知道anthropic/claude-3-7-sonnet-20250219应该路由到哪一个具体后端。

如果在 Claude Code 的模型配置中填的是一个不存在的名称，比如你在网关后台只能选择claude-3-5-haiku，但客户端传的是一个完整的带日期版本名，网关可能不会自动做归一化处理，于是报错。

5.3 修复网关映射与模型透传

在自建网关上，建议把模型路由分成两层配置：

• 对外模型名：客户端实际发送的模型名。
• 对内模型服务：真正执行推理的模型服务地址和内部模型名。

一个常见的路由配置示例如下：

model_routes: - alias: "anthropic/claude-3-7-sonnet-20250219" provider: name: "anthropic" api_key_env: "INTERNAL_ANTHROPIC_API_KEY" base_url: "https://api.anthropic.com" target_model: "claude-3-7-sonnet-20250219" - alias: "claude-3-5-sonnet-latest" provider: name: "internal-openai-compatible" base_url: "http://127.0.0.1:8000/v1" target_model: "my-company-chat-v2"

针对不同的 alias，网关需要执行不同的转发逻辑。有的 alias 可以直接透传给 Anthropic 官方，有的 alias 则需要把 Anthropic 协议转换成 OpenAI 兼容协议，再发给内部模型服务。

修复这类报错的步骤通常是：

1. 在 Claude Code 日志或抓包结果中找到实际发送的model字段。
2. 到网关后台确认该字段是否有对应路由。
3. 如果没有，添加路由，并指定 internal target model。
4. 添加后先通过 curl 模拟 Claude Code 的请求，确认网关能正常返回。
5. 重启 Claude Code，换到新的模型名再试。

5.4 如果用的是 Spring AI 或兼容 SDK，还需要检查 base-url 差异

Spring AI 这类框架接入 Anthropic 时，对 Base URL 的处理和 Claude Code 不完全一样。框架会自己拼接路径，可能使用/v1/messages，也可能使用/api等商家自定义路径。如果网关只实现了 Claude Code 常用路径，却没有兼容框架拼接出来的路径，就会出现模型路由正常但请求路径 404 的情况。

排查时可以先把 Spring AI 的日志级别调到 debug，观察它实际请求的 URL。例如在application.yml中临时开启：

logging: level: org.springframework.ai: debug org.springframework.web.client: debug

查看日志里实际发出去的 URL、Header 和响应状态码，再和网关日志中的记录对比。问题通常出在以下三处不一致：

• Spring AI 配置的 Base URL 与网关要求的 Base URL 不一致。
• Spring AI 使用的模型名不在网关路由表内。
• Spring AI 自动附加的模型前缀或 Header 与网关预期不同。

调整时要谨记：不要在多个框架里同时修改模型名和 Base URL。应该固定一个变量，用抓包或日志确认好后，再处理下一个变量。

6. AI 编程工具接入非 Anthropic 模型时，网关要补齐哪些能力

6.1 最小可用网关必须具备的协议能力

很多开发者把“接入非 Anthropic 模型”简单理解成“把 model 字段改一改”。但 Claude Code 是一个面向 Agent 的 AI 编程工具，不只是发一次普通问答。它会携带系统提示、工具定义、多轮消息历史，并使用流式响应逐步渲染输出。网关如果只处理普通 JSON，会在更复杂场景下失败。

一个最小可用网关，至少要能处理以下内容：

• 正确接收POST /v1/messages，并解析 JSON Body。
• 从x-api-key、Authorization或自定义 Header 中取得调用方身份。
• 根据model字段完成路由。
• 将请求体转换成后端模型服务的协议。
• 接收后端响应，可能需要做流式转发或普通 JSON 转换。
• 把后端错误信息标准化成 Anthropic 风格的错误格式。

如果后端不是 Anthropic 官方 API，而是 OpenAI 兼容服务，你需要自己处理协议差异。这不只是把messages和tools字段名改掉，还涉及角色格式、工具调用参数表达、内容分段方式以及流式事件类型的不同。

6.2 流式与非流式响应的一致性

Claude Code 默认使用流式响应，SSE 事件类型包括message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop等。网关在后端不是 Anthropic 时，不能简单地把后端事件透传，需要把事件类型重新映射到 Anthropic 协议。

这里有一个常见的坑：后端模型的某次输出可能不在 text 块中，而在 tool_use 相关的 content block 中。如果网关只处理content_block_delta里的text_delta，会导致 Claude Code 无法识别工具调用，Agent 流程中断。最小网关至少要把tool_use的输入参数完整组装，不能在流式过程中丢字段。

非流式调用也要检查。Claude Code 等客户端在工具调用和后台任务中可能会使用非流式接口。网关要同时保证流式和非流式返回的结果语义一致。

6.3 鉴权模型：既要保留原 Header，也要支持新凭据

接入自建网关后，Claude Code 携带的 API Key 通常不再是 Anthropic 官方 Key，而是网关生成的 Key。网关完成自身鉴权后，再去调用后端模型服务时，需要使用后端自己的凭据。

因此，鉴权至少要拆成两层：

• 第一层：验证客户端是否有权使用这个网关。
• 第二层：由网关持有后端模型服务的密钥，按路由配置选择对应凭据。

不要直接把客户端的 Key 透传给后端，除非你明确知道后端能识别同一个 Key。把两层凭据混在一起，是自建模型网关最容易出现的安全问题。一旦客户端 Key 泄露，可能同时影响多个后端系统。

6.4 切换后要在真实 Agent 任务上做回归

普通问答验证通过，只能说明协议链路基本可用。Claude Code 在写代码、跑命令、读文件时会触发复杂的工具循环，这时候模型会连续请求多次，中间可能穿插工具调用结果。网关如果对某些内容块处理有偏差，问题会被放大。

建议至少在切换后的网关环境里执行这些回归任务：

• 让 Claude Code 阅读一个项目文件并修改其中一段代码。
• 让 Claude Code 使用一次工具调用，例如执行测试命令。
• 让 Claude Code 连续完成一个多步骤任务，例如创建文件、运行脚本、修 bug。
• 发送较长的代码上下文，观察是否出现截断或超时。

回归时不仅要看最终结果，还要看流式事件类型是否存在缺失。常用方式是抓取一次会话的网关请求日志，检查是否有长时间没有事件的阶段。

7. 生产级的 AI 接入基础设施（AI Infra）应该怎么搭

7.1 学习环境直接调用，生产环境走统一网关

在学习和原型验证阶段，使用官方 API、Beta 测试 Key、快速改代码完全没问题。但进入生产后，直接让业务系统各自保存 Anthropic API Key，会出现几个连锁问题：

• Key 分散在多个服务环境变量里，无法统一轮换。
• 各服务对 model 名的理解不一致，模型下线时难以评估影响范围。
• 缺少统一的调用日志，出问题时无法还原某条请求的完整链路。
• 成本无法按团队或业务线拆分。

所以生产环境通常要引入统一模型网关。网关负责鉴权、路由、限流、日志和模型切换，业务系统只需要知道网关地址和网关生成的 Key。Claude Code 这类工具可以指向网关，Spring AI 这类框架也可以配置成网关地址。真正与 Anthropic 官方或第三方模型服务交互的凭据，只保存在网关或密钥管理服务中。

7.2 密钥、日志、监控、成本与容灾

生产环境建议至少关注五件事：

第一，密钥管理。不要把 API Key 明文写在配置文件里。使用环境变量注入、云上密钥管理服务或单独的密钥平台。日志中不要记录完整 Key，只保留 Key 的哈希或后缀，方便定位到具体调用方。

第二，请求日志。网关需要记录请求时间、调用方身份、模型名、实际路由到的后端、HTTP 状态码、响应耗时、token 使用量和错误消息。缺少这些字段，后续做成本核算和故障复盘会很困难。

第三，监控告警。需要关注的指标包括请求成功率、P95 延迟、429 限流次数、403 失败次数、token 消耗速率。403 占比突然上升，往往意味着 Key 轮换或权限策略变更，而不是模型本身出问题。

第四，成本控制。Anthropic 类长文本模型的调用成本与输入 token 相关。Agent 工具如果频繁重发完整上下文，成本会快速膨胀。网关最好能为每个调用方设置 token 或金额预算，并且在接近阈值时告警。

第五，容灾与重试策略。不要把 403 和 429 同样处理。403 重复重试只会放大问题，429 可以做退避重试。超时和连接错误的重试次数、间隔也要单独配置。

7.3 模型路由规则与发布流程

模型版本更新后，经常会出现“旧模型名失效”的问题。Anthropic 有些模型名带有明确日期，例如claude-3-5-sonnet-20241022这种命名方式，模型服务下线后该名称可能无法继续使用。

模型路由发布应该遵循类似应用的发布流程：

1. 先在预发环境添加最新的模型名，让客户端指定该模型名跑一次回归。
2. 验证通过后，在网关管理后台新增 alias，并指向新模型。
3. 正常流量中的一小部分切到新 alias，观察延迟、错误率和输出质量。
4. 全部切换后，再下线旧模型，避免客户端还在用旧名称。
5. 关键系统要记录模型名实际生效时间，方便后续成本归因。

模型路由规则不要直接在代码中散落维护，尽量集中在网关配置或专门的配置服务中，并通过多环境差异管理配置内容。

7.4 Agent 从玩具到业务系统的差距

Claude Code、Cursor、Spring AI 这类工具最大的价值不只是单轮问答，而是 Agent 可以自主规划任务并调用工具。但 Agent 从演示变成业务系统，差距往往体现在这些工程细节上：

• 上下文窗口有限，需要正确裁剪和压缩。
• 工具权限需要收口，不能只靠模型自觉。
• 错误恢复和重试策略必须明确。
• 模型输出需要校验，不能直接信任。
• 多模型切换时，能力差异可能导致同一套 Agent 流程表现不同。

接入 Anthropic 生态时，可以把“能调通 API”作为起点，把“通过统一网关稳定支撑多个 Agent 业务”作为下一阶段目标。这中间既需要模型路由、鉴权、日志，也需要流程设计、权限控制和灰度发布机制。

8. 常见问题速查与排查清单

8.1 常见问题速查表

下面这些是从一线接入和网上讨论中比较高频的问题，按现象整理成速查表：

8.2 可复用的上线前排查清单

在切换模型、接入新网关或发布 AI 功能前，建议逐项确认：

1. 使用官方 API 和官方 Key 的一次最小调用是否正常。
2. 当前出口 IP 是否能访问目标域名，是否需要在平台侧配置白名单。
3. API Key 是否只使用环境变量或密钥管理系统注入，没有硬编码。
4. Base URL 是否完整且没有多余的路径前缀，是否与 SDK 文档口径一致。
5. anthropic-version是否显式设置，且版本与使用的模型能力匹配。
6. 模型名是否能从控制台查到，并在网关路由表中有对应条目。
7. 自建网关是否同时支持流式和非流式调用。
8. 网关是否记录了调用方身份、模型名、路由结果、状态码和耗时。
9. 是否区分了 403、401、404、429 的重试策略。
10. 模型版本新增或下线是否走灰度发布流程，是否已通知所有调用方。

这个清单不仅适用于 Anthropic API，也适用于任何会切换模型网关的 Agent 项目。每次遇到连接失败，先把问题定位到链路的具体层，再动手修改；每次修改只改一个变量，并保留日志证据。这种做法会让复杂的模型接入问题变得可控。