Claude Code 配置 API 接口：卡登录、Base URL 与模型映射排查

更新于 2026-10-23 · onomeo.cyou

简答：终端能用、重启后失效，或 VS Code 仍停在登录页时，按“临时变量验证 → ~/.claude/settings.json 持久化 → VS Code 单独配置”处理。自定义网关通常把 ANTHROPIC_BASE_URL 填到域名或网关根路径，不要先写 /v1；Claude Code 的验证请求再访问 /v1/messages。首次启动仍要求登录时，先区分认证确认、未继承环境变量和未完成本地初始化三种情况。

定义：Claude Code 配置 API 接口，是通过环境变量、settings.json 或 IDE 设置指定认证凭证、请求地址、模型名称和超时参数，让 CLI 或 VS Code 将请求发送到 Anthropic API 或兼容的 LLM 网关。

先看三处配置位置：临时验证、全局持久化、VS Code

终端能用、重启后失效、换到 VS Code 又要求登录，通常不是同一个配置位置在生效。截至2026年10月23日，Claude Code 官方文档将 Shell 环境变量、settings 文件和 IDE 表面分别说明；建议先用临时变量验证，再写入持久化配置。本站为第三方指南，非 Claude Code 官方，以其官网文档为准。

用户级 ~/.claude/settings.json 只作用于本机，不会自动同步到队友或云会话；官方设置文档也将 ~/.claude.json 作为单独的本地配置文件，不建议手动编辑。可查看Claude Code settings 文件与优先级说明。

第一步：用临时变量验证 API 接口

先不要同时修改多个文件。向网关索取三项信息：Base URL、凭证类型以及网关支持的模型名。若文档要求 Authorization: Bearer，使用 ANTHROPIC_AUTH_TOKEN；若要求 x-api-key，使用 ANTHROPIC_API_KEY。官方网关文档对这两种变量与请求头的对应关系有明确说明，可查看Connect Claude Code to an LLM gateway。

macOS、Linux、WSL：Bash 或 Zsh

export ANTHROPIC_BASE_URL="https://你的网关地址"
export ANTHROPIC_AUTH_TOKEN="你的令牌"
claude

如果服务方要求 API Key，则将第二行改为 export ANTHROPIC_API_KEY="你的密钥"。验证密钥时只检查变量是否存在，不要把完整内容输出到终端或日志。

Windows PowerShell

$env:ANTHROPIC_BASE_URL = "https://你的网关地址"
$env:ANTHROPIC_AUTH_TOKEN = "你的令牌"
claude

PowerShell 的 $env: 赋值只对当前会话及其启动的进程生效。需要长期生效时，再写入用户环境变量或 settings 文件。

最小请求：确认地址、路径和凭证

Claude Code 官方网关示例把 Base URL 写成网关根地址，并请求其后的 /v1/messages。因此一般不要把 /v1 先写进 ANTHROPIC_BASE_URL，除非网关文档明确要求；否则容易形成 /v1/v1/messages 并返回 404。

curl -i -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"你的模型名","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

使用 ANTHROPIC_API_KEY 时，将认证头替换为：

-H "x-api-key: $ANTHROPIC_API_KEY"

PowerShell 7：保留错误响应体

$body = @{
  model = "你的模型名"
  max_tokens = 1
  messages = @(@{ role = "user"; content = "." })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
  -Method Post `
  -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{
    Authorization = "Bearer $env:ANTHROPIC_AUTH_TOKEN"
    "anthropic-version" = "2023-06-01"
  } `
  -ContentType "application/json" `
  -Body $body `
  -SkipHttpErrorCheck

-SkipHttpErrorCheck 是 PowerShell 7 的参数；如果使用 Windows PowerShell 5.1，可改用 curl.exe -i，避免 Invoke-RestMethod 遇到 4xx 时直接抛异常而看不到响应体。官方验证示例见网关连接文档的 verification request。

第二步：写入 ~/.claude/settings.json 持久化

最小请求返回后，再把配置写入用户级 settings 文件。官方文档说明，环境变量可以放在 settings 文件的 env 对象中；用户级文件通常是 ~/.claude/settings.json，Windows 下对应 %USERPROFILE%\.claude\settings.json。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的网关地址",
    "ANTHROPIC_AUTH_TOKEN": "你的令牌",
    "API_TIMEOUT_MS": "1200000"
  }
}

API_TIMEOUT_MS 的单位是毫秒。官方环境变量参考给出的默认值为 600000 毫秒，即 10 分钟；上例的 1200000 表示 20 分钟。它只适合处理确认过的慢链路，不会修复 401、403、404 或模型名错误。详情见Claude Code 环境变量参考。

不要把个人凭证写进项目共享的 .claude/settings.json。如果确实需要使用项目级本地文件，应采用 .claude/settings.local.json 并确保不会提交到仓库。settings 文件必须是严格 JSON，不能加入注释或尾随逗号。修改后重新启动 Claude Code，再运行 /status 查看实际加载的认证方式和地址。

第三步：模型名与别名映射怎么配置

ANTHROPIC_BASE_URL 只改变请求发送到哪里，不会自动把网关模型名转换成 Anthropic 模型名。接入第三方网关时，应先确认网关接受的模型 ID，再决定使用固定模型、模型别名，还是官方提供的默认模型变量。

可以先在当前终端测试：

export ANTHROPIC_MODEL="你的网关模型名"
claude

也可以写入 settings 文件：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的网关地址",
    "ANTHROPIC_AUTH_TOKEN": "你的令牌",
    "ANTHROPIC_MODEL": "你的网关模型名",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "你的网关模型名"
  }
}

官方模型配置文档区分了完整模型名、模型别名和默认模型变量；可查看Claude Code model configuration。如果返回“模型不存在”，不要继续修改认证变量，先用最小请求验证该模型 ID。

CLI 首次启动仍弹登录：按这个顺序判断

首次运行时出现登录界面，不一定代表 API 接口配置失败。需要把“认证来源确认”“进程没有继承变量”和“本地初始化未完成”分开检查。

1. 先检查变量是否存在。Bash 使用 test -n "$ANTHROPIC_AUTH_TOKEN" && echo set || echo missing；PowerShell 使用 if ($env:ANTHROPIC_AUTH_TOKEN) { "set" } else { "missing" }。不要打印完整 Key。
2. 从同一个终端启动 CLI。如果变量在一个终端中设置，却从桌面图标或另一个终端打开，新的进程可能没有继承这些变量。
3. 确认是不是 API Key 的一次性确认。官方环境变量文档说明，交互模式检测到 ANTHROPIC_API_KEY 时可能先询问是否使用该 Key；确认后进入会话，再运行 /status 判断实际认证来源。
4. 检查本地初始化文件。执行 ls -la ~/.claude.json；Windows PowerShell 可执行 Test-Path "$HOME\.claude.json"。官方 settings 文档说明，该文件由 Claude Code 自行维护，用于账户信息、MCP 配置和项目状态，不建议手动编辑。如果全新安装时文件尚未生成，先在同一终端完成一次官方新手引导，再退出并重新启动 CLI；这是缩小“未完成初始化”范围的排查步骤，不是对所有登录弹窗原因的统一结论。
5. 进入会话后运行 /status。如果显示自定义 Base URL 和 API Key 或 Auth Token，说明接口配置已被读取；如果仍只显示登录方式，继续检查变量继承、settings 文件路径和是否启动了另一份 CLI。
6. 需要恢复订阅登录时，清除全部网关变量。Bash 使用 unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL；PowerShell 使用 Remove-Item Env:ANTHROPIC_API_KEY,Env:ANTHROPIC_AUTH_TOKEN,Env:ANTHROPIC_BASE_URL -ErrorAction SilentlyContinue，同时检查 Shell 配置文件和 settings 文件。

关于安装、登录和认证故障，可继续查看官方的安装与登录排错文档。关于变量优先级和本地配置文件，参见settings 文件说明。

VS Code 扩展为何还要登录，应该改哪里

VS Code 扩展有自己的启动进程。官方文档明确指出，如果 Shell 中设置了 ANTHROPIC_API_KEY，但 VS Code 没有继承该环境，扩展仍可能显示登录提示。可以从终端用 code . 启动 VS Code，或在 VS Code 的用户设置中配置扩展需要的环境变量。

打开命令面板，执行 Preferences: Open User Settings (JSON)，加入与你的网关匹配的配置：

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://你的网关地址"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value": "你的令牌"
    }
  ]
}

若网关要求 x-api-key，将第二个变量名改为 ANTHROPIC_API_KEY。保存后重新加载窗口，再打开 Claude Code 面板。VS Code 扩展和 CLI 的版本、登录界面及可用设置可能随版本变化，具体字段以当前扩展界面和官方文档为准。可查看Claude Code for VS Code 官方说明。

错误排查表：先看状态码和返回体

unsupported_parameter、流式中断等项目是兼容性排查方向，不代表所有网关都会返回同样错误；最终以实际返回体、网关日志和服务方文档为准。官方网关文档还提供了错误排查表，可查看LLM gateway troubleshooting。

配置完成后的安全检查

• 凭证只放在本地环境变量、个人 settings 文件或受控的密钥管理工具中。
• 不要把令牌写入会提交到仓库的项目级 settings 文件。
• 验证时只输出变量是否存在，不输出完整 Key。
• 使用 /status 检查 Base URL、认证来源和模型是否符合预期。
• 如果不想使用按量 API 认证，清除 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_BASE_URL，并重新启动 Claude Code。
• 第三方网关的模型映射、价格、限速和数据处理规则，以该网关公开文档和服务条款为准，本文不替任何网关确认。

常见问题

Claude Code 的 ANTHROPIC_BASE_URL 要不要带 /v1？

按照官方网关示例，通常填写网关根地址，验证请求再访问 /v1/messages。因此优先不要在 Base URL 末尾写 /v1；只有网关文档明确要求时才例外。

ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 可以同时设置吗？

排错时不建议同时设置。前者对应 x-api-key，后者对应 Authorization: Bearer。根据网关要求选择一种，更容易判断 401 的来源。

settings.json 已经配置，为什么 CLI 仍然弹登录？

先确认启动的是同一份 CLI，再检查 ~/.claude/settings.json 是否为合法 JSON、变量是否写在 env 下，并检查 ~/.claude.json 是否已经完成本地初始化。进入会话后使用 /status 判断实际加载结果。

API_TIMEOUT_MS 应该设置多大？

单位是毫秒。官方参考默认值为 600000，慢链路可以逐步调大，例如测试 1200000；但 401、403、404、模型不存在和参数错误都不应靠增加超时解决。

ANTHROPIC_MODEL 与 ANTHROPIC_DEFAULT_SONNET_MODEL 有什么区别？

ANTHROPIC_MODEL 直接指定主会话模型；ANTHROPIC_DEFAULT_SONNET_MODEL 用于让 sonnet 别名解析到指定模型。两者都不能替代网关本身的模型映射，最终仍要以网关接受的模型 ID 为准。

VS Code 扩展一直显示登录页怎么办？

扩展可能没有继承终端变量。可以从终端用 code . 启动，或在 VS Code 用户设置 JSON 中添加 claudeCode.environmentVariables，保存后重新加载窗口。

常见问题

Claude Code 的 ANTHROPIC_BASE_URL 要不要带 /v1？

通常填写网关根地址，Claude Code 的验证请求再访问 /v1/messages。除非网关文档明确要求，否则不要先在 Base URL 末尾添加 /v1。

ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 可以同时设置吗？

排错时不建议同时设置。前者对应 x-api-key，后者对应 Authorization: Bearer，应按网关要求选择一种。

settings.json 已配置，为什么 CLI 仍然弹登录？

检查是否从同一终端启动、settings.json 是否为合法 JSON、变量是否位于 env 下，并检查 ~/.claude.json 是否已经完成本地初始化。进入会话后运行 /status。

API_TIMEOUT_MS 应该设置多大？

官方参考默认值为 600000 毫秒。确认是链路慢后可逐步增加，例如测试 1200000；认证、路径和模型错误不能靠增大超时修复。

ANTHROPIC_MODEL 与 ANTHROPIC_DEFAULT_SONNET_MODEL 有什么区别？

ANTHROPIC_MODEL 直接指定主会话模型；ANTHROPIC_DEFAULT_SONNET_MODEL 用于把 sonnet 别名解析到指定模型，最终仍需网关支持该模型 ID。

VS Code 扩展一直显示登录页怎么办？

从终端用 code . 启动以继承环境变量，或在 VS Code 用户设置中加入 claudeCode.environmentVariables，保存后重新加载窗口。

相关阅读

• 查看更多 AI API 接入与错误排查指南
• 对比 Cursor 的 Base URL 与 API Key 配置方法

参考资料

1. Connect Claude Code to an LLM gateway（code.claude.com）
2. Environment variables（code.claude.com）
3. Troubleshoot installation and login（code.claude.com）