企业官网建设流程全解析

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 任务、其他程序都指向同一个本地地址，不再依赖窗口存在。

一句话：配置在界面里做，消费在终端里做。下面先跑通最小闭环。

五分钟跑通第一条命令

环境与依赖

仓库用 pnpm 管理工作区，Node 版本有硬性约束（package.json的 engines 字段）。

安装并启动

# 克隆仓库（只需一次），这是唯一的 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 路径为例）：

1. model：提供商:模型格式，冒号只按第一个拆分
2. stream：true走 SSE 流式，false等完整 JSON
3. temperature/top_p/max_tokens：采样参数随请求透传给后端模型
4. 鉴权：Authorization: Bearer（OpenAI/Gemini 路径）或x-api-key（Anthropic 路径）
5. 采样参数是"每次请求"级覆盖，不影响 GUI 里的任何设置

✅ 验证方法：响应 JSON 里choices[0].message.content非空，或 Anthropic 方言下content[0].text有值，即为成功。

场景二：按方言给现有客户端换"插座"

这个场景解决"我已经有代码/工具链了，不想重写"。答案通常是改一个环境变量：

# 让你的 OpenAI SDK 复用 Cherry 已配置好的所有 Provider export OPENAI_BASE_URL="http://127.0.0.1:23333/v1" export OPENAI_API_KEY="$CHERRY_KEY" # 验证：列出网关能转发的全部模型 curl -s $OPENAI_BASE_URL/models -H "Authorization: Bearer $CHERRY_KEY"

Gemini 方言走独立路径，鉴权用x-goog-api-key或?key=查询参数，模型名里用冒号分隔提供商与方法名，例如:generateContent后缀。三种方言之外，还有POST /v1/responses（OpenAI 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_KEY"

MCP 服务器支持 Streamable HTTP 代理（POST /v1/mcps/:id/mcp），脚本可以直接对网关发起 JSON-RPC 调用，拿到预热好的工具目录。✅ 验证方法：search 返回的命中列表里包含切片文本与相关度分数。

场景四：批量任务脚本化

这个场景解决"重复 20 次的操作"。下面是一个可直接保存为summarize.sh的批量摘要脚本，演示"遍历输入 → 调网关 → 落盘结果"的完整闭环：

#!/usr/bin/env bash # 批量摘要：遍历 docs/ 下所有 .md，经 Cherry Studio 网关生成摘要 set -euo pipefail BASE="http://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] Description=Cherry Studio（内置 AI 网关宿主） After=network.target [Service] # 替换为你第 1 步查到的可执行文件绝对路径 ExecStart=/opt/cherry-studio/cherry-studio Restart=on-failure RestartSec=5 [Install] WantedBy=multi-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显示 active，curl /health返回 ok，故意systemctl stop后 5 分钟内告警文件新增一条记录。

性能与行为调优决策表（参数 → 改法 → 预期效果）：

避坑手册：五个高频现场

1. 401 Unauthorized现象：所有/v1/*请求都返回 401。 根因：漏带鉴权头，或用了?key=这种 Gemini 风格（该风格仅/v1beta路径有效）。 修复：curl -s http://127.0.0.1:23333/v1/models -H "Authorization: Bearer $CHERRY_KEY"

2. 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 是权威接口文档。

下一步：

1. 把网关包成团队内部 API：给同事一段设置OPENAI_BASE_URL的 onboarding 脚本——curl -s http://127.0.0.1:23333/openapi/json直接导出完整 OpenAPI 规范，丢进任何代码生成工具。
2. 给 CI 加一步冒烟测试：上面第 3 步的cherry-health.sh改造成 CI job，失败即阻断流水线。
3. 参与贡献：本地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