Hugging Face Inference Provider Setup and Model Selection

Hugging Face Inference Providers puts an OpenAI-compatible chat completions router in front of a range of hosted models (DeepSeek, Llama, and others) using a single token. OpenClaw only interacts with the chat completions endpoint; for text-to-image, embeddings, or speech, call the HF inference clients directly.

Getting started

Create a fine-grained token

Head to Hugging Face Settings Tokens and generate a new fine-grained token.

Warning

The Make calls to Inference Providers permission must be enabled on the token, otherwise API requests will be refused.

Run onboarding

In the provider dropdown, select Hugging Face, then provide your API key when asked:

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

Select a default model

From the Default Hugging Face model dropdown, pick a model. When your token is valid, the list is populated from the Inference API; otherwise OpenClaw falls back to the built-in catalog shown below. Your selection gets stored as agents.defaults.model.primary:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

Verify the model is available

openclaw models list --provider huggingface

Non-interactive setup

openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

Assigns huggingface/deepseek-ai/DeepSeek-R1 as the default model.

Model IDs

Model references follow the pattern huggingface/<org>/<model> (Hub-style IDs). OpenClaw's built-in catalog:

Tip

With a valid token, OpenClaw also picks up any other model through GET https://router.huggingface.co/v1/models during onboarding and at Gateway startup, so your catalog can hold far more than the three listed above. You can attach :fastest or :cheapest to any model id; HF's router then directs traffic to the appropriate inference provider. Configure your default provider order under Inference Provider settings.

Advanced configuration

Model discovery and onboarding dropdown

Model discovery in OpenClaw uses:

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # or $HF_TOKEN

The response follows the OpenAI format: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.

When a key is set (via onboarding, HUGGINGFACE_HUB_TOKEN, or HF_TOKEN), the Default Hugging Face model dropdown in interactive setup gets its entries from this endpoint. Gateway startup repeats the same call to refresh the catalog. Discovered models are combined with the built-in catalog above (which supplies metadata like context window and cost when an id matches). If the call fails, returns nothing, or no key is configured, OpenClaw uses only the built-in catalog.

To turn off discovery while keeping the provider:

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 available; otherwise OpenClaw builds a name from the model id (e.g. deepseek-ai/DeepSeek-R1 becomes "DeepSeek R1").
• Override display name: give each model a custom label in config:

{
  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 modifies: the suffix is passed through unchanged as part of the model id, and HF's router selects the matching inference provider. If you want a distinct alias per suffix, add each variant as its own entry under models.providers.huggingface.models (or in model.primary).
• Config merge: existing entries in models.providers.huggingface.models (e.g. in models.json) survive a config merge, so any custom name, alias, or model options you define there remain intact across restarts.

Environment and daemon setup

If the Gateway runs as a daemon (launchd/systemd), ensure HUGGINGFACE_HUB_TOKEN or HF_TOKEN is accessible to that process (for instance, in ~/.openclaw/.env or through env.shellEnv).

Note

OpenClaw supports both HUGGINGFACE_HUB_TOKEN and HF_TOKEN. When both are present, HUGGINGFACE_HUB_TOKEN wins.

Config: DeepSeek R1 with fallback

{
  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

{
  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

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

Related

• Model selection, A summary covering every provider, model references, and failover logic.

• Model selection, Guidance on picking and setting up models.

• Inference Providers docs, The official Hugging Face Inference Providers reference.

• Configuration, Complete configuration details.