Claude Code 接入第三方 API：Base URL、API Key 与常见报错

Claude Code 通过 Nbility 连接 Claude 模型的文章封面

Claude Code 不一定只能使用默认登录方式。只要第三方网关兼容 Anthropic Messages API，就可以通过环境变量把 Claude Code 的请求转到自己的 API 地址。

真正容易出错的并不是安装，而是三个看起来很小的细节：

ANTHROPIC_BASE_URL 应该填什么，是否要带 /v1；
API Key 应该放在 ANTHROPIC_AUTH_TOKEN 还是其他变量里；
Claude Code 使用的模型名，是否真的存在于当前 Token 的可用模型中。

这篇文章以 Nbility Claude Code 配置文档为例，从安装、临时测试、持久化配置一直讲到错误排查。所有示例都使用占位符，不会要求你把真实 API Key 写进代码或 Git 仓库。

先理解请求是怎么走的

Claude Code 连接第三方 API 所需的地址、密钥和模型配置

配置完成后，请求链路是：

Claude Code
    ↓ Anthropic Messages API
https://api.nbility.ai
    ↓ 鉴权、路由、计费与日志
Claude 模型

Claude Code 仍然负责读取代码、规划修改、调用终端和编辑文件。网关负责接收模型请求，再把它路由到对应的 Claude 模型。

这里有一个重要区别：Claude Code 使用的是 Anthropic 兼容协议，不是普通的 OpenAI Chat Completions 配置。Nbility 提供原生 Claude Messages 兼容接口：

POST https://api.nbility.ai/v1/messages

因此在 Claude Code 里，Base URL 使用：

https://api.nbility.ai

不要在这里手动追加 /v1。Claude Code 会根据 Anthropic API 规则拼接实际接口路径。如果把 Base URL 写成 https://api.nbility.ai/v1，部分版本或客户端可能最终请求到重复路径。

安装并确认 Claude Code 可以启动

如果你还没有安装，官方目前推荐使用原生安装脚本。

macOS、Linux 或 WSL：

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex

也可以使用 npm：

npm install -g @anthropic-ai/claude-code

安装完成后先检查版本和运行环境：

claude --version
claude doctor

这一步只验证 Claude Code 本身是否正确安装。先解决 command not found、权限或运行库问题，再处理 API 配置，否则两类错误会混在一起。

最稳妥的方法：先做一次临时配置

不要一开始就修改多个 Shell 配置文件。先在当前终端设置变量，验证成功后再持久化。

macOS、Linux 或 WSL：

export ANTHROPIC_BASE_URL="https://api.nbility.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-4-6"

Windows PowerShell，仅对当前窗口生效：

$env:ANTHROPIC_BASE_URL = "https://api.nbility.ai"
$env:ANTHROPIC_AUTH_TOKEN = "YOUR_API_KEY"
$env:ANTHROPIC_MODEL = "claude-sonnet-4-6"

然后进入一个测试目录运行：

claude

启动后可以先问一个不会修改文件的问题，例如：

请只读取当前目录结构，并告诉我这是一个什么类型的项目，不要修改文件。

如果模型能够正常回复，说明至少这几项已经跑通：

Claude Code 安装正常；
Base URL 能连接；
API Key 能通过鉴权；
模型名可用；
Anthropic Messages 协议兼容正常。

三个环境变量分别负责什么

安全保存 Claude Code API Key 与项目配置

`ANTHROPIC_BASE_URL`

它决定 Claude Code 把 Anthropic API 请求发到哪里。

export ANTHROPIC_BASE_URL="https://api.nbility.ai"

这是 Claude 兼容接口的服务根地址，不是 OpenAI 兼容接口常见的 https://api.nbility.ai/v1。

`ANTHROPIC_AUTH_TOKEN`

它保存第三方网关的 API Key：

export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"

不要把真实 Key 写入文章、公开脚本、仓库、截图或终端录屏。团队环境应该使用操作系统密钥管理、CI Secret 或服务器的 Secret 管理功能。

`ANTHROPIC_MODEL`

它指定 Claude Code 默认调用的模型：

export ANTHROPIC_MODEL="claude-sonnet-4-6"

日常编码通常可以从 Sonnet 档开始；复杂推理或大型重构再考虑更强模型。模型是否可用，以 Nbility Token 管理页面实际展示的模型为准，不要只复制旧教程里的名称。

Nbility 的模型列表会展示主要模型，但文档也明确提醒：完整可用范围应以当前 Token 支持的模型为准。

验证成功后再持久化

macOS 或 Linux

如果使用 Zsh，把变量写入 ~/.zshrc：

cat >> ~/.zshrc <<'EOF'
export ANTHROPIC_BASE_URL="https://api.nbility.ai"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-4-6"
EOF

source ~/.zshrc

如果使用 Bash，则写入 ~/.bashrc，再执行：

source ~/.bashrc

注意：Shell 配置文件通常是明文文件。如果电脑有多用户、自动备份或配置仓库，优先使用更安全的密钥管理方式，不要把包含真实 Key 的配置文件提交到 dotfiles 仓库。

Windows PowerShell

写入当前用户环境变量：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.nbility.ai", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_API_KEY", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_MODEL", "claude-sonnet-4-6", "User")

设置完成后关闭并重新打开终端，确保新进程加载变量。

使用 `settings.json` 管理配置

Claude Code 支持用户级和项目级设置。用户级配置通常位于：

~/.claude/settings.json

可以将环境变量写入 env：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.nbility.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

这种方式直观，但需要注意两点：

settings.json 里的 Key 仍是明文；
项目级 .claude/settings.json 可能被提交到 Git。

因此，项目共享配置适合保存权限、Hooks 或不敏感的模型设置，不适合保存团队共用的真实 API Key。Key 更适合由每位开发者自己的环境变量或 Secret 工具注入。

怎么确认实际使用了哪个模型

进入 Claude Code 后，可以使用模型相关命令查看或切换当前模型。不同版本的交互界面可能调整，因此应以当前 claude 中显示的命令帮助为准。

排查时，不要只看本地环境变量。还要确认：

用户级 settings.json 是否覆盖了 Shell；
项目级 .claude/settings.json 是否覆盖了用户配置；
当前终端是否是设置变量之后才打开的；
Token 是否拥有该模型权限；
模型名是否和控制台展示完全一致。

如果更换模型后仍然调用旧模型，最简单的办法是关闭当前 Claude Code 会话，重新打开一个终端，再启动新会话验证。

常见报错怎么排查

Claude Code 第三方 API 常见错误与排查方向

`401 Unauthorized` 或认证失败

优先检查：

[ ] ANTHROPIC_AUTH_TOKEN 是否存在
[ ] Key 前后是否多了空格或引号
[ ] 是否误用了网页登录 Cookie 或其他平台的 Token
[ ] Shell 配置修改后是否重新加载
[ ] settings.json 是否覆盖了环境变量
[ ] Token 是否有效、是否有余额或权限

可以只检查变量是否存在，不要直接输出完整 Key：

if [ -n "$ANTHROPIC_AUTH_TOKEN" ]; then
  echo "ANTHROPIC_AUTH_TOKEN is set"
else
  echo "ANTHROPIC_AUTH_TOKEN is missing"
fi

不要在群聊或工单里粘贴完整 Key。需要排查时，提供错误码、请求时间和脱敏后的 Key 前后几位即可。

`404 Not Found`

常见原因是 Base URL 路径错误。

Claude Code 使用 Nbility 时应填：

https://api.nbility.ai

而不是：

https://api.nbility.ai/v1
https://api.nbility.ai/v1/messages

Base URL 只填服务根地址，具体 /v1/messages 路径由客户端处理。

`model not found`

这通常不是网络问题，而是模型名或权限问题：

模型名拼写错误；
复制了已下线或旧版本的模型名；
当前 Token 没有对应模型；
环境变量和 settings.json 使用了不同模型名。

回到 Token 管理页面查看当前可用模型，复制完整模型 ID，再重新启动 Claude Code。

`429 Too Many Requests`

429 可能表示请求过快、上游容量紧张、并发限制或额度压力。不要在失败后立即无限重试。

更合理的处理方式是：

等待几秒后重试；
降低并发任务数量；
检查是否同时打开了多个 Claude Code 会话；
查看 Token、渠道或模型当前是否有限制；
必要时切换可用模型。

请求超时或一直停在连接中

依次检查：

网络能否访问 https://api.nbility.ai
系统代理是否只对浏览器生效
终端是否继承了正确代理变量
公司网络是否拦截 HTTPS 或 SSE
网关或上游是否正在短暂波动

Claude Code 的回复包含流式传输。某些代理能够访问普通网页，却会缓冲或中断长连接，所以“官网能打开”不等于 Claude Code 的流式请求一定正常。

配置改了却没有生效

通常是配置优先级或进程环境导致的：

已运行的 Claude Code 不会自动继承后来修改的 Shell 变量；
IDE 内置终端可能保留旧环境；
用户级和项目级配置可能互相覆盖；
PowerShell 用户变量需要新终端才会加载。

关闭 Claude Code 和当前终端，重新打开后再测试，往往比反复修改配置更有效。

一份更安全的使用清单

[ ] API Key 不进入 Git、截图、日志和聊天记录
[ ] Claude Code 的 Base URL 使用 https://api.nbility.ai
[ ] OpenAI SDK 的 Base URL 才通常使用 https://api.nbility.ai/v1
[ ] 模型名以当前 Token 的可用列表为准
[ ] 先临时配置验证，再持久化
[ ] 配置修改后启动新终端和新会话
[ ] 401/403 优先检查认证，不盲目重试
[ ] 404 优先检查 Base URL 和路径
[ ] model not found 优先检查模型名与权限
[ ] 429 和 5xx 使用有限重试，不无限循环

为什么通过网关使用 Claude Code

第三方 API Gateway 的价值不只是“换一个地址”。对经常使用 Claude Code 的个人或小团队，更实际的价值包括：

在一个入口管理 API Key 和可用模型；
查看调用记录和消耗；
按 Token 隔离不同设备或项目；
在模型或渠道变化时减少客户端配置改动；
出现问题时，更容易区分客户端、网关和模型层。

但网关不会替你解决所有问题。Claude Code 仍然拥有读取文件、编辑代码和执行命令的能力。开始使用前，应该检查项目权限、敏感文件和 Git 状态，不要因为模型接入成功就跳过安全边界。

如果你需要一个支持 Claude Messages 格式的统一入口，可以查看 Nbility Claude Code 配置文档。注册后也可以在工单支持页面提交工单，申请用于测试的 $5 平台额度。