尧图网站建设 
Cherry Studio 故障排查7 类高频报错的自查手册【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 是一个支持 300 助手、统一接入多家大模型LLM提供商的桌面 AI 客户端。它内置了一套日志扫描引擎自动识别常见报错、给出归属与处置方向。这份手册基于这套引擎的真实规则整理帮你遇到报错时先自查、再定位、后修复减少无效搜索。## 30 秒自检清单 先快速判断问题落在哪一类命中再跳对应小节 - [ ] 报错含 ECONNREFUSED / ECONNRESET / ENOTFOUND → 网络问题跳「连不上」 - [ ] 状态码 401 / 403 / 402 / 429 → 认证、额度、限流跳「认证与额度」 - [ ] 提示 prompt is too long / context_length_exceeded → 上下文超限跳「出不了结果」 - [ ] 提示 ENOSPC / no space left on device → 磁盘写满跳「环境报错」 - [ ] 提示 SQLITE_CORRUPT / database disk image is malformed → 本地数据库损坏跳「环境报错」 - [ ] 提示 MCP error -32000 / Connection closed → MCP 服务没起来跳「环境报错」Cherry Studio 里一条消息从界面到模型会经过渲染进程 → IPC → 主进程 AI 核心这条链路。报错基本都发生在这条链路上看懂图能帮你判断错误出在哪一层。## 报错速查表先对号入座 把日志里的那一行对照下表找处置动作。这是全文的索引锚点。 | 报错 / 日志关键词 | 可能原因 | 处置动作 | |---|---|---| | ECONNREFUSED / ERR_CONNECTION_REFUSED / socket hang up | 目标端点宕机或代理/防火墙拦截 | 检查端点地址、关代理或换网络 | | ENOTFOUND / EAI_AGAIN / ERR_NAME_NOT_RESOLVED | 本机离线或 DNS 解析失败 | 换网络、修 DNS、检查代理设置 | | ETIMEDOUT / fetch failed / UND_ERR_CONNECT_TIMEOUT | 请求超时多为瞬时或代理问题 | 重试、换网络、检查代理 | | ERR_CERT_* / SSL_ERROR_* / self-signed certificate | 公司代理或自签证书拦截 HTTPS | 换可信网络或在允许的环境加信任 | | HTTP 401 / HTTP 403 / invalid api key | 密钥缺失、无效或无模型权限 | 重新粘贴完整密钥确认模型可用 | | HTTP 402 / payment required / insufficient balance | 账户余额或额度不足 | 充值或补充额度 | | HTTP 429 / rate limit | 触发限流 | 降频重试或轮换密钥 | | model_not_found / no such model | 模型 id 不存在或端点不匹配 | 更新模型列表核对 id 与端点 | | prompt is too long / context_length_exceeded | 对话超出模型上下文窗口 | 清空上下文、开压缩、换更大模型 | | ENOSPC / no space left on device | 磁盘写满 | 清理磁盘空间后重试 | | SQLITE_CORRUPT / database disk image is malformed | 本地 SQLite 数据库损坏 | 从备份恢复不要直接删库 | | EPERM / EACCES | 文件系统权限被拒杀毒/只读目录 | 加白名单、换可写目录、提权 | | MCP error -32000 / Connection closed | MCP 服务命令缺失或崩溃 | 检查 MCP 命令与依赖是否可用 |## 连不上网络与代理排查 这一类报错的共同点请求根本没到服务端。 ### 症状 发送消息后无响应或弹窗里出现 ECONNREFUSED、ENOTFOUND、ETIMEDOUT、fetch failed 等。 ### 原因 分三种端点地址不可达ECONNREFUSED、本机断网或 DNS 解析失败ENOTFOUND / EAI_AGAIN、请求超时ETIMEDOUT。代理或防火墙是最常见诱因。 ### 解法 1. 先确认基础连通再判断是网络还是配置问题 bash # 检查目标 API 端点是否可达换成你实际使用的地址 curl -I https://api.openai.com返回正常但仍连不上 → 多半是代理/防火墙。关闭系统代理或切到直连重试。公司网络下出现ERR_CERT_*→ 是中间人拦截。换到可信网络再测避免随意信任自签证书。只有个别提供商失败、其余正常 → 通常是该提供商端点或密钥问题转「认证与额度」。注意出现fetch failed: HTTP 4xx时请求其实到达了服务器属于上游返回错误不是超时按对应状态码处理。认证与额度401 / 402 / 429 解决这一类说明请求到达了服务端但被拒绝。症状状态码401/403未授权/无权限、402欠费、429限流或invalid api key。原因401/403是密钥缺失、复制不全或密钥没有该模型的访问权限402是余额/额度/积分不足429是触发频率限制。解法401/403重新复制完整密钥注意首尾不要丢字符、不要多空格确认该密钥能访问你选的模型。402到对应服务商后台充值或补充额度再重试。429降低发送频率、稍后重试高并发场景可轮换多把密钥。若同一密钥在 A 模型能用、B 模型报403→ 是模型级权限问题换用有权的模型或找服务商开权限。状态码含义最快解法401密钥无效重贴完整密钥403无模型权限换有权模型402余额不足充值429限流降频重试出不了结果流中断、上下文超限与模型报错请求发出后「卡住」「断流」或报模型/参数错误都归这里。症状消息流到一半中断StreamError、提示prompt is too long/context_length_exceeded、或model_not_found/UnsupportedParamsError。原因StreamError多是网络或上游问题在下游的表现上下文超限是对话太长超出模型窗口model_not_found是模型 id 失效或端点配错UnsupportedParamsError是客户端发了该提供商不接受的参数如reasoning_effort、max_tokens、response_format。解法StreamError先按网络排查见上节多为瞬时重试即可。上下文超限清空上下文、开启压缩或换窗口更大的模型。model_not_found更新模型列表核对 id 是否与该端点匹配。UnsupportedParamsError属客户端兼容问题先升级客户端到最新版仍复现再提交 issue。一条消息在客户端内部的生命周期从输入到模型、再到 MCP / 知识库 / 网络搜索等工具最后回写。理解它能帮你判断「断」在哪一步。环境报错磁盘、权限与数据库损坏这一类与网络、密钥都无关问题在本机运行环境。症状ENOSPC/no space left on device、EPERM/EACCES、SQLITE_CORRUPT/database disk image is malformed、ERR_DLOPEN_FAILED或 MCP 报-32000 Connection closed。原因磁盘写满、文件系统权限被拒杀毒、只读目录、本地 SQLite 库损坏、原生模块与系统架构不匹配、MCP 命令缺失或崩溃。解法ENOSPC清理磁盘保证可用空间后再用。EPERM/EACCES把安装目录/数据目录加入杀毒白名单或换到可写目录。SQLITE_CORRUPT从备份恢复数据库不要直接删库以免丢失对话。ERR_DLOPEN_FAILED架构不匹配重新安装与系统x64/ARM一致的版本。MCP-32000确认该 MCP 命令可手动运行、依赖齐全再重启。想拿到更详细的运行日志可临时开启诊断默认关闭零开销它会写日志目录下的app.日期.log# Linux / macOS从终端启动让环境变量进入主进程 CS_DIAGNOSTICS1 ./Cherry\ Studio-* # 按你的安装路径调整还卡住这样求助提交 issue 前先把信息备齐能显著加快定位。版本客户端版本号设置页可见。系统操作系统与版本、CPU 架构x64 / ARM。日志片段出错的完整报错行 前后几行含时间戳已脱敏别贴真实密钥。复现步骤操作路径 期望/实际结果最好能稳定复现。按项目模板提交可对照 issue 模板字段填写问题模板.github/ISSUE_TEMPLATE/0_bug_report.yml诊断日志目录与CS_DIAGNOSTICS说明docs/references/diagnostics/README.md内置扫描规则本手册关键词来源src/main/services/diagnostics/scan/rules/把报错那一行先对上「报错速查表」再按对应小节的「症状 → 原因 → 解法」走一遍绝大多数问题都能自己解决。【免费下载链接】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 故障排查：7 类高频报错的自查手册
Cherry Studio 故障排查7 类高频报错的自查手册【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studioCherry Studio 是一个支持 300 助手、统一接入多家大模型LLM提供商的桌面 AI 客户端。它内置了一套日志扫描引擎自动识别常见报错、给出归属与处置方向。这份手册基于这套引擎的真实规则整理帮你遇到报错时先自查、再定位、后修复减少无效搜索。## 30 秒自检清单 先快速判断问题落在哪一类命中再跳对应小节 - [ ] 报错含 ECONNREFUSED / ECONNRESET / ENOTFOUND → 网络问题跳「连不上」 - [ ] 状态码 401 / 403 / 402 / 429 → 认证、额度、限流跳「认证与额度」 - [ ] 提示 prompt is too long / context_length_exceeded → 上下文超限跳「出不了结果」 - [ ] 提示 ENOSPC / no space left on device → 磁盘写满跳「环境报错」 - [ ] 提示 SQLITE_CORRUPT / database disk image is malformed → 本地数据库损坏跳「环境报错」 - [ ] 提示 MCP error -32000 / Connection closed → MCP 服务没起来跳「环境报错」Cherry Studio 里一条消息从界面到模型会经过渲染进程 → IPC → 主进程 AI 核心这条链路。报错基本都发生在这条链路上看懂图能帮你判断错误出在哪一层。## 报错速查表先对号入座 把日志里的那一行对照下表找处置动作。这是全文的索引锚点。 | 报错 / 日志关键词 | 可能原因 | 处置动作 | |---|---|---| | ECONNREFUSED / ERR_CONNECTION_REFUSED / socket hang up | 目标端点宕机或代理/防火墙拦截 | 检查端点地址、关代理或换网络 | | ENOTFOUND / EAI_AGAIN / ERR_NAME_NOT_RESOLVED | 本机离线或 DNS 解析失败 | 换网络、修 DNS、检查代理设置 | | ETIMEDOUT / fetch failed / UND_ERR_CONNECT_TIMEOUT | 请求超时多为瞬时或代理问题 | 重试、换网络、检查代理 | | ERR_CERT_* / SSL_ERROR_* / self-signed certificate | 公司代理或自签证书拦截 HTTPS | 换可信网络或在允许的环境加信任 | | HTTP 401 / HTTP 403 / invalid api key | 密钥缺失、无效或无模型权限 | 重新粘贴完整密钥确认模型可用 | | HTTP 402 / payment required / insufficient balance | 账户余额或额度不足 | 充值或补充额度 | | HTTP 429 / rate limit | 触发限流 | 降频重试或轮换密钥 | | model_not_found / no such model | 模型 id 不存在或端点不匹配 | 更新模型列表核对 id 与端点 | | prompt is too long / context_length_exceeded | 对话超出模型上下文窗口 | 清空上下文、开压缩、换更大模型 | | ENOSPC / no space left on device | 磁盘写满 | 清理磁盘空间后重试 | | SQLITE_CORRUPT / database disk image is malformed | 本地 SQLite 数据库损坏 | 从备份恢复不要直接删库 | | EPERM / EACCES | 文件系统权限被拒杀毒/只读目录 | 加白名单、换可写目录、提权 | | MCP error -32000 / Connection closed | MCP 服务命令缺失或崩溃 | 检查 MCP 命令与依赖是否可用 |## 连不上网络与代理排查 这一类报错的共同点请求根本没到服务端。 ### 症状 发送消息后无响应或弹窗里出现 ECONNREFUSED、ENOTFOUND、ETIMEDOUT、fetch failed 等。 ### 原因 分三种端点地址不可达ECONNREFUSED、本机断网或 DNS 解析失败ENOTFOUND / EAI_AGAIN、请求超时ETIMEDOUT。代理或防火墙是最常见诱因。 ### 解法 1. 先确认基础连通再判断是网络还是配置问题 bash # 检查目标 API 端点是否可达换成你实际使用的地址 curl -I https://api.openai.com返回正常但仍连不上 → 多半是代理/防火墙。关闭系统代理或切到直连重试。公司网络下出现ERR_CERT_*→ 是中间人拦截。换到可信网络再测避免随意信任自签证书。只有个别提供商失败、其余正常 → 通常是该提供商端点或密钥问题转「认证与额度」。注意出现fetch failed: HTTP 4xx时请求其实到达了服务器属于上游返回错误不是超时按对应状态码处理。认证与额度401 / 402 / 429 解决这一类说明请求到达了服务端但被拒绝。症状状态码401/403未授权/无权限、402欠费、429限流或invalid api key。原因401/403是密钥缺失、复制不全或密钥没有该模型的访问权限402是余额/额度/积分不足429是触发频率限制。解法401/403重新复制完整密钥注意首尾不要丢字符、不要多空格确认该密钥能访问你选的模型。402到对应服务商后台充值或补充额度再重试。429降低发送频率、稍后重试高并发场景可轮换多把密钥。若同一密钥在 A 模型能用、B 模型报403→ 是模型级权限问题换用有权的模型或找服务商开权限。状态码含义最快解法401密钥无效重贴完整密钥403无模型权限换有权模型402余额不足充值429限流降频重试出不了结果流中断、上下文超限与模型报错请求发出后「卡住」「断流」或报模型/参数错误都归这里。症状消息流到一半中断StreamError、提示prompt is too long/context_length_exceeded、或model_not_found/UnsupportedParamsError。原因StreamError多是网络或上游问题在下游的表现上下文超限是对话太长超出模型窗口model_not_found是模型 id 失效或端点配错UnsupportedParamsError是客户端发了该提供商不接受的参数如reasoning_effort、max_tokens、response_format。解法StreamError先按网络排查见上节多为瞬时重试即可。上下文超限清空上下文、开启压缩或换窗口更大的模型。model_not_found更新模型列表核对 id 是否与该端点匹配。UnsupportedParamsError属客户端兼容问题先升级客户端到最新版仍复现再提交 issue。一条消息在客户端内部的生命周期从输入到模型、再到 MCP / 知识库 / 网络搜索等工具最后回写。理解它能帮你判断「断」在哪一步。环境报错磁盘、权限与数据库损坏这一类与网络、密钥都无关问题在本机运行环境。症状ENOSPC/no space left on device、EPERM/EACCES、SQLITE_CORRUPT/database disk image is malformed、ERR_DLOPEN_FAILED或 MCP 报-32000 Connection closed。原因磁盘写满、文件系统权限被拒杀毒、只读目录、本地 SQLite 库损坏、原生模块与系统架构不匹配、MCP 命令缺失或崩溃。解法ENOSPC清理磁盘保证可用空间后再用。EPERM/EACCES把安装目录/数据目录加入杀毒白名单或换到可写目录。SQLITE_CORRUPT从备份恢复数据库不要直接删库以免丢失对话。ERR_DLOPEN_FAILED架构不匹配重新安装与系统x64/ARM一致的版本。MCP-32000确认该 MCP 命令可手动运行、依赖齐全再重启。想拿到更详细的运行日志可临时开启诊断默认关闭零开销它会写日志目录下的app.日期.log# Linux / macOS从终端启动让环境变量进入主进程 CS_DIAGNOSTICS1 ./Cherry\ Studio-* # 按你的安装路径调整还卡住这样求助提交 issue 前先把信息备齐能显著加快定位。版本客户端版本号设置页可见。系统操作系统与版本、CPU 架构x64 / ARM。日志片段出错的完整报错行 前后几行含时间戳已脱敏别贴真实密钥。复现步骤操作路径 期望/实际结果最好能稳定复现。按项目模板提交可对照 issue 模板字段填写问题模板.github/ISSUE_TEMPLATE/0_bug_report.yml诊断日志目录与CS_DIAGNOSTICS说明docs/references/diagnostics/README.md内置扫描规则本手册关键词来源src/main/services/diagnostics/scan/rules/把报错那一行先对上「报错速查表」再按对应小节的「症状 → 原因 → 解法」走一遍绝大多数问题都能自己解决。【免费下载链接】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），仅供参考