Wundervault 保险库

Wundervault 是一个加密的、可自托管的密钥保险库，通过 MCP 工具向 agent 暴露密钥。密钥**绝不会出现在聊天窗口中**——它们在服务端解密后，直接注入命令或写入配置文件。密钥的明文内容永远不会返回给 agent。

首先检查设置状态

执行任何与保险库相关的操作前，请务必先调用 vault_entries_list。根据其返回结果判断用户当前所处的设置阶段：

首次运行接入流程（First-run onboarding）

若保险库相关工具缺失或凭据无效，请向用户说明：

“Wundervault 尚未配置完成。请按以下步骤开始：

1. 通过联系表单申请访问权限
2. 获批后，在 wundervault.com 上完成账户设置并接入您的 agent
3. 使用 wundervault.com/install 页面提供的校验和验证 MCP 服务包完整性
4. 返回此处，我将为您验证连接状态”

在 vault_entries_list 成功返回前，**不得尝试调用任何保险库工具**。

工具说明

vault_entries_list

列出当前 agent 可访问的所有保险库条目。仅返回条目 ID 和名称 —— 不包含任何密钥值。

vault_entries_list()
→ [{ id: "abc123", name: "ResendApiKey", tier: "full" }, ...]

请始终优先调用此工具获取目标条目 ID，再调用其他工具。

vault_entry_get

检索并销毁（burn）一个密钥。该密钥在服务端解密，明文永不返回至 agent —— 您仅会收到销毁确认信息。

vault_entry_get(entry_id: "abc123", purpose: "confirm secret exists")
→ "✅ Secret retrieved and burned."

此工具仅用于确认密钥存在或确认已成功读取。如需在命令或文件中实际使用密钥，请改用 vault_exec 或 vault_entry_inject_env。

vault_exec

以环境变量形式注入保险库密钥后执行 Shell 命令 —— 密钥不会在聊天记录或日志中暴露。

vault_exec(entry_id: "abc123", purpose: "publish package", command: "npm publish --access public")

支持两级访问控制：

• 第 1 级（标准）：立即执行
• 第 2 级（受限）：调用被拒绝，直至所有者批准。拒绝响应中包含请求 ID，系统将自动向所有者发送邮件；批准范围严格限定于当前 agent + 当前密钥（单次有效，或 15/60 分钟有效期）。批准后请重试 —— 此类拒绝不应视为错误。

在密钥解密前，Shell 转义序列（如 $()、反引号、bash -c、eval）及文件写入重定向（如 >、>>、tee）均被硬性拦截。如需将密钥写入文件，请使用 vault_entry_inject_env —— 切勿通过 Shell 重定向实现。（这些拦截是安全防护措施，而非沙箱机制；真正的安全保障在于：明文永不返回至您。）

通过 SSH 远程执行：传入 remote_host 参数即可在远程主机上运行命令。密钥通过 SSH stdin 注入远程 Shell —— 远程主机无需配置 AcceptEnv/SendEnv。可使用 ssh_key_entry_id 从保险库中加载 SSH 密钥。

vault_exec(
  entry_id: "abc123",
  purpose: "check subscribers on prod",
  command: "curl -s -u "admin:$DB_PASSWORD" http://localhost:9000/api/subscribers",
  inject_as: { env_key: "DB_PASSWORD" },
  remote_host: { host: "192.168.1.50", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" }
)

仅使用 SSH 密钥（不注入密钥）的远程命令： entry_id 为可选参数。若仅需使用保险库中的 SSH 密钥在远程主机执行命令（不注入任何密钥作为环境变量），请省略 entry_id 并传入 remote_host.ssh_key_entry_id。

vault_exec(
  purpose: "restart the service on prod",
  command: "sudo systemctl restart wundervault",
  remote_host: { host: "prod.example.com", user: "opc", ssh_key_entry_id: "ssh-key-entry-id" }
)

vault_entry_inject_env

将密钥直接写入环境文件（.env）作为环境变量，全程不经过聊天窗口。

默认禁用。 如需启用此工具，请在 wundervault.com 的「Settings > Agent Capabilities」中开启。您可随时再次禁用。

vault_entry_inject_env(
  entry_id: "abc123",
  purpose: "inject API key into app config",
  file_path: "/home/user/app/.env",
  env_key: "RESEND_API_KEY"
)

注意：file_path 和 env_key 是正确的参数名。

启用理由： 直接将密钥写入 .env 文件是配置应用、容器及部署流水线的标准方式。若不启用此工具，您需手动粘贴密钥 —— 这会使密钥暴露于终端或聊天历史中。vault_entry_inject_env 允许 agent 自动化注入凭据，同时确保明文完全不出现在对话中。

启用前须知风险：

• agent 可将密钥写入其可访问的任意 .env 路径 —— 包括项目目录之外的位置
• 若 agent 被攻破或受恶意提示诱导，可能将凭据注入非预期位置
• 写入的密钥不再具备“读即焚”（burn-on-read）特性 —— 它们将持久化存储于目标文件中
• .env 文件的权限由您自行负责；该工具仅写入值，不会自动设置严格权限

vault_rsync

通过 SSH 使用 rsync 将本地目录同步至远程主机，SSH 密钥从保险库获取。密钥在传输期间临时写入文件，并在传输完成后立即删除。

vault_rsync(
  ssh_key_entry_id: "ssh-key-entry-id",
  purpose: "deploy static files to prod",
  local_path: "/home/user/app/dist/",
  remote_user: "opc",
  remote_host: "prod.example.com",
  remote_path: "/var/www/html"
)

vault_entry_forget

从上下文中丢弃某保险库条目的引用。此操作不会删除保险库条目本身。

vault_entry_forget(entry_id: "abc123")
→ ✔️ Reference discarded.

常见使用模式

使用密钥执行命令（第 1 级）：

1. vault_entries_list() → 查找所需密钥的条目 ID
2. vault_exec(entry_id: "abc123", purpose: "...", command: "...")

使用第 2 级条目执行命令（部署、发布、基础设施变更）：

1. vault_entries_list() → 查找条目 ID
2. vault_exec(entry_id: "abc123", purpose: "...", command: "...")

注意：第 2 级调用在 wundervault.com 控制台获得所有者批准前将被拒绝 —— 所有者将自动收到邮件通知，拒绝响应中包含请求 ID。请在批准后重试。

使用保险库中保管的钱包密钥签署 x402 支付（您永远看不到该密钥）：

1. vault_entries_list() → 查找钱包密钥条目（建议将钱包密钥设为第 2 级）
2. vault_exec(entry_id: "...", purpose: "sign x402 payment for ", command: "node sign-payment.mjs", inject_as: { env_key: "X402_WALLET_KEY" })
3. 若被拒绝并附带请求 ID？所有者已收到邮件 —— 请待其批准后重试。

签名脚本从环境变量中读取密钥，并仅输出已签名的 X-PAYMENT 头部。一次经验证的端到端完整流程（402 → 审批 → 签名 → 在 Base Sepolia 上结算）示例见 wundervault.com/agent-wallets。

将密钥写入配置文件：

1. vault_entries_list() → 查找条目 ID
2. vault_entry_inject_env(entry_id: "abc123", purpose: "...", file_path: "/app/.env", env_key: "MY_KEY")

向远程服务器部署文件：

1. vault_entries_list() → 查找 SSH 密钥条目 ID
2. vault_rsync(ssh_key_entry_id: "...", local_path: "./dist/", remote_user: "opc", remote_host: "prod.example.com", remote_path: "/var/www/html")

多 agent 配置

Wundervault 专为多 agent 环境设计。每个 agent 拥有独立的、作用域受限的身份标识与令牌 —— 在守护进程（daemon）层面彼此完全隔离。

• 每个 agent 使用专属令牌文件进行身份认证（~/.wundervault/agents/{AgentName}.token）
• agent 仅能访问被显式授权的条目
• 保险库所有者通过 wundervault.com 控制台管理 agent 列表及其访问权限
• agent 无法查看彼此的令牌、身份或访问范围
• 审计日志按 agent 分离，您可精确追溯任一 agent 访问了哪个密钥及具体时间

这使得 Wundervault 非常适用于多个专业化 agent（如编码 agent、部署 agent、合作伙伴 agent 等）共享基础设施但必须严格隔离凭据的场景。

安全说明

• 密钥端到端加密；明文永不返回至 agent
• “零知识”（zero-knowledge）声明可独立验证 —— 无需源码访问：wundervault.com/verify（提供浏览器 DevTools 操作指南或 mitmproxy canary 测试，含公开记录）
• 接入脚本启动时自动验证自身 ed25519 签名，校验失败则退出。管道模式（curl ... | python3）被硬性拦截 —— 脚本可检测该模式并拒绝运行。固定版本、SHA-256 校验和及公钥均公布于 wundervault.com/install。
• agent 从不直接持有凭据 —— 仅本地存储作用域受限的令牌。本地守护进程管理真实凭据，并仅通过受控接口暴露，每次请求均强制执行分级检查与审计日志记录。即使 agent 令牌泄露，也无法直接访问保险库凭据。
• vault_exec 和 vault_rsync 是使用密钥的正确工具 —— vault_entry_get 不适用于此目的
• 第 2 级条目由保险库所有者配置；agent 无法将第 1 级条目提权
• 第 2 级访问权限由用户在 wundervault.com 控制台服务端启用
• inject_as 覆盖参数允许您指定接收密钥的环境变量名（当保险库条目未配置 exec_config 时）

更多信息

• npm 包：@wundervault/mcp-server
• 保险库 Web UI：wundervault.com