Provider Key Manager

一条命令更换供应商 API Key，全员生效，零遗漏。

痛点

OpenClaw 多 agent 架构下，每个 agent 都有独立的 models.json，更换一个 provider key 需要：

1. 修改 openclaw.json 全局配置
2. 修改 13+ 个 agent 的 models.json
3. 更新 pass 存储
4. 重启 Gateway
5. 逐个验证

一个 key 要改 15+ 处，漏改一个就报错。

方案：环境变量统一引用

OpenClaw 原生支持 ${ENV_VAR} 语法引用环境变量：

// openclaw.json
{
  "env": {
    "vars": {
      "ZAI_API_KEY": "actual-key-value-here"
    }
  },
  "models": {
    "providers": {
      "zai": {
        "apiKey": "${ZAI_API_KEY}",  // ← 引用环境变量，不硬编码
        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4"
      }
    }
  }
}

核心原则：

• API Key 只存在 env.vars 中（单一真相源）
• 所有 provider 的 apiKey 用 "${ENV_VAR}" 引用
• 各 agent 的 models.json 删除 apiKey 字段，继承全局 provider
• 换 key = 改一个 env var + 重启，全员自动生效

触发词

换key, 更换key, provider key, API key 更换, 模型key, key管理, 供应商密钥

命令

1. 审计当前配置

python3 ~/clawd/skills/provider-key-manager/scripts/manager.py audit

扫描所有 agent 的 models.json，报告：

• ✅ 使用 ${ENV_VAR} 引用的 provider
• ❌ 硬编码 apiKey 的 provider
• ⚠️ key 值不一致的 agent

2. 迁移到环境变量模式

python3 ~/clawd/skills/provider-key-manager/scripts/manager.py migrate [--provider zai] [--dry-run]

自动执行：

1. 将 openclaw.json 中的硬编码 key 移入 env.vars
2. 替换 provider apiKey 为 "${ENV_VAR}"
3. 从各 agent models.json 中删除 apiKey 字段（继承全局）
4. 更新 pass 存储
5. 生成迁移报告

3. 更换 API Key

python3 ~/clawd/skills/provider-key-manager/scripts/manager.py update <provider> <new-key> [--base-url <url>]

一条命令完成：

1. 更新 env.vars 中的 key
2. 如有 agent 仍硬编码，同步更新
3. 更新 pass 存储
4. 测试 key 可用性
5. 输出重启命令

4. 测试 Key 可用性

python3 ~/clawd/skills/provider-key-manager/scripts/manager.py test <provider>

对指定 provider 发送最小请求，验证 key 有效。

5. 查看 Provider 总览

python3 ~/clawd/skills/provider-key-manager/scripts/manager.py status

显示所有 provider 的 key 来源、baseUrl、模型列表。

Provider ↔ 环境变量映射

架构图

┌─────────────────────────────────┐
│     openclaw.json               │
│  ┌───────────────────────┐      │
│  │ env.vars              │      │
│  │  ZAI_API_KEY: "xxx"   │ ← 单一真相源 (Single Source of Truth)
│  │  XAI_API_KEY: "yyy"   │      │
│  └───────────┬───────────┘      │
│              │ ${ZAI_API_KEY}   │
│  ┌───────────▼───────────┐      │
│  │ models.providers.zai  │      │
│  │  apiKey: "${ZAI_API_KEY}"    │
│  │  baseUrl: "https://..." │    │
│  └───────────────────────┘      │
└─────────────────────────────────┘
              │ 继承
    ┌─────────┼─────────┐
    ▼         ▼         ▼
 agent/     agent/    agent/
 main/      ops/     code/ ...
 models.json models.json
 (无 apiKey，继承全局)

注意事项

1. env.vars 中的 key 是明文 — 但 openclaw.json 已在 .gitignore，不会被 commit
2. per-agent models.json 仍需保留 provider 结构 — 只是删除 apiKey 字段
3. 迁移后换 key 流程：manager.py update zai <new-key> → Gateway 重启 → 完成
4. 回退方案：迁移前自动备份所有 models.json 到 /tmp/provider-key-backup/