JBB 金贝贝 Logo JBB 金贝贝AI API Gateway · 原 JBBToken

CLIENT GUIDE / CLAUDE CODE

让 Claude Code 通过 JBB 工作：先接通，再验证缓存与工具

Claude Code 支持用 ANTHROPIC_BASE_URL 连接 LLM Gateway。JBB 已确认 POST /v1/messages、x-api-key 和核心请求字段进入处理链；具体模型、分组、Prompt Caching 与 Tool Use 仍要用你的 Key 做小额度验证。

复制环境变量 查看验证顺序

PRE-FLIGHT

先准备 JBB Key 和一个真正通过 Messages 实测的模型

Claude Code 使用 Anthropic Messages 请求形状。JBB 当前公开模型目录中的 Claude 条目仍标记为 OpenAI endpoint，因此模型名称本身不能证明它适合 Claude Code。

01安装客户端

使用 Claude Code 官方安装器，完成后运行 claude --version 与 claude doctor。

02创建独立 Key

在 JBB 控制台生成专用 API Key，设置合理额度和分组，禁止复制账号密码或 Session。

03确认模型 ID

只使用已在同一分组通过 /v1/messages 的完整模型 ID；不要猜测 sonnet、opus 别名。

macOS / Linux / WSL · 官方安装
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
Windows PowerShell · 官方安装
irm https://claude.ai/install.ps1 | iex
claude --version
claude doctor

安装命令与系统要求以 Claude Code 官方 Setup 为准。Claude Code、Claude 和 Anthropic 是 Anthropic 的产品与商标；本页不表示双方存在合作或背书。

ENVIRONMENT

首次连接只设当前终端，验证成功后再持久化

ANTHROPIC_BASE_URL 只写站点 origin；JBB 已确认 x-api-key 认证路径，因此使用 ANTHROPIC_API_KEY。Claude Code 会把自定义 Base URL 后的模型字符串原样交给 Gateway，模型拼写错误通常到首次请求才暴露。

Bash / Zsh
export ANTHROPIC_BASE_URL="https://downstream.jbbtoken.cn"
export ANTHROPIC_API_KEY="<YOUR_JBB_API_KEY>"
export ANTHROPIC_MODEL="<MESSAGES_TESTED_MODEL_ID>"

claude --model "$ANTHROPIC_MODEL"
Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://downstream.jbbtoken.cn"
$env:ANTHROPIC_API_KEY = "<YOUR_JBB_API_KEY>"
$env:ANTHROPIC_MODEL = "<MESSAGES_TESTED_MODEL_ID>"

claude --model $env:ANTHROPIC_MODEL
为什么不用官方模型别名直接开跑

Claude Code 的主会话、Plan、后台功能可能解析到不同模型族。Gateway 模式下应把 ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL 和 ANTHROPIC_DEFAULT_HAIKU_MODEL 分别固定到同一分组已验证的完整 ID；没有验证记录时宁可不填，也不要把三个族盲目指向一个模型。

SETTINGS

共享配置可以进项目，凭证不能进 Git

全局用户配置位于 ~/.claude/settings.json，Windows 对应 %USERPROFILE%\.claude\settings.json。项目级 .claude/settings.json 会进入版本库，绝不能写 JBB Key。

JSON · 用户级 settings.json（不含 Key）
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://downstream.jbbtoken.cn",
    "ANTHROPIC_MODEL": "<MESSAGES_TESTED_MODEL_ID>"
  }
}
  • Key 保留在当前 Shell、用户级 Secret 管理器或受控的 credential helper 中。
  • 若使用 .claude/settings.local.json，先确认它已加入 .gitignore。
  • ANTHROPIC_API_KEY 在交互模式可能要求一次确认；如与已保存登录冲突，运行 /status 检查来源，必要时执行 /logout。
  • 项目共享文件只放 Base URL、权限和非敏感模型策略，不放 Token。

配置范围、优先级与凭证冲突参考 Settings 和 Connect to an LLM Gateway。

CONNECTION TEST

按“版本 → 直连 → Claude Code → /status”四层验收

直连示例会向模型发起最小请求，可能产生少量计费。先使用独立低额度 Key；本页制作过程没有使用有效 Key，也没有发起付费调用。

cURL · x-api-key 最小验证
curl "$ANTHROPIC_BASE_URL/v1/messages"   -H "x-api-key: $ANTHROPIC_API_KEY"   -H "anthropic-version: 2023-06-01"   -H "content-type: application/json"   -d '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'
PowerShell · x-api-key 最小验证
$headers = @{
  "x-api-key" = $env:ANTHROPIC_API_KEY
  "anthropic-version" = "2023-06-01"
}
$body = @{
  model = $env:ANTHROPIC_MODEL
  max_tokens = 1
  messages = @(@{ role = "user"; content = "." })
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post `
  -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers $headers -ContentType "application/json" -Body $body
检查通过信号不能证明什么
claude --version客户端可运行不证明 Gateway 或模型可用。
直连 Messages有效响应或明确模型错误401 只表示凭证被拒绝；不能算模型成功。
Claude Code 首条消息正常文本响应不证明缓存和工具已可用。
/status显示 JBB Base URL 与 API key 来源只确认客户端正在使用这套配置。
/v1/messages/count_tokens当前 404不要依赖该端点；客户端版本行为需实测。

PROMPT CACHING

Claude Code 会自动构造缓存，JBB 是否命中取决于实际转发链

官方说明中，Claude Code 默认管理 Prompt Caching；当使用自定义 ANTHROPIC_BASE_URL 时，缓存发生在哪里、是否工作由 Gateway 和上游决定。JBB 的 Claude 请求结构接受 cache_control，但本任务没有验证具体模型的命中、usage 或计费。

  • 固定模型和 effort，在同一会话连续完成两轮稳定任务，再比较响应 usage。
  • 重点观察 cache_creation_input_tokens 与 cache_read_input_tokens；字段不存在时不能宣称已命中。
  • 切换模型、effort、工具集合、MCP 连接或执行 /compact 都可能让下一轮重建缓存。
  • 正常使用不要设置 DISABLE_PROMPT_CACHING=1；该变量只适合定位缓存问题。
  • 实际费用以 JBB 当前 CacheRatio、CreateCacheRatio 和账单 为准，不套用 Anthropic 官方价格。

官方行为参考 How Claude Code uses prompt caching；JBB 兼容边界见 Claude-compatible API。

TOOLS & MCP

本地工具由 Claude Code 执行，模型必须先正确返回工具调用

Claude Code 的文件读取、编辑和 Shell 工具运行在用户机器上；API 负责让模型看到工具定义并返回工具调用。JBB DTO 接受 tools 与 tool_choice，但不同模型、分组和上游可能支持、转换、忽略或拒绝这些字段。

  • 先让 Claude Code 执行只读任务，例如列目录和读取一个测试文件，再测试编辑或 Shell。
  • 工具权限由本地 Claude Code 设置控制；不要用放宽本地权限来掩盖 API 侧 400 或模型不支持。
  • 工具调用连续失败时保存请求 ID、模型、分组和错误正文，停止无限重试。
  • 自定义 Base URL 下，MCP Tool Search 可能默认关闭；只有确认 Gateway 转发 tool_reference 后才设置 ENABLE_TOOL_SEARCH=true。
  • Remote Control 等依赖 claude.ai 身份的能力在自定义 Gateway 模式下可能不可用，不应当作 JBB 故障。
最小工具验收

在临时目录创建一个无敏感信息的文本文件，让 Claude Code 先读取、再修改、最后运行本地测试。三步都成功只证明当前“客户端 × 模型 × 分组 × Gateway”组合可工作，不代表所有模型通用。

TROUBLESHOOTING

先看 /status，再按认证、模型、请求形状和上游分层

  • LOGIN
    仍然要求登录

    确认变量在启动 claude 之前已经设置；运行 /status 查看 Base URL 和 credential source，必要时 /logout。

  • 401
    Key 未被接受

    JBB 使用 x-api-key，检查是否设置了 ANTHROPIC_API_KEY、Key 状态、额度与分组。

  • 404
    路径或能力缺失

    Base URL 不要带 /v1；/v1/messages/count_tokens 当前明确为 404。

  • 400
    模型或字段不兼容

    检查完整模型 ID、Thinking、Tool Use、缓存字段和当前 Claude Code 版本；不要无上限换账号重试。

  • 429
    额度或频率限制

    核对 JBB 余额、Key 限额和分组；等待后有限重试，不要启动并发 retry storm。

  • 5xx
    Gateway 或上游错误

    保存请求 ID、时间、模型和错误正文；先用直连最小请求区分 Claude Code 与服务端问题。

PRODUCTION GATE

完成九项检查后再把 Claude Code 用到真实仓库

  • Claude Code 版本、claude doctor 和系统要求检查通过。
  • ANTHROPIC_BASE_URL 为站点 origin，不包含 /v1。
  • JBB Key 不在 Git、截图、命令历史、日志和聊天记录中出现。
  • 主模型与 Sonnet、Opus、Haiku family pin 均使用同一分组已验证的完整 ID。
  • 直连 Messages 和 Claude Code 首条消息均通过，并在 /status 确认配置来源。
  • 缓存以 usage 与实际账单验证，不以“响应变快”判断。
  • 读取、编辑、Shell 和 MCP 分开测试，权限遵循最小化原则。
  • 429、5xx 与网络超时采用有上限退避，禁止无限重试和账号轮询。
  • 先在测试仓库、小额度 Key 和可回滚分支运行，再逐步扩大范围。
创建专用 Key 查看协议边界 选择模型 核对价格