光谱AI 操作手册

SpectrAI 操作手册 v1.0.4 · 桌面端 · 第 10 章

#概述

本章汇总官网 FAQ、已知 Bug 页、反馈页与社区高频问题，优先解决“能不能继续用”和“该去哪里报错”这两件事。排查顺序建议是：先看现象，再核对设置，最后决定是本地修复、降级处理还是提交 Bug。

官网原始 FAQ 以安装、登录、会话、Provider、远程控制、性能、数据、升级 8 组为主。本章额外拆出“MCP 与工具”和“多 Agent 协同”，方便定位桌面端特有问题。

⚠️ 注意

遇到无法启动、数据库异常或疑似数据丢失时，先备份数据目录与日志，再做清理或回退。

#核心概念

诊断信息至少包含三项：版本号、报错码、日志。版本号看“设置 → 关于”，报错码优先记录 401、404、429 或启动错误文案，日志优先提供 main.log 片段。

降级处理遵循“先轻后重”：先清理缓存文件并重启，再回退旧版本，最后才备份并重建数据库。

联系支持适用于可稳定复现、升级后新增、或已影响数据安全的问题。提交时附“环境 + 重现步骤 + 期望 vs 实际 + 日志片段”。

#操作步骤：定位日志与上报 Bug

1. 打开主界面菜单“帮助 → 打开日志目录”，优先使用应用内入口定位日志。

1. 找到日志文件 main.log。
   • Windows：默认先检查 %APPDATA%\SpectrAI\logs\。
   • macOS：默认先检查 ~/Library/Logs/SpectrAI/。
   • 如果已经在 第 9 章 设置与快捷键 改过数据目录，以应用内实际打开的位置为准。

1. 打开“设置 → 关于”，记录完整版本号，并截取报错弹窗或异常界面。

1. 打开反馈页 https://claudeops.wbdao.cn/feedback.php，把问题类型、版本号和联系方式填写完整。

1. 按“环境 + 重现步骤 + 期望 vs 实际 + 日志片段”的模板提交；日志只贴关键片段。

#详细配置

本章不涉及独立设置项，相关配置见 第 9 章 设置与快捷键。

#常见问题

以下问答按安装、登录、会话、Provider 与 API、MCP 与工具、多 Agent 协同、远程控制、性能与稳定、数据与升级分组排列。

安装：为什么安装包损坏或被杀毒软件拦截？

只从官网重新下载，并校验文件大小。Windows 常见是误报或下载不完整，先加信任再安装。

安装：为什么 macOS 提示“无法打开应用”？

如果应用来自官方安装包，“已损坏”通常是 macOS 的安全拦截，不一定真是文件坏了。

按这个顺序处理：

1. 先确认来源。
   只处理官方安装包。
2. 移除隔离属性。
   打开终端执行：

sudo xattr -rd com.apple.quarantine /Applications/SpectrAI.app

如果应用不在这个路径，把命令里的路径换成实际路径。

1. 再试一次”右键打开”。
   先不要反复双击，右键应用选择”打开”；如果系统弹出确认，再允许一次。
2. 还被拦截时，到系统设置放行。
   打开”系统设置 → 隐私与安全性”，找到刚才被拦截的应用并点”仍要打开”。
3. 还提示损坏，再重新下载。
   这时再怀疑安装包不完整会更合理。

安装：为什么 Windows 会弹出 SmartScreen 警告？

先点“更多信息”核对发布者和版本，再决定是否继续。来源不是官网时不要放行。

安装：安装目录权限不足或卸载后仍有残留怎么办？

改用当前用户可写目录，或以管理员身份运行安装器。彻底清理前先备份用户数据目录。

登录：为什么收不到邮箱验证码或重置码失效？

先查垃圾邮件和邮箱拦截，再等 1 到 3 分钟后重发。重置流程以最后一次验证码为准，旧码会失效。

登录：为什么我找不到手机号验证码或微信扫码登录？

桌面端当前支持邮箱 + 密码登录（注册时用邮箱验证码验证），以及 GitHub、Google 两种第三方登录；不提供手机号验证码和微信扫码登录。旧截图里的入口不代表当前版本仍提供。

登录：如何退出登录或申请注销？

退出登录走“设置 → 账号”。需要停用或注销时，通过反馈页提交申请并附注册邮箱。

会话：会话长时间无响应怎么办？

先看顶部状态、终端输出和 Butler 提示；等待权限或人工确认不算卡死。几分钟无新增输出时结束当前轮并重试。

会话：编辑消息后上下文丢失或恢复后紊乱怎么办？

这是旧版本高频问题，当前版本已修复主要场景。先升级到最新版并重启，再避免在同一轮未结束时连续改历史消息。

会话：为什么搜索不到旧会话，或长会话越来越卡？

先清空关键词、标签和收藏筛选。旧版本检索与收藏分页有修复项；长会话建议整理结论后新开会话继续。

Provider：为什么会报 401 API Key 验证失败？

401 多半是 Key 无效、过期，或 Base URL 与 Key 不匹配。回到“设置 → Provider 与 API”重新粘贴并检查接口地址。

Provider：为什么会报 404 模型不存在？

模型名写错、区域未开通或当前接口不提供该模型都会触发 404。用模型列表或 Test 按钮先验证一次。

Provider：为什么会报 429 限额或频率超限？

先减少并发、超大附件和重复重试，再去服务商控制台看额度。内置 Provider 用量看“设置 → 账号”。

Provider：中国大陆访问外部 Provider 被屏蔽怎么办？

先配置代理再测试连接。代理入口和系统代理联动见 第 9 章 设置与快捷键。

Provider：CLI Provider 为什么启动失败？

先确认 CLI 已安装、已登录，且 node -v 满足要求；部分 CLI Provider 需要 Node.js v20+。多版本 Node.js 并存时优先修正 PATH。

Provider：内置 Provider 用完了怎么办？

查看“设置 → 账号”中的订阅与额度，再选择等待重置、升级订阅或切到自备 API 的 Provider。

Provider：为什么 Test 按钮一直转圈？

先保存配置并重新打开设置页测试。若最近改过 Provider，升级到最新版后重启，可避开旧缓存问题。

MCP：为什么 MCP 服务器启动失败？

内置 MCP 通常不依赖系统 Node.js。第三方 npx/npm MCP 仍可能受拉包慢、参数错或代理缺失影响。

工具：为什么工具调用超时或结果不显示？

先区分是“没启动”还是“执行慢”。前者看 MCP 状态，后者增加超时、减少大输入；恢复旧会话后异常时先升级到最新版。

Skill：为什么 Skill 安装失败？

先核对 GitHub 地址、子目录或 npm 包名，再看安装日志是否卡在下载依赖。国内网络下代理没配好时最常见。

多 Agent：Mission 为什么卡在某个阶段？

先看阶段条是否停在“头脑风暴”“任务拆解”或等待审批。Mission 模式部分阶段本来就要求人工确认。

多 Agent：子 Agent 失败后如何重试？

在 Team 或 Mission 面板里直接重试失败的子任务，不要整段重复发提示词。重试前先补齐缺失的权限、文件或 Provider 配置。

多 Agent：为什么不能追加指令，或 Teams 评分看起来异常？

当前轮执行、等工具权限或等子 Agent 返回时，Supervisor 模式会临时禁用追加输入。评分用于同轮相对比较；显示异常先升级并重新打开会话。

远程控制：手机扫码后为什么没有反应？

先确认“设置 → Cloud Relay”已连接，且二维码对应机器在线。管理员刚开通权限时，先到“设置 → 账号 → 账号管理”刷新状态。

远程控制：为什么 Telegram 推送收不到？

先主动给 Bot 发一条消息，再检查 Token、授权用户、事件开关和代理。国内网络未配代理时常会直接失败。

远程控制：为什么飞书验签或回调一直失败？

当前桌面端优先使用飞书机器人长连接模式，重点核对 App ID、App Secret、Encrypt Key 和 open_id 白名单。按旧 webhook 文档配置时请整套重配。

远程控制：为什么移动端推送会延迟？

保持桌面端在线，并检查 Cloud Relay 和手机网络。大量并发通知、弱网或系统省电都会放大延迟。

性能：应用启动很慢怎么办？

升级后的首次启动可能在做迁移、索引恢复或 Provider 初始化。若每次都慢，查看 main.log 是否在持续重试。

性能：内存占用高或文件树卡顿怎么办？

常见原因是超长会话、多个 Agent 并发、超大仓库或生成目录过多。结束空闲任务，并尽量只打开当前模块目录。

性能：GPU 占用异常或终端打字延迟怎么办？

先区分是整应用掉帧还是只有终端变慢。前者重启并更新显卡驱动，后者先关高频日志、实时预览和空闲远程面板。

数据：怀疑数据丢失时先查哪里？

先不要继续新建空会话。优先检查当前数据目录、旧 ClaudeOps 数据目录、claudeops.db 是否还在，以及日志里的迁移或数据库错误。

升级：升级后旧会话为什么不见了？

SpectrAI 会自动迁移旧 ClaudeOps 数据。看到空白列表时，先确认是否切到了新的自定义数据目录，或启动异常后误建了空数据库。

数据：如何跨设备同步，或卸载前保留数据？

当前桌面端以本地数据为主，跨设备请整体备份并迁移数据目录。卸载前至少保留 claudeops.db、attachments、logs 和 skills。

升级：如何退回旧版本或做最小重置？

先备份数据目录再回退版本。若只是启动异常，先删 claudeops.db-wal 和 claudeops.db-shm 重启；仍失败时再备份并移走 claudeops.db 验证。

#联系研发

提交前先准备版本号、截图、重现步骤和 main.log 关键片段，再选择入口：

• 反馈页：https://claudeops.wbdao.cn/feedback.php
• 已知 Bug 列表：https://claudeops.wbdao.cn/bugs.php
• 官方 FAQ：https://claudeops.wbdao.cn/faq.php
• 社区交流：以官网发布页公布的微信交流群为准
• 紧急通道：应用内“问题反馈”按钮

反馈模板建议固定为：“环境、重现步骤、期望结果、实际结果、日志片段、是否可稳定复现”。

#相关章节

• 第 4 章 多 Agent 协同：Butler 自动干预、Mission 模式和 Agent Teams 的基础行为说明。
• 第 5 章 工具与 MCP：MCP、Skill 与工具权限的安装和接入入口。
• 第 8 章 Provider 与 API：Provider 接入、API Key、Test 按钮与常见状态码排查。
• 第 9 章 设置与快捷键：代理、日志、数据目录、账号与远程控制设置的统一入口。