Agent Vault 多用户权限管理终极指南：RBAC 双轴角色体系与团队协作最佳实践-迪斯科星球

Agent Vault 多用户权限管理终极指南：RBAC 双轴角色体系与团队协作最佳实践

【免费下载链接】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是一个开源的 HTTP 凭证代理与密钥保险库（credential proxy and vault），专为 Claude Code、OpenClaw、Hermes 等 AI 代理设计。本文带你快速掌握它的多用户管理与权限管理机制：通过实例角色 + 库角色构成的 RBAC 双轴体系，你可以在一个 Agent Vault 实例上安全地组织团队与代理协作，让每个成员只拥有"刚好够用"的权限。

为什么 AI 代理仓库需要细粒度权限管理 🤔

AI 代理最大的风险是凭证泄露：一旦被提示词注入，持有真实密钥的代理就可能把ANTHROPIC_API_KEY这类机密"泄露"出去。Agent Vault 的思路是让代理不持有任何真实凭证——所有请求经由代理转发，由 Vault 在服务端注入密钥。

但"谁能看凭证、谁能改服务规则、谁能审批"这件事，同样需要精细管控。这正是它的 RBAC 权限体系要解决的问题。

权限模型总览：RBAC 双轴设计

Agent Vault 把权限拆成两个完全独立的维度（详见 docs/learn/permissions.mdx）：

实例角色（Instance Roles）：管理"整个 Agent Vault 服务器"的权限
库角色（Vault Roles）：管理"某个具体 Vault 内部"的操作权限

拥有实例角色不意味着拥有库权限，反之亦然。

实例角色：owner / member / no-access

用户和代理（Agent）都有实例级角色，层级为no-access<member<owner：

能力	Owner	Member	No Access
修改实例设置（邀请模式、域名）	✅	❌	❌
管理用户（列出、删除、改角色）	✅	❌	❌
管理代理（创建、删除、轮换令牌）	✅	✅	❌
创建新 Vault	✅	✅	❌
列出 / 删除所有 Vault	✅	❌	❌
重置实例	✅	❌	❌
访问 Vault 内容	需先加入	需先加入	需先加入

💡no-access角色非常适合"只该转发流量、不该碰任何管理功能"的代理——它仍可登录、查看自己的资料，并在被授权的 Vault 内正常工作。

库角色：admin / member / proxy

每个 Vault 内部有三个角色，权限自下而上递增：

能力	Admin	Member	Proxy
使用代理、发现服务、发起 Proposal	✅	✅	✅
查看凭证名称	✅	✅	✅
直接设置 / 删除凭证	✅	✅	❌
审批 / 驳回 Proposal	✅	✅	❌
管理 Vault 服务规则	✅	✅	❌
邀请用户进 Vault、移除成员、改角色	✅	❌	❌
删除 Vault	✅	❌	❌

🎯最小权限原则的落地：绝大多数 AI 代理只需要proxy角色——能转发请求、能发起凭证申请，但改不了配置、看不到管理界面。

两个轴如何相互作用

一个直观的例子（来自官方文档）：

Alice是实例 Owner，但没加入paymentsVault → 她能在列表里看到它并随时加入，但在加入前看不到凭证、不能审批；
Bob是payments的 Vault Admin，但只是实例 Member → 他能审批该 Vault 内的所有 Proposal、管理成员，却不能创建用户或重置实例。

快速上手：创建 Owner、建库与邀请成员

第 1 步：首个用户成为 Owner

服务器启动后，第一个注册的用户自动成为实例Owner，并自动获得默认 Vault 的admin权限，无需额外配置：

第 2 步：按项目创建独立 Vault

Vault 是凭证与服务的逻辑隔离容器。建议按项目或团队各建一个（如claude-code、payments），名字用小写字母、数字和连字符：

agent-vault vault create my-vault

也可以在项目目录执行agent-vault vault init，生成agent-vault.json绑定文件并提交到代码仓库，团队所有成员和代理在该目录工作时会自动指向这个 Vault。

第 3 步：邀请团队成员

一条命令即可发送邀请，可以同时指定实例角色和 Vault 角色（相关实现见 cmd/user_invite.go）：

agent-vault user invite alice@example.com --vault my-vault:admin

配置了 SMTP 时，被邀请者会收到带浏览器接受链接的邮件；
新用户点链接设置密码即可创建账号并自动获得 Vault 授权；已有用户则立即生效；
用agent-vault user invite list查看邀请状态，用invite revoke撤销过期邀请。

第 4 步：创建代理并授予最小权限

给云端代理、CI 流水线创建一个带令牌的具名代理，并只授予proxy角色：

agent-vault agent create my-agent --vault my-vault:proxy

之后把AGENT_VAULT_TOKEN和AGENT_VAULT_ADDR注入代理的运行环境即可。

调整角色：权限变更一步到位

变更实例角色（仅 Owner 可操作）

# 提升一个用户为 Owner agent-vault owner user set-role alice@example.com --role owner # 调整代理的实例角色 agent-vault agent set-role my-agent --role member

⚠️安全护栏：Agent Vault 会阻止降级"最后一个 Owner"的操作，确保实例始终有人可管理。

变更 Vault 角色（Vault Admin 或 Owner 可操作）

agent-vault vault user set-role alice@example.com --role member --vault my-vault agent-vault vault agent set-role my-agent --role proxy --vault my-vault

Web 界面同样可以在 Users / Agents 标签页直接操作（前端实现见 web/src/pages/vault/UsersTab.tsx、web/src/pages/vault/AgentsTab.tsx）。

Owner 的跨 Vault "超级能力"

实例 Owner 拥有三个不需要 Vault 成员身份即可执行的操作：

查看所有 Vault（未加入的会显示在 "Other Vaults" 分区）；
一键加入任意 Vault：agent-vault owner vault join my-vault，以 admin 身份接管——专门用于恢复无人维护的"孤儿 Vault"；
删除任意 Vault：agent-vault owner vault delete my-vault。

注意：加入之前，Owner 依然无法查看该 Vault 的凭证——权限边界依然有效。

团队协作最佳实践清单 ✅

1. 给代理"零管理权限"生产代理统一设为：实例no-access+ Vaultproxy。它只能转发流量和发起 Proposal，碰不到任何配置。

2. 开启"仅邀请"模式，关闭公开注册通过agent-vault config set开启 invite-only 后，只有收到邀请的人才能创建账号，杜绝陌生账号注册到你的实例。

3. 用 Proposal 审批流代替"直接给凭证"proxy角色代理不能直接写凭证，但可以发起 Proposal：申请新增服务或凭证，附上说明后由member/admin在浏览器或 CLI 一键审批/驳回，7 天未处理自动过期。这是"代理自主 + 人类把关"的核心闭环。

4. 用请求日志做审计每个 Vault 都会记录经手请求的方法、端点、状态码和延迟（不含请求体等敏感内容），默认保留 7 天、每库上限 10000 行（见 docs/reference/cli.mdx）。团队成员出现异常行为时，日志就是第一现场：

5. 角色分层，人岗匹配

成员类型	建议实例角色	建议 Vault 角色
平台管理员	owner	按需加入
项目维护者	member	admin / member
普通开发者	member	member
生产 AI 代理	no-access	proxy

常见问题 FAQ

Q：Owner 能自动看到所有 Vault 的凭证吗？不能。Owner 只能"看到 Vault 列表"，必须先join才能查看凭证和审批 Proposal。

Q：把唯一的 Owner 降级会怎样？操作会被直接拒绝，Agent Vault 不允许实例出现"零 Owner"状态。

Q：代理的令牌泄露了怎么办？用agent-vault agent rotate <name>轮换令牌，配合vault agent remove把它移出对应 Vault。

企业官网建设流程全解析