ANTHROPIC_BASE_URL 完整指南:Claude Code 切换自定义端点

你打开 Claude Code 准备干活,但默认端点延迟高、想接 AI 网关用 Prompt Cache、或者团队要求所有 API 流量过自家代理 —— 这时候你需要的就是一个环境变量:ANTHROPIC_BASE_URL。这是 Claude Code 配置里最被低估的一项,设对了 5 秒切完所有流量,设错了能调一晚上。本文把 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 的来龙去脉、两种配置方式的取舍、全平台步骤、验证手段、5 个常见错误一次讲清楚。

ANTHROPIC_BASE_URL 是什么

ANTHROPIC_BASE_URL 是 Anthropic 官方 SDK 和 Claude Code 都识别的一个环境变量,作用很简单:覆盖默认的 https://api.anthropic.com,把所有 API 请求路由到你指定的自定义端点。

SDK 拿到 base URL 之后,会在它后面拼接路径(比如 /v1/messages、/v1/models),然后照常发请求。除了请求地址变了,其他行为完全一致 —— SDK 不知道、也不关心后面接的是 Anthropic 官方还是 AI 网关、本地 mock、企业代理。

什么时候需要设置 ANTHROPIC_BASE_URL?

• 接 AI 网关:比如 BUZZ,统一计费、Prompt Cache、多上游路由,Claude Code 走过去后所有原生功能都保留。
• 企业代理:公司要求所有外部 API 调用必须经过审计代理,运维给你一个 base URL 就完事。
• 本地 mock / 录制重放:测试时用 LocalStack、wiremock 或自写 mock server 接管真实 Anthropic 端点。
• 多账户隔离:个人 key 和公司 key 不要混,通过两个不同的 base URL 物理分离。
• 低延迟边缘:某些网关有更近的边缘节点,Claude Code 长会话体感会快很多。

不需要设置的场景:你用 Anthropic 官方账户、官方 API key、官方端点,这是默认值,什么都不用改。

两种配置方式

Claude Code 接受两种配置 ANTHROPIC_BASE_URL 的方式,各有取舍:

取舍逻辑:

• 个人开发机、长期一套配置 → shell export 写到 ~/.zshrc 或 ~/.bashrc。
• 多项目、不同项目用不同端点 → settings.json,每个项目根目录一份 .claude/settings.json。
• 公司团队、统一审计代理 → settings.json + 提交到仓库,新人 clone 即生效。
• 临时跑一次实验 → 命令行前缀 ANTHROPIC_BASE_URL=https://xxx claude,只对这次调用生效。

优先级:命令行环境变量 > shell 环境变量 > 项目级 settings.json > 用户级 settings.json > SDK 默认值。同时设了多个,前面的覆盖后面的。

macOS / Linux 配置

主流场景就是写到 shell rc 文件里,常驻生效。先确认你用的是 bash 还是 zsh:

echo $SHELL
# /bin/zsh   → 改 ~/.zshrc
# /bin/bash  → 改 ~/.bashrc(Linux)或 ~/.bash_profile(macOS)

zsh(macOS 默认)

# 追加到 ~/.zshrc
cat >> ~/.zshrc <<'EOF'

# Claude Code 自定义端点
export ANTHROPIC_BASE_URL=https://buzzai.cc
export ANTHROPIC_AUTH_TOKEN=sk-buzz-xxxxxxxxxxxxxxxx
EOF

# 重新加载
source ~/.zshrc

# 验证环境变量已设置
echo $ANTHROPIC_BASE_URL
# https://buzzai.cc

echo $ANTHROPIC_AUTH_TOKEN
# sk-buzz-xxxxxxxxxxxxxxxx

# 启动 Claude Code
claude

bash(大多数 Linux 发行版默认)

# 追加到 ~/.bashrc
cat >> ~/.bashrc <<'EOF'

# Claude Code 自定义端点
export ANTHROPIC_BASE_URL=https://buzzai.cc
export ANTHROPIC_AUTH_TOKEN=sk-buzz-xxxxxxxxxxxxxxxx
EOF

source ~/.bashrc

# 验证
env | grep ANTHROPIC_
# ANTHROPIC_BASE_URL=https://buzzai.cc
# ANTHROPIC_AUTH_TOKEN=sk-buzz-xxxxxxxxxxxxxxxx

claude

fish

# fish 用 set -Ux 持久化全局环境变量
set -Ux ANTHROPIC_BASE_URL https://buzzai.cc
set -Ux ANTHROPIC_AUTH_TOKEN sk-buzz-xxxxxxxxxxxxxxxx

# 验证
echo $ANTHROPIC_BASE_URL
claude

临时单次调用

# 不写进 rc 文件,只对这一次 claude 进程生效
ANTHROPIC_BASE_URL=https://buzzai.cc ANTHROPIC_AUTH_TOKEN=sk-buzz-xxx claude

这种写法适合做对比测试 —— 同一个项目,一次走官方,一次走自定义端点,看结果差异。

Windows 配置

Windows 上 Claude Code 在 PowerShell、cmd、WSL 都能跑,环境变量配置三种环境写法不一样。

PowerShell(推荐)

# 当前会话临时设置(关闭 PowerShell 后失效)
$env:ANTHROPIC_BASE_URL = "https://buzzai.cc"
$env:ANTHROPIC_AUTH_TOKEN = "sk-buzz-xxxxxxxxxxxxxxxx"

# 验证
echo $env:ANTHROPIC_BASE_URL
claude

# 持久化到当前用户(重启 PowerShell 后仍然生效)
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://buzzai.cc", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-buzz-xxxxxxxxxxxxxxxx", "User")

# 持久化到机器级别(所有用户共享,需要管理员权限)
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://buzzai.cc", "Machine")

cmd.exe

:: 当前会话临时设置
set ANTHROPIC_BASE_URL=https://buzzai.cc
set ANTHROPIC_AUTH_TOKEN=sk-buzz-xxxxxxxxxxxxxxxx

:: 验证
echo %ANTHROPIC_BASE_URL%
claude

:: 持久化(用户级,需要重启 cmd 生效)
setx ANTHROPIC_BASE_URL "https://buzzai.cc"
setx ANTHROPIC_AUTH_TOKEN "sk-buzz-xxxxxxxxxxxxxxxx"

WSL(Ubuntu / Debian)

WSL 里就当 Linux 处理,改 ~/.bashrc 或 ~/.zshrc。注意 WSL 的环境变量和 Windows 主机的环境变量是隔离的,Windows 那边设的不会自动传到 WSL。

settings.json 配置

Claude Code 的 settings.json 走分层结构:

settings.json 模板:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://buzzai.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-buzz-xxxxxxxxxxxxxxxx"
  }
}

关键点:

• env 是一个对象,key 是环境变量名,value 是字符串。
• Claude Code 启动时会把 env 里的变量注入到子进程,行为等价于 export。
• 不要把含 secret 的 settings.json 提交到公共仓库。secret 写到 .claude/settings.local.json 并 .gitignore 掉,settings.json 只放无敏感的配置(比如 model 默认值、tool 白名单)。

典型的"团队共享 + 个人 secret"模式:

// .claude/settings.json    ← 提交到仓库
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://buzzai.cc"
  },
  "model": "claude-sonnet-4-6"
}

// .claude/settings.local.json    ← .gitignore
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-buzz-xxxxxxxxxxxxxxxx"
  }
}

这样新同事 clone 仓库后,只需要补一份 settings.local.json 填自己的 token 就能跑,base URL 已经统一在仓库里了。

ANTHROPIC_AUTH_TOKEN vs ANTHROPIC_API_KEY

这是踩坑率最高的一项。两个变量名长得像,但是不通用,搞混直接 401。

怎么判断你拿到的 key 应该用哪个?

• 如果是 Anthropic 官方控制台生成、以 sk-ant-api03- 开头的长串 → ANTHROPIC_API_KEY。
• 如果是 AI 网关 / 第三方端点发的 token、文档明确说"用 Bearer token"或者 token 不以 sk-ant- 开头 → ANTHROPIC_AUTH_TOKEN。
• 实在拿不准 → 看那家服务商的接入文档,他们会写清楚用哪个 header。

Claude Code 1.x 版本起两个环境变量都识别。如果同时设置两个,优先级是 ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY。建议只设一个,避免混淆。

Anthropic 官方 SDK 的对应规则一致:

// TypeScript SDK
import { Anthropic } from "@anthropic-ai/sdk";

// 官方端点 → 用 apiKey 走 x-api-key
const official = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// 自定义端点 → 用 authToken 走 Bearer
const custom = new Anthropic({
  baseURL: "https://buzzai.cc",
  authToken: process.env.ANTHROPIC_AUTH_TOKEN,
});

# Python SDK
from anthropic import Anthropic
import os

# 官方
official = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# 自定义端点
custom = Anthropic(
    base_url="https://buzzai.cc",
    auth_token=os.environ["ANTHROPIC_AUTH_TOKEN"],
)

切换后怎么验证生效

设完别急着干活,先做三步验证。

第一步:确认环境变量真的进了进程

# macOS / Linux
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN | head -c 12   # 只看前 12 位,避免泄露

# Windows PowerShell
echo $env:ANTHROPIC_BASE_URL
$env:ANTHROPIC_AUTH_TOKEN.Substring(0, 12)

如果 echo 出来是空,说明你写的 rc 文件不是当前 shell 加载的那个,或者 source 没生效。

第二步:curl 直接打你的端点

# 列出可用模型,大部分网关都实现了 /v1/models
curl -sS "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" | head -40

# 发一条最小的 messages 请求,确认能走通
curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "ping"}]
  }'

如果 curl 拿到 200 + 正常 JSON 响应 → 端点通、token 对、header 写法对。如果 401 → token 类型搞反了或者 token 失效。如果 404 → base URL 拼错了,通常多了 /v1 后缀。

第三步:Claude Code 实跑 + 看流量去向

# 开 debug 日志启动 Claude Code
ANTHROPIC_LOG=debug claude

# 或者 export 一次
export ANTHROPIC_LOG=debug
claude

debug 日志会打印实际请求的完整 URL,直接确认有没有走到自定义端点。然后到你端点的控制台(BUZZ 控制台 / 自家代理日志)看是否有这次调用的记录,token 计数对不对。

常见错误

过去半年我们看到 Claude Code 用户最常踩的 5 个坑,每个一行修。

错误 1:base URL 末尾带斜杠或多 /v1 后缀

# 错
export ANTHROPIC_BASE_URL=https://buzzai.cc/         # 多斜杠 → //v1/messages
export ANTHROPIC_BASE_URL=https://buzzai.cc/v1       # 多路径 → /v1/v1/messages

# 对
export ANTHROPIC_BASE_URL=https://buzzai.cc

SDK 内部会拼接 /v1/messages,base URL 写裸域名就行。

错误 2:把 token 类型搞反(401)

# 错:网关 token 设成 ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=sk-buzz-xxx     # 网关收不到 Bearer header

# 对
export ANTHROPIC_AUTH_TOKEN=sk-buzz-xxx

错误 3:rc 文件错配(zsh 用户写到 ~/.bashrc)

# 检查你用哪个 shell
echo $SHELL

# zsh → 写 ~/.zshrc
# bash → 写 ~/.bashrc 或 ~/.bash_profile

错误 4:settings.json env 字段语法错

// 错:env 写成数组
{ "env": ["ANTHROPIC_BASE_URL=https://buzzai.cc"] }

// 错:value 不是字符串
{ "env": { "ANTHROPIC_BASE_URL": https://buzzai.cc } }

// 对
{ "env": { "ANTHROPIC_BASE_URL": "https://buzzai.cc" } }

错误 5:用 GUI 启动 Claude Code 不读 shell 环境变量

macOS 在 Finder 双击启动的 GUI 进程,默认不会加载 ~/.zshrc 或 ~/.bashrc。从 Spotlight 启动的 Claude Code Desktop 也是同理。解决办法:

• 从 terminal 用 claude 命令启动(继承 shell 环境)。
• 或者把环境变量写到 settings.json 的 env 字段(GUI 启动也读)。
• 或者用 launchctl setenv(macOS GUI 进程级别注入)。

FAQ