BUZZ AI Gateway
文档 · 指南 · Claude Code

Claude Code 配置 BUZZ

两个环境变量,把 Claude Code CLI 接入 BUZZ AI Gateway。原有项目、配置和命令行习惯都不需要改动,模型 ID 也保持不变,只把目的地换成网关。

BASE https://buzzai.cc
一行安装脚本。 如果你只想直接跑通,执行 curl -fsSL https://buzzai.cc/sh/claudecode.sh | bash 即可,跳过下面所有手动步骤。本页剩余内容是给想理解脚本到底改了什么、需要 Windows 步骤、或者要排查卡在某一步的人看的。

关键的两个变量

Claude Code 内部走的是官方 Anthropic SDK,有两个环境变量决定它把请求送去哪儿:

变量设置为作用
ANTHROPIC_BASE_URLhttps://buzzai.cc目标 host。CLI 会自己拼接 /v1/messages、/v1/models 等子路径,所以这里只填 host 根域 — 不带路径,不带末尾斜杠。
ANTHROPIC_AUTH_TOKEN你的 BUZZ key,例如 sk-...以 Authorization: Bearer <value> 形式发出。BUZZ 同时接受带 sk- 前缀和不带前缀的 key。
不要同时设置 ANTHROPIC_API_KEY。 该变量是 Anthropic 直连专用的旧风格凭据,会作为 x-api-key 头发出。两个变量都设时,最终生效的版本依赖 SDK 实现细节。安全做法是只设 ANTHROPIC_AUTH_TOKEN 并显式 unset ANTHROPIC_API_KEY。

macOS 与 Linux

两边操作完全一致,区别只在于改哪个 shell 启动文件。先用 echo $SHELL 看自己用的是哪种 shell。

# ~/.zshrc
export ANTHROPIC_BASE_URL="https://buzzai.cc"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_BUZZ_KEY"
unset ANTHROPIC_API_KEY

# 重载并验证
source ~/.zshrc
echo "$ANTHROPIC_BASE_URL"
echo "${ANTHROPIC_AUTH_TOKEN:0:8}..."

# 启动 CLI
claude
# Linux 改 ~/.bashrc;macOS 改 ~/.bash_profile
export ANTHROPIC_BASE_URL="https://buzzai.cc"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_BUZZ_KEY"
unset ANTHROPIC_API_KEY

source ~/.bashrc
echo "$ANTHROPIC_BASE_URL"
echo "${ANTHROPIC_AUTH_TOKEN:0:8}..."

claude
# ~/.config/fish/config.fish
set -Ux ANTHROPIC_BASE_URL "https://buzzai.cc"
set -Ux ANTHROPIC_AUTH_TOKEN "sk-YOUR_BUZZ_KEY"
set -e ANTHROPIC_API_KEY

echo $ANTHROPIC_BASE_URL
claude

把 token 前 8 位打印出来是个值得养成的小习惯:既能确认变量已设置,又不会把完整密钥写进终端历史或被录屏。

如果想做项目级覆盖、又不污染全局 shell profile,可以用 direnv 配合 .envrc,或者用任务 runner 加载 .env,把变量限制在项目目录里。

Windows

两个推荐 shell:PowerShell(优先)与 Command Prompt。变量是同一套,只是语法不同。

PowerShell,当前会话

$env:ANTHROPIC_BASE_URL = "https://buzzai.cc"
$env:ANTHROPIC_AUTH_TOKEN = "sk-YOUR_BUZZ_KEY"
Remove-Item Env:ANTHROPIC_API_KEY -ErrorAction SilentlyContinue

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_AUTH_TOKEN.Substring(0, 8)

claude --print "ping"

PowerShell,持久化(用户级)

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://buzzai.cc", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-YOUR_BUZZ_KEY", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $null, "User")

持久化版本设完后要新开一个 PowerShell 窗口才能生效 — 当前进程继续保留旧环境,因为 Windows 只在 shell 启动时读用户变量。

Command Prompt

:: 仅当前 cmd 会话
set ANTHROPIC_BASE_URL=https://buzzai.cc
set ANTHROPIC_AUTH_TOKEN=sk-YOUR_BUZZ_KEY
set ANTHROPIC_API_KEY=

:: 持久化(用户级),需要新开 cmd 窗口才生效
setx ANTHROPIC_BASE_URL "https://buzzai.cc"
setx ANTHROPIC_AUTH_TOKEN "sk-YOUR_BUZZ_KEY"

不要把明文 token 粘贴到 CI 日志里。在 PowerShell 中给别人接手的脚本写法,优先选 Read-Host -AsSecureString。

settings.json 全局与项目配置

想让配置跨 shell 持久化、随 dotfiles 同步、或者按仓库不同设置,就把值写到 Claude Code 的 settings.json。CLI 会按顺序读两份文件并合并:

作用域路径覆盖关系
全局~/.claude/settings.json(macOS / Linux)· %USERPROFILE%\.claude\settings.json(Windows)—
项目启动 CLI 所在目录的 .claude/settings.json覆盖全局

结构是 JSON,包含一个 env 块。env 里的键会在请求发出前注入 CLI 进程环境,效果等同 shell 导出但落盘存储。

全局设置

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://buzzai.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-YOUR_BUZZ_KEY"
  },
  "model": "claude-opus-4-7",
  "permissions": {
    "allow": ["Read", "Edit", "Bash(git status)"]
  }
}

项目级覆盖

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://buzzai.cc",
    "ANTHROPIC_AUTH_TOKEN": "sk-PROJECT_TEAM_KEY"
  },
  "model": "claude-sonnet-4-6"
}
不要把真实 token 提交到仓库。 把 .claude/settings.json 加进 .gitignore,用占位符版的 .claude/settings.json.example 做模板。两边都设时,shell 环境变量优先于 settings.json — 这正是你想要的临时覆盖语义。

验证生效

没法验证的配置不值得信任。三种检查方式,按方便程度递减:

1. CLI debug 模式

claude --debug --print "Say hi" 2>&1 | grep -i "base\|host\|http"

debug 输出会打印 SDK 解析出来的最终 base URL。trace 中看到 https://buzzai.cc 且 /v1/messages 返回 200,就是真的生效了。

2. curl 直接打端点

绕开 CLI,直接复现请求形状,可以分清问题在 CLI 还是在端点。

curl -sS https://buzzai.cc/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-20251001",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Reply with the single word: pong."}]
  }' | jq '.content[0].text, .usage'

成功会返回模型文本和 usage 对象(input_tokens / output_tokens)。失败会返回 error 包络,type 字段会告诉你具体哪一步出了问题。

3. 模型列表探活

curl -sS https://buzzai.cc/v1/models \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" | jq '.data[].id' | head -20

curl 通但 CLI 不通 — 问题在环境变量传递,不在端点。检查变量是否真的被 export 出去,以及启动 claude 的那个 shell 是否真的加载了导出。

常见错误与修复

切换到 BUZZ 后 401 Unauthorized

原因:ANTHROPIC_API_KEY 设置了 BUZZ token,CLI 用 x-api-key 发出,但配置的是 Bearer 路径。
修复:unset ANTHROPIC_API_KEY,改用 ANTHROPIC_AUTH_TOKEN。

/v1/messages 返回 404

原因:ANTHROPIC_BASE_URL 带了路径(例如 https://buzzai.cc/v1),SDK 又自己拼一遍,结果变成 /v1/v1/messages。
修复:只填 host 根域 — https://buzzai.cc,不带路径,不带末尾斜杠。

503 model_not_found

原因:该模型别名在你所在的 group 下没有可用 channel。BUZZ 在这种情况下返回 HTTP 503 + buzz_error / model_not_found。
修复:调 GET /v1/models 看实时列表,换一个可用别名,或改用带日期的形式如 claude-haiku-4-5-20251001。

明明导出了变量,CLI 还在打 api.anthropic.com

原因:变量在一个 shell 设置,但 claude 是从另一个进程(不同的终端 app、IDE 内置终端、tmux pane)启动的。
修复:在真正运行 CLI 的那个 shell 里执行 printenv ANTHROPIC_BASE_URL 确认,然后重启 IDE 或终端,让它继承新的环境。

SSL / TLS 握手失败

原因:你的环境里有出站 HTTPS 代理在做拦截但根证书没装信任。
修复:把代理的 CA 加进系统信任库,或者给 Claude Code 进程设 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem。

OAuth 登录持续覆盖 token

原因:之前跑过 claude login,缓存的 OAuth 凭据在指向 api.anthropic.com 时优先级高于 ANTHROPIC_AUTH_TOKEN。
修复:执行 claude logout,再带着 env 变量重启,让 CLI 走 token 路径。

默认模型固化

Claude Code 在 settings.json 里支持 model 字段,会成为新会话的默认模型。常用值(都可以从 GET /v1/models 取得):

带日期的别名(如 claude-haiku-4-5-20251001)同样接受。如果不带日期的别名在你 group 下返回 503 model_not_found,改用带日期形式即可。完整实时列表见 GET /v1/models。

相关链接