Agent Vault Proposals机制解析AI Agent如何安全地申请新凭据完整工作流图解【免费下载链接】agent-vaultA HTTP credential proxy and vault for AI agents like Claude Code, OpenClaw, Hermes, custom agents harnesses, and more.项目地址: https://gitcode.com/gh_mirrors/ag/agent-vaultAgent Vault是一个面向 AI Agent如 Claude Code、OpenClaw、Hermes 等的 HTTP 凭据代理与安全金库credential proxy and vault。当 Agent 在执行任务中需要访问一个未被授权的新服务时它不能擅自获取密钥而是通过内置的Proposals申请机制向人类发起一次结构化的变更申请由 Vault 管理员审批后才能生效。本文完整图解这一Agent 申请 → 人类审批 → 凭据注入的安全闭环。一、为什么需要 Proposals403 就是申请入口在传统架构里Agent 一旦缺少某个 API 密钥要么直接失败要么更危险地把密钥硬编码进提示词或代码。Agent Vault 的做法更优雅Agent 的所有出站 HTTP 请求都经过 Agent Vault 的代理层当目标主机不匹配Vault 中任何已配置的 Service 时代理返回一个带proposal_hint的403 响应响应体中直接告诉 Agent被拒绝的主机是什么、应该调用哪个接口创建申请POST /v1/proposals、支持哪些鉴权类型。这个403 即指引的设计让没有预装说明的 Agent 也能自发现正确的申请路径。核心逻辑见 ForbiddenHintBody。二、一个 Proposal 里有什么一条 Proposal 本质是一次结构化的变更请求最多包含三部分内容来源proposal.go组成部分说明Services新增/修改/删除允许访问哪些主机 如何鉴权的规则例如为api.stripe.com配置 Bearer TokenCredential slots凭据槽位请求人类提供STRIPE_KEY、Agent 回填一个密钥、或删除某个凭据Messages面向开发者的message 面向审批人的user_message显示在浏览器审批页凭据槽位有四种玩法见 validate.go人类在审批时填写值默认static无valueAgent 提交时就带上值创建时即加密审批时人类确认OAuth 类型审批页展示Connect按钮走授权流程或手动粘贴 Token删除action: delete移除指定凭据键一个安全细节Agent 提供的凭据值在创建申请的那一刻就被加密落库元数据中只保留has_value标记handle_proposals.go——即使数据库泄露明文也拿不走。三、完整工作流从 403 到凭据注入┌─────────────────────────────────────────────────────────────┐ │ Agent 请求 api.stripe.com │ │ │ │ │ ▼ │ │ Agent Vault 代理无匹配 Service → 403 proposal_hint │ │ │ │ │ ▼ │ │ Agent 调用 POST /v1/proposals │ │ services credentials message │ │ │ │ │ ▼ │ │ 服务端校验结构/引用/限额→ 创建 Proposal │ │ 返回 approval_urlAgent 在聊天中分享链接或邮件通知 │ │ │ │ │ ▼ │ │ 人类点击链接 → 登录 → 填写凭据 → Allow / Deny │ │ │ │ │ ├── approved → 单事务原子合并 services credentials │ │ ├── rejected → 记录拒绝原因 │ │ └── 7 天未处理 → 自动过期 (expired) │ │ │ │ │ ▼ │ │ Agent 轮询状态 → 自动重试原请求 → 请求被注入凭据成功 ✅ │ └─────────────────────────────────────────────────────────────┘1️⃣ 创建阶段先过安检请求在落库前必须通过多重校验Validate至少包含 1 个 Service 或凭据槽位且各自不超过 10 个凭据键必须是UPPER_SNAKE_CASE如STRIPE_KEY且不重复Service 中auth引用的每一个凭据键必须能解析到本次申请的槽位或 Vault 中已有凭据ValidateCredentialRefs杜绝引用了一个不存在的密钥每个 Vault 的 pending 申请上限 20 条防止 Agent 刷单式轰炸审批人。2️⃣ 审批阶段两条路径浏览器审批Agent 把形如/approve/3?tokenav_appr_...的链接发到聊天里。该 token 有效期 24 小时授予只读详情提交审批必须登录且具备 Vault 成员权限——这就是权限隔离的关键创建申请的 Agentproxy 角色不能审批自己的申请服务端显式拦截了 self-approve / self-rejecthandle_proposals.go。CLI 审批agent-vault vault proposal list --vault my-vault --status pending agent-vault vault proposal approve 3 STRIPE_KEYsk_test_abc123CLI 会展示摘要、交互式提示缺失的凭据值Agent 提供的值还支持接受或人工覆盖二选一。实现见 cmd/proposal.go。3️⃣ 生效阶段一个事务全部落库点击Allow后服务端在一把 Vault 级锁内完成加载现有 Service 配置按名称对申请项做 upsert/delete 合并MergeServices凭据值解密→用当前主密钥重新加密→写入 Vault调用ApplyProposal单事务提交服务变更与凭据变更。这意味着要么全部生效、要么完全不生效Agent 绝不会拿到一半的权限。4️⃣ 免等待Agent 自动轮询Agent 创建申请后会自动轮询状态一旦 approved 就重试原始请求——人类批准后无需任何手动操作任务自动继续。四、状态机与生命周期状态含义pending等待审批可被 approve/rejectapplied已批准并原子合并生效rejected被拒绝可附原因Agent 可读expired7 天 TTL 到期自动过期惰性过期列表查询时触发见 handle_proposals.go五、小结这套机制妙在哪里Agent 永远拿不到自己没被授权的密钥——权限提升必须经过人类审批人拿到的不是生硬 JSON而是可读的 user_message 结构化变更清单加密先行值在创建即加密、批准时重加密全程不落明文防滥用条数上限、TTL、proxy 角色禁审、引用完整性校验一应俱全。想深入了解推荐阅读 docs/learn/proposals.mdx 官方文档以及 internal/proposal/ 下的校验与合并实现、internal/server/handle_proposals.go 的完整 HTTP 处理链路。【免费下载链接】agent-vaultA HTTP credential proxy and vault for AI agents like Claude Code, OpenClaw, Hermes, custom agents harnesses, and more.项目地址: https://gitcode.com/gh_mirrors/ag/agent-vault创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考