macOS 首次打不开
如果 macOS 阻止打开，请在 Finder 里右键 Mycel，选择「打开」。当前文档只承诺 Apple Silicon macOS 下载路径；Intel Mac 和 Windows 仍需要单独验证。
激活失败或离线
- 先确认邮箱和 license key 是否对应。
- 网络恢复后重新激活；离线状态有宽限期，但不要把宽限期当成永久离线授权。
- 需要换设备时，使用账号/激活界面的 deactivate 流程释放当前设备。
同步被关闭
同步相关命令已经在关闭同步时加了保护：关闭后不应该再继续同步索引或显示误导性状态。如果你仍看到同步状态异常，重启 Mycel 后再观察一次。
MCP 工具不可见
- 确认 Mycel 正在运行。
- 确认 MCP 客户端配置里的 binary 路径存在。
- 重启 agent 客户端，让它重新读取配置。
- 打开 Mycel 的 MCP 设置面板，查看客户端注册和 bridge 状态。
如果你用的是 Codex，请检查 TOML 配置；如果用的是 Claude Code 或其他通用 MCP 客户端，请检查对应 JSON 配置。Cursor CLI 的模型发现读取的是 .cursor/cli-config.json 已验证字段，不是泛称“任意 JSON”。
Agent 已显示，但模型列表不对
- 先区分是CLI 未安装、已安装但未登录、本地配置不存在，还是该 agent 不支持模型 flag。
- 当前只从 Codex、Claude Code、ZCode、Cursor CLI、Pi 这五类本地配置读取模型；其他 agent 即使可用，也可能只有默认模型入口。
- Claude Code、Codex、Cursor CLI、Hermes Agent、Pi 有已验证模型参数；不支持模型切换的 agent 在工作台里会禁用具体模型行。
- ZCode 只接受已验证的
{'{'} model: {'{'} main, lite {'}'} {'}'}配置形状；格式不符合时会被忽略，不会猜测字段含义。 - 模型目录为空不等于 MCP 工具不可用。先看 AI 工作台是否还能用默认模型工作，再回头修配置。
语义搜索没有结果
- 先确认库已经完成扫描。
- 向量搜索依赖本地嵌入与索引状态；刚打开大库时需要等待索引完成。
- 如果只想确认文件是否存在，先用普通搜索或文件列表。
手机捕获没进入库
- 同网本地页：确认手机能访问桌面端显示的地址。
- relay：确认 relay 地址、write token、drain token 匹配。
- iOS Shortcut：当前仍需要按仓库说明手动配置。
- Android share target：确认 PWA 已安装并从系统分享菜单进入。
Chrome 剪藏失败
先确认桌面端正在运行，再看扩展弹窗里的连接状态。本地 bridge 不可用时，扩展会把内容放进 outbox；恢复连接后再发送。
还没解决
把 Mycel 版本、系统版本、你正在使用的 agent 客户端、是否自托管 relay、复现步骤发到 silicoville@gmail.com X。
