Cherry Studio CLI 完全指南用一条 curl 驱动 300 AI 模型从本地跑通到 systemd 守护【免费下载链接】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你在无头 Linux 服务器上 ssh 登录想调一次 Cherry Studio 里配好的模型却连桌面都打不开或者你每天要在 GUI 里点二十几次发送来做批量测试——这些卡壳场景恰恰是 Cherry Studio 内置的 API Gateway 命令行接口存在的意义。这个 HTTP 网关把桌面端已配置好的全部模型、知识库和 MCP 工具通过 OpenAI、Anthropic、Gemini 三种协议方言暴露在本机127.0.0.1:23333任何 curl 或脚本都能直接驱动。本文带你从零把这个本地 AI 服务跑进生产。心智模型把它当成你的本地协议翻译官动手前先建一个直觉Cherry Studio 本质是一台方言翻译机。你在 GUI 里配置了 OpenAI、Anthropic、Gemini 等各家 Provider每个 Provider 的请求格式、鉴权头、流式协议都不一样而 API Gateway 的作用是让外部调用方只说它自己熟悉的方言由 Cherry 负责翻译成后端 Provider 真正需要的格式再把流式结果翻译回调用方的方言。这个心智模型决定了你的使用方式GUI 负责配置Provider、密钥、知识库命令行负责消费调用、批量、自动化。配置一次之后所有脚本、CI 任务、其他程序都指向同一个本地地址不再依赖窗口存在。场景更合适的入口原因配置 Provider、密钥、模型GUI图形化表单天然适合一次性配置调试知识库检索效果GUI可直观看到切片与召回结果批量调用、定时任务、CI 集成命令行HTTP 网关可脚本化、可断言、可无人值守让别的程序如 IDE 插件复用已配模型命令行只需改 baseURL 到本机网关无显示器的服务器命令行唯一不依赖桌面的操作面一句话配置在界面里做消费在终端里做。下面先跑通最小闭环。五分钟跑通第一条命令环境与依赖仓库用 pnpm 管理工作区Node 版本有硬性约束package.json的 engines 字段。项要求备注Node.js 24.11.1 24.16.0仓库用engine-strict锁版本建议 nvm 安装 24.x 稳定版包管理器pnpm 11.x仓库声明packageManager: pnpm11.8.0系统Linux / macOS / WindowsLinux 需具备编译环境better-sqlite3 会重新编译安装并启动# 克隆仓库只需一次这是唯一的 clone 地址 git clone https://gitcode.com/GitHub_Trending/ch/cherry-studio cd cherry-studio # 安装依赖postinstall 会自动构建工作区内的 dsh-bridge 包 pnpm install # 以开发模式启动桌面应用会先重新编译 better-sqlite3 再拉起 Electron # 无显示器的服务器请用 VNC/X11 转发先开一次窗口完成网关开关配置 pnpm dev启动后在设置里找到API Gateway页面点启动。此时界面会显示服务地址、API Key形如cs-sk-xxxxxxxx以及 Authorization 头示例把 Key 抄下来备用。验证两条 curl 确认网关活着/health是免鉴权的公开端点专门给探活脚本用# 探活期望返回 JSON包含 status 与 version 字段 curl -s http://127.0.0.1:23333/health # 预期输出示意{status:ok,timestamp:...,version:2.0.10}再拿 Key 列一下模型确认鉴权链路也通了# 所有 /v1 路由都要带 Bearer 鉴权Key 换成界面里那串 cs-sk-xxx curl -s http://127.0.0.1:23333/v1/models \ -H Authorization: Bearer $CHERRY_KEY | head -c 400 # 预期{object:list,data:[{id:openai:gpt-4o, ...}]}✅ 两条都有输出你的终端里就有一个完整的本地 AI 服务了。⚠️ 注意模型 ID 的格式是提供商:模型如anthropic:claude-sonnet-4-6这个格式后面会反复出现。能力全景按场景消费这个网关场景一把请求喂进模型这一节解决如何用命令行发出一次模型调用。核心事实输入方言由 URL 路径决定同一个后端模型走不同路径就按不同协议应答你的现有 SDK 客户端几乎零改造。# OpenAI Chat 方言最通用绝大多数 SDK 都支持自定义 baseURL curl -s http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d {model:openai:gpt-4o,messages:[{role:user,content:用一句话介绍你自己}],stream:false} # stream 置 true 则返回 SSE 流模型 ID 必须带提供商前缀同一请求换成 Anthropic 方言鉴权头变成x-api-key# Anthropic Messages 方言注意鉴权头与 model 字段格式都不同 curl -s http://127.0.0.1:23333/v1/messages \ -H x-api-key: $CHERRY_KEY -H Content-Type: application/json \ -d {model:anthropic:claude-sonnet-4-6,max_tokens:256,messages:[{role:user,content:你好}]}关键参数以 OpenAI 路径为例model提供商:模型格式冒号只按第一个拆分streamtrue走 SSE 流式false等完整 JSONtemperature/top_p/max_tokens采样参数随请求透传给后端模型鉴权Authorization: BearerOpenAI/Gemini 路径或x-api-keyAnthropic 路径采样参数是每次请求级覆盖不影响 GUI 里的任何设置✅ 验证方法响应 JSON 里choices[0].message.content非空或 Anthropic 方言下content[0].text有值即为成功。场景二按方言给现有客户端换插座这个场景解决我已经有代码/工具链了不想重写。答案通常是改一个环境变量# 让你的 OpenAI SDK 复用 Cherry 已配置好的所有 Provider export OPENAI_BASE_URLhttp://127.0.0.1:23333/v1 export OPENAI_API_KEY$CHERRY_KEY # 验证列出网关能转发的全部模型 curl -s $OPENAI_BASE_URL/models -H Authorization: Bearer $CHERRY_KEYGemini 方言走独立路径鉴权用x-goog-api-key或?key查询参数模型名里用冒号分隔提供商与方法名例如:generateContent后缀。三种方言之外还有POST /v1/responsesOpenAI Responses API可用适合需要 function calling 回传的新客户端。✅ 验证方式与场景一相同任意方言收到 200 且内容非空。场景三一次检索整个知识库这个场景解决脚本里需要 RAG 检索但不想开 GUI。知识库走 Cherry 自有 REST 方言同样带 Bearer 鉴权# 列出全部知识库支持 offset/limit 分页 curl -s http://127.0.0.1:23333/v1/knowledge-bases -H Authorization: Bearer $CHERRY_KEY # 语义检索跨知识库召回相关切片喂给你自己的生成流程 curl -s http://127.0.0.1:23333/v1/knowledge-bases/search \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d {query:网关的鉴权机制是什么,limit:5} # MCP 工具目录列出所有活跃 MCP 服务器及其网关地址 curl -s http://127.0.0.1:23333/v1/mcps -H Authorization: Bearer $CHERRY_KEYMCP 服务器支持 Streamable HTTP 代理POST /v1/mcps/:id/mcp脚本可以直接对网关发起 JSON-RPC 调用拿到预热好的工具目录。✅ 验证方法search 返回的命中列表里包含切片文本与相关度分数。场景四批量任务脚本化这个场景解决重复 20 次的操作。下面是一个可直接保存为summarize.sh的批量摘要脚本演示遍历输入 → 调网关 → 落盘结果的完整闭环#!/usr/bin/env bash # 批量摘要遍历 docs/ 下所有 .md经 Cherry Studio 网关生成摘要 set -euo pipefail BASEhttp://127.0.0.1:23333/v1 # 网关地址改这里即可指向别的实例 MODEL${CHERRY_MODEL:-openai:gpt-4o} # 模型可环境变量覆盖 OUT./summaries; mkdir -p $OUT for f in $; do # 用 jq 安全构造 JSON避免文档里的引号/换行把请求体打坏 body$(jq -n --arg m $MODEL --arg c $(cat $f) \ {model:$m,stream:false,messages:[{role:user,content:(请用一句话总结\n$c)}]}) # -m 300 防止单次调用挂死拖垮整个批次 if curl -s -m 300 $BASE/chat/completions \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d $body | jq -r .choices[0].message.content $OUT/$(basename $f .md).txt; then echo ✅ $f else echo ❌ $f fi done上图是网关的核心工作链路请求进来先过鉴权输入被翻译成内部统一消息格式由与 GUI 完全相同的AiStreamManager引擎驱动生成再翻译回你的方言输出。理解这条链路后任何流式断了超时了的问题都能定位到具体环节。生产级落地systemd 托管 健康检查目标是让配置好模型的服务像基础设施一样稳定运行开机自启、挂了自动拉起、定时探活报警。第 1 步确认打包版安装路径并确认网关随应用自启。# 查看打包版可执行文件位置按你的安装方式调整 which cherry-studio || ls /opt/cherry-studio/cherry-studio # 前提设置界面里 API Gateway 已开启启动时自动开启 # 应用主进程会依据持久化的 feature.api_gateway.enabled 意图自动拉起网关第 2 步交给 systemd 托管进程崩溃自动重启。sudo tee /etc/systemd/system/cherry-studio.service /dev/null EOF [Unit] DescriptionCherry Studio内置 AI 网关宿主 Afternetwork.target [Service] # 替换为你第 1 步查到的可执行文件绝对路径 ExecStart/opt/cherry-studio/cherry-studio Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload # 让 systemd 加载新单元文件 sudo systemctl enable --now cherry-studio systemctl status cherry-studio --no-pager # 预期 active (running)第 3 步部署定时健康检查不健康时主动告警。# 探活脚本/health 是免鉴权端点专为无人值守探测设计 sudo tee /usr/local/bin/cherry-health.sh /dev/null EOF #!/usr/bin/env bash curl -sf -m 5 http://127.0.0.1:23333/health /dev/null \ || { echo [ALERT] $(date %F %T) Cherry Studio 网关无响应 /var/log/cherry-health.log; } EOF sudo chmod x /usr/local/bin/cherry-health.sh # crontab -e 追加每 5 分钟探一次 echo */5 * * * * /usr/local/bin/cherry-health.sh | crontab -✅ 验证链路systemctl status显示 activecurl /health返回 ok故意systemctl stop后 5 分钟内告警文件新增一条记录。性能与行为调优决策表参数 → 改法 → 预期效果你遇到的情况调整项预期效果局域网内其他机器也要调用设置界面把 host 从127.0.0.1改为0.0.0.0网关接受远程连接注意同步收紧防火墙23333 端口被占用设置界面改 port1000–65535换端口后原脚本改 BASE 地址即可担心 Key 泄露设置界面点重新生成换新 Key旧 Key 立即失效timing-safe 比对旧值不再匹配长回答被中途判定失败了解 20 分钟流空闲超时模型思考时间超过 20 分钟无 token 才触发正常流式不受影响停网关时 MCP 会话残留了解 stop 行为先关会话再关 HTTP网关停止时所有 MCP 会话被强制终结不会泄漏到下次启动避坑手册五个高频现场1. 401 Unauthorized现象所有/v1/*请求都返回 401。 根因漏带鉴权头或用了?key这种 Gemini 风格该风格仅/v1beta路径有效。 修复curl -s http://127.0.0.1:23333/v1/models -H Authorization: Bearer $CHERRY_KEY2. 403 Forbidden现象头带了Key 也复制了仍然 403。 根因Key 与网关当前生效的feature.api_gateway.api_key不一致——重新生成过 Key 但脚本里还是旧的。 修复从设置界面复制最新 Key 更新脚本或curl -s http://127.0.0.1:23333/v1/models -H x-api-key: $CHERRY_KEY交叉验证。3. 启动报 EADDRINUSE / 端口冲突现象网关启动失败日志里出现端口占用错误。 根因23333 已被本机上另一个进程或上一次没退干净的实例占用。 修复ss -lntp | grep 23333定位占用进程或改端口后在设置里重启网关。4. 模型 404 / 模型不存在现象请求 400 或model not found。 根因model字段漏了提供商前缀写了gpt-4o而不是openai:gpt-4o。 修复curl -s $OPENAI_BASE_URL/models -H Authorization: Bearer $CHERRY_KEY取真实 ID 列表。5. 期待一个cherry-studio可执行命令现象照着别的教程敲cherry-studio start命令不存在。 根因v1 时代的 CLI 安装路径v1.cli.install已退役当前版本没有独立 CLI 二进制命令行面就是内置 HTTP 网关。 修复把cherry-studio start/stop的心智替换成启动应用 启动网关宿主操作全部走 curl仓库内 docs/references/api-gateway/README.md 是权威接口文档。下一步把网关包成团队内部 API给同事一段设置OPENAI_BASE_URL的 onboarding 脚本——curl -s http://127.0.0.1:23333/openapi/json直接导出完整 OpenAPI 规范丢进任何代码生成工具。给 CI 加一步冒烟测试上面第 3 步的cherry-health.sh改造成 CI job失败即阻断流水线。参与贡献本地pnpm ci:basic-check跑通静态检查再pnpm ci:test-check跑全量测试为 docs/contrib/development.md 描述的开发流程贡献一个 PR。命令行带来的自由度就藏在这些可以被脚本驯服的 HTTP 响应里。下次发版前先看看它又学会了什么curl -s http://127.0.0.1:23333/health | jq .version【免费下载链接】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），仅供参考 Cherry Studio CLI 完全指南：用一条 curl 驱动 300+ AI 模型，从本地跑通到 systemd 守护
Cherry Studio CLI 完全指南用一条 curl 驱动 300 AI 模型从本地跑通到 systemd 守护【免费下载链接】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你在无头 Linux 服务器上 ssh 登录想调一次 Cherry Studio 里配好的模型却连桌面都打不开或者你每天要在 GUI 里点二十几次发送来做批量测试——这些卡壳场景恰恰是 Cherry Studio 内置的 API Gateway 命令行接口存在的意义。这个 HTTP 网关把桌面端已配置好的全部模型、知识库和 MCP 工具通过 OpenAI、Anthropic、Gemini 三种协议方言暴露在本机127.0.0.1:23333任何 curl 或脚本都能直接驱动。本文带你从零把这个本地 AI 服务跑进生产。心智模型把它当成你的本地协议翻译官动手前先建一个直觉Cherry Studio 本质是一台方言翻译机。你在 GUI 里配置了 OpenAI、Anthropic、Gemini 等各家 Provider每个 Provider 的请求格式、鉴权头、流式协议都不一样而 API Gateway 的作用是让外部调用方只说它自己熟悉的方言由 Cherry 负责翻译成后端 Provider 真正需要的格式再把流式结果翻译回调用方的方言。这个心智模型决定了你的使用方式GUI 负责配置Provider、密钥、知识库命令行负责消费调用、批量、自动化。配置一次之后所有脚本、CI 任务、其他程序都指向同一个本地地址不再依赖窗口存在。场景更合适的入口原因配置 Provider、密钥、模型GUI图形化表单天然适合一次性配置调试知识库检索效果GUI可直观看到切片与召回结果批量调用、定时任务、CI 集成命令行HTTP 网关可脚本化、可断言、可无人值守让别的程序如 IDE 插件复用已配模型命令行只需改 baseURL 到本机网关无显示器的服务器命令行唯一不依赖桌面的操作面一句话配置在界面里做消费在终端里做。下面先跑通最小闭环。五分钟跑通第一条命令环境与依赖仓库用 pnpm 管理工作区Node 版本有硬性约束package.json的 engines 字段。项要求备注Node.js 24.11.1 24.16.0仓库用engine-strict锁版本建议 nvm 安装 24.x 稳定版包管理器pnpm 11.x仓库声明packageManager: pnpm11.8.0系统Linux / macOS / WindowsLinux 需具备编译环境better-sqlite3 会重新编译安装并启动# 克隆仓库只需一次这是唯一的 clone 地址 git clone https://gitcode.com/GitHub_Trending/ch/cherry-studio cd cherry-studio # 安装依赖postinstall 会自动构建工作区内的 dsh-bridge 包 pnpm install # 以开发模式启动桌面应用会先重新编译 better-sqlite3 再拉起 Electron # 无显示器的服务器请用 VNC/X11 转发先开一次窗口完成网关开关配置 pnpm dev启动后在设置里找到API Gateway页面点启动。此时界面会显示服务地址、API Key形如cs-sk-xxxxxxxx以及 Authorization 头示例把 Key 抄下来备用。验证两条 curl 确认网关活着/health是免鉴权的公开端点专门给探活脚本用# 探活期望返回 JSON包含 status 与 version 字段 curl -s http://127.0.0.1:23333/health # 预期输出示意{status:ok,timestamp:...,version:2.0.10}再拿 Key 列一下模型确认鉴权链路也通了# 所有 /v1 路由都要带 Bearer 鉴权Key 换成界面里那串 cs-sk-xxx curl -s http://127.0.0.1:23333/v1/models \ -H Authorization: Bearer $CHERRY_KEY | head -c 400 # 预期{object:list,data:[{id:openai:gpt-4o, ...}]}✅ 两条都有输出你的终端里就有一个完整的本地 AI 服务了。⚠️ 注意模型 ID 的格式是提供商:模型如anthropic:claude-sonnet-4-6这个格式后面会反复出现。能力全景按场景消费这个网关场景一把请求喂进模型这一节解决如何用命令行发出一次模型调用。核心事实输入方言由 URL 路径决定同一个后端模型走不同路径就按不同协议应答你的现有 SDK 客户端几乎零改造。# OpenAI Chat 方言最通用绝大多数 SDK 都支持自定义 baseURL curl -s http://127.0.0.1:23333/v1/chat/completions \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d {model:openai:gpt-4o,messages:[{role:user,content:用一句话介绍你自己}],stream:false} # stream 置 true 则返回 SSE 流模型 ID 必须带提供商前缀同一请求换成 Anthropic 方言鉴权头变成x-api-key# Anthropic Messages 方言注意鉴权头与 model 字段格式都不同 curl -s http://127.0.0.1:23333/v1/messages \ -H x-api-key: $CHERRY_KEY -H Content-Type: application/json \ -d {model:anthropic:claude-sonnet-4-6,max_tokens:256,messages:[{role:user,content:你好}]}关键参数以 OpenAI 路径为例model提供商:模型格式冒号只按第一个拆分streamtrue走 SSE 流式false等完整 JSONtemperature/top_p/max_tokens采样参数随请求透传给后端模型鉴权Authorization: BearerOpenAI/Gemini 路径或x-api-keyAnthropic 路径采样参数是每次请求级覆盖不影响 GUI 里的任何设置✅ 验证方法响应 JSON 里choices[0].message.content非空或 Anthropic 方言下content[0].text有值即为成功。场景二按方言给现有客户端换插座这个场景解决我已经有代码/工具链了不想重写。答案通常是改一个环境变量# 让你的 OpenAI SDK 复用 Cherry 已配置好的所有 Provider export OPENAI_BASE_URLhttp://127.0.0.1:23333/v1 export OPENAI_API_KEY$CHERRY_KEY # 验证列出网关能转发的全部模型 curl -s $OPENAI_BASE_URL/models -H Authorization: Bearer $CHERRY_KEYGemini 方言走独立路径鉴权用x-goog-api-key或?key查询参数模型名里用冒号分隔提供商与方法名例如:generateContent后缀。三种方言之外还有POST /v1/responsesOpenAI Responses API可用适合需要 function calling 回传的新客户端。✅ 验证方式与场景一相同任意方言收到 200 且内容非空。场景三一次检索整个知识库这个场景解决脚本里需要 RAG 检索但不想开 GUI。知识库走 Cherry 自有 REST 方言同样带 Bearer 鉴权# 列出全部知识库支持 offset/limit 分页 curl -s http://127.0.0.1:23333/v1/knowledge-bases -H Authorization: Bearer $CHERRY_KEY # 语义检索跨知识库召回相关切片喂给你自己的生成流程 curl -s http://127.0.0.1:23333/v1/knowledge-bases/search \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d {query:网关的鉴权机制是什么,limit:5} # MCP 工具目录列出所有活跃 MCP 服务器及其网关地址 curl -s http://127.0.0.1:23333/v1/mcps -H Authorization: Bearer $CHERRY_KEYMCP 服务器支持 Streamable HTTP 代理POST /v1/mcps/:id/mcp脚本可以直接对网关发起 JSON-RPC 调用拿到预热好的工具目录。✅ 验证方法search 返回的命中列表里包含切片文本与相关度分数。场景四批量任务脚本化这个场景解决重复 20 次的操作。下面是一个可直接保存为summarize.sh的批量摘要脚本演示遍历输入 → 调网关 → 落盘结果的完整闭环#!/usr/bin/env bash # 批量摘要遍历 docs/ 下所有 .md经 Cherry Studio 网关生成摘要 set -euo pipefail BASEhttp://127.0.0.1:23333/v1 # 网关地址改这里即可指向别的实例 MODEL${CHERRY_MODEL:-openai:gpt-4o} # 模型可环境变量覆盖 OUT./summaries; mkdir -p $OUT for f in $; do # 用 jq 安全构造 JSON避免文档里的引号/换行把请求体打坏 body$(jq -n --arg m $MODEL --arg c $(cat $f) \ {model:$m,stream:false,messages:[{role:user,content:(请用一句话总结\n$c)}]}) # -m 300 防止单次调用挂死拖垮整个批次 if curl -s -m 300 $BASE/chat/completions \ -H Authorization: Bearer $CHERRY_KEY -H Content-Type: application/json \ -d $body | jq -r .choices[0].message.content $OUT/$(basename $f .md).txt; then echo ✅ $f else echo ❌ $f fi done上图是网关的核心工作链路请求进来先过鉴权输入被翻译成内部统一消息格式由与 GUI 完全相同的AiStreamManager引擎驱动生成再翻译回你的方言输出。理解这条链路后任何流式断了超时了的问题都能定位到具体环节。生产级落地systemd 托管 健康检查目标是让配置好模型的服务像基础设施一样稳定运行开机自启、挂了自动拉起、定时探活报警。第 1 步确认打包版安装路径并确认网关随应用自启。# 查看打包版可执行文件位置按你的安装方式调整 which cherry-studio || ls /opt/cherry-studio/cherry-studio # 前提设置界面里 API Gateway 已开启启动时自动开启 # 应用主进程会依据持久化的 feature.api_gateway.enabled 意图自动拉起网关第 2 步交给 systemd 托管进程崩溃自动重启。sudo tee /etc/systemd/system/cherry-studio.service /dev/null EOF [Unit] DescriptionCherry Studio内置 AI 网关宿主 Afternetwork.target [Service] # 替换为你第 1 步查到的可执行文件绝对路径 ExecStart/opt/cherry-studio/cherry-studio Restarton-failure RestartSec5 [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload # 让 systemd 加载新单元文件 sudo systemctl enable --now cherry-studio systemctl status cherry-studio --no-pager # 预期 active (running)第 3 步部署定时健康检查不健康时主动告警。# 探活脚本/health 是免鉴权端点专为无人值守探测设计 sudo tee /usr/local/bin/cherry-health.sh /dev/null EOF #!/usr/bin/env bash curl -sf -m 5 http://127.0.0.1:23333/health /dev/null \ || { echo [ALERT] $(date %F %T) Cherry Studio 网关无响应 /var/log/cherry-health.log; } EOF sudo chmod x /usr/local/bin/cherry-health.sh # crontab -e 追加每 5 分钟探一次 echo */5 * * * * /usr/local/bin/cherry-health.sh | crontab -✅ 验证链路systemctl status显示 activecurl /health返回 ok故意systemctl stop后 5 分钟内告警文件新增一条记录。性能与行为调优决策表参数 → 改法 → 预期效果你遇到的情况调整项预期效果局域网内其他机器也要调用设置界面把 host 从127.0.0.1改为0.0.0.0网关接受远程连接注意同步收紧防火墙23333 端口被占用设置界面改 port1000–65535换端口后原脚本改 BASE 地址即可担心 Key 泄露设置界面点重新生成换新 Key旧 Key 立即失效timing-safe 比对旧值不再匹配长回答被中途判定失败了解 20 分钟流空闲超时模型思考时间超过 20 分钟无 token 才触发正常流式不受影响停网关时 MCP 会话残留了解 stop 行为先关会话再关 HTTP网关停止时所有 MCP 会话被强制终结不会泄漏到下次启动避坑手册五个高频现场1. 401 Unauthorized现象所有/v1/*请求都返回 401。 根因漏带鉴权头或用了?key这种 Gemini 风格该风格仅/v1beta路径有效。 修复curl -s http://127.0.0.1:23333/v1/models -H Authorization: Bearer $CHERRY_KEY2. 403 Forbidden现象头带了Key 也复制了仍然 403。 根因Key 与网关当前生效的feature.api_gateway.api_key不一致——重新生成过 Key 但脚本里还是旧的。 修复从设置界面复制最新 Key 更新脚本或curl -s http://127.0.0.1:23333/v1/models -H x-api-key: $CHERRY_KEY交叉验证。3. 启动报 EADDRINUSE / 端口冲突现象网关启动失败日志里出现端口占用错误。 根因23333 已被本机上另一个进程或上一次没退干净的实例占用。 修复ss -lntp | grep 23333定位占用进程或改端口后在设置里重启网关。4. 模型 404 / 模型不存在现象请求 400 或model not found。 根因model字段漏了提供商前缀写了gpt-4o而不是openai:gpt-4o。 修复curl -s $OPENAI_BASE_URL/models -H Authorization: Bearer $CHERRY_KEY取真实 ID 列表。5. 期待一个cherry-studio可执行命令现象照着别的教程敲cherry-studio start命令不存在。 根因v1 时代的 CLI 安装路径v1.cli.install已退役当前版本没有独立 CLI 二进制命令行面就是内置 HTTP 网关。 修复把cherry-studio start/stop的心智替换成启动应用 启动网关宿主操作全部走 curl仓库内 docs/references/api-gateway/README.md 是权威接口文档。下一步把网关包成团队内部 API给同事一段设置OPENAI_BASE_URL的 onboarding 脚本——curl -s http://127.0.0.1:23333/openapi/json直接导出完整 OpenAPI 规范丢进任何代码生成工具。给 CI 加一步冒烟测试上面第 3 步的cherry-health.sh改造成 CI job失败即阻断流水线。参与贡献本地pnpm ci:basic-check跑通静态检查再pnpm ci:test-check跑全量测试为 docs/contrib/development.md 描述的开发流程贡献一个 PR。命令行带来的自由度就藏在这些可以被脚本驯服的 HTTP 响应里。下次发版前先看看它又学会了什么curl -s http://127.0.0.1:23333/health | jq .version【免费下载链接】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），仅供参考