Agent Cloak

Agent loak

  

不想自己设置吗？ 在以下位置尝试托管版本 agentcloke.up.railway.app

位于AI代理和您的电子邮件之间的源可用代理服务。AgentCloak在服务器端保存OAuth令牌、IMAP凭据和Apps Script机密，过滤敏感内容，编辑PII和电子邮件地址，并进行消毒以进行及时注入——因此代理可以安全地对电子邮件进行分类、总结和起草，而不会看到他们不应该看到的东西。

关键安全特性

• 按设计只读 --代理可以搜索、阅读和创建草稿。他们不能发送、删除、丢弃或修改任何电子邮件。
• 敏感电子邮件屏蔽 --来自金融机构、安全发件人和政府机构的电子邮件在代理人看到之前就被屏蔽了。阻止分为可独立切换的类别：安全电子邮件（密码重置、2FA代码、登录提醒）、财务电子邮件（银行对账单、付款、税务文件）和敏感发件人（security@、fraud@、.gov地址）。默认情况下，包括40+个域、13个发送者模式和50+个主题模式。
• 个人身份信息脱敏 -将SSN、信用卡号码、帐号、路由号码、API密钥和大额金额替换为 [REDACTED] 占位符。美元金额编辑可以独立切换。
• 电子邮件地址编辑 --电子邮件地址从所有结构化字段中删除(from, to, cc, participants)并且仅替换为显示名称。电子邮件正文中的地址被编辑为 [EMAIL_REDACTED]这可以防止代理将联系信息泄露到外部系统。
• 附件筛选 --附件元数据（文件名、类型、大小）可以完全对代理隐藏，防止它们引用或请求访问敏感文件。
• 文件夹限制 --限制代理访问特定文件夹（例如仅限INBOX）。允许文件夹外的邮件被阻止，受限制的文件夹名称在标签列表中隐藏。
• 线程回复自动填充 --当代理创建对线程的草稿回复时，收件人将从线程的参与者自动填充到服务器端。代理永远不需要查看或处理电子邮件地址。
• HTML和Unicode清理 --HTML被转换为明文。可用于提示注入的危险Unicode字符（零宽度字符、bidi覆盖、标记字符）被删除。
• 快速注射检测 --检测电子邮件内容中的已知注入模式，并用警告标记。
• 凭据保留在服务器端 -代理使用API密钥进行身份验证。Gmail OAuth令牌、IMAP凭据和Apps Script机密在SQLite中静态加密，从不通过MCP接口公开。
• Web仪表板 -所有过滤器设置、API键和连接都通过基于浏览器的仪表板进行管理。代理无法访问或修改这些设置。

运作原理

AI Agent (Claude Code, OpenClaw, any MCP client)
  │
  │  MCP Streamable HTTP + API key
  ▼
AgentCloak Server
  ├── 7 MCP tools (search, read, threads, drafts, labels)
  ├── Content filter pipeline (blocklist → sanitizer → PII → injection)
  ├── Attachment filtering & folder restriction
  ├── Email address redaction (structured fields + body text)
  ├── Gmail provider (OAuth2, token refresh)
  ├── Apps Script provider (no Google Cloud project needed)
  ├── IMAP provider (encrypted credentials)
  ├── Web dashboard (React + Tailwind)
  └── SQLite storage (tokens, API keys, filter configs)

代理使用API密钥通过MCP通过HTTP进行连接。每封电子邮件在到达代理之前都会经过四级过滤管道：

1. 文件夹限制 --如果配置了允许的文件夹，则这些文件夹外的邮件将在任何其他处理之前被阻止。
2. 黑名单 --阻止来自金融机构、政府机构和安全发件人的电子邮件。每个类别（安全、财务、敏感发件人）都可以独立切换。始终应用自定义阻止域和主题模式。
3. 消毒剂 --将HTML转换为纯文本，删除危险的Unicode（零宽度字符、双向覆盖、标记字符）。
4. PII补救措施 -将SSN、信用卡号码、帐号、API密钥和电子邮件地址替换为 [REDACTED] 占位符。美元金额编辑可独立切换。
5. 注射检测 --检测电子邮件内容中的提示注入模式，并预先添加警告（不阻止）。
6. 附件筛选 --启用后，会从输出中删除附件元数据，这样代理就看不到文件名、类型或大小。

除了主体级过滤外，所有结构化字段(from, to, cc, participants)处理后仅显示显示名称——电子邮件地址永远不会返回给代理。

MCP工具

项目结构

agentcloak/
├── packages/
│   ├── server/          # Core proxy server (Hono + MCP SDK)
│   ├── web/             # Web dashboard (React + Tailwind + Vite)
│   ├── cli/             # CLI for setup, key management, filters, password reset
│   └── mcp-stdio/       # Stdio proxy for stdio-only environments
└── deploy/
    ├── docker/          # Docker deployment
    └── cloudflare/      # Cloudflare Workers (planned)

快速开始

先决条件

• Node.js 20+ 和 pnpm 10+
• IMAP凭据 （可选）--如果通过IMAP连接非Gmail帐户，您需要IMAP主机、端口和电子邮件提供商提供的特定于应用程序的密码。

提示： Google OAuth是完全可选的。您可以使用电子邮件/密码登录仪表板，并通过IMAP或Apps Script连接电子邮件，无需Google Cloud项目。仅当您想在仪表板上“使用谷歌登录”或想通过OAuth连接Gmail帐户时，才设置谷歌OAuth。

1.安装

git clone https://github.com/ryanfren/AgentCloak.git
cd agentcloak
pnpm install

2.设置谷歌云项目（可选）

Google OAuth是 可选的。您只需要在以下情况下使用它：

• 仪表板上的“使用谷歌登录”（电子邮件/密码无需使用）
• Gmail OAuth作为电子邮件连接方法（IMAP和Apps Script在没有它的情况下工作）

如果你不需要，跳到 步骤3.

创建一个项目并启用Gmail API：

1. 去 Google 云控制台
2. 单击顶部的项目下拉列表并选择 新项目.为其命名（例如“AgentLoak”）并单击 创建.
3. 确保在项目下拉列表中选择了新项目。
4. 首选 API和服务>库 （或在顶部搜索栏中搜索“Gmail API”）。
5. 找到 Gmail API 然后单击 启用.

配置OAuth同意屏幕：

1. 首选 API和服务>OAuth同意屏幕.

1. 选择 外部的 当用户键入并单击 创建.

> “内部”仅适用于Google Workspace组织。外部适用于所有Google帐户。

1. 填写应用程序信息页面上的必填字段：

- 应用程序名称：任何内容（例如“AgentLoak”） - 用户支持电子邮件：您的电子邮件地址 - 开发人员联系电子邮件：您的电子邮件地址 - 将其他内容留空/默认，然后单击 保存并继续.

1. 在 范围 页面，单击 添加或删除作用域 并添加以下内容：

- openid - https://www.googleapis.com/auth/userinfo.email - https://www.googleapis.com/auth/userinfo.profile - https://www.googleapis.com/auth/gmail.readonly - https://www.googleapis.com/auth/gmail.compose

点击 更新那么 保存并继续.

> 前三个作用域用于仪表板登录。最后两个用于连接Gmail帐户（阅读电子邮件+创建草稿）。

1. 在 测试用户 页面，单击 添加用户 并添加 Gmail地址 您想通过AgentLoak访问。这是必需的——只有列出的测试用户才能在应用程序处于测试模式时登录。

点击 保存并继续那么 返回仪表盘.

重要提示： 您的应用程序将在 测试 默认模式。这很好，你会的 不 需要发布或验证应用程序。测试模式仅限于您在上面添加的测试用户登录。如果跳过添加测试用户，在尝试登录时将出现“403:access_denied”错误。

创建OAuth凭据：

1. 首选 API和服务>凭据.
2. 点击 创建凭据>OAuth客户端ID.
3. 集 应用程序类型 到 Web应用程序.
4. 在...之下 授权重定向URI，单击 添加URI 并输入：

    http://localhost:3000/auth/callback

> 如果你改变了你的端口 .env，请改用该端口。

1. 点击 创建.复制 客户端ID 和 客户端密钥 --下一步你需要它们。

3.配置环境

cp .env.example .env

编辑 .env:

# Required — random string, 32+ characters (used for session cookies)
SESSION_SECRET=change-me-to-a-random-string-at-least-32-chars

# Server
BASE_URL=http://localhost:3000
PORT=3000

# Optional — Google OAuth credentials (only needed for Google sign-in and Gmail OAuth connections)
# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=GOCSPX-your-secret
# GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

如果没有Google OAuth变量，仪表板只显示电子邮件/密码登录。有了它们，这两种方法都可用。

4.构建并启动服务器

pnpm build   # builds all packages (server, web dashboard, CLI, stdio bridge)
pnpm dev     # starts the server on http://localhost:3000

SQLite数据库在以下位置自动创建 data/agentcloak.db 第一次跑步。服务器从同一个进程为API和web仪表板提供服务。

5.登录仪表板

打开 http://localhost:3000。如果您在步骤2中配置了Google OAuth，则可以使用电子邮件/密码创建帐户，或使用“使用Google登录”。仪表板用于管理连接、API密钥和筛选器。

密码重置： 由于AgentLoak在没有电子邮件服务的情况下在本地运行，请使用CLI重置密码： ``bash agentcloak reset-password --email user@example.com `` 这将提示输入新密码并使所有现有会话无效。

6.连接电子邮件帐户

从 连接 页面：

• Gmail（OAuth） --点击“连接Gmail”。您将通过Google OAuth授权只读访问。AgentCloak在服务器端存储OAuth令牌。从步骤2开始需要Google Cloud项目。
• Gmail（应用程序脚本） --点击“通过应用程序脚本连接”。这是连接Gmail的最快方式——电子邮件访问不需要谷歌云项目。将生成的脚本复制到 script.google.com，只需单击一下即可授权，将其部署为web应用程序，然后将URL粘贴回去。看 应用程序脚本设置 详见下文。
• 互联网邮件访问协议 --点击“添加IMAP帐户”。输入您的服务器详细信息（主机、端口、用户名、应用程序密码）。您可以在保存之前测试连接。凭证被加密并存储在SQLite中。

7.创建API密钥

单击连接，然后单击 “创建密钥” 在API密钥部分。立即复制密钥——它只显示一次。密钥前缀为 ac_.

8.配置内容过滤器

在连接详细信息页面上向下滚动至 内容过滤器默认情况下，所有过滤器均已启用。你可以：

• 独立切换阻止类别（安全、财务、敏感发件人）
• 切换PII编辑、电子邮件地址编辑、美元金额编辑
• 启用/禁用附件过滤和提示注入检测
• 添加自定义屏蔽域和主题关键字
• 限制代理对特定文件夹的访问

单击任何过滤器旁边的信息图标，了解其功能的详细说明。

9.连接您的AI代理

Claude代码（推荐——零安装）：

Claude Code通过HTTP直接连接到AgentCloak的MCP端点。不需要本地包或代理。

添加到单个项目（本地范围）：

claude mcp add --transport http agentcloak http://localhost:3000/mcp \
  --header "Authorization: Bearer ac_your_key_here"

全局添加（适用于所有项目）：

claude mcp add --transport http agentcloak --scope user http://localhost:3000/mcp \
  --header "Authorization: Bearer ac_your_key_here"

或编辑 ~/.claude.json 直接。Claude Code从三个作用域读取MCP服务器。 最高优先级的作用域获胜，因此只在一个作用域中配置每个服务器 以避免在更新API密钥时出现混淆。

全球 --添加到顶级 mcpServers 在 ~/.claude.json:

{
  "mcpServers": {
    "agentcloak": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer ac_your_key_here"
      }
    }
  }
}

项目本地 --在特定项目路径下添加 ~/.claude.json。当从该目录启动Claude Code时，这会覆盖全局配置：

{
  "projects": {
    "/Users/you/your-project": {
      "mcpServers": {
        "agentcloak": {
          "type": "http",
          "url": "http://localhost:3000/mcp",
          "headers": {
            "Authorization": "Bearer ac_your_key_here"
          }
        }
      }
    }
  }
}

项目共享 --创建 .mcp.json 在项目根目录中（提交给git）。使用env变量表示机密：

{
  "mcpServers": {
    "agentcloak": {
      "type": "http",
      "url": "${AGENTCLOAK_URL:-http://localhost:3000}/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENTCLOAK_API_KEY}"
      }
    }
  }
}

常见陷阱： - ~/.claude/mcp.json 不是可识别的配置文件。 不要在那里放置MCP配置。 - 不要在多个作用域中定义同一服务器。 如果agentcloak同时存在于项目本地和全局范围内，则项目本地配置将悄无声息地获胜。更新全局密钥将无效。 - 更新API密钥时，搜索 ~/.claude.json 首先确认服务器名称配置在哪个范围内。 - 重新启动Claude代码 在任何配置更改之后。MCP连接在启动时建立。

添加后，重新启动Claude Code。AgentCloak工具(search_emails, read_email等等）将自动出现。

其他MCP客户端：

任何支持Streamable HTTP传输的MCP客户端都可以连接到 http://localhost:3000/mcp 带有标题 Authorization: Bearer ac_....

对于仅支持stdio的客户端（不支持HTTP传输），请使用 @agentcloak/mcp-stdio 包装作为桥梁。

云部署（铁路）

AgentLoak可以部署到 铁路 用于多租户云托管。这允许多个用户注册，连接他们自己的电子邮件帐户，并生成API密钥，而无需在本地运行任何内容。

部署到铁路

1. 安装铁路CLI 并登录：

   brew install railway
   railway login

1. 创建项目和服务：

   railway init

1. 添加持久卷 在 /app/data （适用于SQLite数据库）：

   railway volume add --mount /app/data

1. 设置环境变量：

   railway variables set SESSION_SECRET="$(openssl rand -hex 32)"
   railway variables set BASE_URL="https://your-app.up.railway.app"
   railway variables set PORT=3000
   railway variables set DATABASE_PATH=/app/data/agentcloak.db

如果使用Google OAuth，请同时设置：

   railway variables set GOOGLE_CLIENT_ID="your-client-id"
   railway variables set GOOGLE_CLIENT_SECRET="your-secret"
   railway variables set GOOGLE_REDIRECT_URI="https://your-app.up.railway.app/auth/callback"

1. 部署：

   railway up

1. 生成公共域 从铁路仪表板或CLI。

将Claude Code连接到云部署

替换 localhost:3000 使用您的铁路URL：

claude mcp add --transport http agentcloak --scope user \
  https://your-app.up.railway.app/mcp \
  --header "Authorization: Bearer ac_your_key_here"

或在 ~/.claude.json:

{
  "mcpServers": {
    "agentcloak": {
      "type": "http",
      "url": "https://your-app.up.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer ac_your_key_here"
      }
    }
  }
}

多租户备注

• 每个用户在仪表板上使用电子邮件/密码注册，连接自己的Gmail（通过OAuth），并生成自己的API密钥。
• 如果使用Google OAuth进行Gmail连接，服务器运营商只需设置一次GCP项目。用户只需在Google Cloud Console中添加为测试用户（或者可以发布OAuth应用程序以删除此限制）。
• Apps Script连接方法是为自托管者设计的，由于谷歌的授权流，可能不适用于多租户部署。

筛选器配置

过滤器可以通过web仪表板按连接进行配置。所有设置都存储在SQLite的服务器端——代理无法访问或修改它们。每个开关都包含一个信息图标，详细解释了它的作用。

默认块列表（分为可切换的类别）：

• 40+金融领域 --银行、经纪公司、支付处理商、抵押贷款服务商（切换：金融电子邮件阻止）
• 13种敏感的发送者模式 --安全声明@、警报@、欺诈@、.gov地址等。（切换：敏感发件人屏蔽）
• 34种安全主题模式 --密码重置、2FA代码、验证电子邮件、登录警报（切换：安全电子邮件阻止）
• 24种金融主题模式 --银行对账单、付款确认书、税务文件（切换：财务电子邮件阻止）

可配置设置：

自定义规则（通过仪表板管理）：

• 自定义阻止域 --添加要阻止的发件人域（例如marketing.example.com）
• 自定义屏蔽主题关键字 --将主题行模式添加到块中（支持正则表达式）
• 允许的文件夹 --限制代理访问特定文件夹（留空以允许所有文件夹）

自定义规则也可以通过CLI进行管理：

agentcloak filters add-domain example.com --user-id 
agentcloak filters add-subject "confidential" --user-id 

CLI命令

应用程序脚本设置

Apps Script提供程序允许您在不设置Google Cloud项目的情况下连接Gmail。它不使用OAuth，而是使用部署为web应用程序的Google Apps脚本将AgentLoak连接到您的Gmail。完整的过滤器管道仍然在AgentLoak端运行——该脚本只处理Gmail API调用。

何时使用此功能： 你想要连接Gmail的最快路径，或者你不想处理谷歌云控制台、同意屏幕和测试用户管理。

何时改用OAuth： 您已经设置了Google Cloud项目，或者您不希望单独管理Apps脚本部署。

步骤

1. 在AgentLoak仪表板中，单击 “通过应用程序脚本连接”.
2. 使用唯一密钥生成脚本。点击 “复制脚本”.
3. 首选 script.google.com 并创建一个新项目。
4. 删除默认代码并粘贴复制的脚本。点击 保存 （或Ctrl/Cmd+S）。
5. 点击 跑。一个对话框将要求您授权脚本：

- 点击 “查看权限” 然后选择您的Google帐户。 - 谷歌将展示 “谷歌尚未验证此应用程序” 警告。这是意料之中的——你自己写的脚本，它不是一个已发布的应用程序。 - 点击 “高级” （在警告的左下角）。 - 点击 “转到\（不安全）” 在最底层。 - 将出现一个谷歌授权对话框，要求获得Gmail权限。 选中复选框 要授予访问权限，请单击 “继续”.

1. 脚本运行完毕后（您将在日志中看到“执行完成”），单击 部署>新部署.
2. 将类型设置为 Web 应用，“执行方式”为 我，以及“谁有权访问” 任何人.
3. 点击 部署 并复制部署URL。
4. 返回AgentLoak，粘贴URL并单击 “测试连接”。您应该看到您的电子邮件地址已确认。
5. 点击 “连接”.

该连接现在与Gmail OAuth的工作方式相同——所有相同的MCP工具、过滤器和安全功能都适用。

运作原理

生成的脚本包含一个秘密，用于验证AgentLoak和脚本之间的请求。该秘密在AgentLoak的数据库中静态加密（与IMAP凭据相同）。该脚本在您的Google帐户下运行，并使用 GmailApp 搜索、阅读和创建草稿。AgentLoak向脚本的web应用程序URL发送请求，脚本返回在到达代理之前通过AgentLoak的过滤管道的电子邮件数据。

与Gmail OAuth相比的局限性

• GAS执行限制 --Google Apps脚本对每个请求的执行时间限制为6分钟。对大型邮箱的复杂查询可能会变慢。
• 搜索最多返回500个线程 — GmailApp.search() 每个查询有500个线程上限。对于大多数用例来说，这就足够了。
• 无推送通知 --只投票。新电子邮件到达时没有实时通知。
• 脚本重新部署 --如果脚本模板在未来的AgentLoak版本中更新，则需要复制新脚本并创建新的部署。
• 结果计数已估算 --总结果计数是最小估计值，而不是精确计数。

当前限制

• 无法访问附件内容。 禁用附件筛选时，附件元数据（文件名、类型、大小）可用，但无法访问实际文件内容。这是一个具有安全意识的默认设置——PDF和图像等附件可能包含绕过基于文本的过滤器的敏感信息。
• 没有发送功能。 代理人可以创建草稿，但不能发送电子邮件。这是故意的。
• 每个API密钥的单个用户。 每个API密钥映射到一个电子邮件连接。
• 基于正则表达式的PII检测。 PII编辑使用模式匹配，而不是ML。可能会遗漏某些格式。

未来的增强功能

• 附件内容阅读 --添加a read_attachment 该工具从PDF和其他文档中提取文本，在返回代理之前通过过滤器管道运行。
• Outlook提供程序 --通过原生Outlook/Microsoft Graph支持扩展到Gmail和IMAP之外。
• 基于机器学习的注射检测 --可插拔分类器，用于更复杂的快速注射检测。
• Cloudflare Workers部署 --使用D1存储进行边缘部署。
• 审核日志记录 --记录哪些代理访问以进行合规性和调试。

用例

你今天能做什么

日常工作流程

• 电子邮件分类和优先级 --“今天什么重要？”在收件箱中进行智能排名
• 随访检测 --将发送的电子邮件与回复进行交叉引用，以查找删除的帖子和未回复的消息
• 答复草稿 --阅读上下文，撰写上下文回复，另存为草稿供您审阅
• 主题摘要 --将一个20条信息的线索压缩为关键点和行动项

研究与准备

• 会议准备 --在通话前从特定发件人或域中提取所有内容，以总结关系历史
• 求职仪表板 --跟踪各公司的申请、招聘人员外联和面试阶段
• 供应商/租户沟通审查 --总结一段时间内与物业经理、承包商或业务联系人的所有通信

分析

• 通讯摘要 --在多封时事通讯电子邮件中总结关键故事，而不是逐一阅读
• 订阅审核 --查找所有促销发件人以决定取消订阅哪些内容
• 电子邮件模式 --确定谁给你发邮件最多，标签分布，按类别列出未读数量

按比例起草

• 批量草稿回复 --起草一份简短的回复，回复过去一周所有未回复的招聘人员信息
• 模板响应 --从一个提示中生成礼貌的拒绝、感谢信或跟进

潜在的未来用例（需要增强）

高价值，适度努力：

1. 附件阅读 --解锁发票处理、合同审查、阅读转发的PDF。可能是最大的单一能力差距。需要a read_attachment PDF/文档文本提取工具通过过滤器管道运行。

1. 电子邮件组织 --标签、归档、加星、标记已读/未读。现在，代理可以告诉你该做什么，但实际上无法清理你的收件箱。添加 modify_labels 和 archive 带有确认功能的工具将实现收件箱零工作流。

1. 预定摘要 --“每天早上7点，总结隔夜电子邮件，并给我发一条Slack消息。”需要一个调度程序（cron）和一个出站集成。将AgentLoak从被动转变为主动。

1. 语义搜索 --Gmail的查询语法很强大，但很字面。像“查找有人提到推迟截止日期的电子邮件”这样的自然语言查询需要将电子邮件索引到向量存储中。

中等价值，低成本：

1. 链接提取和预览 --获取并汇总电子邮件中的URL（链接的文章、职位发布、文档），以便在不离开对话的情况下添加上下文。

1. 联系人丰富 --与谷歌联系人集成，自动知道发件人是谁以及他们的关系背景。

1. 以草稿形式转发 --创建包含原始内容的转发草稿，而不仅仅是新的电子邮件和回复。

高价值，更高努力：

1. 多账户聚合 --跨工作+个人Gmail或Gmail+IMAP的统一视图，具有每个帐户的过滤规则。

1. 实时通知 --Gmail发布/订阅推送通知，而不是轮询。启用诸如“如果我收到Meta的电子邮件，请立即通知我”之类的警报

1. 跨会话的持久内存 --通过将摘要或元数据存储在本地索引中，跟踪随时间推移的趋势（“上周你有12封招聘人员电子邮件，本周你有8封”）。

1. 日历集成 --从电子邮件中读取日历邀请，并直接创建/修改谷歌日历事件。

技术栈

• 荣誉 --HTTP框架（可跨Node、Workers、Deno、Bun移植）
• MCP-SDK --模型上下文协议服务器（流式HTTP传输）
• React+顺风CSS+Vite --Web仪表板
• 谷歌应用编程接口 -Gmail API客户端
• ImapFlow --IMAP客户端
• 更好平方3 --SQLite存储
• 佐德 --MCP工具输入的模式验证
• html转换为文本 --HTML到明文转换
• 清醒反应 --图标库

许可证

商业来源许可证1.1 --您可以自行托管用于内部使用、个人项目和非商业目的。唯一的限制是将其作为竞争性托管服务提供。2030年2月18日，代码转换为Apache 2.0。