Configure Hugging Face Inference in OpenClaw

Hugging Face Inference Providers puts an OpenAI-compatible chat completions router in front of a large set of hosted models (DeepSeek, Llama, and others), all reachable with a single token. OpenClaw only communicates with the chat completions endpoint; if you need text-to-image, embeddings, or speech, go straight to the HF inference clients.

Getting started

Create a fine-grained token

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

Warning

API requests will be rejected unless the token has the Make calls to Inference Providers permission turned on.

Run onboarding

Pick Hugging Face from the provider dropdown, then supply your API key when asked:

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

Select a default model

Select a model from the Default Hugging Face model dropdown. Once your token is valid, the list is pulled from the Inference API; if not, OpenClaw falls back to the built-in catalog shown below. Whatever you pick 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"

Makes huggingface/deepseek-ai/DeepSeek-R1 the default model.

Model IDs

Model refs take the form huggingface/<org>/<model> (Hub-style IDs). Here is OpenClaw's built-in catalog:

Tip

With a valid token, OpenClaw additionally finds any other model through GET https://router.huggingface.co/v1/models during onboarding and again at Gateway startup, so your catalog may end up much larger than the three models listed above. Any model id can have :fastest or :cheapest appended; HF's router then directs the request to the matching inference provider. Configure your default provider order under Inference Provider settings.

Advanced configuration

Model discovery and onboarding dropdown

Model discovery in OpenClaw works like this:

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

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

When a key is configured (through onboarding, HUGGINGFACE_HUB_TOKEN, or HF_TOKEN), this endpoint populates the Default Hugging Face model dropdown during interactive setup. The same call runs again at Gateway startup to refresh the catalog. Built-in models that match contribute metadata like context window and cost. A failed discovery yields a catalog failure outcome, while a successful but empty response stays empty. If no key exists, the static catalog is still available and discovery never starts.

To turn discovery off while keeping the provider:

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

Model names, aliases, and policy suffixes

• Name from API: a discovered model is named using the API's name, title, or display_name when one is present; if none is, OpenClaw builds a name from the model id (for instance, deepseek-ai/DeepSeek-R1 turns into "DeepSeek R1").
• Override display name: give a 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 come from HF router conventions, and OpenClaw does not rewrite them: the suffix travels verbatim inside the model id, and HF's router selects the matching inference provider. If you want a separate alias for each suffix, list every variant as its own entry under models.providers.huggingface.models (or inside model.primary).
• Config merge: entries already present in models.providers.huggingface.models (in models.json, for example) survive a config merge, so any custom name, alias, or model options you set there remain in place after restarts.

Environment and daemon setup

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

Note

Both HUGGINGFACE_HUB_TOKEN and HF_TOKEN are accepted by OpenClaw. Should both be set, 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 rundown of every provider, how model refs work, and what happens during failover.

• Models, Picking models and setting them up.

• Inference Providers docs, Hugging Face's own documentation for Inference Providers.

• Configuration, The complete configuration reference.