Cherry Studio API Gateway 实战指南从本地部署到多协议流式调用【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 是一款支持 300 预配置助手与多 LLM 提供商的跨平台桌面客户端。它内置的 API GatewayAPI 网关把桌面端已配置的所有模型、知识库和 MCP 服务Model Context Protocol一种给 AI 挂载外部工具能力的协议暴露为本地 HTTP 接口同时兼容 OpenAI、Anthropic、Gemini 三种协议方言。如果你在自研应用里想复用本地已经配好的模型密钥或让 Claude Code、Cursor 等第三方工具直连这些模型这一篇会带你从启动网关到完成一次流式调用。快速上手获取并安装 Cherry Studio 桌面客户端Windows / macOS / Linux 均有发行版。如果是从源码运行git clone https://gitcode.com/GitHub_Trending/ch/cherry-studio corepack enable pnpm install pnpm dev在桌面端「设置 → 工具设置 → API Gateway」中打开开关。网关默认监听127.0.0.1:23333首次启动时自动生成cs-sk-前缀的 API Key设置页源码。配置认证头。网关按以下优先级读取凭证认证中间件x-api-key请求头Anthropic 风格优先Authorization: Bearer tokenOpenAI 风格x-goog-api-key或?key查询参数仅限 Gemini 路由验证网关已就绪以下两个端点无需认证curl http://127.0.0.1:23333/health # → { status: ok, timestamp: ..., version: ... } curl http://127.0.0.1:23333/openapi/json # → 完整的 OpenAPI JSON 规范完全本地生成可离线网关默认仅绑定回环地址loopback即 127.0.0.1局域网其他设备无法直接访问。如需 LAN 访问须在「设备连接」设置中显式开启此时监听地址才会切换为0.0.0.0。核心机制一次生成请求的完整链路定义在 请求引擎processMessage中共五步解析模型地址请求体里的model字段格式为providerId:modelId按第一个:切分例如anthropic:claude-sonnet-4-6。网关据此解析出目标提供商与模型stream字段决定是否走流式路径。协议转换MessageConverterFactory按路由方言openai/anthropic/gemini/openai-responses实例化对应转换器把输入消息转为 AI SDK 内部的UIMessage[]同时提取采样参数temperature、topP、maxOutputTokens等与客户端工具定义适配器源码。驱动模型调用AiStreamManager.streamPrompt()发起推理。网关在此身份是「对等、非持久化」的订阅者——与桌面端 UI 使用同一套流管理引擎但网关会话不落库、不广播状态AiStreamManager。协议回转输出侧StreamAdapterFactory把内部UIMessageChunk事件流转成调用方方言的 SSE 事件再经ISseFormatter序列化为text/event-stream字符串非流式请求则累积全部块后一次性返回 JSON。超时与中止客户端断连触发abort20 分钟无数据块的空闲超时会以失败504 或方言错误帧收场而不是静默截断。两个关键不变量值得注意。其一调用方拥有上下文网关会话标记为contextOwner: callerCherry Studio 不会替你截断工具结果或做摘要压缩多轮历史由你自己管理。其二助手无关assistant-agnostic网关不挂接任何内置助手采样参数、工具、推理选项全部按请求透传行为只取决于你发什么。接口速查方法路径协议方言用途GET/公开网关信息与端点清单GET/health公开健康检查GET/openapi、/openapi/json公开Scalar 文档页 / OpenAPI 规范GET/v1/models?offsetlimitOpenAI列出可用模型id 为providerId:modelIdPOST/v1/chat/completionsOpenAI聊天补全stream: true时返回 SSEPOST/v1/responsesOpenAI ResponsesOpenAI Responses 方言生成POST/v1/messagesAnthropicMessages 方言生成POST/v1/messages/count_tokensAnthropicToken 估算POST/v1beta/models/{providerId:modelId}:generateContentGeminiJSON 生成POST/v1beta/models/{providerId:modelId}:streamGenerateContent?altsseGeminiSSE 流式生成GET/v1/knowledge-basesCherry REST知识库列表POST/v1/knowledge-bases/searchCherry REST跨知识库语义检索GET/v1/mcps、/v1/mcps/:idCherry RESTMCP 服务器目录POST/v1/mcps/:id/mcpMCP Streamable HTTPMCP 代理initialize / tools/call 等 JSON-RPC 请求聊天补全OpenAI 方言必填项model、messages请求校验。其余字段宽松透传不会被网关拒绝。curl http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer cs-sk-xxxx \ -H Content-Type: application/json \ -d { model: openai:gpt-4o, messages: [{role: user, content: Hello}], stream: false }响应OpenAI 标准结构{ id: chatcmpl-xxx, object: chat.completion, model: openai:gpt-4o, choices: [{ index: 0, message: {role: assistant, content: Hi! How can I help you?}, finish_reason: stop }], usage: {prompt_tokens: 12, completion_tokens: 9, total_tokens: 21} }模型列表curl http://127.0.0.1:23333/v1/models -H Authorization: Bearer cs-sk-xxxx{ object: list, data: [ {id: openai:gpt-4o, object: model, created: 1700000000, owned_by: OpenAI}, {id: anthropic:claude-sonnet-4-6, object: model, created: 1700000000, owned_by: Anthropic} ] }模型列表只包含「已启用提供商下的已启用模型」且做了网关 id 去重列表实现。调用前先查列表确认providerId:modelId拼写是排查 400 的第一步。实战场景场景一流式输出边生成边返回类似打字机效果OpenAI 官方 SDK 指向本地网关即可零代码改造import OpenAI from openai; const client new OpenAI({ baseURL: http://127.0.0.1:23333/v1, apiKey: cs-sk-xxxx }); const stream await client.chat.completions.create({ model: openai:gpt-4o, messages: [{ role: user, content: 用一句话解释 SSE }], stream: true }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content ?? ); }场景二多轮对话网关不替你维护上下文contextOwner: caller历史消息由客户端自行累积并随每次请求完整发送const history [{ role: user, content: 我叫小明 }]; function ask(question) { history.push({ role: user, content: question }); return fetch(http://127.0.0.1:23333/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer cs-sk-xxxx }, body: JSON.stringify({ model: deepseek:deepseek-chat, messages: history, stream: false }) }).then(r r.json()).then(d { history.push(d.choices[0].message); return d.choices[0].message.content; }); }场景三跨协议调用与知识库检索同一把 Key 可调用 Anthropic 方言x-api-key头优先curl http://127.0.0.1:23333/v1/messages \ -H x-api-key: cs-sk-xxxx -H Content-Type: application/json \ -d {model:anthropic:claude-sonnet-4-6,messages:[{role:user,content:Hi}]}对桌面端已建好的知识库做语义检索curl http://127.0.0.1:23333/v1/knowledge-bases/search \ -H Authorization: Bearer cs-sk-xxxx -H Content-Type: application/json \ -d {query:部署流程,knowledge_base_ids:[kb-id],document_count:5}错误响应按请求路径选信封错误处理/v1/messages返回 Anthropic 的{ type: error, error: {…} }/v1/chat、/v1/responses返回 OpenAI 的{ error: { message, type, code } }/v1beta返回 Google 的{ error: { code, message, status } }。客户端按自己使用的协议方言解析即可无需写分支。避坑指南现象401Unauthorized: missing credentials请求头缺少凭证。处理确认x-api-key、Authorization: Bearer、x-goog-api-key三者至少带一个。现象403Forbidden密钥不匹配或网关尚未生成 Key。处理到 API Gateway 设置页复制或重新生成Key 后重试注意 Key 变更需手动同步到所有客户端。现象400Invalid model format/not available through the API gatewaymodel未使用providerId:modelId格式提供商未启用或该模型不可路由Agent 专属提供商、外部 CLI 提供商不在网关服务范围内。处理先GET /v1/models拿合法 id 列表。现象流式请求中途断开且没有 HTTP 错误200 已提交后上游错误会转成对应方言的 SSE 终端错误帧而非改变状态码。处理流式客户端必须处理事件流中的 error 帧不能只看 HTTP 状态。现象50420 分钟无数据块的空闲超时。处理检查上游提供商状态长任务客户端侧做断点续查。现象局域网设备连不上网关默认仅回环可达。处理在「设备连接」页显式开启 LAN 暴露后监听地址才会切到0.0.0.0。进阶与扩展关键配置项偏好定义键默认值说明feature.api_gateway.enabledfalse启动时是否自动开启网关feature.api_gateway.host127.0.0.1设为0.0.0.0才允许 LAN 访问feature.api_gateway.port23333本地端口UI 限制 1000–65535feature.api_gateway.api_key自动生成首次激活生成cs-sk-uuid二次开发入口请求核心引擎模型解析、超时、提交屏障proxyStream.ts协议转换器与流适配器新增方言的落点adapters/认证中间件middleware/auth.ts错误信封与流式错误帧errors.ts知识库路由routes/knowledge.ts完整设计文档API Gateway Reference【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考