jason.woltje
193479b52d
Mosaic concepts pages now own the adapted content; source/license metadata under docs/reference/concepts. Adds ACT-1 agent-context planning capture, pinned concept test package + preparation utility, foundation observation notes (durability, evidence, federation, onboarding, workflow), and the #1495 consolidation assessment. TOOLS.md updated for the host-dev launcher.
210 lines
8.7 KiB
Markdown
210 lines
8.7 KiB
Markdown
---
|
|
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) 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](https://huggingface.co/docs/api-inference/quicktour) 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](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 a model. The list loads from the Inference API when your token is valid; otherwise OpenClaw shows the built-in catalog below. Your choice is saved as `agents.defaults.model.primary`:
|
|
|
|
```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 --accept-risk --skip-health \
|
|
--mode local \
|
|
--auth-choice huggingface-api-key \
|
|
--huggingface-api-key "$HF_TOKEN"
|
|
```
|
|
|
|
Sets `huggingface/deepseek-ai/DeepSeek-R1` as the default model.
|
|
|
|
## Model IDs
|
|
|
|
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` |
|
|
|
|
<Tip>
|
|
When your token is valid, OpenClaw also discovers any other model from **GET** `https://router.huggingface.co/v1/models` at onboarding time and Gateway startup, so your catalog can include far more than the three models above. You can append `:fastest` or `:cheapest` to any model id; HF's router routes to the matching inference provider. Set your default provider order in [Inference Provider settings](https://hf.co/settings/inference-providers).
|
|
</Tip>
|
|
|
|
## Advanced configuration
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Model discovery and onboarding dropdown">
|
|
OpenClaw discovers models with:
|
|
|
|
```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. Matching built-in models supply metadata such as context window and cost. Failed discovery produces a catalog failure outcome; a successful empty response stays empty. Without a key, the static catalog remains available without starting discovery.
|
|
|
|
Disable discovery without removing the provider:
|
|
|
|
```bash
|
|
openclaw config set plugins.entries.huggingface.config.discovery.enabled false
|
|
```
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="Model names, aliases, and policy suffixes">
|
|
- **Name from API:** discovered models use the API's `name`, `title`, or `display_name` when present; otherwise OpenClaw derives a name from the model id (e.g. `deepseek-ai/DeepSeek-R1` becomes "DeepSeek R1").
|
|
- **Override display name:** set a custom label per model in config:
|
|
|
|
```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.
|
|
|
|
</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`. If both are set, `HUGGINGFACE_HUB_TOKEN` takes precedence.
|
|
</Note>
|
|
|
|
</Accordion>
|
|
|
|
<Accordion title="Config: DeepSeek R1 with fallback">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
model: {
|
|
primary: "huggingface/deepseek-ai/DeepSeek-R1",
|
|
fallbacks: ["huggingface/openai/gpt-oss-120b"],
|
|
},
|
|
models: {
|
|
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
|
|
"huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Config: DeepSeek with cheapest and fastest variants">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
|
|
models: {
|
|
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
|
|
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },
|
|
"huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Config: DeepSeek + GPT-OSS with aliases">
|
|
```json5
|
|
{
|
|
agents: {
|
|
defaults: {
|
|
model: {
|
|
primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
|
|
fallbacks: ["huggingface/openai/gpt-oss-120b"],
|
|
},
|
|
models: {
|
|
"huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
|
|
"huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
</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>
|