11.1 多密钥治理：keys、keyId 与认证档案

本节以官方 models.providers 配置为准，讲清多密钥治理的落点：密钥通过 ${VAR} 或 SecretRef 注入；同一 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、${VAR} 或 SecretRef 注入）见 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 密钥轮换工作流：生成 → 更新 → 验证 → 弃用

生产环境中密钥轮换是一项常规但风险较高的操作，需要严格分步执行，避免认证窗口断开。

第一步：生成新密钥

1. 在密钥管理系统中生成新密钥（如在 OpenAI、Anthropic 或其他模型供应商的控制台中申请新的 API Key）

2. 将新密钥临时保存在安全的本地文件或密钥管理工具中（如 HashiCorp Vault、AWS Secrets Manager），不直接写入配置文件

3. 为新密钥标记生成时间与预期弃用时间（用于后续审计）

第二步：更新配置与环境变量

1. 在 OpenClaw 的 models.providers 配置中，为目标 provider 新增一个密钥条目（保持旧 key 暂时存在）

2. 通过环境变量或密钥系统注入方式（${VAR} 或 SecretRef）将新 key 加载到系统

3. 配置中暂时保持 keyId 仍指向旧密钥（默认优先级），新密钥作为 secondary 备选

第三步：验证新密钥可用性

1. 使用官方诊断命令验证新 key 是否正常工作：

   openclaw models status --check
   openclaw health --json

2. 若指令成功返回，表示新密钥与模型供应商的连接正常

3. 观察一小段时间（如 5-10 分钟），监控日志中是否出现认证错误

第四步：灰度切换主密钥

1. 修改配置中的 keyId 指向新密钥，使其成为主密钥

2. 可选的灰度策略：根据环境（开发、灰度、生产）分步切换；或使用加权轮询，让部分流量先用新密钥试水

3. 执行命令重新加载配置：

   openclaw config reload

4. 观察切换后的 5-15 分钟内的日志，确保无异常认证失败

第五步：吊销与清理旧密钥

1. 在模型供应商控制台中吊销旧密钥

2. 从 OpenClaw 配置文件中完全移除旧密钥的引用

3. 在审计日志中记录本次轮换的完整时间戳、参与者、原因（例如”定期轮换”或”紧急响应泄露”）

4. 保留轮换前后的 auth-profiles 文件快照，便于事故复盘时追查”哪把 key 在故障窗口被使用”

11.1.5 密钥泄露应急响应

⚠️ 历史教训：CVE 漏洞导致 150 万 API 密钥泄露

早期版本中，一个 CVE 漏洞曾导致 Gateway 在未经认证的情况下暴露内部状态，最终造成约 150 万个 API 密钥泄露。这一事件深刻说明：即使是本地部署的系统，如果网关端口被意外暴露到公网，后果同样严重。生产环境中务必遵守“绑定 127.0.0.1 + 防火墙白名单”的双重防线，并定期运行 openclaw doctor --security 检查端口暴露风险。

当发现密钥已被泄露或滥用时，需要立即执行更激进的应急步骤。

第一步：立即吊销受泄露密钥

1. 进入模型供应商控制台（如 OpenAI、Anthropic 等），立即吊销泄露的密钥

2. 吊销操作在供应商侧通常秒级生效，可防止进一步滥用

3. 检查供应商的使用记录（Usage Log），识别泄露后的异常流量消耗

4. 如需要，向模型供应商提交滥用举报，请求对异常费用的核销

第二步：轮换所有依赖此密钥的服务

1. 识别本 OpenClaw 实例中所有使用该密钥的 provider 与 agent（参考 auth-profiles.json）

2. 按优先级（关键智能体优先）逐个执行”密钥轮换工作流”的后续步骤

3. 若有多个智能体或多个供应商受影响，采用并行轮换以加快恢复速度

第三步：审计访问日志与状态追踪

1. 收集与分析泄露时段前后的完整系统日志：

   openclaw logs --follow --json --from "2026-03-09T10:00:00Z" --to "2026-03-09T12:00:00Z"
   openclaw audit --agent <agentId> --timerange "2h"

2. 查看 auth-profiles.json 的历史版本，追踪”在泄露窗口期间，哪个智能体被触发、使用了哪把密钥、与哪些外部系统交互”

3. 特别关注”写操作”（如数据库更新、文件修改、邮件发送），评估泄露造成的实际损害范围

第四步：深度隔离与监控加强

1. 如怀疑还有其他密钥风险，考虑临时停用所有智能体的主要功能，只保留只读工具

2. 部署额外的监控告警：监测模型 API 的异常调用模式（如突然大量调用、异常 IP 地址）

3. 考虑启用更严格的 Guardrail 与 Sandbox 沙箱限制，减小其他密钥被滥用的风险范围

4. 向使用过此实例的所有最终用户通知泄露事件，建议他们检查是否有敏感数据被暴露

11.1.6 轮换流程：灰度、验证、切换、吊销（快速参考）

建议把轮换写成四步，避免脏窗口。

1. 新增 secondary：在密钥系统与环境变量中准备新 key。

2. 验证：用 models status --check 验证新 key 可用。

3. 切换：修改 keyId 或相关档案指向，让主流量逐步切换。

4. 吊销：观察一段时间后吊销旧 key，并保留审计记录。

操作示例：

openclaw models status --check
openclaw status --deep

11.1.7 常见误区

• 把 key 明文写进配置文件或日志。

• 在故障窗口直接替换原 key 值而不保留回滚点。

• 切换后不做探针验证，导致把认证问题误判为模型质量问题。

💡 踩坑实录：密钥轮换的“5分钟空窗期”

在轮换 API Key 时，先在供应商控制台撤销了旧密钥，再更新 OpenClaw 配置。结果这 5 分钟内所有请求都返回 401，触发了全量冷却。正确做法：先添加新密钥到 auth profile → 确认新密钥生效 → 再撤销旧密钥。openclaw secrets reload 支持热加载，无需重启 Gateway。