提到 Anthropic 和 Claude API 时开发者第一反应通常是模型能力。但把 Claude Code 放进研发环境之后最先出问题的往往不是模型回答质量而是连接层、路由层和审计层unable to connect to anthropic services、failed to connect to api.anthropic.com又或者一个看起来像内部提示词的报错expected a gateway model route reference。与此同时更多团队开始关心一个现实约束输入给模型的文本从哪里来、内部聊天里流传的外部资料是否允许被处理、每次调用的日志到底有没有被妥善保存。本文不讨论具体商业纠纷而是把关注点放在工程落地上先理解 Claude Code 的接入链路再排查连接异常然后配置统一网关最后补齐审计日志和内容过滤能力。1. 先建立一张 Claude Code 接入链路图再改任何配置1.1 Claude Code 本质上是一个 Anthropic Messages API 客户端Claude Code 是 Anthropic 提供的命令行和编辑器 AI 助手。无论你是在终端里输入claude还是在 VS Code 中加载 Claude Code 扩展它本身不会自己产生模型能力而是把一个对话、一段代码或一个操作指令发送到模型服务端然后接收模型返回结果继续执行。默认场景下的请求路径大致如下Claude Code CLI / VS Code 扩展 | | 读取 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL v API 网关可选企业内部自建 | | POST /v1/messages v api.anthropic.comClaude Code 使用的核心接口是 Anthropic Messages API默认地址为https://api.anthropic.com/v1/messages。它会把多轮消息、系统提示词、工具定义和本轮用户输入放在一个请求体中提交。如果你没有额外配置请求就会直接发送到 Anthropic 官方服务如果你配置了ANTHROPIC_BASE_URL请求就会先到达你指定的网关或接入层。在实际问题排查中切忌只盯着报错文本。上面的链路图说明一个报错可能来自网络层、端点配置、鉴权方式、模型名匹配、网关响应格式等多个环节。必须先确认当前 Claude Code 被“引导”到了哪一条路径再继续定位。1.2 个人直连和企业统一网关是两种完全不同的接入方式只在本机做实验时直连官方 API 最省事。每个开发者用自己的 API Key把请求发到api.anthropic.com环境变量清晰前端工具也很容易跑通。但研发团队接入 Claude Code 时直连会带来几个运维问题API Key 分散在开发者本地离职或泄漏后很难统一吊销。没有统一审计入口谁在什么时候发了什么请求完全靠客户端本地日志。如果以后要切换到其他兼容模型或企业内部合规网关需要通知每个人修改环境变量。无法在入口处做内容过滤、限流和告警。因此团队环境通常采用“统一网关”模式。Claude Code 的请求先到达企业内部网关网关负责鉴权、路由、限流、日志和内容检查再把通过检查的请求转发到 Anthropic 官方 API 或已授权的第三方模型服务。个人学习和企业统一接入的对比见下表对比维度个人直连企业统一网关配置成本低设置环境变量即可中等需要部署和维护一个服务API Key 管理分散在每个终端集中在网关侧客户端使用短期令牌日志审计依赖客户端本地可在网关层统一记录内容过滤基本没有可在请求进入上游前过滤模型切换手动改本地配置网关层路由客户端基本无感适合场景学习、个人项目研发团队、合规要求较高的生产环境2. Claude Code 的环境变量、模型名和路由必须同时匹配2.1 关键环境变量速查Claude Code 的配置目标很简单告诉它“把请求发到哪里用什么身份请求哪个模型”。不同版本对部分变量的解析会有差异但下面几个变量在社区和官方接入场景中出现频率最高。环境变量作用示例注意点ANTHROPIC_API_KEY官方或网关的 API Keysk-ant-...直连官方时使用网关场景下也可以用网关发布的 KeyANTHROPIC_AUTH_TOKENBearer Token部分网关要求sk-litellm-master-key不一定所有 Claude Code 版本都支持需看当前文档ANTHROPIC_BASE_URL覆盖默认请求地址http://127.0.0.1:4000一般不要带/v1/messages后缀避免重复拼接ANTHROPIC_MODEL默认主模型名claude-sonnet必须和网关或官方 API 可识别的模型名一致ANTHROPIC_SMALL_FAST_MODEL后台轻量任务的模型名claude-haiku如果没有配置默认按 Anthropic 客户端逻辑回退在终端里推荐把环境变量写在项目级.env文件或启动脚本中而不是塞进全局配置。在 VS Code 中可以通过任务或调试配置注入环境变量也可以在 Claude Code 的设置文件中配置。最稳妥的方式是先通过 Shell 文件确认变量env | grep -i anthropic如果看到某个变量存在且指向旧网关而当前项目想使用新网关就必须先清理旧变量。很多“配置改了不生效”的案例原因是 Shell 启动时加载了旧的环境变量而不是项目内新写的那一行。2.2expected a gateway model route reference到底在说什么当你把ANTHROPIC_BASE_URL指向一个兼容网关时网关不仅要接收请求还要以 Anthropic Messages API 的格式返回响应。Claude Code 收到响应后会校验响应中的模型来源和路由信息。如果你看到doesnt look like an Anthropic model: expected a gateway model route reference常见的解释是Claude Code 认为这次请求没有落到一个能够被它识别的 Anthropic 模型路由上。可能的原因有三种网关配置的模型名和ANTHROPIC_MODEL不一致。网关把请求转发到了 OpenAI 风格的接口返回的是choices结构而不是 Anthropic 的content结构。网关本身支持多个模型但没有把当前请求路由到 Anthropic 兼容模型上。如果只是把api.anthropic.com改成本地地址却没有在本地服务里实现/v1/messages协议转换就很容易出现这个错误。它并不是“Claude Code 不认识 Anthropic”而是“网关没有给出 Claude Code 认识的路由和响应格式”。2.3 Claude Code 可以接入非 Anthropic 模型吗很多团队问过这个问题。从协议和工具链上看Claude Code 的对话流程并不是直接兼容任意模型的 JSON 格式。官方客户端会发送 Anthropic Messages 格式的请求其中包含工具定义、多轮历史、系统提示词等结构。如果希望把请求路由到一个非 Anthropic 模型必须在上游前面保留一层协议转换网关。可行的做法是Claude Code 仍按 Anthropic 格式向网关发请求网关把请求转换成目标模型供应商的格式例如 OpenAI Chat Completions 格式或本地模型的 OpenAI 兼容格式目标模型返回后网关再把结果转换成 Anthropic Messages 格式返回给 Claude Code。这个方案在技术上是可完成的但需要注意几个边界非 Anthropic 模型未必支持 Claude Code 需要的所有工具 Claude Code接入链路与网关配置：从连接报错到统一审计
提到 Anthropic 和 Claude API 时开发者第一反应通常是模型能力。但把 Claude Code 放进研发环境之后最先出问题的往往不是模型回答质量而是连接层、路由层和审计层unable to connect to anthropic services、failed to connect to api.anthropic.com又或者一个看起来像内部提示词的报错expected a gateway model route reference。与此同时更多团队开始关心一个现实约束输入给模型的文本从哪里来、内部聊天里流传的外部资料是否允许被处理、每次调用的日志到底有没有被妥善保存。本文不讨论具体商业纠纷而是把关注点放在工程落地上先理解 Claude Code 的接入链路再排查连接异常然后配置统一网关最后补齐审计日志和内容过滤能力。1. 先建立一张 Claude Code 接入链路图再改任何配置1.1 Claude Code 本质上是一个 Anthropic Messages API 客户端Claude Code 是 Anthropic 提供的命令行和编辑器 AI 助手。无论你是在终端里输入claude还是在 VS Code 中加载 Claude Code 扩展它本身不会自己产生模型能力而是把一个对话、一段代码或一个操作指令发送到模型服务端然后接收模型返回结果继续执行。默认场景下的请求路径大致如下Claude Code CLI / VS Code 扩展 | | 读取 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL v API 网关可选企业内部自建 | | POST /v1/messages v api.anthropic.comClaude Code 使用的核心接口是 Anthropic Messages API默认地址为https://api.anthropic.com/v1/messages。它会把多轮消息、系统提示词、工具定义和本轮用户输入放在一个请求体中提交。如果你没有额外配置请求就会直接发送到 Anthropic 官方服务如果你配置了ANTHROPIC_BASE_URL请求就会先到达你指定的网关或接入层。在实际问题排查中切忌只盯着报错文本。上面的链路图说明一个报错可能来自网络层、端点配置、鉴权方式、模型名匹配、网关响应格式等多个环节。必须先确认当前 Claude Code 被“引导”到了哪一条路径再继续定位。1.2 个人直连和企业统一网关是两种完全不同的接入方式只在本机做实验时直连官方 API 最省事。每个开发者用自己的 API Key把请求发到api.anthropic.com环境变量清晰前端工具也很容易跑通。但研发团队接入 Claude Code 时直连会带来几个运维问题API Key 分散在开发者本地离职或泄漏后很难统一吊销。没有统一审计入口谁在什么时候发了什么请求完全靠客户端本地日志。如果以后要切换到其他兼容模型或企业内部合规网关需要通知每个人修改环境变量。无法在入口处做内容过滤、限流和告警。因此团队环境通常采用“统一网关”模式。Claude Code 的请求先到达企业内部网关网关负责鉴权、路由、限流、日志和内容检查再把通过检查的请求转发到 Anthropic 官方 API 或已授权的第三方模型服务。个人学习和企业统一接入的对比见下表对比维度个人直连企业统一网关配置成本低设置环境变量即可中等需要部署和维护一个服务API Key 管理分散在每个终端集中在网关侧客户端使用短期令牌日志审计依赖客户端本地可在网关层统一记录内容过滤基本没有可在请求进入上游前过滤模型切换手动改本地配置网关层路由客户端基本无感适合场景学习、个人项目研发团队、合规要求较高的生产环境2. Claude Code 的环境变量、模型名和路由必须同时匹配2.1 关键环境变量速查Claude Code 的配置目标很简单告诉它“把请求发到哪里用什么身份请求哪个模型”。不同版本对部分变量的解析会有差异但下面几个变量在社区和官方接入场景中出现频率最高。环境变量作用示例注意点ANTHROPIC_API_KEY官方或网关的 API Keysk-ant-...直连官方时使用网关场景下也可以用网关发布的 KeyANTHROPIC_AUTH_TOKENBearer Token部分网关要求sk-litellm-master-key不一定所有 Claude Code 版本都支持需看当前文档ANTHROPIC_BASE_URL覆盖默认请求地址http://127.0.0.1:4000一般不要带/v1/messages后缀避免重复拼接ANTHROPIC_MODEL默认主模型名claude-sonnet必须和网关或官方 API 可识别的模型名一致ANTHROPIC_SMALL_FAST_MODEL后台轻量任务的模型名claude-haiku如果没有配置默认按 Anthropic 客户端逻辑回退在终端里推荐把环境变量写在项目级.env文件或启动脚本中而不是塞进全局配置。在 VS Code 中可以通过任务或调试配置注入环境变量也可以在 Claude Code 的设置文件中配置。最稳妥的方式是先通过 Shell 文件确认变量env | grep -i anthropic如果看到某个变量存在且指向旧网关而当前项目想使用新网关就必须先清理旧变量。很多“配置改了不生效”的案例原因是 Shell 启动时加载了旧的环境变量而不是项目内新写的那一行。2.2expected a gateway model route reference到底在说什么当你把ANTHROPIC_BASE_URL指向一个兼容网关时网关不仅要接收请求还要以 Anthropic Messages API 的格式返回响应。Claude Code 收到响应后会校验响应中的模型来源和路由信息。如果你看到doesnt look like an Anthropic model: expected a gateway model route reference常见的解释是Claude Code 认为这次请求没有落到一个能够被它识别的 Anthropic 模型路由上。可能的原因有三种网关配置的模型名和ANTHROPIC_MODEL不一致。网关把请求转发到了 OpenAI 风格的接口返回的是choices结构而不是 Anthropic 的content结构。网关本身支持多个模型但没有把当前请求路由到 Anthropic 兼容模型上。如果只是把api.anthropic.com改成本地地址却没有在本地服务里实现/v1/messages协议转换就很容易出现这个错误。它并不是“Claude Code 不认识 Anthropic”而是“网关没有给出 Claude Code 认识的路由和响应格式”。2.3 Claude Code 可以接入非 Anthropic 模型吗很多团队问过这个问题。从协议和工具链上看Claude Code 的对话流程并不是直接兼容任意模型的 JSON 格式。官方客户端会发送 Anthropic Messages 格式的请求其中包含工具定义、多轮历史、系统提示词等结构。如果希望把请求路由到一个非 Anthropic 模型必须在上游前面保留一层协议转换网关。可行的做法是Claude Code 仍按 Anthropic 格式向网关发请求网关把请求转换成目标模型供应商的格式例如 OpenAI Chat Completions 格式或本地模型的 OpenAI 兼容格式目标模型返回后网关再把结果转换成 Anthropic Messages 格式返回给 Claude Code。这个方案在技术上是可完成的但需要注意几个边界非 Anthropic 模型未必支持 Claude Code 需要的所有工具