Spaces:
Running
Running
| ════════════════════════════════════════════════════════════════ | |
| 🦞 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 | |
| ════════════════════════════════════════════════════════════════ | |