企业官网建设流程全解析

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-vault

Agent Vault是一个面向 AI Agent（如 Claude Code、OpenClaw、Hermes 等）的 HTTP 凭据代理与安全金库（credential proxy and vault）。当 Agent 在执行任务中需要访问一个未被授权的新服务时，它不能擅自获取密钥，而是通过内置的Proposals（申请）机制向人类发起一次结构化的"变更申请"，由 Vault 管理员审批后才能生效。本文完整图解这一"Agent 申请 → 人类审批 → 凭据注入"的安全闭环。

一、为什么需要 Proposals：403 就是"申请入口"

在传统架构里，Agent 一旦缺少某个 API 密钥，要么直接失败，要么（更危险地）把密钥硬编码进提示词或代码。Agent Vault 的做法更优雅：

1. Agent 的所有出站 HTTP 请求都经过 Agent Vault 的代理层；
2. 当目标主机不匹配Vault 中任何已配置的 Service 时，代理返回一个带proposal_hint的403 响应；
3. 响应体中直接告诉 Agent：被拒绝的主机是什么、应该调用哪个接口创建申请（POST /v1/proposals）、支持哪些鉴权类型。

这个"403 即指引"的设计，让没有预装说明的 Agent 也能自发现正确的申请路径。核心逻辑见 ForbiddenHintBody。

二、一个 Proposal 里有什么？

一条 Proposal 本质是一次结构化的变更请求，最多包含三部分内容（来源：proposal.go）：

凭据槽位有四种玩法（见 validate.go）：

• 人类在审批时填写值（默认static，无value）
• Agent 提交时就带上值（创建时即加密，审批时人类确认）
• 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_url，Agent 在聊天中分享链接（或邮件通知） │ │ │ │ │ ▼ │ │ 人类点击链接 → 登录 → 填写凭据 → 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?token=av_appr_...的链接发到聊天里。该 token 有效期 24 小时，授予只读详情；提交审批必须登录且具备 Vault 成员权限——这就是权限隔离的关键：

创建申请的 Agent（proxy 角色）不能审批自己的申请，服务端显式拦截了 self-approve / self-reject（handle_proposals.go）。

CLI 审批：

agent-vault vault proposal list --vault my-vault --status pending agent-vault vault proposal approve 3 STRIPE_KEY=sk_test_abc123

CLI 会展示摘要、交互式提示缺失的凭据值，Agent 提供的值还支持"接受或人工覆盖"二选一。实现见 cmd/proposal.go。

3️⃣ 生效阶段：一个事务，全部落库

点击Allow后，服务端在一把 Vault 级锁内完成：

1. 加载现有 Service 配置；
2. 按名称对申请项做 upsert/delete 合并（MergeServices）；
3. 凭据值解密→用当前主密钥重新加密→写入 Vault；
4. 调用ApplyProposal单事务提交服务变更与凭据变更。

这意味着要么全部生效、要么完全不生效，Agent 绝不会拿到"一半的权限"。

4️⃣ 免等待：Agent 自动轮询

Agent 创建申请后会自动轮询状态，一旦 approved 就重试原始请求——人类批准后无需任何手动操作，任务自动继续。

四、状态机与生命周期

五、小结：这套机制妙在哪里

• 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