Enhance .env.example with clearer instructions

Updated comments for clarity and added API key rotation section.

.env.example

@@ -5,7 +5,7 @@
 # For local development: cp .env.example .env && nano .env
 
 # ── REQUIRED: Core Configuration ──
-# [REQUIRED] LLM provider API key
+# [REQUIRED] Primary LLM provider API key (for the provider in LLM_MODEL)
 # - Anthropic: sk-ant-v0-...
 # - OpenAI: sk-...
 # - Google: AIzaSy...
@@ -105,9 +105,6 @@ LLM_API_KEY=your_api_key_here
 #
 # NVIDIA (NVIDIA_API_KEY):
 #   - nvidia/nemotron-3-super-120b-a12b
-# Optional: NVIDIA key rotation pool
-# Comma-separated keys, rotated per request
-# NVIDIA_API_KEYS=key1,key2,key3
 #
 # Groq (GROQ_API_KEY):
 #   - groq/mixtral-8x7b-32768
@@ -127,6 +124,91 @@ LLM_API_KEY=your_api_key_here
 # Or any other OpenClaw-supported provider (format: provider/model-name)
 LLM_MODEL=anthropic/claude-sonnet-4-5
 
+# ════════════════════════════════════════════════════════════════
+# 🔑 API KEY ROTATION (per-provider key pools)
+# ════════════════════════════════════════════════════════════════
+# Every provider supports a comma-separated key pool.
+# Keys are rotated round-robin on every request — useful when you
+# have multiple accounts or want to spread rate-limit quota.
+#
+# Pattern: <PROVIDER>_API_KEYS=key1,key2,key3
+# Fallback order: plural pool → singular key → LLM_API_KEY
+#
+# Uncomment and fill in only the providers you use:
+#
+# ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2,sk-ant-key3
+# OPENAI_API_KEYS=sk-key1,sk-key2,sk-key3
+# GEMINI_API_KEYS=AIzaSy-key1,AIzaSy-key2
+# DEEPSEEK_API_KEYS=key1,key2
+# OPENROUTER_API_KEYS=sk-or-key1,sk-or-key2
+# KILOCODE_API_KEYS=key1,key2
+# OPENCODE_API_KEYS=key1,key2
+# ZAI_API_KEYS=key1,key2
+# MOONSHOT_API_KEYS=key1,key2
+# MINIMAX_API_KEYS=key1,key2
+# XIAOMI_API_KEYS=key1,key2
+# VOLCANO_ENGINE_API_KEYS=key1,key2
+# BYTEPLUS_API_KEYS=key1,key2
+# MISTRAL_API_KEYS=key1,key2
+# XAI_API_KEYS=key1,key2
+# NVIDIA_API_KEYS=key1,key2,key3
+# GROQ_API_KEYS=gsk-key1,gsk-key2,gsk-key3
+# COHERE_API_KEYS=key1,key2
+# TOGETHER_API_KEYS=key1,key2
+# CEREBRAS_API_KEYS=key1,key2
+# HUGGINGFACE_HUB_TOKENS=hf_key1,hf_key2
+
+# ════════════════════════════════════════════════════════════════
+# 🌐 MULTI-PROVIDER SETUP (use multiple models simultaneously)
+# ════════════════════════════════════════════════════════════════
+# LLM_MODEL sets your DEFAULT model. But you can activate multiple
+# providers at once — OpenClaw auto-discovers any provider whose
+# API key is present in the environment.
+#
+# HOW IT WORKS:
+#   1. LLM_MODEL + LLM_API_KEY  → sets your default model & exports
+#      the matching provider key automatically (e.g. ANTHROPIC_API_KEY)
+#   2. Any additional provider key you set directly (e.g. OPENAI_API_KEY)
+#      is also picked up by OpenClaw → that provider's models become
+#      available in the Control UI for manual selection.
+#   3. Rotation pools (*_API_KEYS) work for every active provider
+#      independently and in parallel.
+#
+# EXAMPLE — default Anthropic, also use OpenAI and Groq:
+#
+#   LLM_MODEL=anthropic/claude-sonnet-4-6   # default
+#   LLM_API_KEY=sk-ant-xxx                  # → auto-sets ANTHROPIC_API_KEY
+#
+#   OPENAI_API_KEY=sk-oai-xxx               # activates OpenAI models
+#   OPENAI_API_KEYS=sk-oai-k1,sk-oai-k2    # optional: rotation pool
+#
+#   GROQ_API_KEY=gsk-xxx                    # activates Groq models
+#   GROQ_API_KEYS=gsk-k1,gsk-k2,gsk-k3     # optional: rotation pool
+#
+# EXAMPLE — OpenRouter only (easiest: one key, 300+ models):
+#
+#   LLM_MODEL=openrouter/anthropic/claude-sonnet-4-6
+#   LLM_API_KEY=sk-or-v1-xxx
+#   # Switch between any of 300+ models in Control UI — no extra keys needed
+#
+# Set any of these directly as HF Space Secrets (not via LLM_API_KEY):
+# ANTHROPIC_API_KEY=sk-ant-xxx
+# OPENAI_API_KEY=sk-oai-xxx
+# GEMINI_API_KEY=AIzaSy-xxx
+# DEEPSEEK_API_KEY=xxx
+# GROQ_API_KEY=gsk-xxx
+# MISTRAL_API_KEY=xxx
+# XAI_API_KEY=xxx
+# NVIDIA_API_KEY=nvapi-xxx
+# COHERE_API_KEY=xxx
+# TOGETHER_API_KEY=xxx
+# CEREBRAS_API_KEY=xxx
+# MOONSHOT_API_KEY=xxx
+# OPENROUTER_API_KEY=sk-or-v1-xxx
+# HUGGINGFACE_HUB_TOKEN=hf_xxx
+
+# ════════════════════════════════════════════════════════════════
+
 # Optional: custom OpenAI-compatible provider
 # Only use this if you want to register your own endpoint at startup.
 # Leave all of these empty unless you need a custom provider.