fix(key-rotator): suppress LLM_API_KEY fallback noise in startup logs

Providers without dedicated keys were logging "1 key" due to
LLM_API_KEY fallback being included unconditionally. Now only
providers with dedicated env vars log individually; all fallback
providers are summarised in a single line.

Also adds API Key Rotation section to README, HF_TOKEN and
WHATSAPP_ENABLED to Space secrets frontmatter, and key rotation
bullet to features list.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -20,6 +20,10 @@ secrets:
     description: "Comma-separated Telegram user IDs for access"
   - name: TELEGRAM_BOT_TOKEN
     description: "Telegram bot token from BotFather"
+  - name: HF_TOKEN
+    description: "HuggingFace token with Write access — enables automatic workspace backup."
+  - name: WHATSAPP_ENABLED
+    description: "Set to 'true' to enable WhatsApp pairing support."
 ---
 
 <!-- Badges -->
@@ -41,6 +45,7 @@ secrets:
 - [💾 Workspace Backup *(Optional)*](#-workspace-backup-optional)
 - [🔔 Webhooks *(Optional)*](#-webhooks-optional)
 - [🔐 Security & Advanced *(Optional)*](#-security--advanced-optional)
+- [🔑 API Key Rotation *(Optional)*](#-api-key-rotation-optional)
 - [🤖 LLM Providers](#-llm-providers)
 - [💻 Local Development](#-local-development)
 - [🔗 CLI Access](#-cli-access)
@@ -54,6 +59,7 @@ secrets:
 ## ✨ Features
 
 - 🔌 **Any LLM:** Use Claude, OpenAI GPT, Google Gemini, Grok, DeepSeek, Qwen, and 40+ providers (set `LLM_API_KEY` and `LLM_MODEL` accordingly).
+- 🔑 **Multi-Key Rotation:** Supply comma-separated key pools per provider (e.g. `ANTHROPIC_API_KEYS=key1,key2,key3`) for automatic round-robin rotation across rate limits.
 - ⚡ **Zero Config:** Duplicate this Space and set **just three** secrets (LLM_API_KEY, LLM_MODEL, GATEWAY_TOKEN) – no other setup needed.
 - 🐳 **Fast Builds:** Uses a pre-built OpenClaw Docker image to deploy in minutes.
 - 🌐 **Cloudflare Outbound Proxy:** HuggingClaw can automatically provision a Cloudflare Worker proxy for blocked outbound traffic such as Telegram API requests.
@@ -181,6 +187,29 @@ Configure password access and network restrictions:
 | `ALLOWED_ORIGINS` | — | Comma-separated allowed origins for Control UI |
 | `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set to `false` to disable the automatic Cloudflare KeepAlive worker |
 
+## 🔑 API Key Rotation *(Optional)*
+
+Spread requests across multiple API keys to avoid rate limits. Supply a comma-separated pool for any provider — keys rotate round-robin per provider independently.
+
+```bash
+# Single provider, multiple keys
+ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2,sk-ant-key3
+
+# Multiple providers simultaneously
+OPENAI_API_KEYS=sk-openai-key1,sk-openai-key2
+GEMINI_API_KEYS=AIza-key1,AIza-key2
+```
+
+**Fallback chain** (per provider):
+1. `{PROVIDER}_API_KEYS` — comma-separated pool *(preferred)*
+2. `{PROVIDER}_API_KEY` — single dedicated key
+3. `LLM_API_KEY` — universal fallback *(default for all providers)*
+
+> [!TIP]
+> If you only set `LLM_API_KEY`, all providers use it as a fallback automatically — no extra config needed. Add per-provider pools only when you need multi-key rotation.
+
+Supported per-provider variables: `ANTHROPIC_API_KEYS`, `OPENAI_API_KEYS`, `GEMINI_API_KEYS`, `DEEPSEEK_API_KEYS`, `GROQ_API_KEYS`, `MISTRAL_API_KEYS`, `OPENROUTER_API_KEYS`, `XAI_API_KEYS`, `NVIDIA_API_KEYS`, `COHERE_API_KEYS`, `TOGETHER_API_KEYS`, `CEREBRAS_API_KEYS`, and more — see `.env.example` for the full list.
+
 ## 🤖 LLM Providers
 
 HuggingClaw supports **all providers** from OpenClaw. Set `LLM_MODEL=<provider/model>` and the provider is auto-detected.

multi-provider-key-rotator.cjs

@@ -175,19 +175,36 @@ function normalizeKeys(...inputs) {
 
 // Build per-provider key pools + rotation indices
 const providerState = PROVIDERS.map(p => {
-  const keys = normalizeKeys(
+  const dedicatedKeys = normalizeKeys(
     process.env[p.envPlural]  || '',
     process.env[p.envSingular] || '',
-    process.env.LLM_API_KEY   || '',
   );
-  if (!keys.length) {
-    console.warn(`[key-rotator] No keys for provider "${p.name}"`);
-  } else {
+  const hasDedicated = dedicatedKeys.length > 0;
+  const keys = hasDedicated
+    ? dedicatedKeys
+    : normalizeKeys(process.env.LLM_API_KEY || '');
+
+  if (hasDedicated) {
     console.log(`[key-rotator] ${p.name}: ${keys.length} key${keys.length === 1 ? '' : 's'}`);
+  } else if (!keys.length) {
+    console.warn(`[key-rotator] No keys for provider "${p.name}"`);
   }
+
   return { ...p, keys, idx: 0 };
 });
 
+// Summarise providers that fall back to LLM_API_KEY
+const fallbackCount = providerState.filter(p => {
+  const dedicated = normalizeKeys(
+    process.env[p.envPlural]  || '',
+    process.env[p.envSingular] || '',
+  );
+  return dedicated.length === 0 && p.keys.length > 0;
+}).length;
+if (fallbackCount > 0) {
+  console.log(`[key-rotator] ${fallbackCount} provider(s) using LLM_API_KEY fallback`);
+}
+
 // ─── Runtime helpers ─────────────────────────────────────────────────────────
 
 function resolveHostname(urlLike) {