文档中心

Appearance

控制台

轮换凭证并撤销访问 ​

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

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

识别凭证的所有者 ​

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

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

wst_ 不直接绑定智能体模板或智能体实例。渠道账号通过 绑定 Agent 实例（默认） 或 绑定 Agent 模板 设置绑定目标，Token 只允许客户端连接该渠道账号。因此，创建和查看 WebSocket Token 时，只需选择 绑定 WebSocket 渠道账号。

轮换模型 API Key ​

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

  1. 在 模型凭证 中选择 新建凭证。
  2. 在 凭证名称 中输入当前租户内未被占用的新名称，输入 API Key，选择 获取模型列表，再选择 创建凭证。
  3. 对新凭证执行 测试连通性。
  4. 找出引用原凭证的每个智能体模板，改为新凭证并选择 保存修改。
  5. 逐个对受影响的智能体实例选择 编辑，检查参数后选择 保存修改。修改智能体模板不会自动更新现有智能体实例。
  6. 在测试实例执行 Playground 和真实调用回归，再更新生产实例。
  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 ​

  1. 确认 Header 属于 MCP 模板还是一个直接创建的 MCP 实例，并列出引用它的智能体模板和智能体实例。
  2. 如果 MCP Server 支持并行密钥，先在服务端增加新值；否则安排维护窗口。
  3. 更新 MCP Headers，选择 测试连接，并检查 工具列表。
  4. 在测试智能体实例中实际调用一个工具。连接测试成功不等于工具调用已经成功。
  5. 对使用能力模板的智能体实例，检查实例参数，并按需选择 保存修改。
  6. 验证所有引用该 MCP 实例的智能体模板和智能体实例后，在 MCP Server 撤销旧值。

修改共享 MCP 实例前，盘点并逐个验证所有引用它的智能体模板和智能体实例。密钥版本历史应保存在外部密钥管理系统中。

轮换飞书或 QQ 应用密钥 ​

  1. 在外部开发者平台生成或取得新应用密钥。
  2. 选择业务低峰或维护窗口。
  3. 选择 编辑，替换对应渠道账号的 应用密钥。
  4. 选择 保存，等待渠道账号重新上线。
  5. 发送一条单聊消息；飞书还应按使用范围验证群聊和流式回复。
  6. 确认新连接工作后，在外部平台撤销旧密钥。

保存变化后的渠道凭证后，渠道账号会重新连接，期间可能短暂中断。外部平台不能同时接受新旧密钥时，请安排维护窗口完成替换和验证。

无中断轮换 Agent API Token ​

  1. 在 Agent API Token 中选择 新建 Agent Token。
  2. 使用能识别调用方和环境、且不同于旧 Token 的 Token 名称，选择同一个 绑定 Agent 实例，并设置 有效期。同一智能体实例内的 Agent API Token 名称不能重复。
  3. 选择 创建 Token，立即把一次性显示的新 agt_ 值写入调用方的密钥存储。
  4. 使用新 Token 完成一次真实 API 调用，并在列表的 最近调用 确认使用记录。
  5. 更新全部调用方后，对旧 Token 选择 停用。
  6. 用旧 Token 发起一次请求，确认鉴权失败；观察业务无异常后再 删除。

停用或过期的 Agent API Token 不能用于新的 Invoke API 请求。同一智能体实例可以同时使用多个有效 Token，因此上述路径支持短暂重叠。

无中断轮换 WebSocket Token ​

  1. 在 WebSocket Token 中选择 新建 WS Token。
  2. 选择原来的 绑定 WebSocket 渠道账号，使用不同于旧 Token 的 Token 名称，并按需设置 有效期。同一渠道账号内的 WebSocket Token 名称不能重复。
  3. 选择 创建 Token，立即保存新 wst_ 值。
  4. 让一个客户端使用新 Token 建立新连接并完成 auth_ok、PING/PONG 和消息往返。
  5. 分批重连其余客户端。现有连接不会在原连接内切换 Token。
  6. 从调用方配置和客户端日志确认所有客户端已经使用新 Token 建立连接，关闭仍使用旧 Token 的连接，再将旧 Token 停用。
  7. 使用旧 Token 尝试新建连接，确认鉴权失败，再选择 删除旧 Token。

创建 WebSocket 渠道账号时也可以选择 同步创建 Token（可一次创建多个）。这适合首次为不同客户端签发独立 Token；后续轮换仍可从凭证管理页增加 Token。

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

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

必须立即切断全部连接时，对 WebSocket 渠道账号选择 停用。确认连接结束后，刷新 WebSocket Token 列表，逐个核对绑定 Token，并单独停用任何仍显示为启用的 Token。恢复服务前，只启用或替换确实需要保留的 Token，再对渠道账号选择 启用；最后让客户端重新连接并验证鉴权和消息往返。不要依赖渠道账号操作自动核对或更改每个 Token 的状态。

区分重置与并行轮换 ​

列表中的 重置 会原位生成新明文，旧值立即失效，不提供重叠期。只在以下场景使用：

  • 旧值已经泄露，需要立即失效。
  • 创建时没有保存明文，且可以同步更新所有调用方。
  • 已安排可接受中断的维护窗口。

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

处理疑似泄露 ​

  1. 识别凭证类型、所有者、绑定资源和所有调用方。
  2. 先限制访问：停用 agt_；对 wst_ 按是否必须驱逐现有连接决定是否同时停用渠道账号；在外部平台撤销模型、MCP 或渠道密钥。
  3. 创建替代值并通过独立可信通道交付。
  4. 对 Agent API Token 检查 最近调用；对 WebSocket Token 检查调用方配置、客户端连接日志和渠道会话。结合智能体实例 Trace和外部系统日志确定影响范围。
  5. 验证替代值后删除旧 Token，或删除不再使用的凭证和渠道账号。
  6. 记录受影响的时间、资源、用户和处置结果。

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