密钥库认证

​

结构

• 密钥库（Vault）：保险箱容器，用于分组管理密钥。
• 密钥（Credential）：保险箱内的具体密钥，每条密钥包含变量名和变量值。

​

创建密钥库

1. 在密钥库页面点击创建密钥库。
2. 填写密钥库名称，点击创建。

​

添加密钥

1. 点击密钥库名称进入详情页。
2. 在密钥列表区域点击新建密钥。
3. 填写以下字段：
   • 名称：密钥的显示名称。
   • 类型：固定为环境变量。密钥以环境变量形式供智能体引用，请求出网时由网关替换为真实值。
   • 变量名：供工具引用的键名，例如 MY_API_KEY。创建后不可修改。
   • 变量值：实际的密钥内容。保存后控制台与接口仅回显末 4 位，明文不再回传，仅在工具调用时由后端解密注入。
   • 替换位置：固定为 Authorization 请求头（Bearer）。真实密钥以 Bearer <密钥> 形式写入请求的 Authorization 头，请求体与查询参数中的占位符不会被替换。
   • 密钥替换生效域名：限制只有发往这些域名的请求才会被替换为真实密钥，其余域名只收到占位符。用逗号或换行分隔，支持 *.example.com 通配子域，最多 10 个域名。填写 * 对全部域名生效，需知悉风险并勾选确认。
4. 勾选共享凭据确认，点击创建完成。

​

密钥替换机制

1. 占位符引用：智能体在工具或 MCP 代码中通过环境变量 ${变量名} 引用密钥。例如在 Authorization 头中写入 Authorization: Bearer ${MY_API_KEY}。
2. 网关替换：请求出网时，网关检查目标域名是否在密钥替换生效域名列表中。命中则将 Authorization 头中的占位符替换为真实密钥；未命中则保留占位符原文，目标域名只收到占位符。
3. 作用范围：仅 Authorization 头中的占位符会被替换，请求体与查询参数中的占位符保持原样。
4. 主机匹配规则：精确匹配与通配匹配；匹配忽略大小写，端口不参与匹配；*.example.com 匹配其子域，不含裸域 example.com，裸域需单独列出。
5. 重定向安全：请求经重定向（3xx）跨域到密钥替换生效域名之外的地址时，重定向后的请求不再替换。

​

选择生效域名

• *（放开）：发往全部域名的请求都会替换为真实密钥，适合不需要限制密钥发送范围的场景。需知悉风险并勾选确认。
• 精确域名（限制）：如 api.example.com、*.example.com，仅发往匹配域名的请求替换为真实密钥，其余请求只收到占位符；占位符不含真实密钥，泄露也不影响密钥安全。适合密钥只应发往自有服务的场景。

​

在代码中引用密钥

import os, requests

# 读到的是占位符，无需关心真实值
token = os.environ["MY_API_KEY"]
requests.get("https://api.example.com/v1/data",
             headers={"Authorization": f"Bearer {token}"})

​

与环境变量的区别

• 使用第三方 SDK 或技能且无法确认其底层请求的鉴权方式时，网关无法保证在正确位置完成替换，请改用会话环境变量。
• 会话环境变量的真实值可被容器内代码读取或打印，可能进入日志与模型上下文，高敏感密钥请使用密钥库。

​

绑定到会话

​

下一步

• 发起会话：创建会话时绑定密钥库。
• 定义 Agent：在智能体上挂载需要鉴权的 MCP 服务或技能。