先看错误信息
获取模型列表失败 / fetch models failedCherry Studio fetch models failed 先查看模型列表请求的状态码，分别排查鉴权、根地址、代理和列表接口。手动添加准确模型只能替代列表发现步骤；仍需单独验证真实聊天，不能修复无效 Key。
正在打开页面…
正在加载内容，请稍候。
- 保留现场
记录状态码、错误正文和请求时间
- 缩小范围
按下方检查项逐个排除，不同时修改多项
- 最小复测
用同一请求验证，再回到原工具测试
选出你的现象，查看下一步
只需选择错误类型，无需粘贴密钥或完整日志。本页不会发送 API 请求，也不会自动判定连接成功。
先取得错误详情，暂时不能确定原因
- 展开错误详情，记录时间、HTTP 状态、错误码和最终请求路径。不要只截最外层提示。
- 核对服务商协议、模型 ID、API 地址；然后按对应教程进行同条件终端检查。
先完成下方最小请求检查。列表成功只证明列表可读取；对话还需返回真实回答，并核对同时间、同模型的请求日志。
检查 Base URL 并生成本机验证命令记录仅在浏览器中生成；下载后可补充脱敏结果，便于对照复测或提交客服。
常见表现
- 点获取模型列表后提示失败或显示空列表
- 手动添加模型后可以聊天，但自动获取失败
- 返回 401、404 或 Failed to fetch
这个报错是什么意思
获取模型列表通常读取服务商的 models 接口，没有发送对话。401 表示需要检查令牌；404 需要核对实际请求路径或列表支持情况；只有网络错误时才优先检查 DNS、TLS 与代理。不能把所有失败都归因于模型离线。
先判断是哪一类问题
对照请求链路定位失败阶段
判断 01
先记下 Cherry Studio 版本、当前 Provider 类型、启用的 Key 与模型 ID，再保留错误中的实际 URL、HTTP 状态码和脱敏正文。历史记录为 2026-09-28 本机安装信息核对到 1.9.12；2026-10-23 重新核对官方文档与 v2.1.7 发布，未安装新版本或完成客户端付费对话，菜单以自己的版本为准。
判断 02
把失败位置分成五步：获取列表 → 将模型加入当前提供商 → 启用提供商 → 在会话中选中模型 → 收到真实回复。列表已返回但会话没有模型时，先看加入与启用状态，不要继续更换 Key；列表请求失败则先按状态码修复。
判断 03
已有终端结果时，对照同一个服务商、同一个 Key 和同一个模型。终端列表成功、客户端失败，才继续查客户端最终 URL、Provider 模板和代理。没有终端记录时，不能直接得出“API 正常、客户端有问题”的结论。
判断 04
GET 列表、连接检测和 POST 对话分别记录结果。若配置了多个 Key，确认本次检测使用哪个 Key；一个 Key 成功不能代表其他轮询 Key 也有权限。知识库的 Embedding 与 Agent 所需协议另外核对。
按顺序修复
01
设置 → 模型服务，核对当前 Provider 的协议类型。
02
核对实际 URL：apizt OpenAI 兼容列表请求应为 https://api.apizt.com/v1/models。
03
按 401 / 404 / 网络错误分支修复，保存配置后重新获取。
04
服务商明确不支持列表时，手动添加控制台中的完整模型 ID，再点击检测。
详细修复步骤
Step 01
先区分对话、嵌入与 Agent
2026-10-23 核对官方模型服务文档：OpenAI、Anthropic、Gemini 的 Provider 模板对应不同协议，Cherry Agent 需要 Anthropic 兼容类型。列表中看见模型不代表它支持 Embedding 或 Agent；先跑通所选协议的短文本，再分别验证向量与工具任务。不要为了获得模型列表而换成与真实接口不匹配的模板。
Step 02
1. 核对服务商与最终 URL
进入设置 → 模型服务 → 当前服务商，核对实际提供的协议。OpenAI 兼容列表通常是 GET /v1/models，对话是 POST /v1/chat/completions；以客户端最终请求为准，避免 /v1/v1/models 或把完整对话路径填入基础地址。本站主站示例使用 api.apizt.com，现有 Cherry 图文教程使用 api.apizt.com；两个入口的适用范围本次未调用确认，请按自己控制台的当前说明取值，不把域名差异直接判成失效。
Step 03
2. 根据响应修复，保留原始错误
401 先查 Key 是否属于该服务商、复制是否完整、是否撤销；403 查当前令牌权限；404 同时看错误正文，区分列表路径、重复 /v1 与服务商未实现列表。只有超时或 Failed to fetch 等无有效 HTTP 响应时，才优先比较终端与客户端的 DNS、TLS、系统时间和代理；保留证书校验。手动添加模型不能绕过认证错误。
Step 04
3. 列表返回后，把模型加入并启用
获取到列表后，将需要的准确 API 模型 ID 加入当前提供商，再确认提供商处于启用状态。显示名称可以不同，实际 ID 必须与服务商授权一致。回到新会话，重新选择该提供商下的模型；设置页出现条目、提供商已启用与当前会话选中是三个不同状态。若提示 model not found，转查模型 ID 与授权，不再把它当成列表发现失败。
Step 05
4. 只有列表不支持时才手动添加
服务商明确不提供列表接口，或已确认该模型的对话端点可用而列表未收录时，从服务商目录复制准确 ID 手动添加，保存、启用并在新会话选中。保留列表失败的状态与原因；手填 ID 仅替代模型发现，不会补齐余额、权限、模型能力或协议。
Step 06
5. 用一次短对话确认已修好
先只保留一个明确的 Provider、Key 和模型，发送“只回复 OK”。收到有效回复后，在对应服务商的请求记录中核对时间与实际模型；只看到检测通过或 HTTP 200 不足以确认。检测和对话可能产生 API 用量，执行前查看当前模型价格与自己的可用额度。文本通过后再分别恢复附件、知识库或 Agent，本页没有执行这些客户端付费操作。
正确配置
curl --connect-timeout 10 --max-time 30 -i \
https://api.apizt.com/v1/models \
-H "Authorization: Bearer $tokenba_API_KEY"常见原因
- 选错 OpenAI / Anthropic / Gemini 服务商类型
- 重复拼接 /v1，或误填完整 chat/completions 路径
- 令牌不可用或没有所需模型权限
- 服务商未实现模型列表接口，或网络连接失败
不要这样填
API 地址：https://www.apizt.com
或：https://api.apizt.com/v1/chat/completions
上述网址不能直接作为 SDK Base URL。怎么确认已经修好
- 保留列表请求的最终 URL、状态码和脱敏错误；若接口不提供列表，明确记录该原因。
- 目标模型已加入正确 Provider，Provider 已启用；新会话显示选中了这个 Provider 和准确模型 ID。
- 发送一次短消息并收到有效回答，核对服务商记录中的时间与模型；只完成配置或检测时记为“对话待验证”。
- 图片、Embedding、Agent 分开验证；没有实际运行的功能不要勾选通过。
避免下次再报错
- 记录工具版本、服务商类型、模型 ID 与请求时间；升级后重新核对界面。
- API Key 只放本地设置或环境变量，截图与日志隐藏完整密钥。
- 配置多个 Key 时逐个核对授权，修改模型后在新会话重新选择。切换域名、Provider 或协议一次只改一项，并保留上一次结果。
仍未解决？这样提供排查信息
记录报错时间、工具版本、模型 ID 和 HTTP 状态码，附上脱敏后的错误正文。
说明问题是否稳定复现，以及同一配置的最小请求是否成功。
可以提供请求 ID 或控制台日志编号，不要发送完整 API Key、密码或个人业务数据。
先区分配置、权限、额度与上游服务问题；不要通过重复充值或高频重试来排查。
真实 401 响应与复现边界
- 2026-09-28 对 apizt GET /v1/models 发起不带 Authorization 的请求，返回 HTTP 401。
- 下方为实际响应脱敏版。令牌缺失时应修复认证，不应改模型名或关闭证书验证。
- 本机安装版本为 Cherry Studio 1.9.12，仅核对了安装信息，尚未完成客户端截图及付费对话测试；按本页步骤记录自己的最终 URL 和检测结果。
HTTP 401
{"error":{"message":"Token not provided (request id: [REDACTED])","type":"new_api_error"}}该记录验证网关的未认证响应，不代表客户端成功获取列表或完成对话。带令牌的 GET 列表与 POST 对话需分别验证。
Cherry Studio 官方模型服务设置Fetch models failed：先查 /v1/models，再检测对话
获取模型列表失败不等于模型不能聊天。apizt 的 OpenAI 兼容列表地址是 https://api.apizt.com/v1/models；按当前 Provider 的状态码修复，列表不支持时才手动添加准确模型 ID。
- 获取结果
- 401 / Unauthorized
- 直接处理
- 核对该 Provider 当前启用的 Key；多 Key 配置逐个检查
- 下一步验证
- 同一 Key 能读取列表或完成有权限的对话
- 获取结果
- 404，URL 含 /v1/v1 或聊天路径
- 直接处理
- 从 API 地址移除重复路径；自动补 /v1 的版本先填 https://api.apizt.com
- 下一步验证
- 最终 GET 地址只有一个 /v1/models
- 获取结果
- GET 200，但显示空列表
- 直接处理
- 查看响应是否为 JSON 与 data；核对 Key 的模型权限
- 下一步验证
- 出现有权限的准确 API 模型 ID
- 获取结果
- 终端成功，Cherry Studio 失败
- 直接处理
- 比较客户端最终 URL、Provider 类型与代理设置
- 下一步验证
- 客户端在同一 Provider 获取成功
- 获取结果
- 服务商明确不支持模型列表
- 直接处理
- 在当前 Provider 手动添加服务商确认的准确模型 ID
- 下一步验证
- 选该模型点击检测并取得回答
- 获取结果
- 获取成功，聊天界面看不到模型
- 直接处理
- 在模型管理中点 + 加入模型，再打开服务商右上角启用开关
- 下一步验证
- 聊天选择器能选中模型并回答
- 获取结果
- 配置多个 Key，成功与失败交替
- 直接处理
- 在密钥管理中逐个启用或指定检测 Key；记录当前 Provider 和实际 API ID
- 下一步验证
- 每个启用 Key 都有对应授权；一个 Key 的成功不能覆盖轮询中的其他 Key
- 获取结果
- 列表正常，知识库或 Agent 失败
- 直接处理
- 对话、Embedding 和 Cherry Agent 按各自 Provider 与协议分开设置
- 下一步验证
- 对话有回答、向量维度匹配、Agent 工具任务分别通过，不把 GET /models 当作全部验收
保留现有服务商，按顺序恢复
- 设置 → 模型服务 → 当前服务商，确认使用 OpenAI 兼容类型与 apizt Key。官方常规地址填根地址并由客户端补路径；不同版本以实际请求 URL 为准，勿把聊天完整端点固定为模型列表地址。
- 在同一电脑使用下方命令读取列表，记录状态码和脱敏正文。它读取模型目录，不发送推理请求。401 必须先修认证，不能当成“不支持列表”。
- 获取成功后点目标模型右侧的 +；核对实际 API ID，启用服务商。若确实没有列表接口，手动添加模型再检测。
- 选当前令牌分组支持的对话模型发送“只回复 OK”，核对客户端回答与控制台同时间、同模型的记录。知识库嵌入与 Cherry Agent 另按对应 Provider 和协议验证。
- 在检测按钮中明确选择 Key 与准确 API 模型 ID，再记录一条固定对话结果；知识库与 Agent 另建验收记录。2026-10-09 核对官方模型服务设置，模板与 API 报告没有验证当前 Cherry Studio 桌面客户端。
配置与验证示例
curl 只读取模型目录，不发送推理请求；不要把真实 Key 写入截图或公开代码。
curl --connect-timeout 10 --max-time 30 -i \
https://api.apizt.com/v1/models \
-H "Authorization: Bearer $tokenba_API_KEY"apizt 的 Cherry Studio 配置教程检查重复路径核对目标模型与接口创建 apizt API Key官方多 Key 管理与指定模型检测官方自定义服务商步骤查看固定任务的 API 验收记录与范围离线检查实际端点与请求/响应结构下载接入包、配置示例与空白任务记录
下载 MIT 接入包与任务记录表核验日期与验证范围见各页记录；历史实测保留原日期，示例和空白记录表不等于真实任务结果。
排查完成后，再开始接入
先按上文检查地址、鉴权与协议，并完成复测。确认要使用 apizt 后，再创建 API Key、选择模型并配置工具；充值不能修复配置错误。
创建 API Key
在控制台创建令牌，选择需要使用的模型权限。
填写接入配置
按工具要求填写 API Key、接口地址与模型 ID。
发起第一次调用
确认收到有效结果，再到控制台查看用量与费用。
FAQ
Cherry Studio fetch models failed 能手动添加模型吗？
若当前版本提供手动添加入口，可以填写目标服务授权的准确模型 ID。随后测试对话；手动列表不能绕过鉴权错误，也不能证明该模型在当前路由可用。
Cherry Studio 获取模型失败但聊天成功怎么办？
列表发现与聊天使用不同端点，分别核对 /models 与实际聊天路径、权限和返回格式。保存两次请求的状态与时间，避免把发现接口失败当作所有模型不可用。
列表拉取失败一定不能聊天吗？
不一定。服务商可能只实现对话接口；手动添加模型后独立验证。认证错误必须先修复。
API 地址末尾要加 /v1 吗？
apizt 的 OpenAI 兼容端点包含 /v1；客户端设置取决于它是否自动补路径，以实际 GET /v1/models 为准。
获取列表成功，为什么聊天里还是找不到模型？
依次确认模型已加入当前提供商、提供商已启用、当前会话已选中该模型。若实际请求返回 model not found，再核对准确 ID 与令牌权限。获取列表只完成发现阶段。
更换成 Chatbox 能直接解决这个错误吗？
不能保证。无效 Key、错误域名或模型权限会继续影响另一款客户端。先修复请求本身；只有需要比较会话组织、内置服务与 BYOK 工作方式时，再看 Cherry Studio 与 Chatbox 的选型页。