Hugging Face Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Hugging Face (inference)

개요

이 페이지는 OpenClaw Hugging Face provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Hugging Face Inference setup (auth + model selection)

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

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

공식 문서 기반 상세

아래는 공식 providers/huggingface 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

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

시작하기

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.

The token must have the Make calls to Inference Providers permission enabled or API requests will be rejected.

Run onboarding

Choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:

```bash
openclaw onboard --auth-choice huggingface-api-key
```

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" },
    },
  },
}
```

Verify the model is available

```bash
openclaw models list --provider huggingface
```

Non-interactive setup

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 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

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.

고급 설정

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. 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
```

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.

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`).

OpenClaw accepts both HUGGINGFACE_HUB_TOKEN and HF_TOKEN. If both are set, HUGGINGFACE_HUB_TOKEN takes precedence.

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" },
      },
    },
  },
}
```

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)" },
      },
    },
  },
}
```

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" },
      },
    },
  },
}
```

관련 문서

Overview of all providers, model refs, and failover behavior.


How to choose and configure models.


Official Hugging Face Inference Providers documentation.


Full config reference.

검증 체크리스트

• openclaw models list --provider huggingface 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers