news 2026/10/7 15:26:36

Agent Vault Services规则深度指南：5种认证类型与出口过滤，精准掌控AI Agent能访问哪些API

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Agent Vault Services规则深度指南：5种认证类型与出口过滤，精准掌控AI Agent能访问哪些API

Agent Vault Services规则深度指南：5种认证类型与出口过滤，精准掌控AI Agent能访问哪些API

【免费下载链接】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 是一个专为 Claude Code、OpenClaw、Hermes 等 AI Agent 打造的HTTP 凭证代理与安全保险库（Vault）。它通过 Services 规则精确声明「哪些域名可以被代理访问、以什么身份认证」，并在请求转发时由服务端自动注入真实密钥——Agent 永远看不到明文凭证。本文带你完整掌握 Agent Vault Services 规则的 5 种认证类型（bearer、basic、api-key、custom、passthrough）与出口过滤机制（主机匹配 + 严格拒绝模式 + 网络出口防护），从零开始精准掌控 AI Agent 能访问哪些 API。

1️⃣ 什么是 Services：AI Agent 的 API 访问"门禁"

当 Agent 发出一个经过代理的请求时，Agent Vault 会按以下流程处理：

  1. 匹配主机：把目标域名与 Vault 中配置的 Services 逐一比对（支持通配符、路径、端口）；
  2. 注入凭证：命中后，服务端从保险库解密对应凭据，写入请求头或替换占位符；
  3. 转发或拒绝：未命中时默认按普通代理流量放行；若开启严格拒绝模式，则直接返回403。

换句话说，一条 Service 规则 =一个访问白名单条目 + 一套认证配方。

规则定义在 YAML 文件中，核心结构只有三个字段：

services: - name: stripe # 服务名（slug，Vault 内唯一） host: api.stripe.com # 主机匹配模式（唯一的匹配字段） auth: # 认证配置（引用凭据的"键名"，而非密钥本身） type: bearer token: STRIPE_KEY

服务名name建议起得明确，如stripe、slack-bot、internal-billing；主机字段host支持四种形态：裸主机名、单级通配符（*.github.com）、内联路径（slack.com/api/*）、端口限定（internal.corp.com:3000）。

2️⃣ 五种认证类型逐一详解

auth块是每条规则的灵魂。Agent Vault 支持 5 种类型，覆盖了市面上几乎所有 API 的鉴权方式（源码见 internal/brokercore/brokercore.go，Web 端选项见 web/src/pages/vault/ServicesTab.tsx）：

① Bearer —— 最通用的 Token 认证

自动附加Authorization: Bearer <token>请求头。token字段填写 Vault 中凭据的键名。Stripe、GitHub、OpenAI 等大多数现代 API 都用这种方式。

auth: type: bearer token: GITHUB_TOKEN

② Basic —— 经典的账号密码认证

附加Authorization: Basic <base64>头，username必填，password可选（默认空）。适合 Jira、Ashby 等传统 Basic Auth 服务。

auth: type: basic username: JIRA_EMAIL password: JIRA_API_TOKEN

③ API key —— 自定义请求头的密钥认证

把凭据值放进一个自定义请求头，header省略时默认为Authorization，还支持可选前缀（如"ApiKey "）。Anthropic 的x-api-key头是典型用法：

auth: type: api-key key: ANTHROPIC_KEY header: x-api-key

④ Custom —— 自由模板，多密钥组合拳

当以上类型都不合适时，可以用{{ 键名 }}占位符模板，一次性注入多个自定义请求头，非常适合内部多租户系统：

auth: type: custom headers: X-API-Key: "{{ ACME_API_KEY }}" X-Tenant-ID: "{{ ACME_TENANT }}"

⑤ Passthrough —— 只放行、不注入

白名单主机但不注入任何凭证：客户端自带的Authorization、Cookie等请求头原样透传给上游。适用于客户端工具自己管理 Token 的场景——此时 Vault 仍提供主机白名单、TLS 拦截与审计日志。注意：passthrough 配置中出现任何凭证字段（token、key、headers等）都会触发校验错误。

💡认证密钥从哪来？所有auth配置引用的都是 Vault 里存储的凭据键名。你可以像下面这样在凭据页面统一保管，规则与密钥彻底解耦：

若某个键在 Vault 中不存在，服务写入会直接返回400错误——避免"规则已配好却认证失败"的尴尬。

进阶：Substitutions 占位符替换

有些 API 把密钥放在 URL 路径、查询串、请求体甚至 WebSocket 消息里。此时在auth旁边加一个substitutions块，Agent Vault 就会在转发前做定向替换（实现见 internal/brokercore/substitution.go）：

substitutions: - key: TWILIO_ACCOUNT_SID placeholder: __account_sid__ in: [path]

in字段是安全边界：只扫描你声明的位置。密钥只允许出现在query里，Agent 就无法通过请求体等其他位置把它偷偷带出去。

3️⃣ 出口过滤：三层防线锁住 AI Agent 的"出口"

第一层：主机匹配与优先级

host是唯一匹配旋钮，命中规则时按以下优先级确定性裁决：

  1. 精确主机 > 通配主机（api.github.com的规则永远压过*.github.com）；
  2. 指定端口 > 任意端口；
  3. 更长的字面路径前缀获胜（所以slack.com/api/apps.connections.*会赢过slack.com/api/*）；
  4. 全部打平时，先声明的规则获胜。

这意味着你可以在同一域名上叠加多套凭证——例如 Slack 的 Bot Token 管/api/chat.*、Connection Token 管/api/apps.connections.*，互不干扰。

第二层：严格拒绝模式（unmatched_host_policy）

默认情况下，未匹配任何 Service 的请求会按普通代理流量放行。如果你希望"不在白名单 = 一律拒绝"，在 Vault 设置中开启严格模式即可（设置项unmatched_host_policy=deny，策略定义见 internal/brokercore/credential.go）：

  • passthrough（默认）：未匹配 → 透传；
  • deny（严格模式）：未匹配 → 返回403，并附带proposal_hint——行为良好的 Agent 会据此自动发起**提案（Proposal）**向你申请访问权，你在浏览器里审核批准即可。

第三层：netguard 出口 IP 防护

即使主机匹配通过，Agent Vault 还会在连接层校验目标 IP，防止 Agent 借道代理攻击内网：

  • 默认阻断所有 RFC-1918 私有段、回环、链路本地、IPv6 ULA、CGN 地址段；
  • 云元数据端点（如169.254.169.254）无条件阻断，防止 SSRF 窃取云凭据；
  • 先解析 DNS → 校验 IP → 直连已验证 IP，彻底免疫 DNS 重绑定攻击；
  • 需要访问内网服务时，用AGENT_VAULT_ALLOW_PRIVATE_RANGES=true或AGENT_VAULT_NETWORK_ALLOWLIST=10.0.0.0/8精确开洞。

实现细节见 internal/netguard/netguard.go。

4️⃣ 用 CLI 管理 Services：4 个高频命令

# 从 YAML 文件整体写入（幂等，可重复执行） agent-vault vault service set -f services.yaml --vault my-vault # 交互式向导：一步步添加服务、认证与凭据引用 agent-vault vault service set --vault my-vault # 查看当前生效的规则 agent-vault vault service list --vault my-vault # 清空所有规则（清空后 Agent 全部收到 403） agent-vault vault service clear --vault my-vault

⚠️remove/enable/disable既可以传服务名也可以传裸主机名；当多条规则共享同一主机时，系统会返回409并列出候选项，改用具体name重试即可。

5️⃣ 总结：一份最小可用的完整规则

services: - name: anthropic host: api.anthropic.com auth: { type: api-key, key: ANTHROPIC_KEY, header: x-api-key } - name: github host: "*.github.com" auth: { type: bearer, token: GITHUB_TOKEN } - name: slack-bot host: slack.com/api/* auth: { type: bearer, token: SLACK_BOT_TOKEN }

核心心法：

  • 🎯最小权限：能用精确主机就不用通配符，能用路径限定就不用整个域名；
  • 🔒密钥解耦：规则只引用键名，真实密钥由 Vault 加密保管、代理时注入；
  • 🛡️严格模式：对外部署建议开启unmatched_host_policy=deny，让"提案审核"成为 Agent 获取新权限的唯一通道；
  • 🧹出口兜底：netguard 的 IP 级校验默认开启，内网与云元数据天然不可达。

更多字段说明与匹配规则的完整参考，见 docs/learn/services.mdx；安全模型（加密、限流、访问控制）见 docs/learn/security.mdx。

【免费下载链接】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），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/10/7 15:25:24

开源｜Comfort Lang v1.0.1，一款主打清爽交互的新型命令式编程语言

前言 早在之前我发布了Comfort Lang入门教程&#xff1a; Comfort Lang入门教程:一款清爽极简的自定义命令式编程语言&#xff0c;介绍了这门语言最初的设计思路与基础用法。 后续又发布了语言规范文章&#xff1a;Comfort Lang 规范正式发布!基于 Python 生态的极简命令式交互…

作者头像 李华
网站建设 2026/10/7 15:22:44

WinForms库存管理系统源码拆解：从数据库附加到事务防超卖

简介&#xff1a;这是一套基于C#语言与Winform框架的库存管理系统完整源码和数据库包&#xff0c;面向初、中级.NET开发者&#xff0c;可用于学习桌面端管理系统的分层开发与SQLite数据库应用。系统使用.NET Framework 4.7.2开发框架和SQLite3数据库&#xff0c;包含界面展示层…

作者头像 李华
网站建设 2026/10/7 15:22:41

golang结构体学习笔记(二)

package mainimport "fmt"// Hero 定义父类 type HeroA struct {name stringage int }// HeroMan 定义子类 type HeroMan struct {HeroA //HeroMan 里直接写了一个 HeroA&#xff0c;这叫匿名字段&#xff0c;也可以理解为 Go 里的组合式继承。HeroMan 并没有真正继…

作者头像 李华
网站建设 2026/10/7 15:21:07

2026年AI漫剧制作工具对比：哪款算真正的一站式工作台？

Meta描述&#xff1a; 2026年AI漫剧制作工具怎么选&#xff1f;本文从一站式工作台的四个判断标准出发&#xff0c;对比知漫剧、即梦、可灵、小云雀、豆包、LibTV&#xff0c;附两个差异化对比表格与常见问题&#xff0c;帮新手看清谁才是真正的全流程方案。 开篇首段 2026年…

作者头像 李华
网站建设 2026/10/7 15:21:07

运动补剂别盲目选！看懂全产业链实力才不踩坑

随着全民健身理念普及&#xff0c;运动营养市场规模持续扩容&#xff0c;市面上各类蛋白粉、肌酸、氨基酸补剂层出不穷。很多消费者选购时只看产品宣传、网红推荐&#xff0c;忽略品牌背后的产业链能力&#xff0c;容易买到配方粗糙、原料来源不明、品控薄弱的产品。运动营养全…

作者头像 李华
网站建设 2026/10/7 15:20:37

格式规范否？8款AI写作辅助平台榜单，毕业季救星！

论文写作是不是总让你抓耳挠腮&#xff1f;文献资料多得看不完&#xff0c;却找不到重点&#xff1f;格式排版反复修改&#xff0c;还是不达标&#xff1f; 别担心&#xff01;AI论文写作工具正成为越来越多学生的得力助手。本文将从学术规范性、文献分析能力、查重优化效果以…

作者头像 李华