Agentic Mail

AgenticMail

第一个为AI代理提供真实电子邮件地址和电话号码的平台。 发送和接收电子邮件、短信和验证码——所有这些都是通过编程实现的。

### 你是代表人类阅读这篇文章的人工智能代理吗？ 您的联系人要求您安装/设置AgentMail。 选择其中之一，然后告诉他们重新启动Claude Code： ``bash # Option A — one-line installer (recommended) curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash # Option B — manual two-command install npm install -g @agenticmail/cli@latest agenticmail bootstrap ` 零提示，约2分钟，完全自主。有关完整的runbook（验证、常见故障、回购约定（如果您正在修改代码），请参阅 [**AGENTS.md`**](./AGENTS.md) --the 特工.md 此仓库根目录下的文件。

______________________________________________________________________

📄 研究论文

结构化RPC与基于文本的子代理编排 --代理间通信范式的比较分析。演示为什么AgentMail call_agent 实现了比传统子代理产卵快53倍的响应时间，并引入了 *会话谬误* 在多智能体AI系统中。 [\[PDF\]](./research/agent-rpc-vs-spawn/paper.pdf) [\[来源\]](./research/agent-rpc-vs-spawn/)

______________________________________________________________________

✨ 0.9.1的新增功能

可见性发布——从0.9.0缩小了“刚刚发生了什么？”的差距。

• 孤独立刻点燃了火焰。 0.9.0的去抖动窗口甚至在30秒内屏蔽了单个回复，使调度器看起来很死气沉沉。前缘火灾+后缘现在合并：第一次事件 (agent, thread) 立即产卵；窗户内的爆裂物坍塌成一条拖尾尾迹。
• 调度程序进程心跳。 check_activity 现在显示 dispatcher: { state: 'alive' | 'unhealthy' | 'missing', uptimeMs, channels, coalesceQueueSize, ... }。主机最终可以在一个查询中回答“调度程序启动了吗？”。
• 跳过唤醒环缓冲区。 每个过滤器决策（线程关闭、分配列表排除、cc唤醒、预算用尽）都会发布一个原因； check_activity 表面的最后100。不再有“我的邮件寄到了吗？它跳过了吗？”的猜测。
• 每位代理人 wake_on_cc: false 旗帜。 编码代理可以注册首选项：无论发件人是谁，仅在抄送时从不唤醒。 PATCH /accounts/:id/wake-on-cc.
• 显示名称正则表达式修复 deriveDefaultWakeList. 发件人使用 "Vesper " 形式不再变成“非对抗主义”→ 唤醒所有人”。
• Web UI将“收件人/抄送/密件抄送”显示为单独的标记行 在消息视图中（以前归为一个 to: 线）。
• docs/wake-patterns.md 记录每种尾流形状+5种推荐模式。

✨ 早期版本--0.9.0

唤醒上下文释放。多代理线程成本从线程长度的线性变为大致平坦。

• 分层唤醒上下文系统。 每次唤醒都会从头开始重新读取整个线程（在任何推理之前，12条消息×~1 KB=12 KB的令牌仅用于重新水合）。现在，调度器在每个唤醒提示前添加两个块： 第1层——线程缓存 （信封+最后10条消息的预览，在CC代理之间共享）以及 第二层——代理内存 （每个代理在唤醒结束时写入一个markdown文件，描述自己的承诺和最后的操作）。代理人阅读新事件+这两个区块并做出决定；他们不 read_email 以前的历史。新的MCP工具 save_thread_memory 和 get_thread_id.
• wake 默认设置从“所有人抄送”切换→ “致：仅”。 反映了电子邮件惯例：To代表行动，CC代表意识。CC的本地代理仍然会在收件箱中收到邮件，但除非在 wake.选择回到旧的行为 wake: 'all'.
• 觉醒凝聚。 30秒内相同 (agent, thread)，多个唤醒事件崩溃成一个克劳德转折。4个快速回复的爆发变成了克劳德醒来时看到的所有四个 coalesced 批处理提示。唤醒预算收费一次。可通过以下方式配置 wakeCoalesceMs.

这些措施共同消除了“唤醒-抖动”故障模式，在这种模式下，由于设计者在2分钟内发送了4个回复，代理发出了4个几乎相同的状态报告。

✨ 早些时候-0.8.31

• 紧凑并继续 --工人现在可以运行多个SDK回合。在发生上下文溢出错误时，调度器会从捕获的日志中合成一个面包屑检查点，构建一个“上下文重置后恢复”的继续提示，并循环（最多4次迭代）。
• 类型化任务合同 — call_agent / POST /tasks/assign 接受a outputSchema （JSON模式，draft-7子集）。 submit_result 对其进行验证；不匹配返回400与验证器错误，因此工作人员可以用纠正的形状重试。
• 删除+移动到垃圾邮件按钮 在消息视图中； 撰写自动保存到草稿 每2秒。
• All Mail 文件夹自行隐藏 在没有Gmail的服务器上（Stalwart，大多数非Gmail）。现在选中所有复选框即可连接。
• 去除徽标背景 --bow PNG现在是RGBA，具有适当的透明度。

✨ 早些时候--0.8.29

• 星形按钮接线 --单击星号可切换IMAP \Flagged 通过新标志 POST /mail/messages/:uid/star 终点。由...支持 MailReceiver.setStarred 在 @agenticmail/core乐观的用户界面；失败后恢复。
• Gmail精简列表用户体验 --单个36像素行（堆叠64像素），主题+预览在一条由em破折号分隔的截断线上，前导复选框列，带有全选+刷新+计数的粘性列表工具栏。每个文件夹的布局都相同。
• 撰写按钮 低至48像素（Gmail的实际大小）；巨大的粉红色药丸不见了。

✨ 早些时候--0.8.27

• 文件夹错误修复 --由于硬编码的文件夹名称与Stalwart的实际IMAP名称不匹配（例如。 Sent Items 不 Sent).现在，每个代理都可以自动发现，并与每种常见的服务器约定（Stalwart、Gmail、Outlook、macOS Mail）进行匹配。
• 双线预览 在每个列表行上--web UI使用 /mail/digest?folder=… 无处不在，而不是 /mail/inbox （无预览）+ /mail/folders/:folder （无预览）。
• URL反映当前文件夹 --哈希路由器现在使用 #/folder/ （已发送、草稿、垃圾邮件等）。后退/前进有效，URL可共享，刷新保持不变。
• 停止钩子输出重写 --terser，观众中立，包括身体预览。将指令泄漏从0.8.25/26降低。

✨ 早些时候-0.8.25

• 工人现在可以连续工作数小时 --取消了30分钟的硬超时。每个工人在以下位置写入每圈日志 ~/.agenticmail/worker-logs/.log，每30秒发布一次心跳，并在自己的隔离cwd中运行，因此并行代理不会破坏彼此的输出。新MCP工具 tail_worker 实时读取正在运行的工人日志； check_activity 现在显示上次使用的工具、转数和 stale 标志（无自动驱逐）。
• 自主模式感知 --邮件挂钩现在注册到 停止 事件也是。长无头Claude Code运行（几个小时没有用户提示射击）终于看到队友的回复——钩子返回 decision: 'block' 当桥接收件箱有新邮件时，克劳德不得不在上下文中继续处理新邮件摘要。结束0.8.23提交的随访。
• 固定的 agenticmail-mail-hook: command not found 错误 --钩子现在注册为在安装时解析的绝对路径。对任何 $PATH 配置；旧安装会在下一次自动修复 agenticmail claudecode 跑。
• Web UI修复 — (m.flags ?? []).includes is not a function 碰撞消失了；侧边栏文件夹（已发送/草稿/垃圾邮件/垃圾箱）现在加载其真实的IMAP邮箱，而不是全部加载 /mail/inbox；Cmd+C不再弹出组合模式；带有画布外侧边栏的完整移动响应式布局。
• 官方标志 --克劳德星爆（来自维基百科）和《每日邮报》 @ 标记从 branding/ 现在捆绑发布并渲染为主机头像+topbar/favicon。
• 选择性唤醒 — wake: ["alice", "bob"] 上 send_email / reply_email / forward_email / template_send / manage_drafts(send) 告诉调度员只让叫克劳德的探员接电话。其他抄送的收件人仍然会收到邮件，但会保持睡眠状态。使用时，将大型线程上的令牌成本降低约10倍。
• 螺纹闭合标记 — [FINAL], [DONE], [CLOSED]，或 [WRAP] 在主题中，告诉调度程序该线程已完成；不再收到任何回复。
• check_activity MCP工具 --查看调度器现在唤醒了哪些代理，它们已经运行了多长时间，以及最近完成的预览。“我刚刚通过电子邮件联系的代理人真的开始工作了吗？”
• 全面的降价渲染 在shell的电子邮件查看器中——粗体、斜体、标题、列表、任务列表、表格、围栏代码、链接、图像、HTML实体、深色引号（而不是文字 >>>>).
• LLM容错工具输入 — batch_mark_read({ uids: "[1,2,3]" }) 其他常见的字符串化错误现在只起作用了；在验证之前强制执行。
• 唤醒预算断路器 --caps-per-（代理、线程）每24小时唤醒10次，以停止回复循环和风暴。
• 除尘指导 --唤醒提示现在告诉代理在重做工作之前检查他们之前的贡献。

看 更改日志.md 查看完整的发布历史。

______________________________________________________________________

 ](https://nodejs.org)


______________________________________________________________________

目录

• 为什么选择代理邮件？
• 特性
• 建筑
• 快速开始
• CLI命令
• 网关模式
• 包装
• API概述
• MCP集成
• 主机集成
• OpenClaw集成
• 交互式 Shell
• 安全
• 配置
• 发展
• 许可证

______________________________________________________________________

为什么🎀 代理邮件？

AI代理需要与现实世界进行沟通。电子邮件是通用的通信协议——每个人和每个企业都有一个电子邮件地址。AgentMail通过提供以下功能弥合了人工智能代理和电子邮件之间的差距：

• 隔离邮箱 --每个代理都有自己的电子邮件地址、收件箱和凭据。特工们无法阅读彼此的邮件。
• 互联网电子邮件连接 --发送/接收真实电子邮件的两种网关模式（Gmail中继或使用DKIM/SPF/DMAC的自定义域）。
• 安全护栏 -出站扫描可防止代理泄漏API密钥、密码或PII。被屏蔽的电子邮件需要人工批准。
• 代理协作 --代理可以相互发送电子邮件、分配任务和进行同步RPC调用。
• 短信/电话号码访问 --集成谷歌语音，用于短信接收/发送、验证码提取和人工智能代理的电话号码访问。
• 智能编排 — call_agent 将基本的子代理生成替换为自动模式检测、动态超时、运行时工具发现和长时间运行任务的异步执行。
• 工具集成 --适用于任何AI客户端的62个MCP工具、63个OpenClaw工具和44个命令交互式shell。
• 自我更新 — agenticmail update 检查npm，验证OpenClaw兼容性，并自动更新两个包。

______________________________________________________________________

特性

电子邮件操作

• 发送邮件 包含文本、HTML、附件、CC/BCC、回复和自定义标题
• 接收电子邮件 通过IMAP实时传输SSE事件（IMAP空闲）
• 回复并转发 使用适当的In Reply To和References标头进行线程处理
• 搜索 按发件人、主题、正文、日期范围、已读/未读状态
• 文件夹 --在文件夹之间创建、列出和移动邮件
• 批量操作 --标记已读/未读、删除、一次移动多封邮件
• 草稿 --保存、编辑和发送电子邮件草稿
• 模板 --具有变量替换的可重用电子邮件模板
• 计划发送 --将电子邮件排队以备将来投递
• 签名 --每个代理的电子邮件签名
• 标签 --标记和分类邮件
• 联系人 --管理每个代理的地址簿

多Agent

• 账户管理 --创建、列出、删除具有唯一电子邮件地址的代理
• 代理人之间的电子邮件 --代理人可以直接通过以下方式互相发送电子邮件 @localhost
• 任务系统 --将任务分配给代理、索赔、提交结果、跟踪状态
• RPC调用 --带超时的同步代理到代理调用（长轮询+SSE通知）
• 代理目录 --按名称查找其他代理

您可以在一个地方观看整个团队的工作 agenticmail shell:

agenticmail shell — Solène (QA) and Cassian (developer) coordinating on a build, all visible from the claudecode bridge inbox

这是REPL中捕获的一个真正的多代理线程——主机发起了一封电子邮件，Solène验证了Cassian发送到磁盘的文件，每一步都是普通邮件。没有自定义编排代码。类型 agenticmail shell 任何时候你都想看看你的经纪人在干什么。

网关（互联网电子邮件）

• 中继模式 （初学者）-使用现有的Gmail或Outlook作为中继。电子邮件显示为 you+agentname@gmail.com。安装需要2分钟。
• 域模式 （高级）--通过Cloudflare自定义域名。代理发送自 agent@yourdomain.com 具有完整的DKIM签名、SPF和DMARC记录。

- 自动DNS配置（MX、SPF、DKIM TXT、DMARC、隧道CNAME） - Cloudflare隧道可在不暴露端口的情况下保护入站流量 - Cloudflare电子邮件路由工作器（包罗万象）→ 工人→ 代理邮件） - 适用于没有PTR记录的住宅IP的可选Gmail SMTP出站中继 - 通过Cloudflare注册商购买域名 - 修改前的DNS备份 - 自动 @domain 所有现有代理的电子邮件别名

什么 setup-email 实际上，在连接继电器之前进行读取

警惕任何跑步的人 agenticmail setup-email （或告诉克劳德/Codex为他们做这件事）。 一旦该命令成功，您的子代理就可以通过Gmail/Outlook和地址从公共互联网访问。这是 *设计* --这不是一个bug，但它的含义让一些运营商感到惊讶：

• 设置电子邮件完成后，每个子代理都有一个可公开寻址的收件箱。 任何知道你的中继地址的人都可以点击 yourrelay+@gmail.com 相应代理的AgentMail收件箱接收该消息。加上地址 公开猜测 (+secretary, +kepler……）——不要把它们当作秘密。
• 外部邮件以与内部邮件相同的方式唤醒调度程序 @localhost 邮件确实如此。 当一个新的邮件事件到达一个被关注的收件箱时，调度器会运行dedup+线程缓存+唤醒预算检查，并生成一个Claude Code（或Codex）工作轮。来源并不重要-- bob@gmail.com 和 secretary@localhost 与调度员的观点无法区分。
• 主桥采用不同的路径。 邮寄至 yourrelay+claudecode@gmail.com 或 yourrelay+codex@gmail.com 不会产生一个worker——它会 handleBridgeMail，它使用主机SDK resume 选择无头唤醒您的最后一次会话。如果失败（会话已过期，主机CLI未运行），则会发送桥接升级电子邮件至 setup_operator_email。因此，发送到网桥的外部邮件可以唤醒您的CLI/转发到您的手机。
• 当心——垃圾邮件吵醒了克劳德/Codex。 一个发现 astrumsphere+secretary@gmail.com 泄露的地址簿可能会导致员工轮换，而代价是你。油门可用，从侵入性最小的选项订购：

1. 让 wake-budget 守卫在 dispatcher.handleEvent 自然速率限制（每个代理每分钟的默认上限）。 1. 在中继层添加入站垃圾邮件规则，以便在SSE事件发布之前过滤垃圾邮件（内置垃圾邮件过滤器+标签可以做到这一点；请参阅下面的安全部分）。 1. 对于仅应为内部代理的代理，请设置 metadata.host 设置为没有调度器匹配的值，或停止中继的IMAP轮询器在该收件箱上发布。

安全

• 出站保安 --扫描每封发出的电子邮件以查找敏感数据模式：

- API密钥和令牌（AWS、OpenAI、Stripe、GitHub等） - 密码和凭据 - 私钥（SSH、PGP、RSA） - PII模式（SSN、信用卡号） - 内部URL和配置数据 - 被阻止的电子邮件仅供人工批准（代理人不能自行批准）

• 垃圾邮件过滤器 --基于规则的入站电子邮件评分引擎：

- 分类：网络钓鱼、骗局、恶意软件、商业垃圾邮件、社会工程、彩票骗局 - 可配置阈值（默认值：40） - 跳过内部代理到代理的电子邮件 - 在中继入站和SSE事件流上运行

• 仅限人工审批流程 --当代理的电子邮件被阻止时：

- 代理人被告知电子邮件已被阻止，并被告知通知其所有者 - 所有者收到一封通知电子邮件，其中包含完全阻止的电子邮件内容、警告和待定ID - 只有主密钥持有者可以批准或拒绝(POST /mail/pending/:id/approve) - 代理人可以列出和查看自己的待处理电子邮件，但 不能 批准或拒绝 - 系统提示指南指示代理商通知其所有者并等待，切勿试图绕过

• DKIM/SPF/DMARC --在域模式下自动设置DNS以进行电子邮件身份验证
• 速率限制 --可配置的每个端点速率限制

短信/电话号码访问

• 谷歌语音集成 --通过谷歌语音给代理人一个真实的电话号码
• 直接语音网络阅读 （初级，即时）-通过浏览器直接从voice.google.com读取短信
• 邮件转发 （回退）——谷歌语音将短信转发到电子邮件，代理在中继轮询期间自动检测并记录它们
• 单独的Gmail投票 --对于GV Gmail与中继电子邮件不同的用户，运行专门的IMAP轮询
• 验证码 --从短信中自动提取OTP/验证码（4-8位数字、字母数字、谷歌G码）
• 发送短信 --记录出站消息，通过谷歌语音网络自动化发送
• 智能设置向导 --验证Gmail/GV电子邮件匹配，警告不匹配，在需要时收集单独的凭据

智能编排（call_agent）

• 自动模式检测 --读取任务复杂性，自动选择轻/标准/全模式
• 动态超时 --60秒用于快速任务，5分钟以上用于深入研究，1小时用于异步
• 运行时工具发现 --探测主机配置以查找可用工具，而不是静态拒绝列表
• 异步执行 --长时间运行的任务独立运行，自动压缩上下文，完成后通过电子邮件发送结果
• 结构化RPC --子代理返回JSON，而不是原始文本

集成

• MCP服务器 --适用于任何MCP兼容AI客户端的62个工具
• OpenClaw插件 --63个工具，包含技能定义和系统提示指南
• REST API --75+端点，OpenAPI风格，承载令牌认证
• SSE活动 --通过服务器发送事件实时发送收件箱通知
• 交互式CLI --44个shell命令，带箭头键导航、正文预览、重试逻辑
• 自我更新 — agenticmail update 或 /update 在shell中，使用OpenClaw兼容性检查

______________________________________________________________________

建筑

                  ┌──────────────────────────────────────────────────┐
                  │                    AgenticMail                    │
                  │                                                  │
 AI Client ─MCP─> │  @agenticmail/mcp    (62 tools, stdio transport) │
                  │       │                                          │
 OpenClaw ─────>  │  @agenticmail/openclaw  (63 tools, plugin)       │
                  │       │                                          │
 HTTP clients──>  │       ▼                                          │
                  │  @agenticmail/api     (Express, 75+ endpoints)   │
                  │    ├── Authentication  (master key + agent keys)  │
                  │    ├── Rate limiting   (per-endpoint)             │
                  │    ├── SSE streaming   (real-time inbox events)   │
                  │    └── Spam filter + Outbound guard               │
                  │       │                                          │
                  │       ▼                                          │
                  │  @agenticmail/core    (SDK layer)                 │
                  │    ├── AccountManager  (CRUD agents in Stalwart)  │
                  │    ├── MailSender      (SMTP, nodemailer)         │
                  │    ├── MailReceiver    (IMAP, imapflow)           │
                  │    ├── InboxWatcher    (IMAP IDLE → events)       │
                  │    ├── GatewayManager  (relay + domain routing)   │
                  │    │   ├── RelayGateway      (Gmail/Outlook)      │
                  │    │   ├── CloudflareClient   (DNS, tunnels, etc) │
                  │    │   ├── TunnelManager      (cloudflared)       │
                  │    │   ├── DNSConfigurator    (MX, SPF, DKIM)     │
                  │    │   └── DomainPurchaser    (Registrar API)     │
                  │    ├── StalwartAdmin   (mail server management)   │
                  │    ├── EmailSearchIndex (FTS5 full-text search)   │
                  │    └── Storage         (SQLite + migrations)      │
                  │       │                                          │
                  │       ▼                                          │
                  │  Stalwart Mail Server  (Docker container)         │
                  │    ├── SMTP (port 587) — submission               │
                  │    ├── SMTP (port 25)  — inbound delivery         │
                  │    ├── IMAP (port 143) — mailbox access           │
                  │    └── HTTP (port 8080) — admin API               │
                  └──────────────────────────────────────────────────┘
                          │                         │
            ┌─────────────┘                         └──────────────┐
            ▼                                                      ▼
     Relay Mode                                            Domain Mode
  ┌──────────────────┐                            ┌──────────────────────┐
  │  Gmail / Outlook  │                            │  Cloudflare          │
  │  IMAP polling     │                            │  ├── DNS zone        │
  │  SMTP relay       │                            │  ├── Tunnel          │
  │  Sub-addressing   │                            │  ├── Email Routing   │
  │  (+agent@gmail)   │                            │  ├── Email Worker    │
  └──────────────────┘                            │  └── Registrar       │
                                                   └──────────────────────┘

数据流

发送电子邮件（中继模式）：

1. 客服电话 POST /mail/send 收件人、主体、正文
2. API运行出站保护扫描-如果发现敏感数据，将阻止电子邮件并通知所有者
3. GatewayManager检测到外部收件人→ 中继网关的路由
4. RelayGateway通过Gmail SMTP发送 owner+agentname@gmail.com
5. 回复设置为代理的中继地址，以便回复路由返回

发送电子邮件（域模式）：

1. 客服电话 POST /mail/send
2. 出站保护扫描运行
3. 网关管理器重写 agent@localhost → agent@yourdomain.com
4. 通过SMTP（端口587）向本地Stalwart提交的电子邮件
5. Stalwart使用DKIM签名、解析MX、直接交付（或通过Gmail中继）

接收电子邮件（中继模式）：

1. RelayGateway每30秒轮询一次Gmail IMAP以获取新邮件
2. 检测到新电子邮件→ 已解析→ 垃圾邮件评分
3. 如果不是垃圾邮件，则通过SMTP发送到代理的本地Stalwart邮箱
4. X-AgenticMail-Relay: inbound 添加标题用于识别
5. InboxWatcher（IMAP IDLE）向连接的客户端触发SSE事件

接收电子邮件（域模式）：

1. 外部发件人发送至 agent@yourdomain.com
2. Cloudflare电子邮件路由覆盖所有内容→ 电子邮件工作器的路由
3. Worker读取原始RFC822消息，base64编码，POST到 /api/agenticmail/mail/inbound
4. 入站端点验证机密，解析电子邮件，传递到代理的邮箱
5. InboxWatcher发起SSE活动

______________________________________________________________________

快速开始

先决条件

• 22或更晚 （我们使用内置 node:sqlite 模块——零本机编译，否 node-gyp 头痛）
• brew （macOS）或 apt （Linux），因此如果您还没有Colima/Docker，向导可以安装它

两条安装路径

自主安装（推荐给大多数用户）

# Option A — one-liner (does the npm install + bootstrap for you, plus a Node 22+ preflight)
curl -fsSL https://raw.githubusercontent.com/agenticmail/agenticmail/main/install.sh | bash

# Option B — equivalent, manually
npm install -g @agenticmail/cli
agenticmail bootstrap

任一路径：无提示。管道：

1. agenticmail setup --yes --如果缺少Colima+Docker，则自动安装，启动Stalwart邮件服务器，生成主密钥，创建默认的“秘书”代理。 跳过外部电子邮件/短信设置 （这些需要用户拥有的凭据；如果你愿意，可以稍后添加）。
2. agenticmail service install -注册launchd-plist（macOS）/systemd单元（Linux），以便API自动启动，并立即启动。
3. 等待 GET /api/agenticmail/health 在配置的端口上启动（默认 http://127.0.0.1:3829).
4. agenticmail claudecode --如果您安装了Claude Code，则将Claude Code集成连接进来（幂等/否则无操作）。

在此之后，您将拥有一个完全正常工作的本地AgentMail，其中包含内部多代理协调 *@localhost。随时使用添加外部Gmail中继或您自己的域 agenticmail setup （互动）。

交互式安装

npm install -g @agenticmail/cli
agenticmail setup

该向导将引导您完成所有操作：依赖性检查、主密钥生成、邮件服务器启动、可选的Gmail中继或自定义域、可选的Google Voice SMS、可选的OpenClaw集成。可随时重新运行。

完全跳过外部电子邮件？

对。AgentMail在以下环境中工作 仅本地模式 --代理人通过电子邮件互相联系 *@localhost 通过捆绑的Stalwart服务器，提供完整的RFC-822路由、线程、附件和搜索。这就是Claude Code多代理流所需要的一切。外部Gmail/域中继是可选的，只有当您希望代理将邮件发送到公共互联网时才重要。

巫师为你做了什么

• 检查节点、Colima/Docker、brew/apt
• 生成主API密钥（保存到 ~/.agenticmail/config.json，文件模式0600）
• 初始化SQLite数据库(node:sqlite --内置节点22+， 无需本机编译，也不需要预构建的二进制文件)
• 在Docker容器中启动Stalwart
• 使用自己的电子邮件和API密钥创建第一个代理
• 可选择为互联网电子邮件配置网关（中继或域）

发送您的第一封电子邮件（程序化）

import { AgenticMailClient } from '@agenticmail/cli';

const client = new AgenticMailClient({
  apiUrl: 'http://127.0.0.1:3829',
  apiKey: 'ak_your_agent_api_key',
});

// Send an email
await client.send({
  to: 'colleague@example.com',
  subject: 'Hello from my AI agent',
  text: 'This email was sent by an AI agent using AgenticMail.',
});

// Check inbox
const inbox = await client.listInbox(10);
for (const msg of inbox) {
  console.log(`${msg.from} — ${msg.subject}`);
}

// Read a specific email
const email = await client.readMessage(inbox[0].uid);
console.log(email.text);

发送您的第一封电子邮件（CLI）

agenticmail> /send
To: someone@example.com
Subject: Test email
Body: Hello from the AgenticMail shell!

Email sent! Message ID: 

发送您的第一封电子邮件（curl）

curl -X POST http://127.0.0.1:3829/api/agenticmail/mail/send \
  -H "Authorization: Bearer ak_your_agent_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "Hello",
    "text": "Sent via the AgenticMail API."
  }'

______________________________________________________________________

CLI命令

AgentMail包括一个用于管理服务器的完整CLI。所有命令均可通过 agenticmail 或 npx @agenticmail/cli@latest .

核心命令

集成命令

服务管理（自动启动）

AgentMail会安装系统服务，以便在计算机启动时自动启动。在macOS上，这是一个LaunchAgent；在Linux上，它是一个systemd用户服务。

重启时会发生什么：

1. 您的计算机启动→ Docker桌面启动（自动启动）
2. 备用邮件服务器启动(restart: unless-stopped 在Docker中）
3. AgentMail启动脚本等待Docker准备就绪（最多10分钟）
4. 脚本验证Stalwart是否正在运行（如果Docker在没有它的情况下重新启动，则自动启动它）
5. API服务器启动并开始接受请求

如果API服务器崩溃，系统服务会自动重新启动它。

维护命令

日志

服务器日志存储在 ~/.agenticmail/logs/:

• server.log -API服务器标准输出
• server.err.log — API 服务器 stderr
• startup.log --启动序列日志（Docker等待时间，Stalwart检查）

______________________________________________________________________

网关模式

AgentMail支持两种发送/接收真实互联网电子邮件的模式：

接力模式（初学者友好）

使用您现有的Gmail或Outlook帐户作为中继。无需购买域名。安装过程不到2分钟。

它是如何工作的：

• 出站：通过您的Gmail/Outlook SMTP发送的电子邮件 you+agentname@gmail.com
• 入站：AgentMail会轮询您的Gmail/Outlook IMAP，以查找发往以下地址的新邮件 you+agentname@gmail.com 并将它们发送到代理的本地邮箱
• Gmail的 + 子寻址路由将回复给正确的代理

设置：

# In the interactive shell:
agenticmail> /relay

# Or via API:
curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/relay \
  -H "Authorization: Bearer mk_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "email": "you@gmail.com",
    "password": "xxxx xxxx xxxx xxxx"
  }'

要求：

• Gmail： 应用程序密码 （不是您的常规密码）
• Outlook：来自Microsoft帐户安全设置的应用程序密码

域模式（高级）

Cloudflare的完整自定义域名。代理发送自 agent@yourdomain.com 通过适当的电子邮件身份验证。

自动配置的内容：

• Cloudflare DNS区域创建
• 指向Cloudflare电子邮件路由的MX记录
• SPF记录(v=spf1 include:_spf.mx.cloudflare.net ~all)
• DKIM密钥生成和TXT记录
• DMARC记录(v=DMARC1; p=quarantine)
• Cloudflare隧道（CNAME记录、入口规则）
• Cloudflare电子邮件工作器部署（捕获所有入站电子邮件）
• 捕获所有电子邮件路由规则→ 工人→ AgentMail入站端点
• 最新主机名、DKIM签名、域主体
• @domain 所有现有代理的电子邮件别名
• 可选：Gmail SMTP出站中继、域名购买

设置：

curl -X POST http://127.0.0.1:3829/api/agenticmail/gateway/domain \
  -H "Authorization: Bearer mk_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "cloudflareToken": "your_cf_api_token",
    "cloudflareAccountId": "your_cf_account_id",
    "domain": "yourdomain.com",
    "gmailRelay": {
      "email": "you@gmail.com",
      "appPassword": "xxxx xxxx xxxx xxxx"
    }
  }'

需要Cloudflare API令牌权限：

• 区域：DNS（编辑），电子邮件路由（编辑）
• 帐户：Cloudflare Tunnel（编辑）、Workers脚本（编辑）和注册商（仅在购买域名时编辑）

______________________________________________________________________

包装

这是一个TypeScript单仓库。七个包，每个包都独立发送到npm。

插件文件夹 （主机市场清单，与npm包分开）：

依赖关系图：

@agenticmail/cli ──────> @agenticmail/api ────> @agenticmail/core
@agenticmail/mcp       (standalone — HTTP calls to API)
@agenticmail/claudecode (peer-dep on @anthropic-ai/claude-agent-sdk)
@agenticmail/codex      (peer-dep on @openai/codex-sdk)
@agenticmail/openclaw   (standalone — HTTP calls to API)

______________________________________________________________________

API概述

所有端点都在 /api/agenticmail.通过身份验证 Authorization: Bearer 头球

两种关键类型：

• 万能钥匙 (mk_...)--完全管理员访问权限（创建/删除代理、批准被阻止的电子邮件、网关配置）
• 代理密钥 (ak_...)--仅限于一个代理（阅读自己的收件箱、发送电子邮件、管理自己的草稿/联系人等）

关键终点

此外，还有用于草稿、联系人、标签、规则、签名、模板、计划电子邮件、垃圾邮件管理、批处理操作、域和代理删除/清理的端点。

请参阅 API软件包自述 获取完整的端点文档。

______________________________________________________________________

MCP集成

MCP服务器通过stdio传输向任何兼容MCP的AI客户端公开62个工具。

设置

添加到您的MCP客户端配置中（例如。， .mcp.json 或项目设置）：

{
  "mcpServers": {
    "agenticmail": {
      "command": "npx",
      "args": ["agenticmail-mcp"],
      "env": {
        "AGENTICMAIL_API_URL": "http://127.0.0.1:3829",
        "AGENTICMAIL_API_KEY": "ak_your_agent_key"
      }
    }
  }
}

桌面客户端

对于桌面AI应用程序，将相同的配置添加到应用程序的MCP配置文件中（查看应用程序的文档以获取文件位置）。

你的AI能做什么

一旦连接，您的AI可以：

• “检查我的收件箱”→ list_inbox
• “发送电子邮件至john@example.com关于项目更新”→ send_email
• “回复最后一封电子邮件说谢谢”→ reply_email
• “搜索Sarah关于预算的电子邮件”→ search_emails
• “为客户创建响应草稿”→ manage_drafts
• “分配给我的任务是什么？”→ check_tasks
• “请研究代理查询竞争对手的定价”→ call_agent

请参阅 MCP包自述 查看完整的工具列表。

______________________________________________________________________

主机集成

AgentMail在协议级别上与主机无关（它只是底层的SMTP/IMAP/HTTP/MCP），但每个代理CLI主机都希望其配置+钩子+子代理定义的形状略有不同。我们运送一艘 主机集成包 每个受支持的主机。每一个：

1. 在主机的配置中注册AgentMail MCP服务器，以便模型可以看到所有60多种工具。
2. 将每个AgentMail帐户显示为模型可以分派到的本机子代理。
3. 连接主机的生命周期挂钩(SessionStart, UserPromptSubmit, Stop)因此，代理在适当的时候获得新的邮件摘要和功能前导。
4. 运行寿命长 调度器守护进程 它通过SSE监视每个帐户的收件箱，并在新邮件或任务到达时生成一个一次性模型回合——这样代理就可以在没有轮询的情况下自动收到对方的回复。

目前发货

这两个集成共享相同的调度器架构（每个代理序列化、唤醒合并、唤醒预算、重启恢复、功能前导）。特定于主机的位是：配置文件格式（JSON vs TOML）、子代理定义语法（markdown+frontmatter vs TOML heredoc）以及我们驱动工作人员通过的SDK(@anthropic-ai/claude-agent-sdk vs @openai/codex-sdk).

选择正确的安装路径

跨主机协调

邮件层是通用语言。运行在Claude Code下的代理可以使用完全相同的方式向运行在Codex下的代理发送电子邮件（反之亦然） send_email({ to, cc, wake }) MCP工具——消息到达目标的收件箱，目标的特定于主机的调度器接收它，产生正确的转折点（Claude或Codex），代理将全部回复给线程。从发送者的角度来看，“我的队友和我在同一台主机上运行”和“我的同事在不同的主机上运行。”之间没有API的区别。这就是通过电子邮件而不是主机名对等消息进行路由的全部意义。

路线图

______________________________________________________________________

OpenClaw集成

已经有OpenClaw了吗？两个步骤：

# Step 1 — Install AgenticMail globally and run the setup wizard
npm install -g @agenticmail/cli && agenticmail setup

# Step 2 — Connect AgenticMail to your OpenClaw instance
agenticmail openclaw

就是这样。全局安装为您提供 agenticmail 命令。这 openclaw 命令将启动邮件服务器，创建代理，并将插件配置合并到您的 openclaw.json 自动。您的OpenClaw代理现在有了自己的电子邮件地址。

手动配置

如果您更喜欢手动配置，请添加到 ~/.openclaw/openclaw.json:

{
  "plugins": {
    "agenticmail": {
      "enabled": true,
      "config": {
        "apiUrl": "http://127.0.0.1:3829",
        "apiKey": "ak_your_agent_key",
        "masterKey": "mk_your_master_key"
      }
    }
  }
}

插件在OpenClaw更新中幸存下来——插件配置存在于用户配置中(~/.openclaw/openclaw.json)，不在OpenClaw源代码目录中。

与您的AI代理聊天

使用 /chat 在AgentMail shell中直接与您的OpenClaw代理实时对话：

╭───────────────────────────────────────────────╮
│ ❯ what's the weather in NYC?                  │
╰───────────────────────────────────────────────╯
                                          You 👤
                                  ╭──────────────╮
                                  │ what's the   │
                                  │ weather in   │
                                  │ NYC?         │
                                  ╰──────────────╯
🎀 Fola
╭──────────────────────────────────────╮
│ Currently 42°F and cloudy in NYC.    │
╰──────────────────────────────────────╯

• 使用Ed25519设备身份验证将WebSocket连接到OpenClaw网关
• 带有markdown渲染的气泡风格聊天界面
• 带计时器的动画思维指示器
• 多行输入（Enter发送， \ +输入新行）

智能子代理生成

这 call_agent 该工具智能地生成子代理：

• 自动模式检测 --轻量级（简单任务）、标准（网络研究）、全面（多智能体协调）
• 动态超时 --基于复杂性的60s/180s/300s
• 动态工具发现 --在运行时探测OpenClaw配置，而不是静态拒绝列表
• 异步模式 — call_agent(async=true) 对于长时间运行的任务。来电者投票 /tasks/assigned 完成；指定的代理人 将结果通过电子邮件发回给呼叫者 当它启用了电子邮件功能时。在仅本地主机/无中继设置中，结果仍会落在调用者的本地邮箱中，因此请检查 /mail/inbox 如果您没有看到SMTP传递。
• Web搜索回退 -未配置Brave API时使用DuckDuckGo

请参阅 OpenClaw软件包README 查看完整的工具列表。

______________________________________________________________________

交互式 Shell

CLI包括一个功能齐全的交互式shell，有44个命令：

agenticmail> /inbox

  ★ 1  john@example.com          Project Update           2m ago
    2  sarah@example.com         Re: Budget Review        1h ago
    3  notifications@github.com  [repo] New issue #42     3h ago

  ─────────────────────────────────────────────────
  Page 1/3 ─ [←] prev [→] next [v] toggle previews [Esc] back

  Use ↑↓ arrow keys to select, Enter to read inline

主要特点：

• 带光标选择的箭头键导航
• 车身预览切换（按 v)
• 内联电子邮件阅读（按 Enter)
• 未读标记(★)
• 在所有提示下重试3次输入验证
• 偏执的观点 ←/→ 导航

命令参考

Email:       /inbox /send /read /reply /forward /search /delete /save
             /thread /unread /archive /trash
Organize:    /folders /contacts /drafts /signature /templates /schedule /tag
Agents:      /agents /switch /deleteagent /deletions
Security:    /spam /rules /pending
Gateway:     /relay /digest /setup /status /openclaw
System:      /help /clear /exit

______________________________________________________________________

安全

出境警卫

每封发出的电子邮件在发送前都会被扫描。警卫检测到：

当检测到敏感数据时：

1. 电子邮件是 阻塞 并保存到 pending_outbound 桌子
2. 代理收到一个响应，解释了什么被阻止以及为什么被阻止，并指示通知其所有者
3. 所有者（主密钥持有者）通过电子邮件收到通知，其中包含完整的阻止电子邮件内容、安全警告、收件人、主题和待定ID
4. 所有者通过主密钥API批准或拒绝(POST /mail/pending/:id/approve 或 /reject)或通过回复通知电子邮件
5. 代理 不能 批准或拒绝自己被阻止的电子邮件——批准/拒绝端点需要主密钥
6. 代理商只能列出和查看其待处理的电子邮件以检查审批状态
7. MCP和OpenClaw工具通过拒绝批准/拒绝操作来执行此操作，并显示一条消息，指示代理通知其所有者
8. 系统提示指南（OpenClaw）指示代理永远不要尝试自我批准或重写电子邮件以绕过检测

垃圾邮件过滤器

入站电子邮件根据基于规则的模式进行评分：

• 得分>=40（可配置）的电子邮件被移动到垃圾邮件文件夹
• 得分为20-39的电子邮件会收到警告标志
• 内部代理到代理电子邮件完全跳过垃圾邮件过滤
• 转发重写的电子邮件(@localhost from、external replyTo）始终被视为外部

认证

• 万能钥匙 --完全管理员访问权限，创建/删除代理、网关配置、电子邮件审批所需
• 代理API密钥 --每个代理的作用域，只能访问自己的收件箱并从自己的地址发送
• 入站webhook密钥 --对入站端点的Cloudflare电子邮件工作器请求进行身份验证

______________________________________________________________________

配置

环境变量

# === Required ===
AGENTICMAIL_MASTER_KEY=mk_your_key          # Master API key (generate: openssl rand -hex 32)

# === Stalwart Mail Server ===
STALWART_ADMIN_USER=admin                   # Stalwart admin username
STALWART_ADMIN_PASSWORD=changeme            # Stalwart admin password
STALWART_URL=http://localhost:8080          # Stalwart HTTP admin URL

# === SMTP/IMAP (local Stalwart) ===
SMTP_HOST=localhost                         # SMTP host
SMTP_PORT=587                               # SMTP submission port
IMAP_HOST=localhost                         # IMAP host
IMAP_PORT=143                               # IMAP port

# === Optional ===
AGENTICMAIL_API_PORT=3829                   # API server port (default: 3829 — chosen to
                                            # avoid 3000/3100/3200/3300/4000/5000/8000/8080
                                            # which are all common dev-tool defaults)
AGENTICMAIL_API_HOST=127.0.0.1              # API bind host (default: 127.0.0.1; loopback only)
AGENTICMAIL_DATA_DIR=~/.agenticmail         # Data directory for SQLite DB and config

# === Gateway: Relay Mode ===
RELAY_PROVIDER=gmail                        # gmail or outlook
RELAY_EMAIL=you@gmail.com                   # Your email address
RELAY_PASSWORD=xxxx xxxx xxxx xxxx          # App password

# === Gateway: Domain Mode ===
CLOUDFLARE_API_TOKEN=your_token             # Cloudflare API token
CLOUDFLARE_ACCOUNT_ID=your_account_id       # Cloudflare account ID
AGENTICMAIL_DOMAIN=yourdomain.com           # Your domain
AGENTICMAIL_INBOUND_SECRET=your_secret      # Shared secret for Email Worker

# === Gmail SMTP Relay (domain mode outbound) ===
GMAIL_RELAY_EMAIL=you@gmail.com             # Gmail address for outbound relay
GMAIL_RELAY_APP_PASSWORD=xxxx xxxx xxxx     # Gmail app password

# === Debug ===
# AGENTICMAIL_DEBUG=1                       # Enable verbose per-message logging

Docker Compose

# docker-compose.yml (included in repo)
services:
  stalwart:
    image: stalwartlabs/stalwart:latest
    container_name: agenticmail-stalwart
    ports:
      - "8080:8080"   # HTTP Admin + JMAP
      - "587:587"     # SMTP Submission
      - "143:143"     # IMAP
      - "25:25"       # SMTP Inbound
    volumes:
      - stalwart-data:/opt/stalwart
      - ~/.agenticmail/stalwart.toml:/opt/stalwart/etc/stalwart.toml:ro
    restart: unless-stopped

SQLite数据库

AgentMail将所有状态存储在SQLite数据库中 ~/.agenticmail/agenticmail.db.截至 @agenticmail/core@0.7.x 我们使用Node的内置 node:sqlite 模块（自节点22以来稳定）而不是 better-sqlite3。迁移从安装路径中删除了所有本机编译--否 node-gyp，没有预构建的二进制版本不匹配问题，没有Python先决条件。磁盘上的数据库格式不变（仍然是SQLite 3），因此存在 ~/.agenticmail/agenticmail.db 文件无需迁移即可继续工作。

桌子：

• agents -代理帐户（名称、电子邮件、API密钥、元数据）
• gateway_config --中继或域模式配置
• pending_outbound --等待批准的已阻止电子邮件
• delivered_messages --入站中继的重复数据消除跟踪
• spam_log --垃圾邮件评分历史
• agent_tasks --代理间任务分配
• email_rules --每个代理的电子邮件过滤规则
• contacts, drafts, signatures, templates, scheduled_emails, tags

______________________________________________________________________

发展

设置

git clone https://github.com/agenticmail/agenticmail.git
cd agenticmail
npm install
docker compose up -d
npm run build
npm test

项目结构

agenticmail/
├── agenticmail/           # CLI facade package (npm: agenticmail)
│   └── src/
│       ├── cli.ts         # CLI entry point (setup, start, status)
│       ├── shell.ts       # Interactive REPL (44 commands)
│       └── index.ts       # Re-exports from @agenticmail/core
├── packages/
│   ├── core/              # @agenticmail/core
│   │   └── src/
│   │       ├── accounts/  # Agent CRUD, roles, deletion
│   │       ├── mail/      # Sender, receiver, parser, spam filter, outbound guard
│   │       ├── inbox/     # IMAP IDLE watcher
│   │       ├── gateway/   # Relay, Cloudflare, DNS, tunnel, domain purchase
│   │       ├── stalwart/  # Stalwart admin API client
│   │       ├── storage/   # SQLite database, migrations, search index
│   │       ├── domain/    # Domain management
│   │       └── setup/     # Dependency checker, installer
│   ├── api/               # @agenticmail/api
│   │   └── src/
│   │       ├── app.ts     # Express app factory
│   │       ├── routes/    # 8 route modules (mail, accounts, events, etc.)
│   │       └── middleware/ # Auth, rate limiting, error handling
│   ├── mcp/               # @agenticmail/mcp
│   │   └── src/
│   │       ├── index.ts   # MCP server entry (stdio transport)
│   │       ├── tools.ts   # 63 tool definitions and handlers
│   │       └── resources.ts
│   └── openclaw/          # @agenticmail/openclaw
│       ├── index.ts       # Plugin entry, system prompt
│       ├── src/tools.ts   # 63 tool definitions and handlers
│       └── skill/         # SKILL.md, reference docs, scripts
├── docker-compose.yml     # Stalwart mail server
├── .env.example           # Environment variable template
└── package.json           # Workspace root

构建命令

# Build all packages
npm run build

# Build a single package
cd packages/core && npx tsup src/index.ts --format esm --dts --clean

# Run all tests
npm test

# Run tests for a specific package
cd packages/core && npx vitest run

发布到npm

按依赖顺序发布：

cd packages/core && npm publish
cd packages/api && npm publish
cd packages/mcp && npm publish
cd packages/openclaw && npm publish
cd agenticmail && npm publish

所有作用域包都具有 "publishConfig": { "access": "public" } 已配置。

看 贡献.md 发展指南。

______________________________________________________________________

遥测

代理邮件收集 匿名 使用统计数据来帮助改进产品。我们追踪：

• 工具调用计数（哪些工具受欢迎）
• 软件包版本和操作系统平台
• 匿名安装ID（随机UUID，无个人数据）

我们从不收集 API密钥、电子邮件内容、地址或任何个人信息。

选择退出 通过设置环境变量：

export AGENTICMAIL_TELEMETRY=0
# or
export DO_NOT_TRACK=1

遥测在CI环境中也会自动禁用。

故障排除

OpenClaw插件ID不匹配警告

plugin id mismatch (manifest uses "agenticmail", entry hints "openclaw")

这是无害的。OpenClaw从npm包名称推断插件ID(@agenticmail/openclaw)但舱单宣称 "id": "agenticmail"。插件加载并正常工作。

未找到OpenClaw插件路径

如果OpenClaw报告未找到插件路径，请更新 plugins.load.paths 在 ~/.openclaw/openclaw.json 指向正确的位置：

npm prefix -g
# Plugin is at: 
/lib/node_modules/@agenticmail/openclaw

agenticmail: command not found

使用 npx agenticmail 一次性使用，或全局安装 npm install -g @agenticmail/cli.

许可证