Agentic Inbox 是一个自托管的电子邮件客户端，包含一个 AI 代理，完全运行在 Cloudflare Workers 上。它利用 Cloudflare 的 Email Routing 接收邮件，使用 Durable Objects 和 SQLite 隔离每个邮箱，并将附件存储在 R2 中。AI 代理可以阅读您的收件箱、搜索对话并起草回复。

1. 前提条件

在开始部署前，请确保您拥有：

  • 一个 Cloudflare 账户。
  • 一个由 Cloudflare 管理的域名（用于接收和发送邮件）。
  • 已在该域名上启用 Cloudflare Email Routing（用于接收邮件）。
  • 已启用 Cloudflare Email Service（用于发送邮件）。
  • 已启用 Workers AI（用于 AI 代理功能）。
  • Cloudflare Access 已配置（生产环境强制要求，用于保护您的收件箱）。

2. 部署步骤

部署分为几个关键阶段，请务必完整执行所有步骤。

第一步：一键部署到 Cloudflare

  1. 点击项目 README 中的 “Deploy to Cloudflare” 按钮（或手动通过 Wrangler 部署）。
  2. 在部署过程中，您会被提示输入 DOMAINS 变量。这是您要接收邮件的域名（例如 yourdomain.com），意味着您将拥有 任意用户名@yourdomain.com 的邮箱。
  3. 部署流程会自动在您的 Cloudflare 账户中配置必要的资源：
    • R2 存储桶：用于存放邮件附件。
    • Durable Objects：用于为每个邮箱提供独立的、有状态的运行环境。
    • Workers AI：为 AI 代理提供推理能力。

第二步：配置 Cloudflare Access（关键安全步骤）

这是必须完成的一步，用于保护您的邮箱不被公开访问。

  1. 在 Cloudflare 仪表板中，进入您的 Worker 设置页面。
  2. 在 “设置” > “域和路由” 下，为您的 Worker 启用一键 Cloudflare Access。
  3. 启用后，会弹出一个模态框，其中包含 POLICY_AUD 和 TEAM_DOMAIN 的值。请记下这两个值。
    • TEAM_DOMAIN 可以是您的 Access 团队 URL，也可以是完整的 .../cdn-cgi/access/certs URL。
  4. 您必须将这两个值作为 Secret（机密变量） 添加到您的 Worker 中。您可以通过 Cloudflare 仪表板（Worker > 设置 > 变量 > 添加机密变量）或 Wrangler CLI 完成此操作。

第三步：设置邮件路由（Email Routing）

  1. 在 Cloudflare 仪表板中，转到您的域名页面。
  2. 进入 “电子邮件” > “邮件路由” 设置。
  3. 创建一个 “全部捕获”（Catch-all）规则，将发送到您域名下任何地址的邮件都转发到您刚刚部署的 Worker。
  4. 这确保了所有发送到 *@yourdomain.com 的邮件都能被 Agentic Inbox 处理。

第四步：启用邮件发送服务（Email Service）

您的 Worker 需要 send_email 绑定才能发送邮件。请参考 Cloudflare Email Service 文档 进行配置，确保 Worker 拥有发送邮件的权限。

第五步：创建您的邮箱

  1. 访问您部署的 Worker 的 URL（例如 https://your-worker.your-subdomain.workers.dev）。
  2. 您将被 Cloudflare Access 拦截，请使用您配置的 Access 策略进行身份验证。
  3. 登录后，在应用中创建一个新邮箱，地址可以是您域名下的任意名称（例如 hello@yourdomain.com）。
  4. 现在，您就可以开始发送和接收邮件了。

3. 常见问题排查

问题 可能原因 解决方案
部署后访问显示 Invalid or expired Access token POLICY_AUD 或 TEAM_DOMAIN 机密变量设置不正确 1. 在 Worker 设置中关闭并重新开启 Access，重新获取最新的 POLICY_AUD 和 TEAM_DOMAIN 值。 2. 更新 Worker 的 Secrets（机密变量）为最新值。
访问时显示 Cloudflare Access must be configured in production 生产环境未启用 Access（该应用强制要求） 按照第二步的指引，为 Worker 启用 Cloudflare Access 并配置 Secrets。
无法接收邮件 邮件路由规则未正确设置 检查域名下的 “邮件路由” 设置，确保存在一条指向您 Worker 的 “全部捕获”（Catch-all） 规则。
无法发送邮件 未配置 send_email 绑定 参考 Cloudflare Email Service 文档，为 Worker 添加 send_email 绑定。
AI 代理无响应 Workers AI 未启用或模型访问问题 确认您的 Cloudflare 账户已 启用 Workers AI，并检查 Worker 的 AI 绑定配置。

4. 本地开发与测试（可选）

如果您想对项目进行二次开发或在本地测试，可以按以下步骤操作。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/cloudflare/agentic-inbox.git
    cd agentic-inbox

  2. 安装依赖：

    1
    npm install

  3. 配置本地环境：

    • 在 wrangler.jsonc 中设置您的域名。
    • 创建 R2 存储桶：wrangler r2 bucket create agentic-inbox。

  4. 运行开发服务器：

    1
    npm run dev

    这会在本地启动一个模拟 Cloudflare 环境的开发服务器。

  5. 部署：

    1
    npm run deploy

5. 架构与安全说明

  • 隔离性：每个邮箱都运行在独立的 Durable Object 中，拥有自己的 SQLite 数据库和 R2 存储空间，实现了良好的数据和状态隔离。
  • 认证边界：该应用强制使用 Cloudflare Access 作为唯一的身份验证和信任边界。任何通过 Access 策略的用户都可以访问应用内的所有邮箱。
  • AI 代理：AI 代理拥有 9 种邮件操作工具，包括读取、搜索、草稿和发送。它会在新邮件到达时自动生成草稿回复，但发送前需要您明确确认，确保人工始终在决策环内。

6. 总结

Agentic Inbox 是一个展示了 Cloudflare 全栈能力的现代化应用。

核心部署路径：

  1. 一键部署到 Cloudflare，并输入您的域名。
  2. 强制配置 Cloudflare Access 并设置所需的 Secrets。
  3. 配置邮件路由（全部捕获到 Worker）和 邮件发送服务。
  4. 访问应用并创建您的第一个邮箱。

最关键的一步是配置 Cloudflare Access，它不仅是安全基础，也是部署流程中容易出错的地方。请务必仔细记录并设置 POLICY_AUD 和 TEAM_DOMAIN 这两个机密变量。完成所有步骤后，您将拥有一个由 AI 助力的、完全自控的邮件系统。

项目地址：https://github.com/cloudflare/agentic-inbox