provider-key-manager

Provider Key Manager

Change the provider API Key with one command, effective for everyone, with zero omissions.

Pain Points

Under OpenClaw's multi-agent architecture, each agent has its own independent models.json. Changing one provider key requires:

1. Modify openclaw.json global config
2. Modify models.json
3. Update pass storage
4. Restart Gateway
5. Verify one by one

One key requires changing 15+ places; miss one and it errors.

Solution: Unified Reference via Environment Variables

OpenClaw natively supports the ${ENV_VAR} syntax for referencing environment variables:

// 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"
      }
    }
  }
}

Core Principles：

• The API Key exists only in env.vars (single source of truth)
• Every provider's apiKey uses "${ENV_VAR}" reference
• Each agent's models.json Delete the apiKey field, inherit the global provider
• Changing a key = change one env var + restart, automatically effective for everyone

Trigger Words

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

Commands

1. Audit the current configuration

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

Scan all agents' models.json and report:

• ✅ Providers using ${ENV_VAR} references
• ❌ Providers with hardcoded apiKey
• ⚠️ Agents with inconsistent key values

2. Migrate to environment variable mode

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

Automatically execute:

1. Move the hardcoded key from openclaw.json into env.vars
2. Replace the provider apiKey with "${ENV_VAR}"
3. From each agent's models.json,delete the apiKey field (inherit the global one)
4. Update pass storage
5. Generate a migration report

3. Change the API Key

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

Complete with one command:

1. Update env.vars the key in
2. If any agent is still hardcoded, update it as well
3. Update pass storage
4. Test key availability
5. Output the restart command

4. Test Key Availability

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

Send a minimal request to the specified provider to verify the key is valid.

5. View Provider Overview

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

Display the key source, baseUrl, and model list of all providers.

Provider ↔ Environment Variable Mapping

Provider	Environment Variable	pass path
zai	ZAI_API_KEY	api/zai
xingjiabiapi	XINGJIABIAPI_KEY	api/xingjiabiapi
xai	XAI_API_KEY	api/xai
xingsuancode	XINGSUANCODE_KEY	api/xingsuancode
moonshot	MOONSHOT_API_KEY	api/kimi
minimax	MINIMAX_API_KEY	api/minimax
xinyuan	XINYUAN_API_KEY	api/xinyuan
boluobao	BOLUOBAO_API_KEY	api/boluobao
google	GOOGLE_API_KEY	api/google-ai-studio

Architecture Diagram

┌─────────────────────────────────┐
│     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，继承全局)

Notes

1. The key in env.vars is plaintext — but openclaw.json is already in .gitignore and will not be committed
2. The per-agent models.json still needs to retain the provider structure — just delete the apiKey field
3. Key change process after migration：manager.py update zai <new-key> → Gateway restart → done
4. Rollback plan: automatically back up all models.json before migration to /tmp/provider-key-backup/