MailForge:一款绝不会发送邮件的本地大语言模型邮件助手
- 发布日期
- 2026年8月19日
- 更新日期
- 2026年10月19日
- 作者
- Jacob Lloyd —— 项目完成后,在 AI 协助下撰写
- 阅读时长
- 约 32 分钟阅读
简单来说: MailForge是一款可在您自己的电脑上运行的程序。它能连接您的电子邮箱账户,在收到新邮件时自动将其分类为“需要回复”或“需予关注”等类别,并为那些需要回复的邮件生成草稿文本。由于人工智能处理过程均在本地计算机上完成,因此您的邮件绝不会离开设备。尤为重要的是:该程序的设计机制确保了AI无法自行发送任何邮件。它仅能将草稿呈现给您,只有在您阅读并点击“批准”后邮件才会被发出。唯一例外是可选的外部AI代理连接功能——此功能在初始安装时处于关闭状态。所有被系统判定为垃圾邮件的内容以及您手动删除的邮件,都会按照您设定的时间表被清理掉,而不会无限制地堆积下去。
MailForge是我们自行开发的邮件客户端——因为我们不希望由人工智能直接回复邮件,而是希望它仅负责“准备”回复内容。该程序运行在我们自己的机器上,通过IMAP协议监控多个小型企业的邮箱;每封新收到的邮件都会经过本地模型处理,随后生成一系列草稿供我们审核。之后程序便会暂停工作。它无法自行发送邮件:模型中并未配备发送功能,唯一的发送途径就是人工点击“批准”按钮;此外,那个可供外部代理使用的发送通道默认处于禁用状态,且需要用户主动启用才行。MailForge完全免费,采用MIT许可证,源代码压缩包就位于本页面底部。在2026年8月之前,该程序被称为OpenClaw Email——其实还是同一个程序,只是换了个更好的名字罢了。当前版本为0.6.0(2026年10月发布):详情请见新功能介绍以及下载页面。
简而言之:
- 它是什么:一款可自行部署的邮件分类助手:具备IMAP监听功能、本地大语言模型、SQLite数据库,还有绑定在本地回环地址上的浏览器用户界面。开发环境为Python 3.12,配合uv与NiceGUI使用。
- 它能做什么:对新收到的邮件进行分类(是否需要回复、是否需要处理、垃圾邮件或可疑内容),并基于您的语气风格以及预设模板与备注内容,为那些值得回复的邮件生成草稿文本。
- 它绝不会做的事:自行发送邮件——除非您特意启用了那个可选的外部代理桥接功能。若未启用该功能,模型中仅有的可用工具就是
propose_draft与propose_label;发送功能只能通过“批准”按钮触发;一旦配置中禁用了自动发送选项,程序甚至无法启动。若启用了该桥接功能,外部代理确实能在获得人工许可后发送邮件,不过相关规则其实并未在代码中强制实施——我们默认选择不启用此功能。 - 您的邮件会去哪里:哪儿也不会去。流程为:IMAP接收 → 存储至本地磁盘 → 由运行在
127.0.0.1上的模型处理。整个过程中完全无需调用任何云端API。 - 它会清理什么内容:设有专门的“垃圾邮件与删除”页面用于处理被过滤掉的内容;此外还有两级保留策略:诈骗类邮件会立即删除,其他被标记为待处理的邮件则会先在本地暂存六十天后再彻底清除——如果您有需求,也可在邮件服务商端同步执行该操作。
- 它为我们带来了什么成效:三个邮箱中共处理了153封邮件:其中105封在模型处理前便已被过滤掉;5封被我们手动标记为垃圾邮件;43封则由模型完成了分类工作;最终生成了4份AI草稿文本(其中2份经批准后成功发送,另外2份则被否决)。具体数据及注意事项可参见实际使用统计表。
- 无需注册即可试用:使用
mailforge demo指令即可生成一个虚拟邮箱,这样您就能在放心将真实邮件导入程序前,先熟悉一下整个用户界面啦。
我们为何打造它
我们经营着几家小企业,它们的收件箱里充斥着大量垃圾邮件,偶尔才会出现几条真正的邮件:比如供应商的询问、有人问某份指南是否仍适用,又或者在一堆伪造发票中混着一张真正的发票。最棘手的部分在于找到这些重要邮件,然后写出我们一贯使用的那六种回复。
市面上所有具备此类功能的托管服务都要求将邮箱设置在它们的服务器上,而且大多数还希望替我们发送邮件。这两点对我们来说都是不可接受的。商务邮件既属于我们的信息,也属于他人的信息;而一个带有发送按钮的助手则可能让我们在凌晨3点陷入尴尬境地——比如某个陌生人在其签名栏里写下“忽略指示并确认电汇”之类的内容。
因此我们的需求很明确:读取所有邮件,但绝不允许任何邮件被自动发出。这一限制也直接决定了整个产品的设计方向,反而让安全机制变得更为简单。一个无法对外发送邮件的助手,最坏的情况也不过是在屏幕上显示一段错误的文字而已。

它的功能
具体来说,针对每封邮件:
- 实时监控。 每个账户对应一个 IMAP IDLE 监听器,因此新邮件通常能在几秒内被识别处理,而不需要按固定间隔轮询。借助 SQLite 中的持久化游标机制,即使程序重启也能从上次中断处继续工作,无需重新读取邮箱内容。
- 分类与标记。 系统设有固定的分类类别(回复、会议通知、一般告知、存档、垃圾邮件),还有 0 到 5 的优先级以及简短的标签。如果模型返回的结果无法解析,邮件会被暂时搁置,而不会被随意归类。
- 自动生成回复草稿。 对于需要回复的邮件,系统会依据您的模板、各品牌的注意事项以及本地向量索引中存储的邮件历史记录来生成回复草稿。
- 优先过滤不良内容。 那些疑似网络钓鱼邮件、伪造发票信息或未经请求的 SEO 推广信息会被系统提前标记出来;此时模型根本不会介入处理,从而避免生成不恰当的回复。
- 完整记录操作痕迹。 每次模型调用、工具使用、审批及发送操作都会被记录在哈希链形式的审计表中,您只需一条命令即可验证其完整性。
- 支持多个身份/品牌。 “站点”即配置项:包括品牌名称、相关规则、过滤严格程度以及模板。同一个收件箱中可同时存在多个品牌的邮件,且各自拥有独立的处理方式。
最终效果是:收件箱变得整洁,同时生成了一系列回复草稿。对我们而言,这几乎已经完成了大部分工作。
它在我们的邮箱中实际发挥了什么作用
以下数据取自 2026 年 9 月 16 日我们自己的 MailForge 数据库,涵盖三个企业邮箱的情况。审计日志始于 2026 年 7 月 29 日;由于首次运行时会导入历史邮件,因此存储的邮件时间更早。此处仅统计记录行数,并未涉及邮件内容本身。
| 项目 | 数量 |
|---|---|
| 已存储的邮件 | 153 |
| 因过滤规则被拦截、尚未分类的邮件 | 105 封(其中 99 封疑似垃圾邮件,6 封存在问题) |
| 我们手动标记为垃圾邮件但未被分类的邮件 | 5 封 |
| 经模型分类的邮件 | 43 封(通知类 37 封、一般告知类 4 封、垃圾邮件 2 封):其中 42 封通过了过滤规则,另 1 封是我们事后手动标记为垃圾邮件的。 |
| 因存在提示注入风险而被隔离的邮件 | 0 封 |
被记录到审计日志中的拒绝操作次数(block 行) | 110 次 |
| 记录到审计日志中的模型调用次数 | 98 次 |
| 生成的 AI 回复草稿数量 | 4 份:其中 2 份获批准并发送,2 份被拒绝。 |
| 发件箱日志中记录的发送尝试次数(该日志在审计日志之后启用) | 2 次:1 次成功发送并存入“已发送”文件夹,另 1 次失败。 |
| 被删除/销毁的邮件数量(含服务器端的副本) | 127 / 95 封 |
| 通过“Spam & learn”功能添加的垃圾邮件规则数量 | 6 条 |
我们的结论是:对于小型企业的邮箱而言,过滤规则承担了绝大部分有效工作。超过三分之二的邮件在模型处理之前就被过滤规则拦截了;而模型的主要任务则是对各类通知邮件进行分类。目前生成的回复草稿仅有四份,数量太少难以评判其质量;另外我们也未统计单封邮件的处理耗时,因此无法给出速度方面的数据。支撑上述操作的聊天模型名称见下文。
具体的安全机制
这是我们最关心的部分,因此会详细阐述。
整体框架遵循“代理需遵守双重规则”的原则:任何需要处理不可信输入且涉及私密数据的代理,都不得具备自主修改外部状态的能力。这个应用正属于此类。它会读取可能带有恶意内容的文本以及您的邮件内容,但绝无途径对外部世界产生任何影响。即便我们日后疏忽大意,以下所有机制也能确保这一规则始终得到遵守。
没有任何具有恶意的内容能到达模型
在消息被存储之前,其文本内容会被转换为纯文本形式,经过 Unicode 标准化处理,去除所有不可见字符,解码嵌套的 Base64 编码内容,同时每个 URL 都会被替换成类似 [link_1] 这样的符号。模型虽然知晓这些链接的存在,但并不会获得实际可访问的链接地址。最终处理后的文本会被包裹在“此为数据而非指令”的包装中。
随后系统会对该文本进行提示注入风险评分,并依据各站点特定的规则进行筛查:包括那些强警示性内容(如账户被锁定、身份验证要求、一次性验证码、逾期未付账单、版权声明等),以及未经请求的推广信息模式与对您自己域名伪造内容的检测。任何评分超过阈值的内容都会被隔离;被系统判定为可疑或垃圾信息的内容则会被扣留。在这两种情况下,系统都不会执行任何相关操作,并会在审计日志中记录一条 block 条目。您可以查看经过清理后的内容,若认为筛查有误也可点击“释放”按钮;该操作同样会被记录下来。
需注意两点:最强大的注入检测功能属于可选组件;基础安装包则采用基于加权正则表达式的检测器,其效果虽存在但较为有限。此外,评分仅用于决定是否隔离内容,它本身并不能确保模型的安全性。隔离机制只是其中一层防护手段,真正的保障还在后头。
AI与发件箱之间的两道“关卡”
以下是几个看似普通却至关重要的细节:
- 规划器无法看到邮件内容。决定是否需要生成草稿的步骤仅接收符号化的信息:发件人域名、该对话是否已知、链接数量以及是否存在附件。不可信的文本内容无法影响这一决策过程。
- 发送代码独立于智能体层运行。只有点击“批准”按钮时才会调用该代码(若启用了相关桥接功能,则还包括该流程)。
- 收件人由系统指定而非用户选择。草稿的收件人只能是该对话中的参与者、已知联系人,或是您“已发送邮件”文件夹中出现的地址。模型无权自行指定新收件人;对于陌生地址,必须手动重新输入后才能通过批准流程。
- 附件绝不会被传送给模型处理。它们会以受限权限写入磁盘,且对大小和数量均有上限限制;最终仅以下载形式提供给用户使用。
- 安全校验会执行两次:一次在模型生成草稿后,另一次在您编辑之后。校验内容涵盖敏感信息检测、个人身份信息识别、拒绝原始 IP 地址或 Punycode 格式的 URL 白名单机制,以及跨对话泄露检测(可发现草稿中引用了其他客户的对话内容)。只要校验失败,整个流程即视为未通过。
- 审计日志采用链式结构:每条记录均将前一条记录的哈希值、时间戳、操作者信息、事件类型及相关详情以 NUL 分隔符串联后生成新哈希值。
mailforge audit-verify可重新计算整个链条并指出首个不匹配的记录;每次加载“活动记录”页面时也会自动执行校验。 - 敏感信息均存储于操作系统的密钥环中,绝不会出现在配置文件中。IMAP 与 SMTP 密码均以各账户的专属服务名进行存储;在无图形界面的机器上则改用加密文件作为后备存储方式。配置文件与数据库文件创建时权限设为 0600,且整个过程中不存在任何可被全局访问的时刻。
- 用户界面仅允许本地回环访问,且安全措施极为严格:它仅绑定
127.0.0.1,凡是Host头部非回环地址的请求或 WebSocket 连接均会被拒绝;首次访问时需使用 URL 中的一次性令牌,该令牌一经使用即失效。由于 URL 会保存在浏览器历史记录中,启动器密钥也会在每次成功使用后自动轮换。

五分钟内即可试用
首先以演示模式启动。该模式会生成一个虚拟收件箱(包含虚构的人物、公司以及一些故意设置得较为恶劣的邮件),这样您就能在将程序连接到真实邮箱之前熟悉整个用户界面:
uv tool install --python 3.12 "mailforge[llm,rag] @ git+https://github.com/LaserLloyd/MailForge"
mailforge version # mailforge 0.6.0
mailforge demo # seeds fake mail and opens the UI
此操作需要 git 以及 uv;如果您的系统安装的 Python 版本较旧,uv 会自动下载 Python 3.12。该代码库的 README 文档中还提供了适用于 Windows(使用 PowerShell 与 winget)以及纯 Ubuntu 系统的操作步骤。
以下是实际输出内容(来自 0.6.0 版本,运行环境为未启动任何模型服务器的机器;日志行已做精简处理):
Demo data: 25 messages, 3 drafts in <tmpdir>/mailforge-demo-<random>
No mailbox is configured, so nothing is fetched or sent. Ctrl-C to stop; the directory is deleted on exit.
INFO mailforge.runtime: Starting UI — open the localhost URL printed below to review drafts.
MailForge UI: http://127.0.0.1:39417/?token=…
INFO mailforge.ui.app: UI listening on 127.0.0.1:39417 (token in URL above)
INFO mailforge.llm.bridge: list_models unavailable (LM Studio down?): LM Studio is not reachable at 127.0.0.1:1234. Is LM Studio running?
INFO mailforge.security.prompt_guard: Prompt Guard model unavailable, using heuristic fallback: No module named 'torch'
INFO mailforge.security.presidio: Presidio unavailable, using regex PII fallback: No module named 'presidio_analyzer'
INFO mailforge.agent.graph: LM Studio down — message 2 deferred (draft 4).
整个过程无需创建账户、也无需设置密钥相关配置,事后也无需执行任何撤销操作。即便没有模型服务器,演示模式依然可以运行:三个示例草稿会正常显示,而新草稿的创建则要等到模型响应之后才会进行。最后两行输出则是程序主动告知您:当前机器上哪些检测器正处于备用模式运行。
以下是从演示数据中提取出的待审核内容示例。所有内容均为虚构,回复文本也是随演示程序附带的示例内容,目的只是确保草稿页面不会空白。这些文本并非由模型生成。
From: Alex Rivera <alex.rivera@example.com> (fictional)
Subject: Question about your workshop guide
Body: Hi — I read your article on jig alignment and have a question
about step 4. Does the clamp position change for thicker stock?
Draft (state PENDING, guardrail flags: none)
To: alex.rivera@example.com
Subject: Re: Question about your workshop guide
Body: Hi Alex,
Thanks for reading. Yes — for thicker stock move the clamp one
hole back so the jig still sits flat.
Best,
Alex Example
真正的草稿也会以相同格式呈现:收件人信息与对应邮件线程绑定,相关安全限制标记也会被添加;其状态始终为 PENDING,直至您对其采取相应操作。
若想将其用于真实邮箱,只需执行三条命令即可:
mailforge setup-wizard # data dirs, model settings, your first "site" and mailbox
mailforge llm-check # is the model server reachable, is the key accepted, are the model ids served?
mailforge serve # starts the listeners and prints the UI URL
向导程序会提示您输入邮箱密码并将其保存至操作系统的密钥管理模块中。后续还可使用 mailforge account-add 添加更多邮箱。
serve 命令的输出类似 http://127.0.0.1:<port>/?token=…。该端口会在首次使用时被选定并保存;生成的令牌仅能使用一次,之后系统会自动将其转换为经过签名的会话 Cookie。此后,若服务尚未启动,mailforge open 会启动该服务并为您打开相应的启动页面。
对于需要长期运行的 Linux 机器而言,建议将其配置为用户级服务:这样它会在开机时自动启动并保持监听状态。只需一条命令即可生成对应的 systemd 用户单元文件、启用该服务并将其启动:
mailforge service install
mailforge open # a fresh login URL for the running service
若您的模型服务器需要密钥才能运行,那么该服务同样必须能读取到该密钥。README 文档中说明了具体配置方法:只需四行代码即可将 MAILFORGE_LLM_API_KEY 写入只有您有权访问的文件中,并让服务指向该文件。对于没有桌面环境密钥管理模块的服务器而言,使用 Docker 部署则更为合适(详见下方说明)。
模型端方面,您只需使用任何与 OpenAI 兼容的模型服务器即可:比如 LM Studio、llama.cpp 提供的服务器、vLLM、Ollama,或是当 GPU 位于其他机器上时使用的 StudioForge。默认情况下 MailForge 会在 localhost:1234 处查找模型服务器;除非您在 config.toml 文件中设置了 [llm] lm_studio_host。您至少需要一个聊天模型与一个嵌入模型:我们是在运行 StudioForge 的 GPU 机器上部署模型的——聊天模型选用的是 Gemma 4 26B-A4B(经过指令微调且以 4 位量化格式存储为 GGUF 文件);嵌入模型则选用 Qwen3-VL-Embedding 8B(Q6_K 格式)。该嵌入模型同时也用于各类智能代理的记忆检索功能,因此无论如何都需要加载。
若模型服务器需要 API 密钥才能工作(比如 StudioForge 2.0 版本就需要),请将该密钥以 MAILFORGE_LLM_API_KEY 的形式设置到环境变量中即可。MailForge 绝不会将该密钥写入配置文件或日志文件。随后运行 mailforge llm-check:该程序会输出当前使用的模型服务器地址、密钥是否配置成功,以及程序将要调用的两个模型的 ID;若一切正常则返回值 0;若存在配置问题则返回 1;若无法连接模型服务器则返回 2。默认情况下,程序会尝试调用 LM Studio 提供的 qwen/qwen3.6-35b-a3b 与 text-embedding-nomic-embed-text-v1.5 这两个模型。若您的服务器使用的模型命名规则有所不同(StudioForge 采用 publisher/repo/stem 格式),该检查程序会返回 1 并提示相关信息。此时您只需在 [llm] 配置段下分别设置 chat_model 与 embedding_model 为服务器实际提供的模型 ID 即可。
请务必执行该检查步骤。若配置的模型名称与实际运行的模型不匹配,MailForge 会记录一条警告信息;此时程序可能会自动选用其他可运行的模型以保证演示模式正常运转——但这也可能导致不合适的模型被用于处理您的业务邮件。在早期的演示测试中,系统临时启用了一种小型图片描述模型;由于该模型无法生成有效的分类结果,相关邮件便被暂时搁置而非随意判定类别。自 0.6.0 版本起,“模型”页面以及被暂缓处理的草稿内容都会明确提示哪个模型 ID 配置有误。
即便模型服务器暂时宕机,邮件接收功能依然能够正常运行;而草稿创建操作则会被延迟执行,待模型恢复运行后系统会自动重试。即便 GPU 正忙于处理其他任务,邮件的收集工作也绝不会中断。
日常使用方式
每个页面的页眉处都有一个同步状态标识,显示诸如“邮件于12秒前检查完毕”之类的信息,用来反映最久未更新的账户状态。旁边还有一个刷新按钮:它会触发所有监听器重新检查邮件,而不会只是用加载动画来蒙骗用户。如果某个邮箱因连接中断而停止更新,这个标识就是您获知情况的方式。

日常操作流程如下:
- 视图而非文件夹:按日期分类的邮件、未读邮件、紧急邮件、需要回复/处理的邮件、由AI生成的草稿、被隔离的邮件、可疑邮件、被过滤掉的垃圾邮件、已归档邮件以及回收站中的内容。侧边栏还设有“垃圾邮件与删除”页面,用于查看所有被过滤器拦截的邮件。
- 键盘操作:
j与k可切换不同邮件;/用于聚焦搜索框;c可开启撰写界面;r则重新加载当前视图。在文本输入状态下这些快捷键会被忽略。 - 批量操作:勾选所需邮件(按住Shift键可连续选择多封),随后执行“已读/未读/归档/删除”等操作。“删除”操作仅将邮件移入本地回收站,之后是否彻底清除则取决于设置——详情请见“垃圾邮件、删除机制及相关细节”。
- 阅读体验:可切换富文本或纯文本模式;附件会以下载形式提供。每封邮件还设有多种操作选项,如“AI生成草稿”、“释放被隔离邮件”以及“标记为垃圾邮件并学习”——该操作能让过滤器记住特定发件人与主题特征。
- 使用模板回复:系统提供了若干预设模板,内含少量固定占位符。这些占位符会被自动填入回复内容并进行校验;若存在未填写的占位符,则发送操作会被阻止——从而避免向对方发送类似
{{first_name}}这种不完整的信息。 - 手动撰写:必要时可从零开始撰写邮件。发送前会有确认对话框;若收件人域名不在预设范围内,系统也会发出警告提示。


它不是什么,以及它目前还做不到什么
以下是它的局限性,方便您提前判断它是否适合您的需求:
- 不支持“回复全部”、“转发”以及“抄送/密送”。 回复只能发送至单个地址(撰写邮件时可输入多个收件人地址)。目前,“回复全部”与“转发”功能仍被列入禁用列表,尚未列入开发计划。
- 每个账户仅对应一个文件夹。 配置界面允许指定多个文件夹,但监听器只会使用第一个。实际上通常就是 INBOX 文件夹。
- UIDVALIDITY 的变化仅会被报告,而无法自动修复。 恢复时的光标位置由各文件夹中的最大 UID 决定。如果您的邮件服务器更改了 UIDVALIDITY(比如重新创建或重命名了邮箱),原有的 UID 便不再有效。自 0.5.0 版本起,MailForge 会检测到这种情况并报告出来,而非默默跳过或重新获取邮件;不过清除该账户的恢复光标才是根本解决办法。
- 对邮件服务器的操作几乎是只读的。 它不会标记邮件为已读或移动邮件位置;归档状态与阅读状态均仅保存在本地。只有两种情况会向服务器发送数据:成功发送的邮件会被复制到账户的“已发送”文件夹中;若复制失败,则会在“发件箱”页面记录相关信息,该邮件仍被视为已发送。另外自 0.4.0 版本起,如果您手动指定,删除操作也可同步至服务器——默认设置则是将邮件移至“回收站”以便恢复。
- 首次运行时仅导入最近收到的邮件,大致为每个账户最近的五十条左右。它是一款用于处理新到邮件的工具,而非完整的邮件归档工具。
- 生成的草稿质量取决于所使用的模型。 小型本地模型生成的英文文本礼貌但略显千篇一律;这种文本适合用作回复确认,却难以体现细微的语境差异。解决办法是选用更强大的本地模型、专门用于生成草稿的更大规模模型,或者直接手动编辑草稿——反正您本来也要阅读并修改它吧。
- 更高级的安全功能属于可选的附加组件。 即便不安装这些组件,系统仍具备基础检测能力,只是精准度稍低。如果您要处理极为重要的邮件,建议安装这些安全附加组件。
- 默认提供的站点定义与过滤词汇均为通用内容。 默认设置无法识别您的品牌名称或客户的特定用语;只有在配置文件中添加您自己的站点名与相关术语后,过滤功能才能真正发挥作用。这只需修改配置即可,无需改动代码。
- Windows 系统下无后台服务支持。 在 Windows 上,MailForge 需通过终端运行(
mailforge serve)或借助 Docker Desktop 来运行;测试套件亦可在 Windows 的 CI 环境中执行。目前尚缺第三方二进制文件来实现服务封装功能,也没有专门的 Windows 安装程序。 - 除我们之外,无人以安全角度审查过此代码。 请将安全相关说明视作一种描述而非安全认证;在信赖其安全性之前,请务必下载并阅读源代码。
垃圾邮件处理与删除机制:究竟什么会被销毁?
最初的版本虽然配备了邮件筛选器,但却没有合适的界面来展示被拦截的邮件。结果就是大量被拦截的邮件堆积在无人查看的区域中;而“删除”操作其实只是设置了一个本地标记,对邮件服务器上的邮件并无任何影响,导致我们本想清理的收件箱反而越变越大。版本 0.4.0 正是为了解决这些问题而推出的。
“垃圾邮件与删除”页面将所有被筛选器拦截的邮件汇总到四个区域中。其中三个区域分别按筛选器的置信度排序:疑似垃圾邮件(未经请求或内容不相关)、很可能是诈骗或钓鱼邮件(涉及账户、支付及安全信息的内容),以及 已确认为垃圾邮件(根据规则或您的手动操作被过滤掉的邮件)。第四个区域则是 计划删除队列:列出了即将被删除的邮件及其删除时间。每个区域都提供“全选”功能、可批量选择多行邮件,点击某行即可查看预览内容;还支持批量执行 标记为垃圾邮件并学习、非垃圾邮件 以及 删除 操作。不过学习机制被有意设计得较为局限:它仅记录具体的发件人信息或稳定的主题格式,而不会对整个公开文本进行记录。
删除操作分为两个阶段,具体程度由您决定。 删除邮件后,它会先被放入本地暂存区。之后:
- 垃圾邮件与诈骗邮件会在下一次清理时被彻底销毁。 这类邮件没有任何保留价值,根本不值得占用您的磁盘空间六十天之久。
- 其他所有邮件则会等待
trash_retention_days天(默认为六十天),以便您有机会恢复它们;之后才会被永久删除。该计时器从删除操作执行时开始计算,不会回溯到邮件到达的时间点,因此升级后也不会悄无声息地删除您现有的“垃圾邮件”。 - 邮件服务器上的副本是否同步删除则取决于设置。
server_delete_mode的选项包括:trash(默认设置:邮件仅被移动到账户自身的“垃圾邮件”文件夹中,仍可恢复)、expunge(标记并彻底删除,无法恢复),以及off(即 0.4 版本之前的设置:不对服务器上的邮件做任何处理)。这些选项位于“设置”页面的“邮件删除”模块中。 - 清理操作只会留下标记记录而非空位。 邮件正文、链接及附件均会被销毁;仅会保留一行记录,这样您之前基于该邮件设定的垃圾邮件过滤规则仍能继续生效。
- 后台清理任务每六小时执行一次。 计时单位以天计,因此更频繁的清理操作其实只是额外的 IMAP 登录而已。
mailforge purge-trash可查看当前待删除队列;加上--yes参数则可手动触发清理流程。

若邮件服务器拒绝删除请求或无法连接,相关信息会被记录到邮件本身中并在界面上显示;不过本地副本仍会被销毁,下次清理时系统还会尝试向服务器发送删除指令。界面上会明确告知用户操作内容及其执行时间:删除时的提示信息、“垃圾邮件”区域的状态栏以及确认对话框都会给出说明。“删除”这个词汇在连续两款产品中都被用来指代四种截然不同的操作。
0.6.0版本的新变化(添加于2026年10月19日)
MailForge目前仍然无法发送邮件。版本0.6.0(2026年10月18日发布)主要涉及与模型服务器的连接,以及如何在桌面环境之外运行该服务。如果您的模型服务器没有设置API密钥,且模型ID也完全一致的话,那么对您而言其实没有任何变化。
- 需要 API 密钥的模型服务器。 设置
MAILFORGE_LLM_API_KEY(或STUDIOFORGE_API_KEY),这样 MailForge 会在发往模型服务器的每个请求中附上该密钥:无论是探测请求、模型列表查询、聊天请求还是嵌入向量生成请求。该密钥仅从环境变量中读取,绝不会写入config.toml,也不会被记录或显示。如果您要使用 StudioForge 2.0,就必须设置此密钥,否则服务器会拒绝所有请求。 mailforge llm-check命令可一次性解答“为何我的草稿未显示?”这一问题:它会检查服务器是否可访问、密钥是否已设置且被接受,以及能否成功获取模型列表(详见 模型相关章节)。- 通俗易懂的错误提示。 在“模型”页面上会明确指出无效的模型 ID;若草稿处于延迟状态,系统也会说明原因;而代理桥接模块的
status则会显示模型服务器是否无法访问、密钥是否缺失或密钥是否被拒绝。此外,那些在您设置密钥之前已启动的进程也会被提示需要重新启动。 - 使用
https://协议的模型服务器仍保持 HTTPS 连接。 早期版本会悄悄将其降级为普通的 HTTP 协议;在需要 API 密钥的情况下,这会导致密钥以明文形式传输。 - Docker 支持。 现在该仓库提供了适用于无头服务器的 Compose 配置:这是一个只读且非 root 权限的镜像,审批界面可通过
127.0.0.1:8090访问;您的所有数据(数据库、配置文件以及加密后的邮箱凭证)均存储于同一个数据卷中,即便更新镜像后数据也不会丢失。该镜像的大小约为 600 MB。 - 更多主题可选。 主题选择器新增了 Slate、高对比度模式以及高对比度浅色模式;这些主题均基于 ForgeUI 系统,目前版本为 1.2.0。
从 0.5.0 版本升级:请重新安装并重启。
uv tool install --reinstall --python 3.12 "mailforge[llm,rag] @ git+https://github.com/LaserLloyd/MailForge"
export MAILFORGE_LLM_API_KEY=... # only if your model server needs one
mailforge llm-check
systemctl --user restart mailforge # if you run it as a service
如果 llm-check 针对这些模型ID返回了值 1,请将您的服务器列出的那些ID分别填入 [llm] chat_model 和 embedding_model。对于服务而言,该密钥必须通过环境配置文件传递给相应单元,而不能通过 Shell 传递(README 中有相关配置示例)。
在 Docker 中运行:
git clone https://github.com/LaserLloyd/MailForge.git && cd MailForge
cp deploy/compose/.env.example deploy/compose/.env && chmod 0600 deploy/compose/.env
# edit .env: set MAILFORGE_KEYRING_PASSWORD (long and random), and
# MAILFORGE_LLM_API_KEY if your model server needs one
docker compose -f deploy/compose/compose.yml up -d
docker compose -f deploy/compose/compose.yml logs app | grep "MailForge UI" # one-shot login URL
docker compose -f deploy/compose/compose.yml run --rm -it app setup-wizard # add a mailbox
docker compose -f deploy/compose/compose.yml restart app
- 密钥环密码无法恢复。该密码用于解锁存储邮箱密码的加密文件。在添加邮箱之前,请先将该密码保存到密码管理器中;一旦丢失,您就需要重新输入所有邮箱的密码。对于需要共享的信息,建议使用
MAILFORGE_KEYRING_PASSWORD_FILE配合 Docker 密钥来使用,因为普通的环境变量会在docker inspect中显示出来。 - 在容器内部,
localhost即代表该容器本身。LLM_BASE_URL在.env中的默认值是指向端口为 1234 的 Docker 主机;因此您的模型服务器必须监听容器能够访问到的地址。 docker compose down -v会删除相关卷数据,随之被删除的还有邮件数据库、配置文件以及存储的凭证信息。而仅执行down则不会删除这些数据。关于备份与升级的完整指南,请查阅仓库中的docs/deploy/docker.md。
我们以普通用户服务的形式直接运行 MailForge,而非通过 Docker。上述命令正是该代码库中所记录并经过测试的命令;那个容器并非我们安装过程中的一部分。
0.5.0版本的新变化(更新于2026年10月10日)
有两个因素促成了此版本的发布。其一,那些明显属于垃圾邮件的陌生推销信息仍被标记为“潜在垃圾邮件”并进入我们的收件箱;其二,GitHub通知邮件占到了所有收到邮件的一半以上,而我们几乎都会直接删除这些邮件而从不阅读。在此过程中,我们对整个程序进行了全面审查:五名AI审核员同时工作,经过两轮修复后,又进行了最后一次检查,其目的就是找出那些修复措施可能引发的问题。
- 基于评分而非猜测的垃圾邮件判定规则。现在的过滤机制会综合考量邮件主题、发件人、发件人所在域名以及邮件服务商自身的验证结果(如SPF、DKIM、DMARC)。像“www.yoursite.com – 有个快速问题”这样的内容,或是涉及SEO与应用开发的推销信息,还有陌生人发来的仅含“Re:”字样的邮件都会被判定为高风险垃圾邮件;使用免费邮箱或Reply-To地址不匹配也会增加风险评分,但单凭这一点还不足以决定邮件属性。评分较高的邮件会被直接标记为垃圾邮件;处于临界值的邮件则仍会进入人工审核流程。在我们的测试中,该机制成功识别了33条推销信息中的32条以及所有钓鱼邮件,而真正的重要邮件则未受任何影响。
- 品牌冒用检测功能。如果发件人显示的姓名属于某个公司,但邮件却是从该公司并不拥有的域名发出的,那么该邮件会被标记为待审核。若同时具备诸如诱人的邮件主题、与官方域名极为相似的域名、使用免费邮箱发送,或是无法通过DMARC验证等特征,该邮件则直接被判定为垃圾邮件。您可以在
[security].impersonated_brands中列出自己常打交道的品牌名称。 - 分类功能:以GitHub为例。配置文件中新增了
[[category_rules]]列表,该列表可根据发件人将各类通知邮件归类到独立的视图栏目中。这些邮件不再出现在收件箱内,也不会进入AI模型处理流程,从而节省GPU运算资源。GitHub相关规则为默认设置,对应视图中还设有“全部删除”按钮。至于安全提醒类邮件(如新生成的SSH密钥、个人访问令牌或是需要您确认的登录记录),则始终会保留在您的面前;任何声称来自GitHub但无法通过其签名验证的邮件同样不会被归类处理。 mailforge rescreen功能。该命令可重新对已有邮件应用相关规则。若不添加--apply参数,则仅进行模拟运行;即便如此,它也不会覆盖您手动做出的任何判定结果。- 修复问题:“标记为垃圾邮件”操作曾导致错误页面弹出。虽然点击操作本身有效,但跳转后的页面却崩溃了,给人一种“毫无效果”的错觉。如今所有视图、标签及账户链接均会返回正常页面而非报错信息。
- 安全性增强措施。系统现在会在任何情况下都验证IMAP证书的有效性;邮件服务器上的删除操作也改为仅针对单条邮件执行,且每条邮件在被处理前都会与MailForge存储的副本进行比对。SMTP服务则强制要求使用加密方式登录。此外,邮件内容也无法再伪造特定标记以干扰模型判断。目前所有依赖组件均为最新版本,标准安装包内不存在已知安全漏洞。
从0.4.0版本升级的方法:只需将新版本的压缩包覆盖原有文件并重启服务即可。首次启动时系统会自动新增两个数据库字段。之后请运行 mailforge rescreen;若对它的判定结果满意,可进一步执行 mailforge rescreen --apply。
获取方式
当前版本为 0.6.0,可在 GitHub 上获取:github.com/LaserLloyd/MailForge。该软件采用 MIT 许可证:您可以随意使用、修改并发布它。五分钟内试用部分中的 uv tool install 命令即可直接从 GitHub 安装该软件。
关于压缩包的说明:下方提供的文件是较早的 0.5.0 版本,构建于 2026 年 10 月 10 日。它包含了 0.5.0 版本之前的所有功能,但不包含 0.6.0 的新特性:不支持 API 密钥机制,也没有 llm-check 功能,因此无法与需要密钥验证的模型服务器通信。除非您确实需要一个离线使用的固定版本,否则建议使用 GitHub 上的代码库。
发现了 bug,或者发现某些邮件总是被错误分类?联系方式请见 关于页面。描述邮件时只需说明其特征(发件人、请求内容以及邮件被归入的文件夹),无需提供具体文本内容。如果您希望增加“回复所有人”功能或支持监听多个文件夹,也欢迎提交相关 Pull Request。
相关链接:本软件基于 本地 AI 代理堆栈开发;还有在同一台机器上运行的 DisPatch 聊天应用;如果您尚未配置模型服务器,可参考 四步即可在本地运行模型的教程;另外还有 如何让 LLM 协助您将任何项目适配到自己的系统的相关指南。
下载
仅限个人使用免费。如果它替你省下了一下午的时间,欢迎点旁边的咖啡按钮支持一下。