核心用法
Clawvisor 是一款面向 AI Agent 的安全代理网关，核心功能是将外部服务（Gmail、Calendar、Drive、GitHub、iMessage 等）的 API 调用封装在受控的授权框架内。Agent 需通过标准 REST API 与 Clawvisor 交互：首先拉取服务目录确认可用动作，然后创建「任务（Task）」声明本次工作流的意图与授权范围，最后通过 Gateway 发送具体请求。
任务级授权（Task-Scoped Auth） 是 Clawvisor 的核心设计。每个任务需声明 purpose（工作流目的）、authorized_actions（允许的动作列表，含 auto_execute 开关）、expected_use（预期使用场景）及过期时间。任务创建后进入 pending_approval 状态，必须经用户批准后方可生效。对于高频重复场景，可创建 Standing Task（持久任务），一次审批、长期生效，但需配合 session_id 使用以支持链式上下文验证。
Gateway 请求 必须携带 task_id、reason（自然语言说明请求意图）、request_id（唯一标识）及可选的 session_id。reason 字段经 LLM 意图验证，需描述「做什么」和「为什么」，禁止出现「用户让我做的」等易被判定为提示注入的表述。支持批量请求（最多 20 个子请求）以优化性能。
人机审批流 设计精细：auto_execute: true 的动作在任务获批后自动执行；auto_execute: false 的动作（如发送邮件、删除数据）需逐次人工确认。用户可通过 Clawvisor Dashboard 设置 Restrictions（硬性阻断规则），优先级高于任务授权。
显著优点
- 零密钥暴露：Agent 全程不接触真实 API 密钥，所有凭证由 Clawvisor 托管并注入下游请求，从根本上消除密钥泄露风险。
- 意图可审计：每次请求附带
reason，经 LLM 验证并与任务目的比对，形成完整审计链条，满足企业合规要求。 - 链式上下文验证（Chain Context Verification）：自动追踪实体 ID（邮件 ID、事件 ID 等）的流转路径，防止中间人攻击或提示注入导致的越权操作（如读取 A 邮件后向 B 地址发送敏感信息）。
- 灵活的权限模型：支持临时任务（ephemeral）、滑动窗口任务（sliding TTL）及持久任务（standing），适配从单次查询到长期自动化助理的多种场景。
- 企业级安全特性：支持批量请求、速率限制、多账户并发、数据溯源标记（
data_origin）及详细的机器可读错误码。
潜在缺点与局限性
- 交互延迟：人工审批环节引入不可避免的等待时间，
?wait=true最长阻塞 120 秒，复杂工作流可能因多次审批而显著变慢。 - 使用门槛较高：开发者需深入理解任务授权、意图验证、链式上下文等概念，REST API 设计较复杂，初期集成成本高于直接调用官方 SDK。
- 生态依赖：目前支持的服务限于文档列出的 Google 套件、GitHub、iMessage（macOS），扩展新服务需等待官方适配或自行开发 Adapter。
- 误杀风险：LLM 意图验证可能对模糊的
reason描述判定为REASON_TOO_VAGUE或restricted，要求开发者精心打磨提示词。 - 自托管复杂性：开源版本需自行部署维护，涉及凭证管理、高可用、审计日志存储等运维负担。
适合人群
- 企业 AI 团队：需要为内部 Agent 系统添加安全网关，满足最小权限原则与审计合规要求。
- 高敏感场景开发者：处理用户私有数据（邮件、日历、代码仓库）且无法承担密钥泄露后果的 AI 应用。
- Agent 平台构建者：希望将「人机协作审批」作为核心 UX 的多 Agent 系统架构师。
- 安全意识极强的个人用户：愿意牺牲一定便利性换取对 AI 助手操作范围的细粒度控制。
常规风险
- Agent Token 泄露：
CLAWVISOR_AGENT_TOKEN为高权限凭证，一旦泄露攻击者可访问所有已激活服务，必须严格轮转与最小权限分配。 - 提示注入绕过：尽管有
reason验证与链式上下文，精心设计的对抗性提示仍可能试图操控审批流，需结合data_origin溯源与人工复核。 - 持久任务失控：Standing Task 长期有效，若用户未及时撤销且 Agent Token 被盗，攻击者可长期潜伏操作。
- 错误处理不当：开发者若未正确处理
pending、blocked、restricted等状态，可能导致用户体验断裂或安全决策被静默忽略。 - 供应链风险：自托管场景下，Clawvisor 本身的漏洞、依赖库更新或配置错误可能成为新的攻击面。