docs/providers/huggingface.md
Hugging Face Inference Providers exposes an OpenAI-compatible chat completions router in front of many hosted models (DeepSeek, Llama, and more) under one token. OpenClaw talks to the chat completions endpoint only; for text-to-image, embeddings, or speech use the HF inference clients directly.
| Property | Value |
|---|---|
| Provider id | huggingface |
| Plugin | bundled (enabled by default, no install step) |
| Auth env var | HUGGINGFACE_HUB_TOKEN or HF_TOKEN (fine-grained token) |
| API | OpenAI-compatible (https://router.huggingface.co/v1) |
| Billing | Single HF token; pricing follows provider rates with a free tier |
<Warning>
The token must have the **Make calls to Inference Providers** permission enabled or API requests will be rejected.
</Warning>
```bash
openclaw onboard --auth-choice huggingface-api-key
```
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
},
},
}
```
openclaw onboard --non-interactive \
--mode local \
--auth-choice huggingface-api-key \
--huggingface-api-key "$HF_TOKEN"
Sets huggingface/deepseek-ai/DeepSeek-R1 as the default model.
Model refs use the form huggingface/<org>/<model> (Hub-style IDs). OpenClaw's built-in catalog:
| Model | Ref (prefix with huggingface/) |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| DeepSeek V3.1 | deepseek-ai/DeepSeek-V3.1 |
| GPT-OSS 120B | openai/gpt-oss-120b |
| Llama 3.3 70B Instruct Turbo | meta-llama/Llama-3.3-70B-Instruct-Turbo |
```bash
GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN # or $HF_TOKEN
```
The response is OpenAI-style: `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
With a configured key (onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), the **Default Hugging Face model** dropdown during interactive setup is populated from this endpoint. Gateway startup repeats the same call to refresh the catalog. Discovered models are merged with the built-in catalog above (used for metadata like context window and cost when an id matches). If the request fails, returns no data, or no key is set, OpenClaw falls back to the built-in catalog only.
Disable discovery without removing the provider:
```bash
openclaw config set plugins.entries.huggingface.config.discovery.enabled false
```
```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:** `:fastest` and `:cheapest` are HF router conventions, not something OpenClaw rewrites: the suffix is sent verbatim as part of the model id and HF's router picks the matching inference provider. Add each variant as its own entry under `models.providers.huggingface.models` (or in `model.primary`) if you want a distinct alias per suffix.
- **Config merge:** existing entries in `models.providers.huggingface.models` (e.g. in `models.json`) are kept on config merge, so any custom `name`, `alias`, or model options you set there persist across restarts.
<Note>
OpenClaw accepts both `HUGGINGFACE_HUB_TOKEN` and `HF_TOKEN`. If both are set, `HUGGINGFACE_HUB_TOKEN` takes precedence.
</Note>