vilvona 1.0.0

package/docs/providers/groq.md

@@ -0,0 +1,171 @@
+---
+summary: "Groq setup (auth + model selection + Whisper transcription)"
+title: "Groq"
+read_when:
+  - You want to use Groq with OpenClaw
+  - You need the API key env var or CLI auth choice
+  - You are configuring Whisper audio transcription on Groq
+---
+
+[Groq](https://groq.com) provides ultra-fast inference on open-weight models (Llama, Gemma, Kimi, Qwen, GPT OSS, and more) using custom LPU hardware. OpenClaw includes a bundled Groq plugin that registers both an OpenAI-compatible chat provider and an audio media-understanding provider.
+
+| Property               | Value                                    |
+| ---------------------- | ---------------------------------------- |
+| Provider id            | `groq`                                   |
+| Plugin                 | bundled, `enabledByDefault: true`        |
+| Auth env var           | `GROQ_API_KEY`                           |
+| Onboarding flag        | `--auth-choice groq-api-key`             |
+| API                    | OpenAI-compatible (`openai-completions`) |
+| Base URL               | `https://api.groq.com/openai/v1`         |
+| Audio transcription    | `whisper-large-v3-turbo` (default)       |
+| Suggested chat default | `groq/llama-3.3-70b-versatile`           |
+
+## Getting started
+
+<Steps>
+  <Step title="Get an API key">
+    Create an API key at [console.groq.com/keys](https://console.groq.com/keys).
+  </Step>
+  <Step title="Set the API key">
+    <CodeGroup>
+
+```bash Onboarding
+openclaw onboard --auth-choice groq-api-key
+```
+
+```bash Env only
+export GROQ_API_KEY=gsk_...
+```
+
+    </CodeGroup>
+
+  </Step>
+  <Step title="Set a default model">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "groq/llama-3.3-70b-versatile" },
+        },
+      },
+    }
+    ```
+  </Step>
+  <Step title="Verify the catalog is reachable">
+    ```bash
+    openclaw models list --provider groq
+    ```
+  </Step>
+</Steps>
+
+### Config file example
+
+```json5
+{
+  env: { GROQ_API_KEY: "gsk_..." },
+  agents: {
+    defaults: {
+      model: { primary: "groq/llama-3.3-70b-versatile" },
+    },
+  },
+}
+```
+
+## Built-in catalog
+
+OpenClaw ships a manifest-backed Groq catalog with both reasoning and non-reasoning entries. Run `openclaw models list --provider groq` to see the bundled rows for your installed version, or check [console.groq.com/docs/models](https://console.groq.com/docs/models) for Groq's authoritative list.
+
+| Model ref                                        | Name                    | Reasoning | Input        | Context |
+| ------------------------------------------------ | ----------------------- | --------- | ------------ | ------- |
+| `groq/llama-3.3-70b-versatile`                   | Llama 3.3 70B Versatile | no        | text         | 131,072 |
+| `groq/llama-3.1-8b-instant`                      | Llama 3.1 8B Instant    | no        | text         | 131,072 |
+| `groq/meta-llama/llama-4-scout-17b-16e-instruct` | Llama 4 Scout 17B       | no        | text + image | 131,072 |
+| `groq/openai/gpt-oss-120b`                       | GPT OSS 120B            | yes       | text         | 131,072 |
+| `groq/openai/gpt-oss-20b`                        | GPT OSS 20B             | yes       | text         | 131,072 |
+| `groq/openai/gpt-oss-safeguard-20b`              | Safety GPT OSS 20B      | yes       | text         | 131,072 |
+| `groq/qwen/qwen3-32b`                            | Qwen3 32B               | yes       | text         | 131,072 |
+| `groq/groq/compound`                             | Compound                | yes       | text         | 131,072 |
+| `groq/groq/compound-mini`                        | Compound Mini           | yes       | text         | 131,072 |
+
+<Tip>
+  The catalog evolves with each OpenClaw release. `openclaw models list --provider groq` shows the rows known to your installed version; cross-check with [console.groq.com/docs/models](https://console.groq.com/docs/models) for newly-added or deprecated models.
+</Tip>
+
+## Reasoning models
+
+OpenClaw maps its shared `/think` levels to Groq's model-specific `reasoning_effort` values:
+
+- For `qwen/qwen3-32b`, disabled thinking sends `none` and enabled thinking sends `default`.
+- For Groq GPT OSS reasoning models (`openai/gpt-oss-*`), OpenClaw sends `low`, `medium`, or `high` based on `/think` level. Disabled thinking omits `reasoning_effort` because those models do not support a disabled value.
+- DeepSeek R1 Distill, Qwen QwQ, and Compound use Groq's native reasoning surface; `/think` controls visibility but the model always reasons.
+
+See [Thinking modes](/tools/thinking) for the shared `/think` levels and how OpenClaw translates them per provider.
+
+## Audio transcription
+
+Groq's bundled plugin also registers an **audio media-understanding provider** so voice messages can be transcribed through the shared `tools.media.audio` surface.
+
+| Property           | Value                                     |
+| ------------------ | ----------------------------------------- |
+| Shared config path | `tools.media.audio`                       |
+| Default base URL   | `https://api.groq.com/openai/v1`          |
+| Default model      | `whisper-large-v3-turbo`                  |
+| Auto priority      | 20                                        |
+| API endpoint       | OpenAI-compatible `/audio/transcriptions` |
+
+To make Groq the default audio backend:
+
+```json5
+{
+  tools: {
+    media: {
+      audio: {
+        models: [{ provider: "groq" }],
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="Environment availability for the daemon">
+    If the Gateway runs as a managed service (launchd, systemd, Docker), `GROQ_API_KEY` must be visible to that process — not just to your interactive shell.
+
+    <Warning>
+      A key exported only in an interactive shell will not help a launchd or systemd daemon unless that environment is imported there too. Set the key in `~/.openclaw/.env` or via `env.shellEnv` to make it readable from the gateway process.
+    </Warning>
+
+  </Accordion>
+
+  <Accordion title="Custom Groq model ids">
+    OpenClaw accepts any Groq model id at runtime. Use the exact id shown by Groq and prefix it with `groq/`. The bundled catalog covers the common cases; uncatalogued ids fall through to the default OpenAI-compatible template.
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "groq/<your-model-id>" },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model providers" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Thinking modes" href="/tools/thinking" icon="brain">
+    Reasoning effort levels and provider-policy interaction.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full config schema including provider and audio settings.
+  </Card>
+  <Card title="Groq Console" href="https://console.groq.com" icon="arrow-up-right-from-square">
+    Groq dashboard, API docs, and pricing.
+  </Card>
+</CardGroup>

package/docs/providers/huggingface.md

@@ -0,0 +1,235 @@
+---
+summary: "Hugging Face Inference setup (auth + model selection)"
+read_when:
+  - You want to use Hugging Face Inference with OpenClaw
+  - You need the HF token env var or CLI auth choice
+title: "Hugging Face (inference)"
+---
+
+[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) offer OpenAI-compatible chat completions through a single router API. You get access to many models (DeepSeek, Llama, and more) with one token. OpenClaw uses the **OpenAI-compatible endpoint** (chat completions only); for text-to-image, embeddings, or speech use the [HF inference clients](https://huggingface.co/docs/api-inference/quicktour) directly.
+
+- Provider: `huggingface`
+- Auth: `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` (fine-grained token with **Make calls to Inference Providers**)
+- API: OpenAI-compatible (`https://router.huggingface.co/v1`)
+- Billing: Single HF token; [pricing](https://huggingface.co/docs/inference-providers/pricing) follows provider rates with a free tier.
+
+## Getting started
+
+<Steps>
+  <Step title="Create a fine-grained token">
+    Go to [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) and create a new fine-grained token.
+
+    <Warning>
+    The token must have the **Make calls to Inference Providers** permission enabled or API requests will be rejected.
+    </Warning>
+
+  </Step>
+  <Step title="Run onboarding">
+    Choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:
+
+    ```bash
+    openclaw onboard --auth-choice huggingface-api-key
+    ```
+
+  </Step>
+  <Step title="Select a default model">
+    In the **Default Hugging Face model** dropdown, pick the model you want. The list is loaded from the Inference API when you have a valid token; otherwise a built-in list is shown. Your choice is saved as the default model.
+
+    You can also set or change the default model later in config:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
+        },
+      },
+    }
+    ```
+
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    openclaw models list --provider huggingface
+    ```
+  </Step>
+</Steps>
+
+### Non-interactive setup
+
+```bash
+openclaw onboard --non-interactive \
+  --mode local \
+  --auth-choice huggingface-api-key \
+  --huggingface-api-key "$HF_TOKEN"
+```
+
+This will set `huggingface/deepseek-ai/DeepSeek-R1` as the default model.
+
+## Model IDs
+
+Model refs use the form `huggingface/<org>/<model>` (Hub-style IDs). The list below is from **GET** `https://router.huggingface.co/v1/models`; your catalog may include more.
+
+| Model                  | Ref (prefix with `huggingface/`)    |
+| ---------------------- | ----------------------------------- |
+| DeepSeek R1            | `deepseek-ai/DeepSeek-R1`           |
+| DeepSeek V3.2          | `deepseek-ai/DeepSeek-V3.2`         |
+| Qwen3 8B               | `Qwen/Qwen3-8B`                     |
+| Qwen2.5 7B Instruct    | `Qwen/Qwen2.5-7B-Instruct`          |
+| Qwen3 32B              | `Qwen/Qwen3-32B`                    |
+| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
+| Llama 3.1 8B Instruct  | `meta-llama/Llama-3.1-8B-Instruct`  |
+| GPT-OSS 120B           | `openai/gpt-oss-120b`               |
+| GLM 4.7                | `zai-org/GLM-4.7`                   |
+| Kimi K2.5              | `moonshotai/Kimi-K2.5`              |
+
+<Tip>
+You can append `:fastest` or `:cheapest` to any model id. Set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers); see [Inference Providers](https://huggingface.co/docs/inference-providers) and **GET** `https://router.huggingface.co/v1/models` for the full list.
+</Tip>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Model discovery and onboarding dropdown">
+    OpenClaw discovers models by calling the **Inference endpoint directly**:
+
+    ```bash
+    GET https://router.huggingface.co/v1/models
+    ```
+
+    (Optional: send `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` or `$HF_TOKEN` for the full list; some endpoints return a subset without auth.) The response is OpenAI-style `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
+
+    When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), OpenClaw uses this GET to discover available chat-completion models. During **interactive setup**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, OpenClaw again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
+
+  </Accordion>
+
+  <Accordion title="Model names, aliases, and policy suffixes">
+    - **Name from API:** The model display name is **hydrated from GET /v1/models** when the API returns `name`, `title`, or `display_name`; otherwise it is derived from the model id (e.g. `deepseek-ai/DeepSeek-R1` becomes "DeepSeek R1").
+    - **Override display name:** You can set a custom label per model in config so it appears the way you want in the CLI and UI:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
+            "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
+          },
+        },
+      },
+    }
+    ```
+
+    - **Policy suffixes:** OpenClaw's bundled Hugging Face docs and helpers currently treat these two suffixes as the built-in policy variants:
+      - **`:fastest`** — highest throughput.
+      - **`:cheapest`** — lowest cost per output token.
+
+      You can add these as separate entries in `models.providers.huggingface.models` or set `model.primary` with the suffix. You can also set your default provider order in [Inference Provider settings](https://hf.co/settings/inference-providers) (no suffix = use that order).
+
+    - **Config merge:** Existing entries in `models.providers.huggingface.models` (e.g. in `models.json`) are kept when config is merged. So any custom `name`, `alias`, or model options you set there are preserved.
+
+  </Accordion>
+
+  <Accordion title="Environment and daemon setup">
+    If the Gateway runs as a daemon (launchd/systemd), make sure `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` is available to that process (for example, in `~/.openclaw/.env` or via `env.shellEnv`).
+
+    <Note>
+    OpenClaw accepts both `HUGGINGFACE_HUB_TOKEN` and `HF_TOKEN` as env var aliases. Either one works; if both are set, `HUGGINGFACE_HUB_TOKEN` takes precedence.
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Config: DeepSeek R1 with Qwen fallback">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: {
+            primary: "huggingface/deepseek-ai/DeepSeek-R1",
+            fallbacks: ["huggingface/Qwen/Qwen3-8B"],
+          },
+          models: {
+            "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
+            "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Config: Qwen with cheapest and fastest variants">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "huggingface/Qwen/Qwen3-8B" },
+          models: {
+            "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
+            "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
+            "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Config: DeepSeek + Llama + GPT-OSS with aliases">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: {
+            primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
+            fallbacks: [
+              "huggingface/meta-llama/Llama-3.3-70B-Instruct",
+              "huggingface/openai/gpt-oss-120b",
+            ],
+          },
+          models: {
+            "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
+            "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
+            "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Config: Multiple Qwen and DeepSeek with policy suffixes">
+    ```json5
+    {
+      agents: {
+        defaults: {
+          model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
+          models: {
+            "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
+            "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
+            "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
+            "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
+          },
+        },
+      },
+    }
+    ```
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Overview of all providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Model selection" href="/concepts/models" icon="brain">
+    How to choose and configure models.
+  </Card>
+  <Card title="Inference Providers docs" href="https://huggingface.co/docs/inference-providers" icon="book">
+    Official Hugging Face Inference Providers documentation.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration" icon="gear">
+    Full config reference.
+  </Card>
+</CardGroup>

package/docs/providers/index.md

@@ -0,0 +1,105 @@
+---
+summary: "Model providers (LLMs) supported by OpenClaw"
+read_when:
+  - You want to choose a model provider
+  - You need a quick overview of supported LLM backends
+title: "Provider directory"
+---
+
+OpenClaw can use many LLM providers. Pick a provider, authenticate, then set the
+default model as `provider/model`.
+
+Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? See [Channels](/channels).
+
+## Quick start
+
+1. Authenticate with the provider (usually via `openclaw onboard`).
+2. Set the default model:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
+}
+```
+
+## Provider docs
+
+- [Alibaba Model Studio](/providers/alibaba)
+- [Amazon Bedrock](/providers/bedrock)
+- [Amazon Bedrock Mantle](/providers/bedrock-mantle)
+- [Anthropic (API + Claude CLI)](/providers/anthropic)
+- [Arcee AI (Trinity models)](/providers/arcee)
+- [Azure Speech](/providers/azure-speech)
+- [BytePlus (International)](/concepts/model-providers#byteplus-international)
+- [Cerebras](/providers/cerebras)
+- [Chutes](/providers/chutes)
+- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+- [ComfyUI](/providers/comfy)
+- [DeepSeek](/providers/deepseek)
+- [ds4 (local DeepSeek V4)](/providers/ds4)
+- [ElevenLabs](/providers/elevenlabs)
+- [fal](/providers/fal)
+- [Fireworks](/providers/fireworks)
+- [GitHub Copilot](/providers/github-copilot)
+- [GMI Cloud](/providers/gmi)
+- [Google (Gemini)](/providers/google)
+- [Gradium](/providers/gradium)
+- [Groq (LPU inference)](/providers/groq)
+- [Hugging Face (Inference)](/providers/huggingface)
+- [inferrs (local models)](/providers/inferrs)
+- [Kilocode](/providers/kilocode)
+- [LiteLLM (unified gateway)](/providers/litellm)
+- [LM Studio (local models)](/providers/lmstudio)
+- [MiniMax](/providers/minimax)
+- [Mistral](/providers/mistral)
+- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+- [NVIDIA](/providers/nvidia)
+- [NovitaAI](/providers/novita)
+- [Ollama (cloud + local models)](/providers/ollama)
+- [Ollama Cloud](/providers/ollama-cloud)
+- [OpenAI (API + Codex)](/providers/openai)
+- [OpenCode](/providers/opencode)
+- [OpenCode Go](/providers/opencode-go)
+- [OpenRouter](/providers/openrouter)
+- [Perplexity (web search)](/providers/perplexity-provider)
+- [Qianfan](/providers/qianfan)
+- [Qwen Cloud](/providers/qwen)
+- [Qwen OAuth / Portal](/providers/qwen-oauth)
+- [Runway](/providers/runway)
+- [SenseAudio](/providers/senseaudio)
+- [SGLang (local models)](/providers/sglang)
+- [StepFun](/providers/stepfun)
+- [Synthetic](/providers/synthetic)
+- [Tencent Cloud (TokenHub)](/providers/tencent)
+- [Together AI](/providers/together)
+- [Venice (Venice AI, privacy-focused)](/providers/venice)
+- [Vercel AI Gateway](/providers/vercel-ai-gateway)
+- [vLLM (local models)](/providers/vllm)
+- [Volcengine (Doubao)](/providers/volcengine)
+- [Vydra](/providers/vydra)
+- [xAI](/providers/xai)
+- [Xiaomi](/providers/xiaomi)
+- [Z.AI (GLM)](/providers/zai)
+
+## Shared overview pages
+
+- [Additional bundled variants](/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy, and Gemini CLI OAuth
+- [Image Generation](/tools/image-generation) - Shared `image_generate` tool, provider selection, and failover
+- [Music Generation](/tools/music-generation) - Shared `music_generate` tool, provider selection, and failover
+- [Video Generation](/tools/video-generation) - Shared `video_generate` tool, provider selection, and failover
+
+## Transcription providers
+
+- [Deepgram (audio transcription)](/providers/deepgram)
+- [ElevenLabs](/providers/elevenlabs#speech-to-text)
+- [Mistral](/providers/mistral#audio-transcription-voxtral)
+- [OpenAI](/providers/openai#speech-to-text)
+- [SenseAudio](/providers/senseaudio)
+- [xAI](/providers/xai#speech-to-text)
+
+## Community tools
+
+- [Claude Max API Proxy](/providers/claude-max-api-proxy) - Community proxy for Claude subscription credentials (verify Anthropic policy/terms before use)
+
+For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
+see [Model providers](/concepts/model-providers).