Cherry Studio 命令行实战3 条 curl 把桌面应用变成本地 AI 网关【免费下载链接】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 是一款桌面端 AI 生产力应用多数人只把它当成聊天窗口用。但它的仓库里内置了一个完整的本地 HTTP 网关开启后应用会以 OpenAI、Anthropic、Gemini 三种协议在127.0.0.1:23333上对外服务把已配置的所有模型、知识库和 MCP 服务都暴露成标准 API。这篇文章聚焦命令行侧从健康检查、列模型到发请求用 3 条 curl 就能把桌面应用当成终端可用的 AI 网关来驱动。先纠正一个误区仓库里没有独立的 CLI 二进制不少教程会教你敲cherry-studio start之类的命令但翻遍这个仓库的脚本和目录并不存在这样的可执行入口。真正面向终端的接口是应用进程内部运行的一个 HTTP 服务网关模块的源码在 src/main/features/apiGateway/完整的接口参考文档在 docs/references/api-gateway/README.md。换句话说Cherry Studio 的命令行不是可执行文件而是一组本地端点——你要做的只是往127.0.0.1:23333发 HTTP 请求。理解了这一点后面所有操作都会简单。而第一步是让这个服务真正跑起来。把内置网关跑起来并用健康检查确认它活着网关由应用内的设置页控制启用 API Gateway 后它默认绑定127.0.0.1:23333端口可在 1000–65535 之间调整。首次启用时会自动生成一个cs-sk-前缀的 API key设置页里可以直接复制或重新生成旁边还附着一段现成的Authorization头示例。页面上的启动、停止、重启按钮对应的主进程动作就是api_gateway.start/api_gateway.stop/api_gateway.restart三个 IpcApi 调用按钮只是这些调用的可视化外壳。服务起来后先敲一条不需要鉴权的探活请求curl http://127.0.0.1:23333/health正常输出是一段带status、timestamp、version三个字段的 JSON。如果连接被拒绝说明网关没启用或端口改过如果能连上、但后续带鉴权的请求报 401那是密钥问题而不是服务问题。确认活着之后下一步是搞清楚它手里有哪些牌。列出网关能驱动的所有模型拿到密钥后第一条真正的请求是列模型。网关把应用里配置的所有模型以 OpenAI 风格列表暴露出来export GATEWAY_KEYcs-sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # 1) 列出全部模型 curl -s http://127.0.0.1:23333/v1/models -H Authorization: Bearer $GATEWAY_KEY返回形如{ object: list, data: [ ... ] }每个条目的 id 形如anthropic:claude-sonnet-4-6或openai:gpt-5-nano——冒号前是提供方冒号后是模型 ID后续请求体的model字段就填这个完整形式。接口支持offset/limit分页也能按提供方类型过滤仓库自带的请求样例 tests/apis/chat.http 里就有?providerTypeanthropiclimit5这样的用法可以直接抄。用客户端自己的协议发一条请求 网关同时挂载了三组协议客户端按自己熟悉的方言说话输出也会用同一种方言返回客户端方言请求路径鉴权方式OpenAI ChatPOST /v1/chat/completionsAuthorization: Bearer keyAnthropicPOST /v1/messagesx-api-key: key优先级更高或 BearerGeminiPOST /v1beta/models/{provider:model}:generateContentx-goog-api-key头或?key查询参数最常用的一条非流式请求接在上一节的export之后# 2) 发一条 OpenAI 协议的聊天请求 curl -s http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer $GATEWAY_KEY \ -H Content-Type: application/json \ -d {model:openai:gpt-5-nano,messages:[{role:user,content:用一句话介绍你自己}]}请求体里加stream: true即切换为 SSE 流式Gemini 对应:streamGenerateContent?altsse。流式有个值得知道的细节网关会先缓冲协议脚手架帧直到出现第一个有提供方语义的块或干净结束才提交 HTTP 200所以你在终端看到的第一帧data:就是模型真正开始出字而不是连接建立。生成类接口解决的是问模型但应用里还有两类资源也挂在同一个端口上。顺便把知识库检索与 MCP 接口也用起来同一个端口上还有几组 Cherry 自家 REST 风格的接口GET /v1/knowledge-bases列出知识库、POST /v1/knowledge-bases/search做跨库语义检索、GET /v1/knowledge-bases/:id取单个知识库MCP 侧则是GET /v1/mcps列出激活的服务目录配合POST /v1/mcps/:id/mcp把 Streamable HTTP MCP 会话代理出来。对终端用户来说这等于在 shell 里跑 RAG 的全部积木先检索拿上下文再把它塞进聊天请求的 system message整条链路不需要离开命令行。看穿这条流网关和图形界面共用同一个引擎上面这些 HTTP 路由最终都汇到同一个引擎docs/references/ai/core-architecture.md 里描述的主进程AiStreamManager。它运行若干条流式执行循环把UIMessageChunk流扇出给多个监听者——图形界面、IM 频道适配器、网关的 SSE 监听器都平等地订阅同一条流。网关走的是特殊的promptStreamLifecycle这一轮对话不落库、不广播话题状态、不可 attach 重连客户端断开就直接 abort。另一条值得记住的不变量是调用方拥有上下文网关请求以contextOwner: caller提交Cherry 不会替你截断工具结果、裁剪或做摘要压缩——你传什么历史它就按什么历史发给模型。对脚本化调用而言这是好事上下文完全可控行为可预测。在图形界面里观察一条消息的完整处理会看到上图这条事件链block-created之后按需触发websearch-*与knowledge-*事件大模型阶段持续吐出text-delta等增量再经后处理与internaltool收尾到block-complete。网关通道看到的 SSE 帧是同一条流的另一种方言投影——事件语义一致只是外壳换成了各家协议自己的格式连错误都按请求路径选择对应的 envelope 返回Anthropic 风格的请求得到 Anthropic 风格的错误体OpenAI 风格的请求得到 OpenAI 风格的错误体。用状态码排障401、403、504 各代表什么 命令行调试最怕报错看不出是哪一层的问题。网关的鉴权和超时有明确的状态码约定现象含义处理401 Unauthorized: missing credentials请求没带任何 token补上 Bearer 或x-api-key头403 Forbiddentoken 不匹配或服务端 key 尚未生成到设置页核对/重新生成 key流式中收到50420 分钟无 chunk 的空闲超时上游卡住网关把暂停当失败处理而非截断返回连接被拒绝网关未启用或端口已改检查设置页开关先用/health探活还有两个容易踩的点鉴权比较是 timing-safe 的x-api-key头优先级高于 Bearer两者同时存在时以x-api-key为准GET /openapi的 Scalar 文档 UI 依赖 CDN 资源断网环境打不开但GET /openapi/json提供的 OpenAPI 描述完全在本地脚本和 SDK 消费它不受影响。现在就跑一遍这三条 curl不要先背接口先在终端按顺序执行/health确认服务在、/v1/models确认密钥有效并看看手里有哪些模型、最后发一条非流式聊天请求。三者都通了之后再开始改请求体里的model遍历不同提供方或加上stream: true逐帧观察 SSE 输出。想深入细节时网关参考文档 docs/references/api-gateway/README.md 就是唯一需要翻开的地方——从路由表到超时策略都写在里面了。【免费下载链接】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），仅供参考