11.1 多密钥治理：认证档案、环境轮换与 auth order
多密钥治理最容易被写成一份“轮换手册”，但它首先是一个认证对象模型问题：谁定义候选密钥集合，谁决定默认选择，谁记录实际使用结果，以及这些信息如何落到不同智能体与不同环境上。只有先把这套对象关系讲清楚，后面的灰度、轮换和应急才不会沦为机械流程。
11.1.1 为什么多密钥治理不是单纯的运维动作
如果系统里只有一把 key，问题通常不只是“坏了就换”这么简单，还会同时引出三类工程风险：
可用性风险：配额耗尽、供应商限流或单 key 被封禁时，全量失败。
隔离性风险：开发流量、生产流量和高风险智能体共用同一凭据，爆炸半径过大。
可审计风险：事故发生后，无法回答“哪条流量使用了哪把 key”。
因此，多密钥治理的目标不只是“多准备几把备用钥匙”，而是把候选集合、默认策略、实际选择和审计落盘四件事分开治理。
11.1.2 认证对象模型：auth profile、auth order、会话覆盖与 auth state
当前更稳妥的理解方式是：长期认证材料、默认选择策略和运行期选择状态已经分层。长期认证材料主要来自 auth-profiles.json 与必要时的 provider 配置；默认优先级由 auth.order 表达；单次对话或任务可通过 session-level auth profile override 临时固定认证档案；运行期冷却、轮换结果与禁用状态进入 auth-state.json。可以先用下面这张图理解它们的关系：
图 11-1：多密钥治理中的认证对象模型
各层分别负责不同的问题：
auth-profiles.json：定义“有哪些长期认证档案可被 agent 选择”。支持 SecretRef 的静态凭据字段可以引用密钥系统；OAuth profile material 属于运行期可变认证材料，不能当作普通 SecretRef 字段处理。auth.order：定义“默认优先尝试哪些 profile / provider 路径”。会话 auth override：定义“本次会话是否临时固定某个 profile”，它不是
agents.entries.*上的静态 agent override 字段。auth-state.json：记录“谁在什么时候进入冷却、禁用或切到后备路径”。
官方文档与当前本地实现都把这两类文件分开：
auth-profiles.json：保存认证档案中的凭据材料或受支持静态凭据字段的 SecretRef 引用，本身应按敏感文件保护auth-state.json：保存运行期冷却、禁用、路由选择等状态
这也是为什么本章不能只谈“配置写法”。如果不理解对象关系，就很难在事故后复盘“默认配置”和“实际运行”之间的差异。
11.1.3 多密钥隔离策略：按环境、按智能体、按供应商切分
多密钥最常见的误区，是把“多把 key”误当成“高可用”本身。真正决定治理质量的，是你按什么边界去切分。
1. 按环境切分
开发、预发布、生产分别使用不同 key。
目标是避免测试流量污染生产配额，也避免生产故障被开发环境的实验请求放大。
2. 按智能体切分
高风险写操作智能体与低风险只读智能体使用不同 key。
目标是把权限边界和凭据边界对齐，降低泄露后的爆炸半径。
3. 按供应商或计费域切分
同一供应商下，不同项目、不同团队或不同计费账号分别配置。
目标是便于成本归因、故障隔离与配额管理。
因此，多密钥治理的重点不是“配置里放几把 key”，而是让密钥边界和系统边界尽可能一致。
11.1.4 正常生命周期：生成、注入、验证、切换、吊销
从工程视角看，密钥轮换是正常生命周期的一部分，而不是临时运维技巧。生产环境里的最小安全流程如下：
图 11-2：多密钥轮换的正常生命周期
把这条生命周期拆开看：
生成与注入：新 key 先进入密钥系统或环境变量，不直接覆盖旧值。
验证：用
openclaw models status确认认证档案状态，用openclaw models status --probe和openclaw health --json确认新 key 可用。灰度切换：再调整
auth.order或会话级 auth override，让默认流量逐步切换；不要把不存在的静态 agent auth override 当作配置入口。吊销与归档：观察稳定后再撤销旧 key，并保留审计快照。
操作示例：
这里真正关键的是顺序：先新增、再验证、后切换、最后吊销。如果反过来做，就会引入脏窗口。
11.1.5 异常生命周期：泄露应急与失败模式
正常生命周期之外，最典型的异常分支就是密钥泄露。泄露后的应对动作不能只理解成“换 key”，而应理解为“从正常生命周期切换到异常响应路径”。
异常路径的核心步骤包括：
立即吊销：先在供应商侧阻断继续滥用。
识别影响范围：确认哪些 provider、哪些 agent、哪些外部系统受影响。
分级与指派 owner：按凭据权限、暴露范围和是否已被利用判断严重度，并指定响应负责人。
修复与验证发布：更新配置、轮换依赖凭据，运行
security audit、models status/--probe和必要的渠道回归。复盘与披露：记录时间线、根因、补救动作和后续防护；涉及用户或第三方时按项目安全流程协调披露。
并行轮换：对受影响路径执行新的正常生命周期。
加强隔离：必要时临时下调工具权限、加强沙箱和审计。
11.1.6 常见误区与验收要点
多密钥治理失败，通常不是因为“不会配置”，而是因为对象关系和生命周期被混在一起了。常见误区包括：
把 key 明文写进配置文件或日志。
直接覆盖旧值，不保留回滚路径。
只改
auth.order或会话级 auth override，不做 live 探针验证。把“候选密钥集合”和“实际运行选择 / 冷却状态”混为一谈。
验收时建议固定看三类证据：
配置证据：
auth-profiles.json、auth.order与会话级 auth override 是否符合预期。探针证据：
models status、models status --probe、health --json是否正常。运行证据：
auth-state.json与结构化日志是否能回答“谁在用哪条认证路径、是否进入冷却”。
只要把这三类证据都收齐，多密钥治理就不再只是一本运维说明单，而是一套可追溯、可切换、可复盘的认证治理机制。
最后更新于