> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-san-bu-fen-shi-xian-yuan-li-yu-gong-cheng-luo-di/11_reliability_security/11.1_auth_profiles.md).

# 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`。可以先用下面这张图理解它们的关系：

```mermaid
flowchart TD
  P["auth-profiles.json<br/>长期认证档案"] --> S
  O["auth.order<br/>默认 profile 顺序"] --> S
  A["会话 auth override<br/>临时固定 profile"] --> S["运行期选择"]
  S --> AP["auth-state.json<br/>实际选择 / 冷却 / 禁用状态"]
```

图 11-1：多密钥治理中的认证对象模型

各层分别负责不同的问题：

* **`auth-profiles.json`**：定义“有哪些长期认证档案可被 agent 选择”。支持 SecretRef 的静态凭据字段可以引用密钥系统；OAuth profile material 属于运行期可变认证材料，不能当作普通 SecretRef 字段处理。
* **`auth.order`**：定义“默认优先尝试哪些 profile / provider 路径”。
* **会话 auth override**：定义“本次会话是否临时固定某个 profile”，它不是 `agents.list[]` 上的静态 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 正常生命周期：生成、注入、验证、切换、吊销

从工程视角看，密钥轮换是正常生命周期的一部分，而不是临时运维技巧。生产环境里的最小安全流程如下：

```mermaid
flowchart LR
  A["生成新密钥"] --> B["注入配置或 SecretRef"]
  B --> C["保留旧 key<br/>新增 secondary profile"]
  C --> D["探针验证<br/>models status --probe"]
  D --> E["灰度调整 auth.order"]
  E --> F["观察日志与健康状态"]
  F --> G["吊销旧密钥"]
  G --> H["记录审计与快照"]
```

图 11-2：多密钥轮换的正常生命周期

把这条生命周期拆开看：

1. **生成与注入**：新 key 先进入密钥系统或环境变量，不直接覆盖旧值。
2. **验证**：用 `openclaw models status` 确认认证档案状态，用 `openclaw models status --probe` 和 `openclaw health --json` 确认新 key 可用。
3. **灰度切换**：再调整 `auth.order` 或会话级 auth override，让默认流量逐步切换；不要把不存在的静态 agent auth override 当作配置入口。
4. **吊销与归档**：观察稳定后再撤销旧 key，并保留审计快照。

操作示例：

```bash
openclaw models status
openclaw models status --probe
openclaw health --json
openclaw status --deep
```

这里真正关键的是顺序：**先新增、再验证、后切换、最后吊销**。如果反过来做，就会引入脏窗口。

## 11.1.5 异常生命周期：泄露应急与失败模式

正常生命周期之外，最典型的异常分支就是密钥泄露。泄露后的应对动作不能只理解成“换 key”，而应理解为“从正常生命周期切换到异常响应路径”。

异常路径的核心步骤包括：

1. **立即吊销**：先在供应商侧阻断继续滥用。
2. **识别影响范围**：确认哪些 provider、哪些 agent、哪些外部系统受影响。
3. **分级与指派 owner**：按凭据权限、暴露范围和是否已被利用判断严重度，并指定响应负责人。
4. **修复与验证发布**：更新配置、轮换依赖凭据，运行 `security audit`、`models status` / `--probe` 和必要的渠道回归。
5. **复盘与披露**：记录时间线、根因、补救动作和后续防护；涉及用户或第三方时按项目安全流程协调披露。
6. **并行轮换**：对受影响路径执行新的正常生命周期。
7. **加强隔离**：必要时临时下调工具权限、加强沙箱和审计。

## 11.1.6 常见误区与验收要点

多密钥治理失败，通常不是因为“不会配置”，而是因为对象关系和生命周期被混在一起了。常见误区包括：

* 把 key 明文写进配置文件或日志。
* 直接覆盖旧值，不保留回滚路径。
* 只改 `auth.order` 或会话级 auth override，不做 live 探针验证。
* 把“候选密钥集合”和“实际运行选择 / 冷却状态”混为一谈。

验收时建议固定看三类证据：

1. **配置证据**：`auth-profiles.json`、`auth.order` 与会话级 auth override 是否符合预期。
2. **探针证据**：`models status`、`models status --probe`、`health --json` 是否正常。
3. **运行证据**：`auth-state.json` 与结构化日志是否能回答“谁在用哪条认证路径、是否进入冷却”。

```bash
openclaw models status
openclaw models status --probe
openclaw status --deep
openclaw logs --follow --json
```

只要把这三类证据都收齐，多密钥治理就不再只是一本运维说明单，而是一套可追溯、可切换、可复盘的认证治理机制。