Chatbox 接入 JBB：Host 不带 /v1，Path 单独填写

PRE-FLIGHT

准备官方 Chatbox、专用 JBB Key 和一个精确模型 ID

先从 Chatbox 官方站点安装客户端，再在 JBB 控制台创建独立、低额度 Key。不要把账号密码、Session 或管理员 Token 填进 Chatbox。

Chatbox、Chatbox AI 及相关商标归其权利人所有；本页不表示 JBB 与 Chatbox 存在官方合作、授权或背书。

MANUAL SETUP

按官方 Model Provider 流程配置，八步可复现

1. 打开 Chatbox，点击侧边栏的设置按钮。
2. 进入模型提供方 / Model Provider。
3. 如果没有需要的提供方，点击底部添加 / Add。
4. 提供方名称填 JBB 金贝贝，API 类型选OpenAI API 兼容。
5. 填入 JBB API Key、API Host 和 API Path；Host 不带 /v1。
6. 添加至少一个精确模型 ID；只勾选已验证的能力。
7. 保存后点击检查 / Check，确认客户端显示连接成功。
8. 回到首页，新建对话，选择刚添加的模型发起首条短消息。

步骤依据：Chatbox 官方“模型配置”文档。

FIELD MAP

API Host 是站点 origin，API Path 才是 Chat Completions 路径

Provider Type: OpenAI API 兼容
API Host: https://jbbt.pages.dev
API Path: /v1/chat/completions
API Key: <YOUR_JBB_API_KEY>
Model: <EXACT_MODEL_ID_FROM_/v1/models>

MODEL CAPABILITIES

不配能力默认是纯文本；vision、reasoning、tool_use 只按实测勾选

Chatbox 官方配置格式允许为模型设置 vision、reasoning 和 tool_use。这些标记会影响客户端如何构造请求，不是展示标签。

• Model ID：保持 JBB 返回的原始大小写和完整字符串。
• Vision：只在当前模型、分组与上游已经通过图片输入测试时勾选。
• Reasoning：需同时确认模型和 JBB 转发链接受相关参数。
• Tool Use：先用最小工具调用单独验证，不要用普通文本回复代替工具成功。
• Context Window / Max Output：只填可追溯的模型限制；留空比猜值更安全。

官方说明：能力配置可选，未配置模型视为纯文本模型。

CONNECTION TEST

先预检 Key 和模型，再用 Chatbox Check 和首条对话闭环

GET /v1/models 用于只读预检；最小 Chat Completions 与 Chatbox 首条对话可能产生少量计费。使用低额度专用 Key，不做无上限重试。

export JBB_API_KEY="<YOUR_JBB_API_KEY>"
curl "https://jbbt.pages.dev/v1/models"   -H "Authorization: Bearer $JBB_API_KEY"

$env:JBB_API_KEY = "<YOUR_JBB_API_KEY>"
Invoke-RestMethod -Uri "https://jbbt.pages.dev/v1/models" -Headers @{ Authorization = "Bearer $env:JBB_API_KEY" }

JSON IMPORT

Chatbox 1.15.1 起支持导入 Provider JSON，配置文件不要携带 Key

官方配置格式当前的 type 为 openai，apiPath 默认 /v1/chat/completions。下面模板故意省略 apiKey，导入后再在 Chatbox 设置中填写。

{
  "id": "jbbt.pages.dev",
  "name": "JBB 金贝贝",
  "type": "openai",
  "iconUrl": "https://jbbt.pages.dev/logo.png",
  "urls": {
    "website": "https://jbbt.pages.dev/",
    "getApiKey": "https://jbbt.pages.dev/dashboard",
    "docs": "https://jbbt.pages.dev/docs/quickstart",
    "models": "https://jbbt.pages.dev/models"
  },
  "settings": {
    "apiHost": "https://jbbt.pages.dev",
    "apiPath": "/v1/chat/completions",
    "models": [
      {
        "modelId": "<EXACT_MODEL_ID>",
        "type": "chat"
      }
    ]
  }
}

• 导入前把 <EXACT_MODEL_ID> 替换为真实模型 ID。
• 不在 JSON、二维码、deep link、聊天或 Git 里携带 API Key。
• 导入后先检查 Host、Path 和模型，再在本地 Chatbox 界面填写 Key。

格式依据：Chatbox 官方“导入第三方提供方配置”。

TROUBLESHOOTING

先查 Host/Path 拼接，再查 Key、模型、能力和上游

• 401
  API Key 未被接受

  检查是否填入 JBB 专用 Key、Key 是否启用、额度和分组是否正确。

• 404
  Host 与 Path 拼接错误

  Host 不要带 /v1，Path 填 /v1/chat/completions；检查是否变成 /v1/v1/chat/completions。

• 400
  模型或能力参数不兼容

  先取消 vision、reasoning、tool_use，用纯文本最小请求定位，再逐项恢复。

• MODEL
  模型不存在或不可见

  从当前 Key 的 /v1/models 重新复制完整 ID，同时检查分组与渠道映射。

• 429
  额度或频率限制

  检查 JBB 余额、Key 限额和分组，使用有上限退避，禁止快速无限重试。

• 5xx
  Gateway 或上游错误

  保存时间、模型、请求 ID 和错误正文，用终端最小请求区分 Chatbox 与服务端问题。

• NO LOG
  Chatbox 报错但 JBB 无日志

  请求大概没有到 JBB；优先检查客户端网络、Host/Path 与是否选中了正确 Provider。

PRIVACY & SECURITY

聊天与设置本地存储，但生成回复的请求会发往 JBB 和上游

Chatbox 官方表示聊天消息和设置数据存储在用户设备。同时官方明确提醒：使用第三方 API 时，需要自行审查对方的隐私政策和服务条款。

• JBB Key 只保存在自己的 Chatbox 客户端，不写入导入 JSON 或 deep link。
• 不向模型发送不必要的密码、Token、身份信息或未脱敏文件。
• 为 Chatbox 单独设置低额度 Key，出现异常调用时可以不影响其他客户端地禁用。
• 对话、上下文、图片和附件会按请求需要进入 JBB 及选定上游；本地存储不等于请求不离开设备。
• 首次配置使用无敏感内容和最小额度完成验证，再逐步放大范围。

隐私依据：Chatbox 官方“我的数据存储在哪里？”。

FAQ

Chatbox 接入 JBB 常见问题

• Q1
  API Host 要不要带 /v1？

  不带。Host 填 https://jbbt.pages.dev，Path 单独填 /v1/chat/completions。

• Q2
  API Path 可以留空吗？

  Chatbox 官方默认是 /v1/chat/completions。JBB 建议显式填写，方便排查和导出。

• Q3
  为什么 Check 成功却无法聊天？

  Check 不等于当前模型和所有能力已通过。检查精确模型 ID，先取消所有能力标记完成纯文本测试。

• Q4
  能否直接导入 JBB 配置？

  Chatbox 1.15.1 起支持 Provider JSON 导入。为避免 Key 经文件或 URL 泄露，导入模板不包含 Key。

• Q5
  模型能力要全选吗？

  不要。只选当前模型 × 分组 × 上游组合已验证的能力；留空则按纯文本模型处理。