Nmail 常见问题 FAQ
按主题分类的高频问题。没找到答案？到 GitHub Issues 搜索或提问。
安装与启动
Q：Windows 双击 exe 弹「已保护你的电脑」？ 未签名程序的正常提示：点「更多信息 → 仍要运行」。首次启动慢几秒是单文件自解压，属正常。
Q：macOS 提示”无法打开，因为无法验证开发者”？
右键 → 打开（不要直接双击）；或终端执行 xattr -dr com.apple.quarantine nmail-macos-arm64 后正常双击。
Q：端口 8720 被占用？ 程序会自动顺延端口并直接打开正确地址，无需手动处理；终端运行时以控制台打印为准。
Q：任务栏图标没变成 Nmail 图标？
Windows 图标缓存问题：把 exe 重命名一次，或运行 ie4uinit -show。
网络（Gmail/Outlook 连不上）
Q：Gmail/Outlook 一直转圈或报 10054/10060/10061？ 大陆网络直连 Google/微软 IMAP 被墙：开好你的代理工具即可——Nmail 自动跟随系统代理（代理工具开了「系统代理」就自动识别并走代理，和浏览器一致，无需任何设置；设置-通用 的状态行会实时显示当前通道）。注意代理工具须开启「系统代理」模式，不开的话 Nmail 和浏览器一样感知不到。所有账号统一生效；国内服务商（QQ/163/126 等）经代理也能正常用，本机服务（如 Proton Bridge）始终直连。
Q：授权登录后提示 authenticated but not connected？ 各邮箱网页版里 POP/IMAP 还没开。Outlook：设置 → 邮件 → 同步电子邮件 → 开启 POP/IMAP；Gmail：设置 → 转发和 POP/IMAP → 启用 IMAP。
Q：Gmail 授权页报 403 org_internal？ 自建 OAuth 客户端时「User Type」选了内部——改成外部，并在「测试用户」里加上你自己的邮箱。
邮箱授权码与密码
Q：添加账号提示登录失败？ QQ/163/126 等填的是授权码不是登录密码（设置里点「帮助」有各服务商获取路径）；Gmail 需要应用专用密码（开两步验证后生成）；Outlook 个人账号还需在网页版开启 POP/IMAP。
Q：账号显示「授权码可能已过期」？ 点账号卡片的编辑更新授权码；OAuth 授权的账号点「重新授权」。
AI 相关
Q：AI 功能全部报「AI 未配置或已停用」？ 设置-AI 配置：新增配置档案（Base URL + API Key + 模型名）并「测试连接」；若之前关过 AI 总开关，把它打开。
Q：API Key 明明没填错却 401？ 大概率是 key 在服务商平台侧已失效/被删（历史踩过 DeepSeek 平台侧删 key 的情况）——重新生成一个粘进来即可。设置页可点「测试连接」即时验证。
Q：AI 只分类不拟稿 / 不自动归档？ 检查账号的 AI 权限位（设置-邮箱账号-AI 权限）：「起草」没开就不会拟稿；自动归档只作用于被分类为营销的邮件。
Q：总管家里让 AI 发信，为什么总在等我批准？ 默认审批模式就是设计如此——发送永远由你拍板。确需自动发：建议设「AI 专属邮箱」或给账号开自动模式（有收件人白名单与每日限额约束）。
Q：想 100% 本地推理（数据不出机）？
Base URL 指向本地 Ollama / LM Studio 的 OpenAI 兼容端点即可（如 http://127.0.0.1:11434/v1），邮件数据零外发。
Q：总管家能帮我做哪些事？ 与人工操作对齐：查概况、搜索（分类/发件人/未读/日期组合过滤，覆盖含归档的全部文件夹）、读信总结、批量标记/归档/移动/删除、改分类、文件夹增删改名、起草/改草稿/定时/丢弃/发送、通讯录增删、白黑名单管理。账号凭据、AI 权限位、API 密钥不在工具清单里（防注入自我扩权）。完整清单见使用指南。
Q：界面上那些”失败：账号不在当前会话范围内”是怎么回事？ 会话范围守卫在正确拦截。若右上角选了某个账号，AI 只能操作该账号；若 AI 自己猜测了范围外的账号 id（比如单账号用户让它”总结各账号”），守卫会拒绝并如实告知。把范围切到”全部账号”（多账号时）或直接问实际账号即可。
Q：过程卡片/审批卡刷新后不见了？ 新版的执行过程与审批卡随会话持久化，需要页面加载新版前端——强刷一次（Cmd/Ctrl+Shift+R）。若看到英文 “executed” 状态或没有”批准后自动继续”，说明浏览器还在跑旧 bundle。
Q：批准之后 AI 怎么没下文了？ 批准/拒绝后 AI 会自动续跑并给总结（v0.4.x Agent 化行为）。没有下文说明页面/实例是旧版——强刷并确认只访问 8720 端口（重复启动会顺延到 8721，旧实例已停用）。
Q：AI 会乱动我的邮件吗？ 四层防线：①账号级 5 位授权（默认只给读+起草+整理，发送/删除要显式开）；②审批模式写操作逐条出卡、可改参数再批；③自动模式收件人白名单+禁附件+每日 ≤20 封/≤200 动作；④全量操作记录，移动/归档/标记/改分类一键撤销。
Q：AI 会记住我的偏好吗？ 会——跨会话记忆（v0.4.0）：你明说过的偏好与纠正（“汇报要简洁”“周报发给某某”）会存进本机记忆库，后续会话自动带上；设置-AI 用量-记忆 可查看/编辑/删除，数据不出本机。
Q：摘要页里「AI 摘要」和那些统计数字什么关系？ 统计部分（概况/图表/待回复/重要邮件）本地生成零 AI 成本，永远都在；「AI 摘要」是总管家真读邮件后写的当日要点与建议（页面底部独立区块），需要 AI。生成三路径：定时（设置开关）、摘要页按钮（可晚上重跑）、对话里说「重新生成 AI 摘要」。AI 摘要失败时自动回退纯统计摘要；通知中心可展开读全文。
Q：长任务跑到上限就断了？ 不会——步数/时间触顶时 AI 先给一段进度小结再暂停（做了什么、到哪一步、建议下一步），点「继续执行」接着跑；刷新后停在触顶态也会恢复继续入口。若它收尾时声称做了某事但记录里没有，系统会当场纠正它改口。
同步与邮件
Q：首次添加账号只同步了一部分邮件？ 首翻会先拉最新一页立即可用，随后后台自动全量回补：所有文件夹 × 全部历史，从新到旧分块补齐（账号状态里可见「回补」进度，中断/重启自动续传）。回补不跑 AI 分类、不发通知；收件箱同时随轮询持续增量。Gmail 的 All Mail 与收件箱重复，不在回补范围。
Q：邮件在网页版邮箱里被移走/删了，Nmail 里还在？ 本地是缓存：点开对应文件夹触发按需同步即对齐；被删邮件会在增量同步时清理。
Q：归档后邮件去哪了？ 真实移动到该账号服务器端的 Archived 文件夹——网页版邮箱同样可见；拖回任意文件夹即撤销。升级前「本地已归档」的旧邮件，应用会弹一次性迁移提示（可跳过）。
Q：Gmail 里移动邮件和别家不一样？
Gmail 的文件夹=标签：移动=加标签+撤出收件箱；删除=进 [Gmail]/Trash；All Mail 不订阅不同步（超大，树里置灰）。
数据与隐私
Q：数据存在哪？换电脑怎么迁移？
见 INSTALL.md「数据位置」：整个数据目录拷走即可（nmail.db + secrets.json + 附件）。
Q：升级会丢数据吗？ 不会。数据在独立目录，新版本首次启动自动跑数据库迁移；卸载重装也不动数据目录。
Q：会有遥测/上传我的邮件吗？ 不会。唯一的外呼是：① 你配置的 AI 端点（发邮件正文用于分类/摘要/起草，指到本地 Ollama 则零外发）② 24h 一次的匿名更新检查（只带 UA 版本号）。详见「隐私与安全」文档。
对外 API
Q：脚本报 403「对外 API 未启用」？
设置-API 打开总开关；再用 API Key 调用（X-Api-Key 请求头）。完整见对外API使用指南。
Q：429 Too Many Requests？ 限流 60 次/分钟或触达该 Key 的每日上限——脚本加间隔/退避重试，或调高上限。
发现问题？直接到 主仓 docs/ 改这篇文档（本页随构建自动更新）。