文档中心
费用中心控制台

轮换凭证并撤销访问 ​

连接 AI 助手

本页适合负责生产智能体模板、智能体实例、外部集成或渠道账号的用户。执行轮换前，应能修改受影响的智能体模板、智能体实例、MCP 实例或渠道账号，并能更新实际调用方保存的密钥。

智能体开发服务平台（AgentWorks）保存运行所需的凭证。有权限的用户可以从控制台再次复制模型 API Key；Token 明文只在创建或重置时显示一次。请使用组织现有的密钥管理流程保存源凭证、审批记录、轮换计划和泄露处置记录；AgentWorks 中的凭证仍按本页步骤逐项更新。

识别凭证的所有者 ​

打开 凭证管理。相关页签和配置管理不同对象：

页签或凭证绑定对象和使用位置并行轮换
模型凭证租户内模型服务凭证；由智能体模板及其智能体实例使用可以创建替代凭证；原凭证的 API Key 不可直接修改
对象存储凭证租户内沙箱存储挂载；同一沙箱表单的所有挂载点共用一个凭证创建替代凭证并迁移挂载；存储类型、AccessKey ID 和 Secret Access Key 不可原位替换
MCP HeaderMCP 模板或实例；用于 MCP Server 请求取决于 MCP Server 是否同时接受新旧凭证
飞书或 QQ 应用密钥一个渠道账号；用于对应渠道连接不支持在一个账号内并行保存两组密钥
WebSocket Token，wst_一个 WebSocket 渠道账号；用于调用智能体的 HTTP 请求与 WebSocket 握手可以为同一渠道账号创建多个 Token

wst_ 不直接绑定智能体模板或智能体实例。渠道账号通过 绑定 Agent 实例（默认） 或 绑定 Agent 模板 设置绑定目标，Token 用于该账号的 HTTP 请求和 WebSocket 订阅。因此，创建和查看 WebSocket Token 时，只需选择 绑定 WebSocket 渠道账号。

轮换模型 API Key ​

现有模型凭证只能修改名称和默认模型，不能替换 API Key。使用替代凭证完成轮换：

  1. 打开 凭证管理，在 模型凭证 中选择 新建凭证。

    打开凭证管理

  2. 在 凭证名称 中输入当前租户内未被占用的新名称，输入 API Key，选择 获取模型列表，再选择 创建凭证。

  3. 对新凭证执行 测试连通性。

  4. 找出引用原凭证的每个智能体模板，改为新凭证并选择 保存修改。

  5. 逐个对受影响的智能体实例选择 编辑，检查参数后选择 保存修改。修改智能体模板不会自动更新现有智能体实例。

  6. 在测试实例执行 网页版对话 和真实调用回归，再更新生产实例。

  7. 在模型服务侧撤销旧 API Key。

  8. 确认没有智能体模板继续引用原凭证后，再选择 删除。控制台会提示被 Agent 引用的凭证不能删除。

不要先撤销旧 Key。这样会使所有仍使用原凭证的实例同时调用失败。请逐个更新并验证受影响的实例，经过观察期并确认全部实例已经切换后再撤销旧 Key；撤销后，回退方案必须使用仍然有效的替代凭证。

轮换对象存储凭证 ​

对象存储凭证可以编辑名称、区域和访问地址，但不能原位替换存储类型、AccessKey ID 或 Secret Access Key。需要轮换密钥时使用替代凭证。只读和读写验证的完整预期结果与停止条件，参见验证对象存储挂载。

  1. 在 凭证管理 的 对象存储凭证 页签新建凭证，使用新的 AccessKey ID 和 Secret Access Key。
  2. 创建或选择一个非生产沙箱，配置只读挂载并保存。平台会在保存前预检凭证和所有 Bucket；按照目标环境支持的方式让这个测试沙箱重新创建或重新启动，再读取内容已知且不含敏感信息的测试对象，并尝试写入一个新对象。预期结果是读取成功、写入被拒绝。
  3. 盘点引用旧凭证的每个沙箱模板和沙箱实例，并记录其中的全部 Bucket、子目录、本地目录和读写模式。一个沙箱表单内的全部挂载点必须一起切换到同一个新凭证。
  4. 从非生产到生产分批更新沙箱配置。每批更新前，先暂停相关读写或安排维护窗口；保存配置后，按照目标环境支持的方式让该批沙箱重新创建或重新启动，再确认运行中的每个挂载已经采用新凭证。这个过程会中断沙箱内正在进行的任务。请以重新启动后的实际读取结果确认凭证已经生效，再进入下一批；任一挂载无法确认时，停止迁移并保留旧凭证和原配置。
  5. 对每个已重新加载的挂载点读取已知测试对象。确需写入时，只在获准的测试目录中创建名称唯一、内容可识别的临时对象，读取并核对内容；确认对象名和路径仅属于本次测试后，按获准方式清理该对象。凭证未获删除权限时，由存储所有者清理本次测试对象，继续使用原有最小权限。检查原有对象没有被修改，并记录验证结果。

警告

撤销或删除前完成引用检查

撤销旧密钥会立即中断所有遗漏挂载的访问；删除 AgentWorks 中的旧凭证也会移除后续回退所需的配置。执行下一步前，确认清单中的每个沙箱模板、沙箱实例和挂载点都已切换，新凭证能够按原读写模式访问，并且没有生产写入仍依赖旧凭证。任一引用、测试结果或回退方式无法确认时，停止轮换并保留旧密钥和旧凭证。

如果旧凭证疑似泄露而不能保留重叠期，请先暂停受影响的读取和写入，在对象存储服务侧撤销旧密钥，再按清单切换到替代凭证。不要为了测试或回退重新启用疑似泄露的密钥；替代凭证验证失败时，保持相关任务停止，修正凭证、权限或挂载后再恢复。

完成引用检查后：

  1. 在对象存储服务侧撤销旧密钥，并验证旧凭证无法再访问、新凭证仍可访问每个挂载点。
  2. 经过观察期并再次确认清单中没有旧凭证引用后，删除 AgentWorks 中的旧对象存储凭证。

删除或替换凭证不会删除 Bucket 中的对象。对象存储所有者通过该存储的版本、生命周期、备份和恢复流程管理对象，并核对访问审计和费用。

更新对象存储凭证后，需要用固定合成数据重新验证三个挂载和持久报告时，参见构建订单与退款交付验收助手。如果旧凭证已经移除或不可用，请从准备样例和存储开始，使用新凭证和全新沙箱重新完成验收检查。

轮换 MCP Header ​

MCP Header 的轮换需要同时更新服务端密钥和受影响的连接，并通过真实工具调用确认新密钥可用。

  1. 确认 Header 属于 MCP 模板还是一个直接创建的 MCP 实例，并列出引用它的智能体模板和智能体实例。

    共享 MCP 实例的所有引用都要纳入检查，后续逐个验证。密钥版本历史应保存在外部密钥管理系统中。

  2. 如果 MCP Server 支持并行密钥，先在服务端增加新值；否则安排维护窗口。

  3. 更新 MCP Headers，选择 测试连接，并检查 工具列表。

  4. 在测试智能体实例中实际调用一个工具。连接测试成功不等于工具调用已经成功。

  5. 对使用能力模板的智能体实例，检查实例参数，并按需选择 保存修改。

  6. 验证所有引用该 MCP 实例的智能体模板和智能体实例后，在 MCP Server 撤销旧值。

轮换飞书或 QQ 应用密钥 ​

一个渠道账号不能并行保存两组应用密钥。更换密钥时，应将外部平台的新密钥、渠道账号配置和消息收发验证安排在同一次轮换中。

  1. 选择业务低峰或维护窗口，预留渠道重新连接的中断时间。

    外部平台不能同时接受新旧密钥时，请安排维护窗口完成替换和验证。

  2. 在外部开发者平台生成或取得新应用密钥。

  3. 选择 编辑，替换对应渠道账号的 应用密钥。

  4. 选择 保存，等待渠道账号重新上线。

    保存变化后的渠道凭证后，渠道账号会重新连接，期间可能短暂中断。

  5. 发送一条单聊消息；飞书还应按使用范围验证群聊和流式回复。

  6. 确认新连接工作后，在外部平台撤销旧密钥。

迁移旧版 Agent API Token ​

旧版 Invoke 使用的 agt_ 与调试用 dbg_ 不用于当前 API 接入。不要仅更换请求地址就沿用旧 Token。先为目标 WebSocket 渠道账号创建 wst_，迁移 HTTP 请求、事件订阅和中断处理，再停用旧集成；参见Direct Invoke 凭证迁移步骤。

分批轮换 WebSocket Token ​

为已有渠道账号分批迁移客户端时，从凭证管理页增加新 Token。首次为不同客户端签发独立 Token，可在创建 WebSocket 渠道账号时选择 同步创建 Token（可一次创建多个）。

注意

停用 Token 不会立即结束所有访问

停用、删除或重置 wst_ 后，不应再把旧值交付给任何调用方。鉴权缓存可能延后 HTTP 请求和新建握手的拒绝生效。

已经建立的 WebSocket 连接不会持续重新校验 Token。已使用旧 Token 完成鉴权的连接可能持续到客户端断线、心跳失败或渠道账号停止。

必须立即切断全部连接时，按处理 WebSocket 连接撤销对渠道账号执行 停用，并核对绑定 Token；后续 启用渠道账号时，也按该节要求恢复和验证。

  1. 在 WebSocket Token 中选择 新建 WS Token。

  2. 选择原来的 绑定 WebSocket 渠道账号，填写新的 Token 名称，并按需设置 有效期。

    使用不同于旧 Token 的名称；同一渠道账号内的 WebSocket Token 名称不能重复。

  3. 选择 创建 Token，立即保存新 wst_ 值。

  4. 让一个服务端客户端使用新 Token 完成 HTTP 鉴权和 WebSocket 握手，并验证调用：

    • 收到 hello 并确认订阅回复中的 subd.d.ok 为 true，再完成消息往返与终止事件核对。
    • 使用审批或用户工具的服务，还需验证一次中断响应。

  5. 分批重连其余客户端。

    现有连接不会在原连接内切换 Token。

  6. 确认所有客户端已经使用新 Token 建立连接，关闭仍使用旧 Token 的连接，再将旧 Token 停用。

    以调用方配置、客户端日志和新连接的实际消息往返为准。不要根据 最近连接 判断所有客户端是否已迁移或旧连接是否已经结束。

  7. 使用旧 Token 分别尝试无副作用的 HTTP 查询和新建连接。

    HTTP 请求与 WebSocket 握手都可能命中鉴权缓存，停用后可能短时间仍被接受。按目标环境的缓存时长等待并复核，确认拒绝后再选择 删除旧 Token。

区分重置与并行轮换 ​

列表中的 重置 会原位生成新明文，不提供主动保留新旧值的重叠期；HTTP 请求和新建握手的鉴权缓存、现有 WebSocket 连接仍需单独核对。只在以下场景使用：

  • 旧值已经泄露，且准备同时处置鉴权缓存和现有连接。
  • 创建时没有保存明文，且可以同步更新所有调用方。
  • 已安排可接受中断的维护窗口。

需要分批迁移时，创建第二个 Token，不要重置原 Token。重置后只能看到一次新明文；关闭弹窗后列表显示脱敏值。

处理疑似泄露 ​

凭证疑似泄露时，处置重点是限制现有访问、替换调用方保存的凭证，并查清受影响的资源和时间范围。恢复调用前，需要验证替代凭证并保留处置记录。

  1. 识别凭证类型、所有者、绑定资源和所有调用方。

  2. 按凭证类型限制访问。

    • Token：停用受影响 Token。
    • WebSocket Token（wst_）：如果必须立即切断现有连接，还需停用对应渠道账号。操作前确认影响范围，同一账号下的其他客户端也会受到影响；参见处理 WebSocket 连接撤销。
    • 模型、MCP 或渠道密钥：在对应的外部平台撤销密钥。

  3. 创建替代值并通过独立可信通道交付。

  4. 检查调用方配置、HTTP 请求日志、客户端连接日志和渠道会话。结合智能体实例 Trace和外部系统日志确定影响范围。

  5. 验证替代值后删除旧 Token，或删除不再使用的凭证和渠道账号。

  6. 记录受影响的时间、资源、用户和处置结果。

外部系统用于发起轮换、检测异常和保留审计记录；AgentWorks 中的模型、MCP 和渠道凭证仍按本页步骤更新。