11.1 多密钥治理：keys、keyId 与认证档案
本节以官方 models.providers 配置为准，讲清多密钥治理的落点：密钥通过 ENV: 注入；同一 provider 下可配置多把 key；默认 key 由 keyId 选择；某些场景下智能体会把 key 选择写入认证档案文件，形成可追溯的“谁在用哪把钥匙”。目标是消除单密钥单点故障，并让轮换、灰度与回滚变成可审计流程。密钥注入的基础用法见 4.2 模型供应商接入与认证方式，本节在此基础上讨论多密钥治理与轮换策略。
11.1.1 为什么不能只配一把 key
单密钥架构在生产里通常会同时引爆三类问题。
可用性：配额耗尽或被封禁时全量失败。
可治理性：无法分清哪些流量消耗了配额，难以对账。
可轮换性：紧急换 key 容易引入脏窗口，导致大量认证失败。
官方配置支持多 key 与 keyId，为轮换与隔离提供结构。参考：https://docs.openclaw.ai/gateway/configuration#models。
11.1.2 多密钥配置与隔离策略
多密钥的基础配置写法（keys、keyId、ENV: 注入）见 4.2 模型供应商接入与认证方式。本节聚焦生产环境下的隔离策略。
生产级多密钥治理的关键不只是“有两把 key”，而是能回答“哪把 key 服务哪些流量，出事时影响范围多大”。建议按以下维度做隔离：
按环境隔离 ：开发、预发布与生产使用不同 key，避免测试流量消耗生产配额或触发限流。
按智能体隔离 ：高风险写操作智能体与低风险只读智能体使用不同 key，限制泄露后的爆炸半径。
按供应商隔离 ：同一供应商的不同项目或不同计费账号分别配置，便于成本归因与配额管理。
11.1.3 认证档案文件：把 key 选择落盘为证据
官方文档指出：当智能体在多 key 场景中选择了某把 key，这个选择可能会被写入智能体的认证档案文件，以便后续复用与审计。
当前路径：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
遗留路径（legacy）：~/.openclaw/agent/auth-profiles.json（存量安装的旧版本路径，首次使用时会自动导入至当前路径）
排查时若在当前路径未找到文件，请先检查是否存在遗留路径的旧文件。参考：https://docs.openclaw.ai/concepts/model-failover。
这件事的工程价值是可追溯：事故复盘时可以回答“哪个智能体在故障窗口使用了哪把 key”。
11.1.4 轮换流程：灰度、验证、切换、吊销
建议把轮换写成四步，避免脏窗口。
新增 secondary：在密钥系统与环境变量中准备新 key。
验证：用
models status --check验证新 key 可用。切换：修改
keyId或相关档案指向，让主流量逐步切换。吊销：观察一段时间后吊销旧 key，并保留审计记录。
操作示例：
11.1.5 常见误区
把 key 明文写进配置文件或日志。
在故障窗口直接替换原 key 值而不保留回滚点。
切换后不做探针验证，导致把认证问题误判为模型质量问题。
最后更新于