Cherry Studio API 快速上手指南：把本地 AI 客户端变成统一 API 网关

Cherry Studio API 快速上手指南把本地 AI 客户端变成统一 API 网关【免费下载链接】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 提供商的桌面客户端内置智能对话、自主 Agent 和预配置 AI 助手。它还有一个常被忽略的隐藏技能——API Gateway开启后你电脑上配好的所有模型都能通过本地 HTTP 接口被其他程序调用Cherry Studio 变成了一个通用的协议翻译网关对上游说 OpenAI、Anthropic 或 Gemini 的协议都行。这篇文章带你从零跑通第一个 API 请求手把手走完启动、调用、流式接收和排错的全流程。三步拿到你的第一个可用地址这一节帮你在最少的操作下拿到地址 密钥这两样调接口必需的东西。Cherry Studio 的 API Gateway 默认是关闭的需要你在客户端里手动开启一共三步装好客户端并配好一个能用的模型。从官方渠道下载安装 Cherry StudioWindows、macOS、Linux 均可然后进入Settings → Model Provider配置至少一个可用的 Provider 和模型。网关只是转发器它转发什么取决于你在这里配了什么。打开 API Gateway 并启动。进入Settings → API Gateway确认端口默认23333若被占用可改成 1000–65535 间的任意可用端口点击Start等状态变为Running。首次启动时Cherry Studio 会自动生成一个cs-sk-开头的网关 API Key直接复制保存即可。记下你的 Base URL。对于 OpenAI 兼容客户端默认地址是http://127.0.0.1:23333/v1配合第 2 步复制的 Key 就齐了。这里有个小技巧网关 Key 和上游 Provider 自己的 API Key 是两回事。你填在这里的 Key 只用于访问 Cherry Studio 的本地网关用来证明你是本机的合法调用方不需要填各家模型厂商的密钥。到这里你已经有了接口地址和认证密钥接下来看看这个网关到底能给你暴露哪些能力。能力全景一个网关能帮你做什么这一节帮你建立全局认知知道哪些场景值得用到它。Cherry Studio 的 API Gateway 同时说着三套主流协议的方言外加 Cherry 自己的 REST 扩展OpenAI 协议POST /v1/chat/completions对话补全、POST /v1/responsesResponses API、GET /v1/models模型列表Anthropic 协议POST /v1/messages、POST /v1/messages/count_tokens本地 token 估算Gemini 协议POST /v1beta/models/{provider:model}:generateContent支持?altsse流式Cherry REST 扩展知识库查询GET /v1/knowledge-bases、POST /v1/knowledge-bases/search和 MCP 服务器目录GET /v1/mcps免认证公共接口GET /health健康检查、GET /openapi/json机器可读的 OpenAPI 规范典型使用场景包括让你本地的其他脚本/应用直接复用 Cherry Studio 里配好的模型作为 Agent 运行时的模型桥或者让局域网内的配对设备手机连接过来使用。普通聊天场景则完全不需要开它。请求真正进来之后在内部是怎么走的下图展示了 Cherry Studio 的消息链路你的请求或界面消息经由 IPC 进入主进程由 AI Core 和 Completion Service 处理后以 UI Message Chunk 流的形式逐块返回。API 请求走的是同一套流式引擎只是入口换成了 HTTP 路由。理解了全局我们进入实战发一个真正的请求。实战发起一次普通对话这一节帮你完成第一次真正的调用。所有/v1接口都要求认证在 Header 里带上你的网关 Keycurl http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer 你的cs-sk-密钥 \ -H Content-Type: application/json \ -d {model: anthropic:claude-sonnet-4-6, messages: [{role: user, content: 你好}]}返回是一个标准的 OpenAI 格式 JSON 响应。这里有两个新手最容易踩的坑先说清楚模型 ID 的写法是providerId:modelId用第一个冒号分隔比如anthropic:claude-sonnet-4-6、openai:gpt-4。网关靠这个冒号判断该转发给哪个 Provider只写gpt-4是找不到模型的。可用的模型 ID 从哪来调GET /v1/models就能列出当前网关里所有模型返回{ object: list, data: [...] }其中的id字段直接抄进请求体的model字段即可不用去猜。确认普通对话跑通后下一步自然是更常见的流式场景——比如你希望文字像打字机一样逐字出现而不是干等几十秒。流式输出怎么接把请求体里加一个stream: true响应就变成 SSEServer-Sent Events事件流每来一块文本就是一个data:行最后是data: [DONE]curl -N http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer 你的cs-sk-密钥 \ -H Content-Type: application/json \ -d {model: openai:gpt-4, messages: [{role: user, content: 讲个笑话}], stream: true}-N参数让 curl 不缓冲输出你能实时看到块到达。用 Node.js 等语言接收时读取response.body的流即可每收到一行data:解析一次 JSON。注意流式响应和普通响应是两种处理方式普通响应是一个完整 JSON流式响应要按 SSE 事件逐条解析——这也是参考文章里特别提醒的地方。调优与配置改哪个参数会怎样这一节帮你在效果、速度和成本之间做取舍。网关的请求体遵循各协议原生格式以下是几个最值得调的参数及其影响参数作用怎么调temperature生成随机性越高越发散精确任务代码、JSON调到 0.2 以下创意写作可用 0.7maxOutputTokens输出长度上限写长文时调大嫌慢就调小topP/topK候选 token 采样范围与 temperature 二选一调即可别同时大幅改stopSequences遇指定字符串立即停止让模型输出固定格式如只输出 JSON时非常有用stream是否流式交互场景一律true批处理用false更简单网关侧的运行时配置都在Settings → API Gateway里端口feature.api_gateway.port默认23333改完需重启网关生效记得同步更新你的 Base URLAPI Key支持复制和重新生成。重新生成后旧 Key 立即失效所有客户端要换 Key自动启动点过 Start 后下次打开 Cherry Studio 会自动拉起网关点 Stop 会清掉这个设置并关闭局域网访问还有一个容易误解的点网关请求不经过Cherry Studio 自己的重试和 fallback 模型机制——你指名哪个模型就只会由那个模型服务。所以上游不稳定时重试逻辑要放在你自己的客户端里做。排错手册你看到了什么就查什么这一节帮你把常见的不对劲现象直接映射到原因和解决办法。现象401 或 403 认证失败401 Unauthorized: missing credentials请求里根本没带 Key或 Header 拼写错了。确认你带的是Authorization: Bearer key或x-api-key: key两种形式之一注意 Key 前后的空格。403 ForbiddenKey 带了但对不上。去 Settings → API Gateway 重新复制一次 Key确认没有复制成旧的重新生成后旧 Key 就废了。现象404 或提示找不到模型模型 ID 写错了。三步排查先调GET /v1/models看网关里到底有哪些模型再确认你用的是providerId:modelId完整格式最后确认对应 Provider 在 Cherry Studio 里是配置好且可用的——网关不会凭空变出一个模型。现象连接被拒绝 / 超时连不上先确认 Cherry Studio 在运行且网关状态是Running网关不随聊天功能自动开启检查端口是否和 Base URL 一致改过端口的人最容易在这里翻车可以用免认证的GET http://127.0.0.1:23333/health探活返回 200 说明网关本身是好的问题出在你的请求上现象流式请求中途断掉返回 504 或错误帧网关对流长时间无新块设有 20 分钟的闲置超时超时会以失败而非截断成功收尾非流式请求超时直接返回 504。这种情况多半是上游模型服务卡住或限速了看一下 Cherry Studio 里该模型直接对话是否正常正常的话就换模型或联系上游另外流式响应一旦开始输出HTTP 200 已提交中途错误会以对应协议的 SSE 错误帧结束你的客户端要能识别并处理这种帧而不是死等。现象其他程序报 CORS 或跨域问题网关对 CORS 是全开origin: true浏览器端调用理论上不会遇到跨域问题。如果你用的是浏览器本地开发工具注意网关默认只监听127.0.0.1回环地址——局域网内的设备要走专门的配对流程Settings → Device Connections而不是直接访问 HTTP 接口。进阶路径往源码里走一步排错都搞定之后如果你想深入理解网关是怎么把三种协议互相翻译的或者想基于它做二次开发可以从这里开始API Gateway 源码目录proxyStream.ts是请求 → 流 → 响应的核心引擎routes/下每个文件对应一组协议路由adapters/里是协议转换器API Gateway 官方参考文档完整的 HTTP 接口表、认证细节和请求流程图比本文详细得多AI 子系统参考想理解流式引擎AiStreamManager本身可以看这里网关的路由、错误封装和密钥机制都相当模块化读一遍routes/chat.ts不到 40 行你就能明白加一个新协议端点到底有多简单——这就是 Cherry Studio 作为二次开发底座的魅力。【免费下载链接】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），仅供参考