跳转到主要内容
Agent 经常需要访问第三方服务——GitHub、Jira、数据库、自建 MCP 服务器等。Vaults 提供安全的凭证托管，让你把 Token 交给我们保管，Session 运行时按需注入，无需硬编码在代码里。

​
核心概念

概念说明
Vault凭证容器，可包含多个 Credential
Credential单条凭证记录，绑定到具体 MCP 服务器 URL
auth.type凭证鉴权类型：static_bearer、mcp_oauth 或 environment_variable
vault_idsSession 创建时引用的 Vault ID 列表

​
安全性

  • access_token永远不会在 API 响应中返回
  • token、refresh_token、client_secret、secret_value 等其他密文也永远不会返回
  • 凭证在服务端加密存储
  • 仅关联的 Session 可在运行时访问凭证内容

​
完整流程

1

创建 Vault

curl -X POST https://api.qoder.com/api/v1/cloud/vaults \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "我的 GitHub 凭证",
    "metadata": {}
  }'
响应示例：
{
  "id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
  "type": "vault",
  "display_name": "我的 GitHub 凭证",
  "credentials": [],
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-18T08:00:00Z",
  "updated_at": "2026-05-18T08:00:00Z"
}
2

追加 Credential

使用 nested auth 对象为 Vault 追加凭证：
curl -X POST https://api.qoder.com/api/v1/cloud/vaults/vault_019e5cdb9c3f71c3b6505eba937a40b4/credentials \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": {
      "type": "static_bearer",
      "mcp_server_url": "https://jira.example.com/mcp",
      "token": "jira_token_xxxxxxxx"
    }
  }'
响应返回 type: "vault_credential" 和经过脱敏的 auth 对象，不包含任何密钥明文。
3

在 Session 中使用

创建 Session 时通过 vault_ids 关联：
curl -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_xxx",
    "vault_ids": ["vault_019e5cdb9c3f71c3b6505eba937a40b4"]
  }'
Session 运行时，Agent 将自动获得 Vault 中所有 Credential 的访问权限，用于连接对应的 MCP 服务器。

​
参数说明

参数类型必填说明
display_namestring是Vault 显示名称
metadataobject否自定义元数据
auth.typestring创建凭证时必选static_bearer、mcp_oauth 或 environment_variable
auth.mcp_server_urlstringMCP 凭证必填MCP 服务器地址
auth.tokenstringstatic_bearer 必填Bearer Token 值，只写

​
常见问题

Q: 能否更新已有 Credential 的 Token？ A: 可以通过删除旧 Credential 并重新创建实现轮换。 Q: 一个 Session 可以关联多少个 Vault？ A: 没有硬性限制，但建议按服务分组管理，保持清晰。 Q: Token 泄露了怎么办？ A: 立即删除对应 Credential 并在第三方平台吊销 Token，然后创建新的 Credential。 Q: 我能查看已存储的 Token 吗？ A: 不能。出于安全考虑，credential 密钥为只写（write-only），写入后不可读取，只能删除后重建。
建议为不同环境（开发/生产）创建独立的 Vault，避免混用凭证。

​
下一步

启动 Session

管理会话生命周期。

Memory Stores

让 Agent 拥有跨 Session 的持久记忆。

定义 Agent

回顾 Agent 配置。

Agent 工具

为 Agent 配备内置、MCP 和自定义工具。