Cherry Studio 接入 8848API：模型配置与日常使用

1. 准备令牌与一个可用模型

先登录控制台，在「令牌管理」创建单独用于此工具的令牌。检查有效期、额度、允许模型和访问限制；令牌不是网站登录密码，也不是厂商官方账号。

• 模型 ID：从当前账户可用列表复制完整名称，不用中文显示名或凭印象填写版本。列表可见不等于该模型支持每一种协议和工具功能。
• 预算：首次选一个已授权的模型，先进行一轮短对话。Agent 可能一项任务连续调用多轮；工具、附件、长历史和自动重试都会增加用量。
• 保护密钥：不要粘贴到聊天、截图、工单正文、公开项目或分享链接。日志和配置备份也按敏感文件保管。
• 已有配置：先用客户端自带导出/备份，或私下保存原配置，再合并新增条目；不要用教程整份覆盖已有服务商、MCP、项目或认证设置。

普通文字聊天优先选择兼容OpenAI Chat Completions的模型。看图、联网、知识库和工具调用是额外能力，不需要在首次接入时一次性打开。

当前Cherry官方地址规则使用站点根地址，客户端会追加聊天路径；不要将Codex的/v1配置机械照搬。若你选择的是其他原生协议，需另按该协议配置，不混用这一组字段。

2. 下载对应系统版本

从 Cherry Studio官方下载页选安装包，详细说明见 官方安装文档。

• Windows：按Intel/AMD与ARM架构选择，使用安装器完成安装。
• macOS：Apple芯片选择ARM64，Intel机器选择Intel包；按DMG引导移入应用程序。
• Linux：按发行版选择DEB/RPM或AppImage。AppImage若需要执行权限，只对确认来源的该文件授权，不批量放开目录权限。

系统阻止打开时先核安装包来源、签名和系统兼容性，不关闭系统安全保护来强行运行。首次使用先不启用MCP、Agent或本地API网关。

3. 新增服务商，填对地址

1. 打开「设置 → 模型服务」，选择「添加服务商」；不同版本也可能称「模型提供商」。
2. 名称填写8848API，类型选择OpenAI / OpenAI兼容，不把OpenAI Responses选项当成相同聊天协议。
3. API地址填写 https://api.884819.xyz，密钥框粘贴自己的平台令牌，不包含Bearer前缀、引号或额外空白。
4. 保存并启用服务商。添加条目与启用服务商是两个步骤，未启用时聊天模型列表可能不显示。
5. 先检查静态字段再使用「检测」；检测可能真正调用模型，需要先确认费用，不连续点击。

4. 获取或手工添加模型

1. 在8848API服务商内获取模型列表，或使用手工添加入口。
2. 手工添加时，模型ID粘贴账户当前可用的完整名称；显示名称可自定义，不能拿显示名称替代请求ID。
3. 按实际能力设置模型类型/标签。只有模型与渠道明确支持图片时才标记视觉；不要为“多功能”把所有能力开关全勾上。
4. 保存后到聊天界面的模型选择器，选择8848API服务商下刚添加的模型，不误用默认官方Provider。

拉取列表成功只说明相应列表请求通过，不能证明聊天、流式、看图或工具调用已经验收。模型没有出现在列表时先核令牌限制，不靠更换中文名称解决。

5. 从一轮普通对话开始

1. 新建普通助手/新话题，暂不加知识库、联网、MCP和附件。
2. 发送一轮短消息，例如“请只回复：连接成功”。
3. 确认文本完整返回，再在平台调用记录核时间、模型与用量。
4. 然后按需要测试多轮或一张非敏感参考图片；图片输入会增加用量，先确认所选模型支持。
5. 连接失败时保留错误正文和请求ID，不在同一时间同时改Key、地址和模型。

你填写在客户端的内容会按请求发送给平台及所用上游，避免用私人文件做第一次测试。静态教程页面本身不接收你的API Key。

6. 常用能力分别配置

助手与话题

助手用于整理角色和系统提示，话题保存上下文。长话题可能重复携带较多历史并增加费用；换任务可新建话题，但不要把新话题当作清除本地备份或云同步数据。

图片与附件

看图必须有视觉模型及渠道支持；文字模型不能靠勾选标签获得视觉能力。文件内容可能进入模型请求，上传前确认隐私与大小限制。

知识库与Embedding

知识库可能需要独立Embedding模型，不能把普通聊天模型ID直接当嵌入模型。导入、检索与重建索引可能产生额外请求，先核配置与费用。

联网、MCP与Agent

这些功能有各自的服务、权限和可能的外部费用，不会因API聊天接通而全部可用。先启用最少工具，不把API Key填写到不明插件。

本地API网关

普通聊天不需要开启它。需要给其他应用调用时再单独配置认证与监听；不要为了接入平台把本地服务暴露公网。

7. 常见问题

401 / 密钥无效

核令牌是否完整、启用、未过期、有额度且允许该模型；不要发完整Key给客服。重新复制后先保存，再受控验证。

404、HTML或路径重复

核当前OpenAI兼容Provider的地址为站点根，最终请求应是/v1/chat/completions，不出现/v1/v1。不要盲目切换多个特殊后缀。

看得到模型但发不了消息

核所选Provider与请求协议、账户权限和渠道状态。列表请求与生成请求不是同一验收。

文字能用，看图/工具报错

按模型能力和渠道支持分别查，先移除附件/工具做对照；不要把所有异常归为客户端安装损坏。

429或超时

停止连续检测，读具体限流/配额或超时信息，保留请求ID。未见回复不等于未收费，先看记录。

8. 备份、隐私和恢复

通过「设置 → 数据」等当前版本入口导出备份。完整备份可能包含API密钥和聊天记录，需加密离线保存；不发送给客服，不放公共仓库。不要声称本地存储天然加密。

要换Key时在对应Provider内更新并保存；旧Key如已泄露，先在平台停用。恢复备份前先保存当前新增内容，避免把之后的聊天和配置全部覆盖。

官方资料与核验边界

• 安装说明
• 官方下载
• 自定义服务商
• API地址规则
• 数据与备份

本文整理安装与配置方法，不代表所有客户端版本、模型、工具调用或远程功能均已实测。本次文档更新未发起付费模型请求；文中的模型验证、首次对话和自动化运行可能计费，请确认模型与预算后自行执行。