.env.example

# ════════════════════════════════════════════════════════════════
# 🦞 HuggingClaw — OpenClaw Gateway for HuggingFace Spaces
# ════════════════════════════════════════════════════════════════
# Copy this file to .env and fill in your values.
# For local development: cp .env.example .env && nano .env

# ── REQUIRED: Core Configuration ──
# [REQUIRED] Primary LLM provider API key (for the provider in LLM_MODEL)
# - Anthropic: sk-ant-v0-...
# - OpenAI: sk-...
# - Google: AIzaSy...
# - OpenRouter: sk-or-v1-... (300+ models via single key)
LLM_API_KEY=your_api_key_here

# [REQUIRED] LLM model to use (format: provider/model-name)
# Auto-detects provider from prefix — any provider is supported!
# Provider IDs from OpenClaw docs: docs.openclaw.ai/concepts/model-providers
#
# ── Core Providers ──
#
# Anthropic (ANTHROPIC_API_KEY):
#   - anthropic/claude-opus-4-6
#   - anthropic/claude-sonnet-4-6
#   - anthropic/claude-sonnet-4-5
#   - anthropic/claude-haiku-4-5
#
# OpenAI (OPENAI_API_KEY):
#   - openai/gpt-5.4-pro
#   - openai/gpt-5.4
#   - openai/gpt-5.4-mini
#   - openai/gpt-5.4-nano
#   - openai/gpt-4.1
#   - openai/gpt-4.1-mini
#
# Google Gemini (GEMINI_API_KEY):
#   - google/gemini-3.1-pro-preview
#   - google/gemini-3-flash-preview
#   - google/gemini-2.5-pro
#   - google/gemini-2.5-flash
#
# DeepSeek (DEEPSEEK_API_KEY):
#   - deepseek/deepseek-v3.2
#   - deepseek/deepseek-r1-0528
#   - deepseek/deepseek-r1
#
# ── OpenCode Providers ──
#
# OpenCode Zen — tested & verified models (OPENCODE_API_KEY):
#   - opencode/claude-opus-4-6
#   - opencode/gpt-5.4
#   Get key from: https://opencode.ai/auth
#
# OpenCode Go — low-cost open models (OPENCODE_API_KEY):
#   - opencode-go/kimi-k2.5
#
# ── Gateway/Router Providers ──
#
# OpenRouter — 300+ models via single API key (OPENROUTER_API_KEY):
#   - openrouter/anthropic/claude-sonnet-4-6
#   - openrouter/openai/gpt-5.4
#   - openrouter/deepseek/deepseek-v3.2
#   - openrouter/meta-llama/llama-3.3-70b-instruct:free
#   Get key from: https://openrouter.ai
#
# Kilo Gateway (KILOCODE_API_KEY):
#   - kilocode/anthropic/claude-opus-4.6
#
# ── Chinese/Asian Providers ──
#
# Z.ai / GLM (ZAI_API_KEY) — OpenClaw normalizes z-ai/z.ai → zai:
#   - zai/glm-5
#   - zai/glm-5-turbo
#   - zai/glm-4.7
#   - zai/glm-4.7-flash
#
# Moonshot / Kimi (MOONSHOT_API_KEY):
#   - moonshot/kimi-k2.5
#   - moonshot/kimi-k2-thinking
#
# MiniMax (MINIMAX_API_KEY):
#   - minimax/minimax-m2.7
#   - minimax/minimax-m2.5
#
# Xiaomi / MiMo (XIAOMI_API_KEY):
#   - xiaomi/mimo-v2-pro
#   - xiaomi/mimo-v2-omni
#
# Volcengine / Doubao (VOLCANO_ENGINE_API_KEY):
#   - volcengine/doubao-seed-1-8-251228
#   - volcengine/kimi-k2-5-260127
#
# BytePlus — international (BYTEPLUS_API_KEY):
#   - byteplus/seed-1-8-251228
#
# ── Western Providers ──
#
# Mistral (MISTRAL_API_KEY):
#   - mistral/mistral-large-latest
#   - mistral/mistral-small-2603
#   - mistral/devstral-medium
#
# xAI / Grok (XAI_API_KEY):
#   - xai/grok-4.20-beta
#   - xai/grok-4
#
# NVIDIA (NVIDIA_API_KEY):
#   - nvidia/nemotron-3-super-120b-a12b
#
# Groq (GROQ_API_KEY):
#   - groq/mixtral-8x7b-32768
#
# Cohere (COHERE_API_KEY):
#   - cohere/command-a
#
# Together (TOGETHER_API_KEY):
#   - together/meta-llama/llama-3.3-70b-instruct
#
# Cerebras (CEREBRAS_API_KEY):
#   - cerebras/zai-glm-4.7
#
# HuggingFace Inference (HUGGINGFACE_HUB_TOKEN):
#   - huggingface/deepseek-ai/DeepSeek-R1
#
# 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.
#
# Smart backoff: when a key gets a 429/402 response, it is temporarily
# suspended so other keys handle traffic.
#   Strike 1 → suspended for KEY_BLACKLIST_COOLDOWN_MS   (default 60 s)
#   Strike 2 → suspended for KEY_BLACKLIST_COOLDOWN_MS × 4 (default 4 min)
#   Strike 3 → suspended for 24 h  (quota likely exhausted — skipped all day)
# A successful response resets the strike counter for that key.
#
# Pattern: <PROVIDER>_API_KEYS=key1,key2,key3
# Fallback order: plural pool → singular key → LLM_API_KEY (optional)
# Set false only if you want to disable global LLM_API_KEY fallback
# across providers.
LLM_API_KEY_FALLBACK_ENABLED=true
#
# Base backoff duration (ms) after the first 429 on a key (default: 60 s).
# Increases exponentially on repeated failures.
# KEY_BLACKLIST_COOLDOWN_MS=60000
#
# Number of consecutive 429/quota errors before a key is suspended for 24 h.
# KEY_MAX_STRIKES=3
#
# Note: KIMI_API_KEYS and MOONSHOT_API_KEYS share the same API endpoint
# (api.moonshot.cn) and are combined into one rotation pool automatically.
#
# 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   # combines with KIMI_API_KEYS
# KIMI_API_KEYS=key1,key2       # combines with MOONSHOT_API_KEYS
# 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
#
# Optional: explicitly pin model lists per provider for Control UI visibility
# when provider keys are configured.
# Format: comma-separated model IDs
# NVIDIA_MODELS=meta/llama-3.1-70b-instruct,nvidia/llama-3.1-nemotron-70b-instruct
# OPENAI_MODELS=gpt-4o-mini,gpt-4.1
# GROQ_MODELS=llama-3.3-70b-versatile,deepseek-r1-distill-llama-70b
#      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.
#
# Example:
#   CUSTOM_PROVIDER_NAME=modal
#   CUSTOM_BASE_URL=https://api.us-west-2.modal.direct/v1
#   CUSTOM_MODEL_ID=zai-org/GLM-5.1-FP8
#   LLM_MODEL=modal/zai-org/GLM-5.1-FP8
#
# Notes:
# - CUSTOM_BASE_URL should be the API base URL, not /chat/completions
# - CUSTOM_PROVIDER_NAME must not reuse a built-in provider name
# - Uses LLM_API_KEY by default; set CUSTOM_API_KEY only if different
#
# CUSTOM_PROVIDER_NAME=modal
# CUSTOM_BASE_URL=https://your-openai-compatible-endpoint/v1
# CUSTOM_MODEL_ID=your-model-id
# CUSTOM_MODEL_NAME=Friendly Model Name
# CUSTOM_API_KEY=your_custom_api_key_here
# CUSTOM_API_TYPE=openai-completions
# CUSTOM_CONTEXT_WINDOW=128000
# CUSTOM_MAX_TOKENS=500

# [REQUIRED] Gateway authentication token
# Generate: openssl rand -hex 32
GATEWAY_TOKEN=your_gateway_token_here

# [OPTIONAL] JupyterLab terminal token for /terminal/
# Set a strong token for private deployments. Must NOT be "huggingface".
JUPYTER_TOKEN=run: openssl rand -hex 32

# (Optional) Password auth — simpler alternative to token for casual users
# If set, users can log in with this password instead of the token
# OPENCLAW_PASSWORD=your_password_here

# ── OPTIONAL: Chat Integrations ──
# Enable WhatsApp pairing flow
# Set to true only if you want WhatsApp enabled
WHATSAPP_ENABLED=false

# Get bot token from: https://t.me/BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here

# Allowed Telegram User IDs (comma-separated numeric IDs)
# TELEGRAM_ALLOWED_USERS=123456789,987654321

# ── OPTIONAL: Cloudflare Outbound Proxy ──
# Automatically bypass platform network blocks for Telegram/WhatsApp/Google/etc.
# Get a Cloudflare API Token with Account: Workers Scripts: Edit permissions.
# CLOUDFLARE_WORKERS_TOKEN=your_cloudflare_api_token_here

# Alternatively, if you already have a worker deployed:
# CLOUDFLARE_PROXY_URL=https://your-proxy.workers.dev
# CLOUDFLARE_PROXY_SECRET=your_proxy_secret_here

# Extra domains to proxy, merged with built-in defaults (Telegram, Discord, WhatsApp,
# Facebook, Google). Comma-separated. Set to "*" to proxy ALL external traffic.
# Leave unset to proxy only the built-in default domains.
# CLOUDFLARE_PROXY_DOMAINS=api.sendgrid.com,slack.com

# ── OPTIONAL: Workspace Backup to HF Dataset ──
HF_USERNAME=your_hf_username
HF_TOKEN=hf_your_token_here

# Backup dataset name (auto-created if missing)
# Default: huggingclaw-backup
BACKUP_DATASET_NAME=huggingclaw-backup

# ── OPTIONAL: Background Services ──
# Workspace auto-sync interval (seconds). Default: 180.
SYNC_INTERVAL=180

# Check openclaw.json for settings changes this often (seconds). Default: 1.
OPENCLAW_CONFIG_WATCH_INTERVAL=1

# Wait for openclaw.json to stay valid and unchanged before syncing. Default: 3.
OPENCLAW_CONFIG_SETTLE_SECONDS=3

# Minimum gap between sessions-triggered immediate syncs (seconds). Default: 30.
SESSIONS_MIN_SYNC_GAP=30

# Webhooks: Standard POST notifications for lifecycle events
# WEBHOOK_URL=https://your-webhook-endpoint.com/log

# Cloudflare proxy & keep-alive: add your Cloudflare API token.
# A Worker is created automatically at boot for both outbound proxying and keep-alive.
# CLOUDFLARE_WORKERS_TOKEN=your_cloudflare_token_here

# Trusted proxies (comma-separated IPs)
# Fixes "Proxy headers detected from untrusted address" behind reverse proxies
# Only set if you see pairing/auth errors. Find IPs in Space logs (remote=x.x.x.x)
# TRUSTED_PROXIES=10.20.31.87,10.20.26.157

# Allowed origins for Control UI (comma-separated URLs)
# Locks down the web UI to only these origins
# ALLOWED_ORIGINS=https://your-space.hf.space

# ════════════════════════════════════════════════════════════════
# QUICK START: Only 3 secrets required!
#   1. LLM_API_KEY    → From your LLM provider
#   2. LLM_MODEL      → Pick a model above
#   3. GATEWAY_TOKEN   → Run: openssl rand -hex 32
# ════════════════════════════════════════════════════════════════