Amux API

Claude Code Base URL 配置与错误排查

更新于 2026-10-30 · amux.shop

简答：如果你已经拿到一个 API 网关地址，却不知道是否要加 /v1、该用哪个密钥变量或模型名，先不要猜：向网关确认 Anthropic API 兼容入口、认证方式和模型映射，再将完整入口写入 ANTHROPIC_BASE_URL。配置后用 /status 检查当前认证与模型，并通过网关日志、响应头或 request ID 验证请求是否真正到达目标网关。

定义：Claude Code 的 Base URL 是用于指定代理或 LLM 网关入口的地址前缀，它对应 Anthropic API 兼容协议，不等同于 OpenAI SDK 的 base_url，也不一定需要添加 /v1。

先看速查表：Base URL、密钥和模型名怎么对应

本文是通用的 Claude Code 接入与排错指南，不是任何目标网关的官方页面。由于不同网关可能提供统一 Anthropic 入口、带子路径的转发入口，或完全不同的协议适配层，不能把某个服务的地址直接套用到另一个服务。

配置项应确认的内容不要直接假定
ANTHROPIC_BASE_URL网关提供的完整 Anthropic API 兼容入口不要默认追加 /v1、/messages，也不要重复拼接路径
ANTHROPIC_AUTH_TOKEN网关要求通过 Authorization 认证时使用的 token不要把所有服务的密钥都当成同一种认证头
ANTHROPIC_API_KEY网关或 Claude Code 明确要求的 API key 变量不要只根据变量名推断目标网关一定接受它
模型配置网关实际暴露的模型标识或映射名不要默认网关支持 Claude Code 当前默认模型名

Anthropic 的 LLM gateway 文档展示了统一 Anthropic 格式入口和带子路径的 pass-through 入口，说明 Base URL 是否包含额外路径取决于网关的接口设计，而不是 Claude Code 的固定规则。该文档还明确展示了 ANTHROPIC_AUTH_TOKEN 的静态 token 用于 Authorization 认证。查看 Anthropic 的 LLM gateway 配置说明。

最短成功标准：当前终端能读取目标变量，/status 显示预期的认证方式和模型，并且一次最小请求返回正常内容；如果要证明请求确实经过网关，还必须结合网关侧日志、响应头、request ID 或服务端监控，单独查看 /status 不足以证明流量已经到达目标网关。

为什么 Claude Code 的 Base URL 不能照搬 OpenAI 的写法

“Base URL”只是一个通用名称，不代表两个客户端使用相同协议。Claude Code 通过 ANTHROPIC_BASE_URL 路由到 Anthropic API 兼容入口；OpenAI SDK 常见的 base_url 则通常服务于 OpenAI 风格的路径、请求体和认证约定。两者可能在地址形式上相似，但请求端点、消息格式、认证头和流式响应要求都可能不同。

因此，如果一个服务只公开说明“OpenAI-compatible”，不能据此确认它能直接承载 Claude Code。应先确认它是否支持 Anthropic Messages API 或提供专门的 Anthropic 兼容入口。若服务文档同时给出 OpenAI 和 Anthropic 两种入口，应选择与 Claude Code 协议对应的那一个。

路径也不能靠猜。Anthropic 官方网关示例中，统一入口可以是网关根地址，某些 pass-through 入口则带有特定子路径；这正是不能机械添加 /v1 或 /messages 的原因。核对官方网关示例中的入口差异。

跨平台配置模板：先用临时变量验证

以下命令只展示变量语法。请将 https://gateway.example、your-token 和 gateway-model-name 替换为服务方明确提供的值。不要把真实密钥写入文章、截图、终端录屏或 Git 仓库。

macOS、Linux 或 WSL

export ANTHROPIC_BASE_URL='https://gateway.example'

export ANTHROPIC_AUTH_TOKEN='your-token'

export ANTHROPIC_MODEL='gateway-model-name'

claude

Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://gateway.example"

$env:ANTHROPIC_AUTH_TOKEN="your-token"

$env:ANTHROPIC_MODEL="gateway-model-name"

claude

Windows CMD

set ANTHROPIC_BASE_URL=https://gateway.example

set ANTHROPIC_AUTH_TOKEN=your-token

set ANTHROPIC_MODEL=gateway-model-name

claude

先使用临时变量而不是立即写入长期配置，便于判断问题来自 URL、认证、模型还是持久化配置。Claude Code 官方帮助中心建议通过 /status 查看当前启用的认证方式，并分别给出了 macOS/Linux、PowerShell 和 CMD 的环境变量检查方法。查看官方环境变量与认证检查方法。

需要长期生效时：settings.json 只放经过评估的配置

Claude Code 文档支持在设置文件的 env 对象中配置环境变量。官方网关示例使用了如下结构，但示例中的 token 仅用于说明格式，不建议把真实密钥直接写进项目文件。

{ "env": { "ANTHROPIC_BASE_URL": "https://gateway.example", "ANTHROPIC_MODEL": "gateway-model-name" } }

如果需要保存密钥，优先使用操作系统环境变量、密码管理器、开发环境 secret 注入或网关提供的安全凭证机制。若必须在本机配置文件中保存，至少确认该文件不会被 Git 跟踪，并检查项目的 .gitignore。Anthropic 的安全建议包括使用环境变量或 secret 管理、避免把密钥提交到代码仓库，并在泄露时及时轮换。查看 API key 安全建议。

不同版本或部署方式的设置文件路径、作用范围和支持字段可能变化。本文只采用官方资料明确展示的 env 配置结构；如果你的当前版本行为不同，应以本机 Claude Code 文档和 claude doctor 输出为准。

验证闭环：变量可见不等于请求已走网关

  1. 检查 Base URL：macOS/Linux 执行 printf '%s\n' "$ANTHROPIC_BASE_URL"；PowerShell 执行 $env:ANTHROPIC_BASE_URL；CMD 执行 echo %ANTHROPIC_BASE_URL%。确认地址没有多余引号、空格或重复路径。
  2. 检查认证冲突：启动 claude 后运行 /status。如果当前仍显示订阅登录或其他认证方式，检查是否残留 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或旧的登录状态。
  3. 检查模型：使用网关明确列出的模型名，或者在 Claude Code 中运行 /model 查看当前选择。官方模型配置说明支持通过 /model、--model 和环境变量调整模型，但网关自定义映射名仍需由网关提供方确认。查看 Claude Code 模型配置说明。
  4. 发送最小请求：输入“只回复：连接测试成功”，确认返回内容正常。不要把“Claude Code 能启动”当作请求成功。
  5. 核对网关侧信号：查看网关请求日志、响应头、request ID、计费记录或服务端访问日志。若这些信息均不可见，只能确认客户端收到响应，不能确认请求是否经过你指定的网关。
  6. 脱敏保存结果：记录状态码、错误类型、时间和 request ID，删除 Authorization、API key、Cookie、完整请求体和可能包含代码的日志内容。

如果目标网关没有请求日志或 request ID，可在其服务端增加受控的访问记录；不要为了验证而公开真实密钥或完整请求内容。Anthropic 的连接排查建议同样强调检查响应状态码、响应体和错误信息。查看官方连接检查方法。

401、403、404、429 和超时的分流排查

现象优先核对下一步
401 或 authentication error密钥是否错误、过期、撤销，认证变量是否选错重新确认网关要求的是 Authorization token 还是 API key，清除旧变量后重新启动终端
403 Forbidden账户、组织、工作区或模型权限确认密钥所属账户具有目标模型调用权限；不要仅凭 403 判断 Base URL 错误
404 Not Found路径、重复的 /v1、误填 /messages 或协议入口对照服务方给出的完整 Anthropic 入口逐字符检查，避免客户端和变量重复拼接
Invalid model 或 model not found模型名是否为网关实际暴露的标识向网关确认模型映射，或使用网关模型列表中的名称
429 或限流请求频率、并发、账户额度或工作区支出上限先查看响应体和 Retry-After；只有确认是临时限流时才按服务方规则退避重试
超时、TLS 或网络错误DNS、代理、证书、端口和网关可达性先检查域名解析、HTTPS 证书和代理配置，不要无条件重复请求
流式中断网关是否完整转发 Anthropic Messages API 的流式响应先验证短的非流式或短响应请求，再核对 SSE、超时和响应转发能力

Anthropic API 错误文档将 401 归为认证错误、403 归为权限错误、404 归为资源或路径不存在、429 归为速率或额度限制，并说明错误响应中包含可用于排查的状态信息。具体网关可能返回自己的错误格式，因此应同时保存脱敏后的原始响应。查看 Anthropic API 错误码说明。

如果你使用的是企业 HTTP/HTTPS 代理，而不是 Anthropic API 兼容网关，应配置 HTTP_PROXY 或 HTTPS_PROXY，不要把普通代理地址误填成 ANTHROPIC_BASE_URL。Anthropic 官方代理文档明确将普通代理配置与 LLM gateway 分开说明。查看官方企业代理配置。

认证变量冲突：为什么配置后仍像在使用原来的登录

Claude Code 的认证方式可能来自订阅登录、API key、企业平台或网关 token。若当前 Shell 中残留 API key，或者不同终端使用了不同变量，实际认证方式就可能与预期不一致。

官方帮助中心建议在 Claude Code 中运行 /status 查看当前启用的认证方式；官方 FAQ 还指出，残留的 ANTHROPIC_API_KEY 可能覆盖登录流程并导致认证异常。这里的“可能”取决于当前版本、登录状态和组织配置，不能把它理解为所有环境下都必然如此。查看环境变量认证优先级说明。

建议按以下顺序处理：先关闭 Claude Code；在当前 Shell 检查并清理不需要的 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN；只保留目标网关要求的认证变量；重新启动终端和 Claude Code；最后再次运行 /status。不要在多个 Shell 配置文件中放置不同的 Base URL。

常见问题

Claude Code 的 Base URL 一定要加 /v1 吗？

不一定。Anthropic 官方网关示例同时包含根地址和带子路径的入口，具体格式取决于网关提供的 Anthropic 兼容接口。没有服务方明确说明时，不要自行追加 /v1。

ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 选哪个？

按目标网关的认证说明选择。Anthropic 官方 LLM gateway 示例中，静态 ANTHROPIC_AUTH_TOKEN 会用于 Authorization 认证；如果目标服务要求 API key 或其他认证头，应遵循该服务的明确说明，不能仅凭变量名猜测。

为什么配置了 ANTHROPIC_BASE_URL，Claude Code 仍然使用原来的登录？

常见排查方向是当前 Shell 中仍有旧的 API key、变量没有在启动 Claude Code 的同一个终端生效，或订阅登录仍是当前认证方式。运行 /status 查看实际认证方式，清除不需要的变量后重新启动终端。

如何判断请求真的经过了目标网关？

仅凭 Claude Code 能启动或 /status 显示变量不足以证明流量已经到达网关。应查看网关请求日志、响应头、request ID、计费记录或服务端访问日志；如果没有这些信号，只能确认客户端收到响应。

模型名应该填写 Claude Code 默认名称还是网关自定义名称？

使用网关实际暴露的模型标识。如果网关做了模型映射，应填写映射后的名称。Claude Code 官方文档可以说明模型选择方式，但不能替你推断某个网关的模型名。

settings.json 里可以直接写真实 API key 吗？

技术上官方网关示例展示了在 settings.json 的 env 对象中配置 token，但安全上不建议把真实密钥直接写入项目文件。优先使用环境变量、密码管理器或 secret 注入，并确认本地配置不会被 Git 跟踪。

相关阅读

参考资料

  1. Anthropic：LLM gateway configuration
  2. Claude Help Center：Manage API key environment variables in Claude Code（support.claude.com）
  3. Claude Help Center：Claude Code model configuration（support.claude.com）
  4. Claude Help Center：How can I check connectivity to the Claude API?（support.claude.com）
  5. Claude Help Center：API key best practices（support.claude.com）
  6. Anthropic：Claude API errors
  7. Anthropic：Corporate proxy configuration