1. 项目概述为你的AI助手装上“安全围栏”如果你和我一样对AI助手Agent的能力感到兴奋同时又对让它直接访问你的邮箱、日历等敏感账户感到一丝不安那么Gatelet这个项目就是为你量身定做的“安全围栏”。简单来说Gatelet是一个自托管的、基于MCPModel Context Protocol协议的权限代理。它扮演着一个“守门人”的角色坐在你的AI助手和你真实的在线服务如Gmail、Google Calendar、Outlook之间。它的核心价值在于“精细化控制”。我们不再需要纠结于是否给AI助手完整的API密钥或者担心它在处理邮件时不小心泄露了什么。通过Gatelet你可以用YAML策略文件像编写防火墙规则一样精确地定义你的助手能做什么、不能做什么甚至能在它不知情的情况下修改它发出的请求。例如你可以允许助手帮你创建日历事件但强制将所有事件的可见性设为“私密”并自动移除所有与会者或者允许它搜索邮件但自动屏蔽所有包含“密码重置”主题的邮件内容。这个项目完美解决了AI助手生态中的一个核心痛点如何在赋予其强大生产力的同时不牺牲个人数据的安全与隐私。它不是一个简单的API包装器而是一个深思熟虑的安全边界。接下来我将带你从零开始深入理解Gatelet的设计哲学、部署选择、策略配置并分享我在实际使用中积累的避坑经验。2. 核心架构与安全模型深度解析2.1 为什么是“代理”而非“库”或“CLI”在深入细节前我们必须理解Gatelet最根本的设计决策它为什么是一个独立的HTTP服务而不是一个以库Library或命令行工具CLI形式集成到AI助手进程中的组件这背后是深刻的安全隔离思想。网络隔离是核心。Gatelet作为一个独立的守护进程运行监听特定的端口默认4000和4001。你的AI助手通过HTTP协议与之通信。这意味着Gatelet运行在完全独立的进程空间和可能的用户权限下。即使AI助手进程被恶意代码或提示词注入攻击完全控制攻击者也无法直接访问Gatelet进程内存中或磁盘上存储的OAuth令牌、加密密钥和策略数据库。这种“进程间通信”的屏障是安全架构的第一道防线。对比CLI模式的致命缺陷。如果Gatelet是一个CLI工具当AI助手需要访问日历时它会直接在你的用户权限下执行gatelet create-event ...命令。这意味着共享文件系统AI助手可以读取~/.gatelet/目录下的所有配置文件可能包含加密密钥或令牌。共享进程树CLI作为AI助手的子进程其内存可能通过某些方式被父进程即被攻陷的AI助手窥探。工具可见性泄露CLI只能通过返回错误如“权限不足”来拒绝操作。但AI助手在调用命令时已经知道了“创建事件”这个工具的存在。而在Gatelet的MCP模型中未被策略允许的工具根本不会注册到MCP服务器列表中。对于AI助手来说这些“危险”的工具就像从未存在过彻底消除了试探攻击的可能性。因此Gatelet的定位非常清晰它不是一个“工具”而是一个“安全边界”。这个设计选择为后续所有的精细化控制奠定了基础。2.2 双端口设计与信任域分离Gatelet启动后会运行两个独立的HTTP服务器这是其“纵深防御”策略的体现:4000(MCP端点)这是AI助手面向的接口。它严格遵循MCP协议只暴露经过策略过滤后的工具列表。所有请求必须携带有效的API密钥Bearer Token。这个端口是攻击面设计得尽可能小且功能单一。:4001(管理面板)这是人类管理员面向的接口。用于连接OAuth账户、编写策略文件、查看审计日志、管理API密钥。访问需要更高级别的“管理员令牌”Admin Token。关键点在Docker部署中这个端口通常只绑定到127.0.0.1意味着只能从宿主机本地访问无法从外部网络甚至Docker网络内部访问。这确保了管理后台的绝对安全。这两个端口代表了两个完全不同的“信任域”。助手域:4000不可信只能进行有限操作管理域:4001是可信的进行全权管理。这种分离防止了通过AI助手接口进行提权攻击的可能。2.3 数据安全从存储到传输Gatelet在数据安全上做了多层防护静态加密Encryption at Rest所有获取的OAuth刷新令牌Refresh Token等核心凭证在存入SQLite数据库前都会使用XSalsa20-Poly1305算法来自libsodium库进行加密。加密所用的主密钥Master Key并非直接存储而是由“管理员令牌”通过HKDF-SHA256算法派生而来。这意味着只要你的管理员令牌不泄露即使有人窃取了整个数据库文件也无法解密其中的凭证。最小权限文件系统在原生主机安装模式下安装脚本会创建一个专用的系统用户如_gatelet来运行Gatelet服务。其数据目录如/var/lib/gatelet或~/.gatelet/data的权限会被设置为700即仅该用户可读、写、执行。而你日常使用的用户也是运行AI助手的用户无权访问此目录。这是操作系统级别的强制访问控制。审计一切Audit Everything所有通过:4000端口发起的工具调用无论成功与否都会被详细记录。日志包括调用的工具、原始参数、经过策略“突变”后的参数、上游API的返回结果、耗时等。这不仅是事后追溯的依据也能帮助你分析和优化策略理解AI助手的行为模式。实操心得务必妥善保管首次安装时生成的“管理员令牌”。它是你数据安全的根。建议立即将其存入密码管理器。Gatelet的设计是“无状态”的它不负责备份或恢复这个令牌。一旦丢失你将无法解密已存储的凭证只能重置整个实例即清空数据重新走OAuth流程。3. 部署方案抉择与实战配置3.1 原生主机安装 vs. Docker如何选择这是部署Gatelet时第一个也是最重要的决策点它直接关系到安全隔离的强度。项目文档给出了清晰的指引但我想结合不同AI助手的工作模式提供更具体的建议。方案一原生主机安装推荐用于“有主机访问权限”的AI助手安装命令curl -fsSL https://gatelet.dev/install-host.sh | bash工作原理脚本会创建一个名为_gateletmacOS或gateletLinux的专用系统用户和用户组并以该用户身份运行Gatelet服务。所有数据文件归该用户所有权限为700。安全隔离强度高。利用Unix/Linux系统的用户权限模型实现了严格的隔离。你的AI助手通常在你的个人用户下运行在文件系统层面完全无法读取Gatelet的数据目录。这是对抗具有主机文件访问能力的AI助手如Claude Code、Cursor等的最有效手段。适用场景你的AI助手是直接安装在操作系统上的桌面应用或CLI工具它们拥有访问你个人主目录~的权限。这是最常见的使用场景。方案二Docker安装安装命令curl -fsSL https://gatelet.dev/install.sh | sh(Linux/macOS) 或通过PowerShell脚本Windows。工作原理在~/.gatelet/目录下创建docker-compose.yml通过Docker容器运行Gatelet。管理面板端口:4001绑定到宿主机127.0.0.1MCP端口:4000仅暴露在Docker内部网络gatelet-internal中。安全隔离强度有条件的中等。Docker提供了进程和网络命名空间的隔离但无法防御拥有Docker CLI访问权限的AI助手。如果一个AI助手能在你的终端里执行命令它就可以运行docker exec -it gatelet-container-name cat /app/data/db.sqlite之类的命令来读取容器内的数据。管理员令牌文件虽然存储在宿主机上root所有但AI助手若以你的用户身份运行通常无法直接读取。适用场景你的AI助手本身也运行在Docker容器中这是最理想的Docker部署场景。你可以将AI助手的容器与Gatelet的容器加入同一个自定义Docker网络如gatelet-internal让它们通过容器名如http://gatelet:4000/mcp安全通信。此时AI助手容器没有宿主机的Docker CLI访问权限隔离是有效的。Windows系统由于Windows服务管理方式不同Docker通常是更简单统一的选择。快速测试与评估Docker部署更干净不污染主机系统用户。决策流程图你的AI助手是否以桌面应用/CLI形式直接运行在主机上 ├── 是 → 选择【原生主机安装】以获得最强文件隔离。 └── 否AI助手运行在独立的Docker容器内 → 选择【Docker安装】并配置容器网络互联。3.2 安装后关键配置步骤详解无论选择哪种安装方式完成安装脚本后都需要进行以下配置访问管理面板打开浏览器访问http://localhost:4001。页面会提示你输入“管理员令牌”。这个令牌在安装过程的终端输出中会明确显示务必复制保存。生成API密钥登录管理面板后第一步通常是生成一个用于AI助手的API密钥。在相应的界面点击生成你会得到一个长字符串的Bearer Token。这个Token将配置到你的AI助手中。连接你的账户在“Accounts”或“Integrations”页面选择要连接的提供商如Google。Gatelet贴心地提供了内置的OAuth客户端ID和密钥这意味着你不需要自己去Google Cloud Console创建项目大大降低了使用门槛。点击连接会跳转到Google的授权页面。这里你会看到一个“未经验证的应用”警告这是正常的因为Gatelet内置的OAuth应用尚未通过Google的验证流程。请仔细阅读警告内容确认请求权限的是你自己localhost然后继续授权。授权后令牌将仅存储在本地你的Gatelet实例中。配置AI助手这是将Gatelet与你的AI助手联动的关键一步。以Claude Code为例你需要编辑其配置文件通常是~/.claude.json。Gatelet管理面板通常提供了“一键配置”功能能自动检测并修改对应AI助手的配置文件。如果没有你需要手动添加一个MCP服务器配置类似如下{ mcpServers: { gatelet: { command: npx, args: [ -y, modelcontextprotocol/server-gatelet, http://localhost:4000/mcp, --token, YOUR_API_KEY_HERE ] } } }注意上述是MCP over stdio的配置示例。但Gatelet是一个HTTP服务器更标准的配置是让AI助手直接通过HTTP连接。请根据你的AI助手支持的MCP传输方式HTTP或stdio来配置。对于Claude Desktop等可能需要使用modelcontextprotocol/server-gatelet这个适配器包。3.3 关于内置OAuth凭证的深入说明Gatelet使用内置的OAuth凭证是为了用户体验的极致简化。但你必须理解其安全含义安全性这些凭证由Gatelet项目维护者申请。它们仅用于在OAuth流程中向Google/Microsoft标识Gatelet应用以便获取一个“授权码”。这个授权码会立刻被发送回你本地运行的Gatelet实例并由该实例兑换成访问令牌和刷新令牌。项目维护者无法通过这些凭证获取你的令牌或数据因为兑换令牌的请求是从你的本地网络发起的。“未验证”警告由于这是一个广泛共享的客户端ID且应用类型为“本地/桌面应用”Google无法验证每一个使用者的意图因此会显示警告。你可以安全地忽略它或者为了完全消除警告并获得更高级别的API配额如果需要你可以在管理面板的“Settings Integrations”中填入自己申请的OAuth凭证。自备凭证步骤以Google为例 a. 访问 Google Cloud Console 。 b. 创建一个新项目。 c. 启用“Gmail API”和“Google Calendar API”。 d. 在“API和服务 凭据”中创建“OAuth 2.0 客户端ID”应用类型选择“桌面应用”。 e. 将获得的客户端ID和客户端密钥填入Gatelet管理面板的对应位置。 f. 在“OAuth同意屏幕”中将测试用户添加为你自己的Google账号。4. 策略引擎精细化控制的灵魂策略文件YAML是Gatelet的核心。它定义了“谁”哪个账户能通过“什么方式”哪些操作做什么以及做的时候要受到哪些“约束”和“修改”。4.1 策略结构精读与编写实践一个完整的策略文件通常针对一个具体的提供商和账户。下面我们以一个更复杂的Google日历策略为例逐层解析# 策略文件my-work-calendar-policy.yaml provider: google_calendar # 指定提供商类型 account: work.emailcompany.com # 指定具体的已连接账户 operations: # 定义所有操作规则 list_calendars: allow: true # 允许助手查看日历列表 list_events: allow: true # 可以添加约束例如只允许查询未来30天的事件 constraints: - field: timeMin rule: must_be_one_of value: [today, tomorrow, nextWeek] # 限制时间范围参数 get_event: allow: true # 允许查看单个事件详情 create_event: allow: true constraints: # 约束1只能往“工作”日历里创建事件 - field: calendarId rule: must_equal value: work_calendar_id_here # 需要替换为实际的日历ID # 约束2事件标题不能为空 - field: summary rule: must_not_be_empty mutations: # 突变1无论助手请求如何强制设置事件为“私密” - field: visibility action: set value: private # 突变2自动移除所有与会者防止助手误发邀请 - field: attendees action: set value: [] # 突变3如果助手尝试设置超过2小时的会议则自动限制为2小时 - field: end.dateTime # 使用点号访问嵌套字段 action: cap value: 7200 # 单位秒 (2小时) # 注意这需要策略引擎支持时间差计算是一个高级用例示例 # 字段策略只允许助手传递这些字段其他字段将被静默丢弃 allowed_fields: [calendarId, summary, description, start, end, location] update_event: allow: true # 只允许更新特定字段例如不允许修改日历ID和事件ID allowed_fields: [summary, description, start, end, location] constraints: # 禁止将事件移动到其他日历 - field: calendarId rule: must_equal value: work_calendar_id_here # delete_event 操作没有被列出因此助手完全不知道有“删除事件”这个工具存在。 # 即使在Google Calendar API层面存在此功能Gatelet也不会将其暴露给助手。关键解读与经验deny by default默认拒绝这是最重要的安全原则。只有在operations下明确allow: true的操作才会被注册为MCP工具。助手无法调用未列出的操作甚至无法感知其存在。constraints约束在调用前生效如果约束检查失败整个工具调用会被Gatelet拒绝并返回一个错误信息给助手例如“calendarId must be ‘primary’, but got ‘other-id’”。这允许助手根据错误进行自我修正。mutations突变在调用前静默生效助手提供的参数会被Gatelet按照策略修改然后再发送给真实的API。助手对这一切毫不知情。这是实现安全强制的强大手段例如始终强制设置visibility: private。allowed_fields与denied_fields这是第二层过滤。allowed_fields是白名单只允许列表内的字段被传递到上游API其他字段被丢弃。denied_fields是黑名单仅丢弃列表内的字段。两者不能同时使用。通常使用allowed_fields更安全实现“最小权限”原则。4.2 邮件内容过滤器守护通信隐私对于Gmail和Outlook Mail提供商Gatelet引入了强大的内容过滤管道guards在search搜索邮件和read_message读取邮件操作返回结果前对邮件内容进行实时处理。过滤管道分为三个阶段顺序执行主题拦截Subject Blocking如果邮件主题行包含任何被屏蔽的关键词如“password reset”, “verification code”那么这封邮件的正文内容将完全不会返回给助手。助手只会知道有一封邮件被屏蔽了但无法得知其内容。这有效防止了敏感验证码被AI助手读取。发件人域名拦截Sender Domain Blocking如果发件人的邮箱域名如accounts.google.com在被屏蔽列表中整封邮件同样会被内容屏蔽。PII信息脱敏PII Redaction使用正则表达式匹配邮件正文中的敏感个人信息如社保号、信用卡号并将其替换为[REDACTED-XXX]的占位符。默认规则已足够实用Gatelet内置了一套合理的默认过滤规则涵盖了常见的密码重置、安全验证邮件主题以及Google和Microsoft官方安全通知的域名。对于大多数用户开箱即用已能提供很好的保护。自定义过滤规则你可以在策略文件的guards部分进行深度定制。例如你所在公司内部使用的特定项目代号或编号格式不希望被助手看到operations: search: allow: true guards: block_subjects: - 年度绩效评估 - 薪酬调整通知 block_sender_domains: - internal-hr.mycompany.com redact_patterns: - pattern: \\b(PRJ|BUG)-\\d{5}\\b # 匹配 PRJ-12345 或 BUG-67890 格式 replace: [REDACTED-PROJECT-REF]注意正则表达式使用JavaScript语法并且默认是全局g和不区分大小写i的匹配模式。在YAML中反斜杠需要转义所以\d要写成\\d。5. 与不同AI助手的集成实战Gatelet的兼容性依赖于MCP协议。目前越来越多的AI助手和开发环境开始原生支持或通过插件支持MCP。5.1 配置Claude Desktop / Claude CodeClaude Desktop及其内置的Claude Code是较早支持MCP的AI助手之一。配置相对直接。定位配置文件Claude的配置通常位于~/.claude.jsonmacOS/Linux或%APPDATA%\.claude.jsonWindows。手动编辑配置在mcpServers部分添加Gatelet的HTTP服务器配置。重要Claude目前主要支持通过stdio调用本地命令的方式连接MCP服务器。对于Gatelet这种HTTP服务器需要一个“桥接”服务器。Gatelet项目推荐使用modelcontextprotocol/server-gatelet这个包。{ mcpServers: { gatelet: { command: npx, args: [ -y, modelcontextprotocol/server-gatelet, http://localhost:4000/mcp, --token, YOUR_ACTUAL_API_KEY_HERE ] } } }这个桥接服务器会启动一个本地进程它通过stdio与Claude通信并将请求转发到Gatelet的HTTP端点。使用管理面板自动配置Gatelet的管理面板:4001通常有一个“Agent Setup”或类似的页面可以自动检测Claude的配置文件并帮你写入正确的配置。这是最省事的方法。重启Claude修改配置后需要完全退出并重启Claude Desktop应用新的MCP服务器才会被加载。5.2 配置Cursor IDECursor是深度集成AI的代码编辑器它也支持MCP。配置方式与Claude类似。打开Cursor设置搜索“MCP”。在MCP Servers配置中添加一个新的服务器。同样由于Gatelet是HTTP服务你可能需要配置为通过一个桥接命令来连接。具体配置格式请参考Cursor的文档。一种可能的方式是在Cursor的settings.json中添加{ mcpServers: { gatelet: { command: npx, args: [ -y, modelcontextprotocol/server-gatelet, http://localhost:4000/mcp, --token, YOUR_API_KEY ] } } }重启Cursor。5.3 配置其他MCP兼容工具如OpenClaw、Gemini CLI对于其他明确列出支持的工具如OpenClaw、Gemini CLI流程大同小异找到该工具的MCP配置文件路径如~/.openclaw/config.json。按照其配置格式添加一个指向http://localhost:4000/mcp或Docker网络内的地址的MCP服务器配置并附上API密钥。重启该工具。通用HTTP MCP配置对于任何原生支持HTTP传输的MCP客户端配置通常如下所示具体格式需查阅客户端文档{ mcpServers: { gatelet: { url: http://localhost:4000/mcp, headers: { Authorization: Bearer YOUR_API_KEY_HERE } } } }5.4 验证连接与工具发现配置完成后如何验证Gatelet是否成功连接在你的AI助手中尝试进行一个与Gatelet相关的对话例如“查看一下我今天的日历安排。”观察助手的反应。如果连接成功助手应该会调用Gatelet提供的工具如google_calendar_list_events并返回结果。你也可以在Gatelet的管理面板:4001的“Audit Log”页面查看是否有来自你助手的工具调用记录。这是最直接的验证方式。6. 高级场景、问题排查与维护6.1 多账户与多策略管理你很可能有多个Google或Microsoft账户如个人账户和工作账户。Gatelet可以同时连接多个账户并为每个账户分配独立的策略。操作流程在Gatelet管理面板的“Accounts”页面分别连接你的personalgmail.com和workcompany.com账户。创建两个策略文件例如policy-personal.yaml和policy-work.yaml分别指定不同的account字段和精细化的操作规则。在管理面板中将这两个策略文件分别关联到对应的账户。在你的AI助手配置中你仍然只使用一个API密钥。当助手调用工具时Gatelet会根据工具调用中隐含的账户上下文通常由策略绑定决定来应用对应的策略。这意味着一个AI助手实例可以通过一个Gatelet连接安全地访问多个受不同策略约束的账户。6.2 审计日志你的安全仪表盘审计日志是Gatelet的“黑匣子”也是你了解助手行为和调试策略的宝贵工具。所有通过:4000端口的调用都会被记录。日志条目通常包含时间戳调用发生的时间。工具名称被调用的MCP工具。API密钥ID用于追踪是哪个密钥发起的调用。原始参数助手最初发送的请求参数。突变后参数经过策略mutations处理后的、实际发送给上游API的参数。对比这两者是理解策略是否生效的关键。结果与错误上游API的返回结果或错误信息。耗时整个调用的处理时间。如何利用审计日志安全监控定期查看是否有异常或未授权的调用尝试。策略调试当助手行为不符合预期时查看原始参数和突变后参数检查约束是否过严或突变是否出错。性能分析观察不同工具调用的耗时判断是否是网络或API限制问题。6.3 常见问题与排查技巧问题1AI助手提示“找不到工具”或“MCP服务器连接失败”。检查步骤确认Gatelet服务正在运行运行gatelet doctor原生安装或docker compose psDocker安装查看服务状态。检查端口确认localhost:4000端口是否可访问。可以尝试curl http://localhost:4000/health如果存在健康检查端点。检查AI助手配置确认MCP服务器配置中的URL和API密钥完全正确特别是Bearer Token的格式。检查网络模式Docker如果AI助手也在Docker中确保它们在同一自定义网络如gatelet-internal中并且使用容器名gatelet而非localhost进行连接。查看Gatelet日志运行gatelet命令时添加--verbose标志或查看Docker容器日志docker compose logs -f寻找连接错误信息。问题2OAuth授权失败提示“redirect_uri_mismatch”。原因这通常发生在你使用自备的OAuth凭证但配置的回调URLredirect_uri与Gatelet实际接收回调的地址不匹配。Gatelet内置的OAuth流程使用的回调地址是http://localhost:4001/auth/callback。解决在Google Cloud Console的OAuth客户端ID配置中确保已添加http://localhost:4001/auth/callback或http://127.0.0.1:4001/auth/callback到“已授权的重定向URI”列表中。问题3策略似乎没有生效助手仍然可以执行被禁止的操作。排查确认策略文件已正确关联账户在管理面板检查账户的“Active Policy”是否是你修改后的文件。检查YAML语法一个缩进错误或冒号缺失就可能导致整个策略解析失败。可以使用在线YAML校验器检查。查看审计日志这是最直接的证据。查看对应工具调用的日志检查“Mutated Params”字段看约束和突变是否被应用。如果“Mutated Params”与“Original Params”完全一样说明策略可能未被加载或该操作未在策略中定义记住未定义即拒绝但如果操作根本未在MCP注册助手就不会调用它所以不会产生日志。这种情况需要检查助手看到的工具列表。问题4更新Gatelet后配置丢失或出错。预防与解决Gatelet的安装脚本和Docker Compose配置都设计为持久化数据。你的数据数据库、令牌、策略文件通常存储在~/.gatelet/data原生或Docker卷中。更新前建议手动备份此目录。更新脚本通常会保留该目录。如果出现问题可以停止服务从备份恢复数据目录然后重新启动服务。6.4 维护与升级原生安装升级只需重新运行安装脚本curl -fsSL https://gatelet.dev/install-host.sh | bash。脚本会检测已安装的版本并执行升级同时保留你的数据目录。Docker安装升级安装脚本默认包含了Watchtower它会每5分钟检查并自动更新镜像。你也可以手动升级进入~/.gatelet目录执行docker compose pull docker compose up -d。数据备份定期备份~/.gatelet/data目录或Docker使用的卷。这个目录包含了加密的数据库和你的策略文件。管理员令牌在首次安装时生成如果丢失将无法解密数据库。请务必将其单独安全存档。7. 扩展与未来构建你自己的ProviderGatelet的魅力之一在于其可扩展的架构。如果你希望让它支持新的服务如Slack、Notion、Jira、GitHub等可以为其开发一个新的“Provider”。Provider的核心结构 一个Provider本质上是一个实现了特定接口的Node.js模块需要定义工具Tools向MCP暴露哪些可调用的功能。每个工具对应一个API操作。策略操作映射将YAML策略中定义的operations键如list_issues映射到具体的工具实现和参数校验逻辑。OAuth集成如何与该服务的OAuth 2.0流程对接。API客户端用于实际调用该服务API的代码。开发流程简述阅读官方指南Gatelet文档网站提供了详细的 创建Provider指南 。参考现有实现src/providers/目录下的gmail、google-calendar等是绝佳的参考模板。实现接口主要需要实现getTools()返回MCP工具列表和executeTool()执行工具调用并应用策略等方法。集成到系统将新Provider注册到Gatelet的主程序中并在管理面板的UI中添加相应的连接和配置界面。社区已经有一些贡献者在尝试为Slack、Linear等工具开发Provider。如果你有特定服务的集成需求不妨参与进来或者提交Issue提出建议。Gatelet代表了一种对AI助手能力进行安全、可控扩展的务实思路。它没有试图创造一个无所不能的超级AI而是专注于为现有的、我们赖以工作的工具套上一层精细的、可编程的权限外壳。通过将策略即代码、默认拒绝、静默突变这些安全工程的最佳实践引入AI助手领域它让我们在享受自动化便利的同时能安心地睡个好觉。