别把 SaaS Token 交给 AI Agent：用 AgentGate 拆解“受限代理 + 可离线验证审计”的实现路径
让 AI Agent 调 GitHub、Slack 或 Google Workspace，最省事的方案往往也是风险最大的方案：把 OAuth access token 或长期 Bearer token 放进 Agent 的环境变量。这样 Agent 虽然立刻能工作，却同时获得了令牌代表的一整片权限；提示词注入、日志泄漏、工具参数误传和错误的自动化动作，都会从模型层问题升级为真实 SaaS 账户的操作风险。
AgentGate 是一个 Apache-2.0 许可的 Go 项目，定位不是再做一个通用 Agent 框架，而是在 Agent 与 SaaS API 之间放一层薄网关。Agent 只拿网关签发的 API key，网关负责 OAuth 回调、令牌加密存储、动作转发和审计。当前仓库提供 GitHub、Slack、Google Workspace、Stripe、Calendly 等服务配置；最新公开版本为 v0.1.3。它仍是 0.x 的早期项目，因此更适合先在受控环境验证架构和权限模型，而不是跳过安全评审直接接管生产账户。
把“能调用 API”拆成四个边界
一个更稳妥的模型是：用户把授权交给网关，Agent 只请求一个被限定的动作，网关才带着令牌调用上游。README 给出的主路径可以概括为：认证中间件校验 Agent key，服务注册表检查 service 与 action，vault 取出该用户的令牌，proxy 请求上游 API，最后写入审计记录再返回结果。
这比“把 GitHub token 交给 Agent”多了几道可独立收紧的边界。
第一，Agent key 可以按服务和用户范围约束。创建 key 时可指定 allowed_services 与 allowed_users，因此一个只负责查询仓库的 Agent 不应天然取得 Slack 或其他用户的权限。第二，动作由服务配置定义，不应让模型随意拼接任意 URL、HTTP 方法和路径。第三，OAuth 或其他 bearer token 保存在 SQLite vault 中，并由 AGENTGATE_VAULT_KEY 提供的 32 字节密钥以 AES-256-GCM 加密；Agent 的请求和响应路径不应返回 token 原文。第四，网关对每个 (agent, service) 使用 token bucket 限流，避免循环式 Agent 把错误扩散为高频 API 调用。
这些机制并不自动证明业务动作安全。例如，一个被允许的 post_message 仍可能把不该发送的文本发到不该发的频道。它们解决的是凭据暴露、授权面过宽和调用面无约束的问题；内容安全、业务审批与最小 OAuth scope 仍要由部署者自己设计。
从本地容器开始，而不是先写 Agent 插件
项目的最小启动方式是运行发布镜像并将数据目录挂载到宿主机。下面的变量名来自官方 Quickstart；示例值只用于本地演示，部署时应由密钥管理系统注入高熵随机值。
mkdir -p data docker run -d --name agentgate \ -p 8080:8080 \ -e AGENTGATE_VAULT_KEY="replace-with-a-32-byte-secret" \ -e AGENTGATE_ADMIN_SECRET="replace-with-an-admin-secret" \ -v "$PWD/data:/data" \ ghcr.io/clawdlinux/agentgate:latest
首次启动会生成一把 Agent API key，并且日志只显示一次。它应立即进入部署平台的 secret store，而不是被复制进提示词、仓库或普通日志。随后可以用一条故意尚未绑定账户的调用验证边界是否真的生效：即使没有用户 token，网关也会拒绝上游调用。
curl -s -X POST http://localhost:8080/v1/act \
-H "Authorization: Bearer $AGENTGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"service":"github","action":"list_repos","on_behalf_of":"demo-user","params":{"per_page":1}}'
在未完成 GitHub OAuth 绑定时，官方示例预期返回 token_missing。这个失败用例很重要：它说明 Agent key 不能替代用户授权，也让团队能先测试“拒绝路径”而不是一开始就接入真实账户。要启用 GitHub OAuth，还需在 GitHub 创建 OAuth App，设置回调地址为 http://localhost:8080/auth/callback/github，并向容器传入 GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET；生产环境则应配置实际的 HTTPS 公网地址和 AGENTGATE_PUBLIC_URL。
审计记录为什么值得单独设计
很多代理服务只在成功调用后记一行日志。问题是，攻击者或故障程序恰好可能反复触发失败请求；如果失败没有痕迹，审计记录会留下难以解释的空洞。
AgentGate 的特色是每次已认证的动作尝试，在响应返回前都会提交一条 receipt；README 将其描述为 Ed25519 签名、哈希链连接的连续记录。于是 token_missing 这类失败也会入账，而不只是 HTTP 200 才有审计。这个设计不能阻止错误操作发生，但能把“尝试过什么、链条是否被改写”从应用日志提升为可验证的证据问题。
验证不必依赖正在运行的网关。部署者可以先导出信任根，再让审计方对宿主机上的 SQLite 文件运行发行包内的独立验证器：
curl -s http://localhost:8080/v1/receipts/pubkey -o trust.json ./agentgate-verify --source sqlite \ --path ./data/agentgate.db \ --trust-root ./trust.json
该流程读取本地数据库与固定的 trust.json，验证时不访问网络，也不需要网关私钥。仅验证哈希链完整性仍不等于证明“没有少记录”：如果交接时另行保存某个序号与哈希检查点，可增加 --expected-head ，把验证提升为对预期链头的断言。对合规、事故复盘或跨团队交接而言，这比只保留可被覆盖的文本日志更有用。
动作白名单要成为配置审查对象
把 token 留在 vault 只是第一步；真正决定 Agent 能做什么的，是服务注册表允许哪些 action。AgentGate 将服务定义维护为 YAML 配置，网关加载合并后的服务配置，并通过 GET /v1/services 与 GET /v1/services/{name} 暴露当前可用服务和动作描述。部署时可以先用这些只读端点生成一份“能力清单”，让安全与业务负责人审核，而不是让 Agent 根据自然语言临时决定请求哪个 SaaS 路径。
以 GitHub 场景为例，读仓库列表、创建 Issue、合并 Pull Request 的风险并不相同。即便 OAuth scope 足以访问仓库，也应该把 Agent key 进一步缩到需要的用户和服务，把写入类 action 分给独立 key，并把高影响操作交给额外审批流程。一个实用的发布顺序是：先只开放查询动作，观察 receipt 中的真实调用模式；确认参数、频率和目标用户符合预期后，再以最小增量添加写操作。这样出现异常时，回滚的是一条配置或一把 key，而不是整套 SaaS 授权。
同样不要把 on_behalf_of 当作任意可填的业务标签。它是网关用来选择用户绑定 token 的身份边界，服务端应从已认证的任务上下文映射或校验该值，不能完全信任模型生成的字符串。对多租户系统尤其如此：如果 Agent 能把该字段改成另一个用户，而 key 的 allowed_users 又没有正确限制，再严密的 token vault 也无法弥补授权对象判断错误。
如何把它接进 Agent 的失败处理
网关 API 的返回结果应该进入 Agent 的显式状态机，而不是由模型根据错误文本自由发挥。对 token_missing，正确动作通常是停止该服务调用并引导账户完成授权；对限流错误，应按退避策略等待或终止任务；对上游 4xx/5xx，则保留 receipt 关联信息后进入重试、人工接管或任务失败队列。尤其不要让 Agent 在收到授权失败后改用另一个用户 ID、改换未获批准的服务，或把管理员 secret 当作“修复权限”的工具。
可以把验证器放进备份或交接作业：定期复制受保护的数据目录、固定当时的 trust root 与链头检查点，然后在隔离环境运行 agentgate-verify。这样验证的对象不仅是“网关今天还在线”，还包括“导出的审计账本是否还能被独立校验”。如果验链失败，优先冻结相关高风险动作、保全数据库副本并调查，而不是简单重启容器后忽略异常。
上线前必须补齐的控制面
第一，按 Agent 职责拆 key，不要让所有 Agent 共用管理员能力；管理员 secret 能创建 key、发起账户绑定，是高价值控制面。第二，先审查每项服务动作和 OAuth scope，再把它暴露给模型；“支持 GitHub”不代表所有 GitHub 写操作都该放行。第三，数据目录需要备份、访问控制和轮换方案：其中既有加密令牌，也有审计账本，丢失 vault key 会影响恢复，泄露 vault key 又会破坏加密边界。第四，把 /healthz、网关拒绝率、限流事件和 receipt 验证纳入运维检查，别只监控容器是否存活。
还要看到它的边界。AgentGate 不是通用 policy engine，不会自动理解一条 Issue、邮件或支付动作在业务上是否合理；它也不替代人工审批、DLP、提示词注入防护或 SaaS 自身的权限治理。项目目前处于 pre-1.0 阶段，连接器覆盖和成熟度都应在落地前逐项核验。真正值得借鉴的不是盲目多加一个网关，而是把凭据保留在用户授权层，把 Agent 的可做之事缩成明确动作，把每次尝试变成可复核的证据，并把这些约束当作 Agent 系统的默认架构。
相关链接