1. 项目概述为你的AI助手装上“安全围栏”如果你和我一样已经习惯了让AI助手比如Claude Code、OpenClaw帮你处理日常事务比如查看邮件、安排日程那么一个核心的焦虑点很快就会浮现权限控制。直接把你的Google或Microsoft账户的完整API密钥交给AI无异于把家门钥匙交给一个不知疲倦但可能“手滑”的管家。它能帮你整理房间也可能一不小心把重要文件扔进碎纸机或者把私人会议邀请发给了整个通讯录。这就是我深度使用并部署了Gatelet的原因。它不是一个简单的API转发器而是一个自托管的、基于策略的权限代理。你可以把它理解为你和你的在线服务如Gmail、Google Calendar、Outlook之间的一个“智能门卫”。这个门卫手里拿着你授权的钥匙OAuth令牌但AI助手每次想进门做点事都必须先向门卫出示“工作许可”即策略文件并且门卫会严格检查它要带进去的工具API操作和材料请求参数甚至可能偷偷把一些“危险物品”比如邮件中的敏感信息替换掉再放行。它的核心价值在于精细到字段级别的控制和默认拒绝的安全模型。AI助手通过Gatelet连接后只能看到并被允许使用你在策略文件中明确列出的那几个工具。它甚至不知道“删除事件”或“永久删除邮件”这种工具的存在因为Gatelet的代码里压根就没实现这些危险操作——这是最彻底的防御。对于允许的操作你还可以设置约束比如“只能修改主日历的事件”和突变比如“自动清空所有参会者并将事件设为私密”确保AI的行为完全在你的安全边界内。2. 核心架构与安全模型深度解析2.1 双端口隔离清晰的信任边界Gatelet的架构设计首先在物理层面划清了界限。它运行两个独立的HTTP服务代理服务端 (默认端口 4000): 这是AI助手连接的地方。它实现了MCPModel Context Protocol协议对外暴露一个/mcp端点。助手通过一个API密钥Bearer Token来认证。这个服务只负责接收MCP请求、加载对应账户的策略、执行策略引擎的校验与突变最后将合规的请求转发给真正的云服务提供商Google、Microsoft。管理面板端 (默认端口 4001): 这是你人类管理员操作的地方。通过浏览器访问localhost:4001使用安装时生成的管理员令牌登录。在这里你可以连接OAuth账户、编写YAML策略文件、查看审计日志、管理API密钥等。这种分离至关重要。AI助手进程永远无法直接访问管理面板的端口也接触不到存储着加密令牌和策略的数据库文件。它只能通过定义良好的MCP接口与代理服务端通信而所有进入这个接口的请求都逃不过策略引擎的审查。2.2 策略引擎YAML定义的行为牢笼策略文件是Gatelet的灵魂它用YAML语法精确描述了“谁哪个账户能用什么操作做什么带哪些限制”。其执行逻辑遵循“最小权限原则”和“默认拒绝”。一个策略文件的生效逻辑链如下身份匹配当AI助手发起一个针对megmail.com邮箱的Gmail操作时Gatelet会找到为该邮箱配置的策略文件。操作查找在策略文件的operations块中查找对应的操作如search。默认拒绝如果该操作没有被列出Gatelet直接返回“工具不存在”给AI助手。助手不会收到“权限不足”的错误它从根本上就不知道有这个功能从而避免了试探性攻击。显式允许如果操作被列出且allow: true则进入下一步校验。约束校验检查请求参数是否满足constraints中定义的规则如must_equal,must_be_one_of。例如你可以规定创建日历事件时calendarId字段必须等于primary。如果校验失败请求会被拒绝并返回明确的错误信息如“calendarId必须为’primary’但收到的是’workgroup.calendar.google.com’”这有助于AI进行自我修正。字段过滤根据allowed_fields白名单或denied_fields黑名单规则剥离请求体中不被允许的字段。参数突变执行mutations中定义的修改。例如无论AI助手请求中写了什么都强制将attendees参会者字段设置为空数组[]并将visibility可见性设置为private。突变对AI助手是透明的它以为请求被原样执行了。审计记录将原始参数、突变后参数、最终结果和耗时完整记录到审计日志中供管理员事后审查。这种层层递进的检查机制确保了即使某个操作被允许其执行的具体方式和影响范围也完全在你的掌控之中。2.3 部署模式与安全隔离的实践权衡Gatelet提供了两种主要的部署方式原生主机安装和Docker容器安装。选择哪种方式直接关系到你的AI助手能接触到多少“底层系统”。1. 原生主机安装推荐用于桌面AI助手这是安全性最高的模式尤其适用于像Claude Code这样直接运行在你个人电脑上的AI助手。原理安装脚本会创建一个专用的系统用户在macOS上是_gateletLinux上是gatelet并以该用户身份运行Gatelet服务。所有数据数据库、加密的令牌、管理员令牌都存储在该用户的家目录下文件权限被设置为700即仅该用户可读、写、执行。安全效果你的AI助手通常以你自己的普通用户身份运行。在Unix/Linux权限模型下普通用户无法读取或修改属于_gatelet用户的文件。这意味着即使AI助手被恶意指令操控试图去读取~/.gatelet/data下的文件也会被操作系统直接拒绝。这实现了进程间基于操作系统用户级别的强隔离。2. Docker容器安装适用于容器化AI环境这种方式提供了不错的隔离性但存在一个关键假设你的AI助手没有对宿主机的Docker守护进程的访问权限。原理Gatelet运行在一个独立的Docker容器中通过Docker的网络与外部通信。管理面板端口4001通常只绑定到127.0.0.1意味着只能从宿主机本地访问。数据通过Docker卷持久化在宿主机上。安全边界如果AI助手也运行在另一个Docker容器中并通过Docker网络与Gatelet通信那么这种隔离是有效的。AI助手的容器无法直接访问宿主机文件系统上的Gatelet数据卷。关键风险如果AI助手是像Claude Code这样的“主机级”应用并且你赋予了它运行docker exec命令的权限很多开发环境默认如此那么安全模型就被打破了。AI助手可以通过docker exec -it gatelet_container cat /path/to/data.db这样的命令直接读取容器内的敏感数据。因此对于非沙盒化的主机级AI助手Docker部署提供的隔离是脆弱的。实操心得部署选择指南场景一个人电脑使用Claude Code/OpenClaw等桌面AI应用。选择原生主机安装。这是最安全、最直接的方式。运行一键安装脚本即可系统服务会自动管理Gatelet的启动和停止。场景二服务器环境AI助手运行在独立的Docker容器或虚拟机中。选择Docker安装。可以利用Docker Compose轻松管理并通过内部网络通信。确保AI助手的容器没有docker.sock的挂载卷以阻断其执行docker exec的能力。一个折中方案即使在个人电脑上你也可以选择Docker安装但需要严格限制AI助手的权限。例如在Claude Code的设置中禁用或严格审查任何涉及执行Shell命令或访问/var/run/docker.sock的功能。3. 从零开始部署与配置实战3.1 环境准备与一键安装Gatelet的安装过程非常简洁它优先考虑安全性和易用性。以下以macOS/Linux的原生安装为例这是我最推荐的方式。# 执行一键安装脚本 curl -fsSL https://gatelet.dev/install-host.sh | bash这个脚本背后做了很多事情理解它们有助于排查问题检测系统识别你的操作系统和架构如macOS arm64, Linux x86_64。下载二进制从GitHub Releases下载对应平台的最新版Gatelet可执行文件。创建系统用户和组创建一个名为_gateletmacOS或gateletLinux的专用用户和组该用户没有登录shell专门用于运行服务。创建数据目录在/usr/local/var/gatelet或类似路径创建数据目录并将其所有权和权限设置为gatelet:gatelet和700。生成管理员令牌首次运行时会生成一个高熵的随机字符串作为管理员令牌并保存在数据目录中。安装系统服务为launchd(macOS) 或systemd(Linux) 创建服务配置文件确保Gatelet在开机时自动启动并以专用用户身份运行。启动服务启动Gatelet服务并打印出管理面板的访问地址和令牌位置提示。安装完成后你会看到类似这样的输出Gatelet installed successfully as a system service. Admin dashboard: http://localhost:4001 Your admin token is in: /usr/local/var/gatelet/admin_token.txt Logs: sudo journalctl -u gatelet -f3.2 初始化配置与账户连接打开浏览器访问http://localhost:4001将admin_token.txt文件中的令牌粘贴进去即可登录管理面板。第一步创建API密钥在左侧菜单进入“API Keys”点击“Generate New Key”。为这个密钥起个名字比如“My-Claude-Desktop”。生成后务必立即复制并妥善保存这个密钥因为它只显示一次。这个密钥就是你的AI助手连接Gatelet时使用的凭证。第二步连接你的在线账户在“Accounts”页面点击“Add Account”。目前支持Google和Microsoft账户。以Google为例点击“Google”按钮会跳转到Google的OAuth授权页面。你会看到一个“未验证的应用”警告。这是正常且预期的因为Gatelet项目使用的OAuth客户端ID尚未通过Google的官方验证。请放心授权过程完全在你和Google之间进行Gatelet作为自托管服务只会将获取到的刷新令牌Refresh Token加密后存储在本地。点击“高级”-“前往gatelet不安全”。选择你要授权的账户并授予Gatelet所请求的权限如管理邮箱、管理日历。授权成功后页面会跳转回Gatelet管理面板你的账户就会出现在列表中。重要提示关于OAuth验证警告这个警告不影响安全性但可能影响用户体验。如果你希望消除这个警告可以在管理面板的“Settings” - “Integrations”中配置你自己在Google Cloud Console注册的OAuth 2.0客户端ID和密钥。这需要一些额外的配置工作但对于生产环境或注重用户体验的场景是值得的。第三步编写并绑定策略点击你刚添加的账户进入详情页。在这里你可以编辑该账户的策略YAML。Gatelet为每个服务提供商如Gmail提供了一个策略模板。你可以基于模板进行修改。一个基础的、允许AI助手读取Gmail邮件主题和发件人但屏蔽所有敏感邮件的策略如下provider: gmail account: your.emailgmail.com operations: search: allow: true guards: # 内容过滤器 block_subjects: - password reset - verification code - security alert block_sender_domains: - accounts.google.com - accountprotection.microsoft.com read_message: allow: true guards: block_subjects: - password reset - verification code - security alert block_sender_domains: - accounts.google.com - accountprotection.microsoft.com redact_patterns: - pattern: \\b\\d{3}-\\d{2}-\\d{4}\\b # 简单匹配SSN格式 replace: [REDACTED-SSN]保存策略后该账户的配置就完成了。3.3 配置AI助手连接Gatelet这是最后一步让AI助手知道Gatelet的存在。管理面板提供了便捷的一键配置功能。在“API Keys”页面找到你刚才创建的密钥点击旁边的“Configure Agent”按钮。在弹出的对话框中选择你使用的AI助手如Claude Code, OpenClaw。点击“Install Config”。Gatelet会尝试将必要的MCP服务器配置写入到该AI助手的默认配置文件中例如对于Claude Code是~/.claude.json。手动配置适用于任何MCP兼容助手如果一键配置不成功或者你使用其他助手可以手动配置。配置的本质是告诉AI助手“有一个MCP服务器运行在http://localhost:4000/mcp这是连接它的令牌。”以Claude Code (~/.claude.json) 为例配置内容大致如下{ mcpServers: { gatelet: { command: npx, args: [ -y, modelcontextprotocol/server-http-client, http://localhost:4000/mcp ], env: { MCP_SERVER_HTTP_AUTHORIZATION: Bearer YOUR_API_KEY_HERE } } } }对于原生支持HTTP MCP服务器的助手如最新版的OpenClaw配置更简单{ mcpServers: { gatelet: { url: http://localhost:4000/mcp, headers: { Authorization: Bearer YOUR_API_KEY_HERE } } } }替换YOUR_API_KEY_HERE为你在Gatelet中生成的真实API密钥。保存配置后重启你的AI助手。现在你的助手应该就能看到并使用你在Gatelet策略中允许的那些工具了例如gmail_search,google_calendar_list_events。4. 高级策略编写与内容过滤实战4.1 精细化控制约束与突变的高级用例基础的允许/拒绝只是开始约束和突变才是实现精细控制的关键。场景一日历助手只能管理“工作”日历假设你有一个专门处理工作日程的AI助手你希望它只能访问你的“Work”日历并且创建的事件默认是忙状态、且不允许修改颜色。provider: google_calendar account: work.emailcompany.com operations: list_calendars: allow: true list_events: allow: true constraints: - field: calendarId rule: must_equal value: work_calendar_id_here # 替换为你的工作日历ID create_event: allow: true constraints: - field: calendarId rule: must_equal value: work_calendar_id_here mutations: - field: transparency action: set value: opaque # 设置为“忙” - field: colorId action: delete # 禁止设置颜色 update_event: allow: true constraints: - field: calendarId rule: must_equal value: work_calendar_id_here - field: eventId rule: must_not_be_empty # 确保eventId不为空 denied_fields: [colorId, attendees] # 更新时不允许修改颜色和参会者这里work_calendar_id_here需要替换成你Google日历中“Work”日历的实际ID可以在日历设置中找到。denied_fields确保了即使AI试图在更新请求中发送这些字段也会被静默剥离。场景二邮件助手自动归档营销邮件并标记类别你希望AI助手能帮你处理订阅的新闻邮件自动将其归类到“Newsletters”标签并归档到“Read”文件夹。provider: gmail account: personal.emailgmail.com operations: search: allow: true read_message: allow: true modify_message: allow: true constraints: - field: addLabelIds rule: must_be_one_of value: [[Label_1]] # 只允许添加“Newsletters”标签的ID - field: removeLabelIds rule: must_be_one_of value: [[INBOX]] # 只允许从收件箱移除 mutations: - field: addLabelIds action: set value: [Label_1] # 强制添加“Newsletters”标签 - field: removeLabelIds action: set value: [INBOX] # 强制移出收件箱归档这个策略允许AI使用modify_message工具但通过约束限制了它只能添加或移除特定的标签再通过突变强制执行为我们预设的操作实现了自动化处理。4.2 内容过滤守护你的隐私底线Gatelet内置的邮件内容过滤器是一个强大的隐私保护工具。它分为三级流水线在邮件内容返回给AI之前进行处理。1. 主题拦截这是第一道防线。如果邮件主题行中包含任何在block_subjects列表中定义的关键词不区分大小写整封邮件的内容将被屏蔽。AI只会收到一条提示告知“此邮件因主题被策略拦截”。默认列表已经包含了许多安全相关的关键词如“password reset”、“verification code”。你可以根据你的语言和需求添加例如添加“发票”、“账单”来屏蔽财务邮件。2. 发件人域名拦截第二道防线。如果发件人的邮箱域名之后的部分出现在block_sender_domains列表中邮件同样会被屏蔽。这对于屏蔽来自特定系统如noreplyamazon.com的自动邮件非常有效。默认拦截了Google和Microsoft的账户安全域名。3. PII信息脱敏这是最后一道也是最精细的防线。它使用正则表达式匹配邮件正文纯文本部分中的敏感信息并将其替换为无害的占位符。默认规则涵盖了美国社会安全号、信用卡号等常见格式。自定义脱敏规则实战假设你在一家名为“Acme Corp”的公司工作公司内部的项目代码格式为PROJ-XXXX-YYYY你不希望AI看到这些代码。operations: read_message: allow: true guards: redact_patterns: - pattern: \\bPROJ-\\d{4}-\\d{4}\\b replace: [REDACTED-PROJECT-CODE] # 你也可以增强默认的信用卡规则匹配更多分隔符 - pattern: \\b(?:\\d[ -]*?){13,16}\\b replace: [REDACTED-PAYMENT]pattern字段使用JavaScript正则表达式语法。\\b表示单词边界\\d表示数字{4}表示重复4次。(?: ... )是非捕获分组[ -]*?匹配零个或多个空格或短横线非贪婪模式。这个更宽泛的规则可以匹配4111-1111-1111-1111或4111 1111 1111 1111等格式。注意事项正则表达式的性能与准确性过于复杂的正则表达式可能会影响邮件解析速度尤其是在处理大量邮件时。建议先在正则表达式测试工具如regex101.com上验证你的模式确保其准确性和性能。同时脱敏发生在Gatelet服务器端这意味着原始邮件在提供商服务器上并未被修改只是AI看到的内容被处理了。5. 运维、监控与故障排查5.1 服务管理与更新原生安装的更新更新原生安装的Gatelet非常简单只需重新运行安装脚本。脚本会检测新版本下载并替换二进制文件然后重启系统服务。你的数据和配置存储在/usr/local/var/gatelet或类似路径会被完整保留。curl -fsSL https://gatelet.dev/install-host.sh | bashDocker安装的更新如果你使用Docker安装安装脚本默认会配置Watchtower容器它每5分钟检查一次镜像更新并自动重启容器。你也可以手动更新# 进入Gatelet的Docker Compose目录 cd ~/.gatelet # 拉取最新镜像 docker compose pull # 重启服务 docker compose up -d5.2 利用审计日志进行监控与调试Gatelet的审计日志是排查问题和监控AI行为的宝贵工具。所有通过MCP接口的调用都会被记录。你可以在管理面板的“Audit Log”页面查看。每一条日志记录包含时间戳请求发生的时间。操作调用的工具名称如gmail_search。账户操作针对的邮箱地址。状态成功 (allowed)、被策略拒绝 (denied)、约束校验失败 (constraint_failed) 或运行时错误 (error)。原始参数AI助手最初发送的请求参数。突变后参数经过策略引擎处理应用了约束、字段过滤、突变后的实际参数。对比这两项你可以清楚地看到策略生效的具体细节。结果摘要/错误信息对于成功的操作会记录返回结果的部分信息如事件ID、邮件数量对于失败的操作会记录具体的错误原因。耗时处理该请求所花费的时间。调试案例假设AI助手报告无法创建日历事件。打开审计日志找到最近一条google_calendar_create_event的记录。查看其状态。如果是constraint_failed错误信息会明确告诉你哪个字段违反了哪条规则。如果是denied说明该操作在策略文件中未被列为allow: true。如果是error可能是网络问题或上游API错误查看错误信息进行判断。对比原始参数和突变后参数确认突变规则是否按预期工作例如参会者列表是否被清空。5.3 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案AI助手无法连接Gatelet1. Gatelet服务未运行。2. 防火墙阻止了端口4000。3. AI助手配置错误。1. 运行sudo systemctl status gatelet(Linux) 或sudo launchctl list | grep gatelet(macOS) 检查服务状态。重启服务sudo systemctl restart gatelet。2. 检查本地防火墙设置确保端口4000可访问。3. 检查AI助手的MCP配置确认URL (http://localhost:4000/mcp) 和API密钥Bearer Token正确无误。管理面板无法访问1. 服务未运行。2. 使用了错误的端口应是4001。3. 管理员令牌错误。1. 同上检查服务状态。2. 确认访问地址是http://localhost:4001。3. 确认粘贴的令牌与admin_token.txt文件内容完全一致注意首尾空格。OAuth授权失败1. 网络问题。2. Google/Microsoft的OAuth应用未配置或配额超限使用自建OAuth时。3. 浏览器Cookie或缓存问题。1. 检查网络连接。2. 如果使用自建OAuth客户端请确保在Google Cloud Console / Microsoft Azure Portal中已正确配置重定向URIhttp://localhost:4001/oauth/callback且API已启用。3. 尝试使用浏览器无痕模式进行授权。AI助手看不到任何工具1. 账户未连接或策略未配置。2. API密钥未关联账户或关联的账户策略全部为deny。3. MCP服务器连接成功但工具列表为空。1. 登录管理面板确认目标账户已成功添加且状态为“已连接”。检查该账户的策略文件确保至少有一个操作的allow: true。2. 在“API Keys”页面检查该API密钥是否关联了正确的账户。3. 查看Gatelet服务日志检查MCP服务器启动时是否报错。操作被拒绝但AI助手显示“工具不存在”这是预期行为。该操作在策略文件中未被列出触发了“默认拒绝”和“隐藏工具”机制。登录管理面板编辑对应账户的策略文件在operations下添加该操作并设置为allow: true如果需要的话。操作被拒绝AI助手收到具体错误如约束失败策略中的constraints规则未满足。根据AI助手收到的错误信息如“field ‘calendarId’ must equal ‘primary’ but got ‘work’”修改请求参数或调整策略中的约束条件。审计日志中有详细记录。邮件内容显示[REDACTED]邮件触发了内容过滤器的拦截或脱敏规则。检查该邮件的主题、发件人域名或正文内容看其是否匹配了策略中guards块定义的block_subjects、block_sender_domains或redact_patterns。根据需要调整过滤规则。5.4 使用gatelet doctor进行健康诊断Gatelet内置了一个诊断工具可以帮助你快速检查运行环境。# 运行所有检查 gatelet doctor # 尝试自动修复可修复的问题 gatelet doctor --fix # 以JSON格式输出便于脚本处理 gatelet doctor --json诊断项目通常包括服务状态Gatelet主服务和管理面板服务是否在运行。端口占用4000和4001端口是否被正确监听。数据目录权限检查数据目录的所属用户和权限是否正确应为专用用户和700权限。数据库可访问性SQLite数据库文件是否可正常读写。网络连通性是否可以访问必要的OAuth端点accounts.google.com, login.microsoftonline.com。定期运行doctor命令是一个好习惯尤其是在升级系统或修改了网络配置之后。