企业官网建设流程全解析

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-studio

Cherry 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_KEY="cs-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 里就有?providerType=anthropic&limit=5这样的用法可以直接抄。

用客户端自己的协议发一条请求

🔌 网关同时挂载了三组协议，客户端按自己熟悉的方言说话，输出也会用同一种方言返回：

最常用的一条非流式请求，接在上一节的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?alt=sse。流式有个值得知道的细节：网关会先缓冲协议脚手架帧，直到出现第一个有提供方语义的块（或干净结束）才提交 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 各代表什么

🔍 命令行调试最怕报错看不出是哪一层的问题。网关的鉴权和超时有明确的状态码约定：

还有两个容易踩的点：鉴权比较是 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