Using Hugging Face with OpenClaw

Prerequisites

• ✓A Hugging Face account with access to Inference Providers and permission to create fine-grained tokens.
• ✓A fine-grained Hugging Face token with the 'Make calls to Inference Providers' permission enabled.
• ✓An existing OpenClaw installation where you can run the `openclaw` CLI and edit its config files.
• ✓Network access from your OpenClaw environment to `https://router.huggingface.co/v1`.

Steps

1. 1

   Create a fine-grained Hugging Face token

   Start by creating the token that OpenClaw will use to talk to Hugging Face Inference Providers. If you skip the specific permission, the router will reject every request and model discovery will fail.

   Go to the Hugging Face token creation page and ensure the token has the 'Make calls to Inference Providers' permission enabled.

2. 2

   Run interactive onboarding for the Hugging Face provider

   Use the OpenClaw onboarding flow to register Hugging Face as a model provider and store your token. Pick Hugging Face in the provider dropdown when prompted, then run this command so OpenClaw knows to ask for a Hugging Face API key.

   If the token is invalid or missing permissions, the subsequent model dropdown will not populate correctly.

   bashCopy

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

3. 3

   Select a default Hugging Face model for your agents

   After onboarding, choose which Hugging Face model OpenClaw should use by default for chat completions. In the Default Hugging Face model dropdown, OpenClaw loads the list from the Inference API when your token works; otherwise it falls back to a built-in catalog.

   You can also hard-code or change the default later in your config using the snippet below.

   jsonCopy

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

4. 4

   Verify Hugging Face models are available in OpenClaw

   Once the token and default model are set, confirm that OpenClaw can see Hugging Face models. This command queries the Hugging Face router (and merges results with the built-in catalog) so you can verify IDs and availability.

   If the list is empty or missing models you expect, your token or network access is likely misconfigured.

   bashCopy

   openclaw models list --provider huggingface

5. 5

   Automate setup with non-interactive onboarding

   For CI or scripted environments, configure Hugging Face without the interactive prompts. This command wires your `HF_TOKEN` into OpenClaw, sets the mode to local, and configures Hugging Face as the auth choice.

   It also sets `huggingface/deepseek-ai/DeepSeek-R1` as the default model so your agents are ready to call the router immediately.

   bashCopy

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

6. 6

   Configure model fallbacks and aliases for Hugging Face models

   Once the basics work, define primary models, fallbacks, and human-friendly aliases so your agents can fail over cleanly across Hugging Face models. json`) and control how models appear in the CLI and UI.

   Use them to wire DeepSeek, Qwen, Llama, and GPT-OSS variants with clear labels and policy suffixes.

   jsonCopy

   {
     agents: {
       defaults: {
         model: {
           primary: "huggingface/deepseek-ai/DeepSeek-R1",
           fallbacks: ["huggingface/Qwen/Qwen3-8B"],
         },
         models: {
           "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
           "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         model: { primary: "huggingface/Qwen/Qwen3-8B" },
         models: {
           "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
           "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
           "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         model: {
           primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
           fallbacks: [
             "huggingface/meta-llama/Llama-3.3-70B-Instruct",
             "huggingface/openai/gpt-oss-120b",
           ],
         },
         models: {
           "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
           "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
           "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
         },
       },
     },
   }
   
   {
     agents: {
       defaults: {
         model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
         models: {
           "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
           "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
           "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
           "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
         },
       },
     },
   }

Configuration

Troubleshooting

GET https://router.huggingface.co/v1/models

Frequently asked questions