Cherry Studio 与 Chatbox 接入 MonkeyAI API Key

本次实测在生产环境验证了什么？

2026-08-09，向 https://monkeytheme.com/v1 发送了 9 个故意用错误 Key 的探测请求，全部返回 HTTP 401 与结构化 JSON 错误体，并带回 x-request-id 响应头。sub2api 后端日志显示 ingress_reject_reason=invalid_api_key，latency_ms 约 500 ms – 1.1 s，说明网关在认证层就拒了，没有打到任何上游 provider。

Cherry Studio 配置步骤

Cherry Studio 的 provider 入口在 设置 → 提供方（Providers）。新增一个自定义 OpenAI 兼容条目，填写下表三个必填字段后保存，再点击条目右侧的 检测。Cherry Studio 检测时会发 GET /v1/models；返回 200 且 JSON 非空，说明 Key、Host、模型发现三条都对。

保存后开一个新对话，切换到 MonkeyAI provider。Cherry Studio 会发 POST /v1/chat/completions，body 与 OpenAI 完全一致：messages 数组、model 字符串，外加可选 temperature、max_tokens、stream、tools。网关原样转发，不改字段。

Chatbox 配置步骤

Chatbox 的 provider 入口在 设置 → 模型（Model）。新增自定义 OpenAI 兼容条目，字段、请求头、底层行为与 Cherry Studio 完全一致；只是 UI 文案略有不同。

Chatbox 同样在保存 provider 时拉 GET /v1/models。列表为空时排查顺序与 Cherry Studio 一致：先看 Host 末尾 /v1，再换 Key 重试。保存后发一条短消息，确认回复与账号模型名一致。

Cherry Studio 视觉/图片输入

Cherry Studio 把图片拼成 content[] 数组，含一段 text 和一段 image_url。2026-08-09 的探测显示，这种结构在错误 Key 下返回 401 INVALID_API_KEY，说明网关不会剥掉多模态字段。配上真实 Key + 账号上的视觉模型（如 gpt-4o、claude-3-5-sonnet），即可正常收到回复。

POST /v1/chat/completions HTTP/1.1
Host: monkeytheme.com
Authorization: Bearer sk-***
Content-Type: application/json

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "这张图里有什么？"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}}
      ]
    }
  ]
}

如果上游账号拒掉 payload（网关返 200，上游再返 400 schema 错误），这是上游账号侧的问题，不是 MonkeyAI。Cherry Studio 会把这个错误原样抛到聊天窗口；这时应该查上游账号的模型可用范围与计费档位。

流式、重试与 Request ID

Cherry Studio 和 Chatbox 默认都开 stream: true。MonkeyAI 返回标准 SSE：data: {...} 帧 + 结尾 data: [DONE]。两个客户端都自带这种解析器，不需要写额外代码。

重试由客户端控制。Cherry Studio 对 5xx、429 默认自动重试，Chatbox 同理。调试时建议把客户端超时设大一些（60–120 秒），否则上游慢响应会被客户端超时先截掉，掩盖真正问题。

两个客户端都会自动生成 x-request-id 风格的自定义头。网关原样保留并在响应里带回同一个 id，便于把客户端日志和网关日志对齐。如果要升级工单，把两边的 id 都复制给支持人员。

常见配置错误

• API Host 写成了 https://monkeytheme.com，漏掉 /v1。客户端会请求 https://monkeytheme.com/chat/completions，网关没这条路由，nginx 直接 404。
• API Host 末尾多写了路径（如 /v1/chat/completions）。Cherry Studio 会再追加 /chat/completions，最终 URL 变成 /v1/chat/completions/chat/completions，同样 404。
• Key 带多余空格或换行。Bearer 头里有连续两个空格仍会返回 401 INVALID_API_KEY，body 与错误 Key 完全一致。粘贴后务必 trim。
• 把后台的 "登录密码" 当作 API Key 用。只有后台的 API Key 才能作为 Bearer Token；密码会返回另一种 code 的 401。
• 把 401 INVALID_API_KEY 当成上游故障。401 来自网关的认证层，跟上游无关。请先用 curl 跑 GET /v1/models 验证 Key。
• API Host 没改，停留在 OpenAI 默认值。Cherry Studio 和 Chatbox 默认都是 https://api.openai.com/v1，保存前必须替换为 MonkeyAI Host。

来源

• Cherry Studio 仓库
• Cherry Studio README（provider 配置）
• Chatbox 仓库
• Chatbox README（OpenAI 兼容 provider）
• MonkeyAI：OpenAI 兼容客户端矩阵
• MonkeyAI：OpenAI 兼容 API 网关说明
• MonkeyAI：OpenAI Python SDK 自定义 Base URL

FAQ