Hugging Face Inference Provider Setup for Neura Market

Hugging Face Inference Providers provides an OpenAI-compatible chat completions router that sits in front of many hosted models (DeepSeek, Llama, and others) all accessible with a single token. OpenClaw only uses the chat completions endpoint; for text-to-image, embeddings, or speech tasks, use the HF inference clients directly.

Getting started

Create a fine-grained token

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

Warning

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

Run onboarding

Select Hugging Face from the provider dropdown, then enter your API key when prompted:

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

Select a default model

In the Default Hugging Face model dropdown, pick a model. When your token is valid, the list loads from the Inference API; otherwise OpenClaw shows the built-in catalog below. Your selection is 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 \
  --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 references use the format huggingface/<org>/<model> (Hub-style IDs). OpenClaw's built-in catalog:

Tip

When your token is valid, OpenClaw also discovers any other model from GET https://router.huggingface.co/v1/models during onboarding 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.

Advanced configuration

Model discovery and onboarding dropdown

OpenClaw discovers models with:

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", ... }, ... ] }.

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

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:

{
  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), ensure 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.

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, Overview of all providers, model refs, and failover behavior.

• Model selection, How to choose and configure models.

• Inference Providers docs, Official Hugging Face Inference Providers documentation.

• Configuration, Full config reference.