OpenClaw Guide

OpenClaw + Hugging Face: Inference Providers Setup

Q: Does OpenClaw support Hugging Face natively?

Yes. OpenClaw includes a native huggingface provider that calls the Hugging Face Inference Providers router using a model id in the form huggingface/ / .

Q: Which environment variable should I use?

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

Q: Why is my Hugging Face token rejected?

The token must have the "Make calls to Inference Providers" permission enabled. A read-only token can browse the Hub but will be rejected for inference calls.

Q: What do the :fastest and :cheapest suffixes do?

Appending :fastest, :cheapest, or a named provider such as :together to the model id tells the Hugging Face router which inference provider should serve the request.

Q: Can OpenClaw use Hugging Face for images or embeddings?

No. The OpenClaw Hugging Face provider covers chat completions only. Image generation, embeddings and speech require using Hugging Face inference clients directly.

Hugging Face Inference Providers gives you one interface to models served by many different inference partners, and OpenClaw can use it as a native provider. The configuration is short. The two things that trip people up are the token permission and the difference between a model existing on the Hub and a model being served for inference.

How the integration works

Hugging Face Inference Providers is a router. Rather than integrating separately with each inference partner, you call one OpenAI-compatible endpoint and Hugging Face forwards the request to whichever provider serves that model. OpenClaw talks to that router through its huggingface provider.

This is not the same as downloading weights from the Hub. You do not need a local GPU for the path in this guide — model availability, provider routing, and billing all run through your Hugging Face account. If you would rather run models on your own hardware, see the Ollama guide instead.

Before you start

A working OpenClaw installation, or a managed instance
A Hugging Face account
A fine-grained Hugging Face token with inference-provider permission
A chat-capable model available through Inference Providers

If OpenClaw is not installed yet, start with the OpenClaw installation guide.

Step 1: create the correct token

Open your Hugging Face account settings and go to Access Tokens.
Create a fine-grained token.
Enable the permission labelled Make calls to Inference Providers.
Copy the token once and store it in a password manager.

This is the step that fails most often. A general read token will happily load model pages and still be rejected the moment OpenClaw asks for inference. If you get a 401 or 403, check the permission before you change anything else.

Step 2: give OpenClaw the token

The fastest route is onboarding, which walks through authentication and model selection together:

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

You can also set the token in the environment. OpenClaw accepts either variable, and HUGGINGFACE_HUB_TOKEN wins if both are present:

# either of these
HUGGINGFACE_HUB_TOKEN=hf_your_token_here
HF_TOKEN=hf_your_token_here

If OpenClaw runs as a background service rather than in your interactive shell, the token has to be visible to that process — exporting it in a shell profile is not enough for a daemon that starts at boot.

Step 3: choose a model

With a valid token configured, OpenClaw discovers available chat-completion models from the Hugging Face router, so the picker shows what your account can actually reach rather than a static list. Model ids follow the pattern huggingface/<org>/<model>:

huggingface/deepseek-ai/DeepSeek-R1
huggingface/deepseek-ai/DeepSeek-V3.1
huggingface/openai/gpt-oss-120b

To set one as the default in config:

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

Step 4: pick how requests are routed

A single model can be served by several inference providers at different speeds and prices. Append a suffix to the model id to choose between them:

huggingface/deepseek-ai/DeepSeek-R1:fastest
huggingface/deepseek-ai/DeepSeek-R1:cheapest
huggingface/deepseek-ai/DeepSeek-R1:together

The suffix is sent verbatim as part of the model id and Hugging Face's router picks the matching provider. :cheapest is a reasonable default for high-volume background work; :fastest suits interactive chat where latency is noticeable.

Step 5: verify

Send one small, non-sensitive prompt and confirm the three layers separately:

OpenClaw recognises the huggingface provider.
The token is accepted for Inference Providers.
The selected model is currently served for chat inference.

Keeping that first request trivial is what makes an auth or routing failure distinguishable from a prompt or tool-calling problem later.

Troubleshooting

401 or 403

Confirm the token carries the Inference Providers call permission.
Check whether a stale HUGGINGFACE_HUB_TOKEN is overriding your new HF_TOKEN.
Restart the OpenClaw process after changing its environment.
Look for stray whitespace or quotes around the value, and confirm the token was not revoked.

Model not available

Re-check the live list rather than reusing a model id from an old blog post.
Confirm the model supports conversational inference.
If the model is gated, accept its licence and confirm your account has access.
Try removing a provider suffix — that specific provider may not currently serve the model.

Image or embedding calls fail

Expected. This provider path is chat completions only. Use the Hugging Face inference clients directly for text-to-image, embeddings, or speech.

Security checklist

Use a dedicated fine-grained token rather than a broad account token.
Keep it in the runtime environment, not in a Git-tracked file.
Never paste it into chat, screenshots, or a support thread.
Rotate it if it ever appears in logs.
Review Hugging Face usage periodically so unexpected calls surface early.

OpenClaw + Hugging Face FAQ

Does OpenClaw support Hugging Face natively?

Yes. OpenClaw ships a huggingface provider that talks to the Hugging Face Inference Providers router. Set a token, choose a model id in the form huggingface/<org>/<model>, and OpenClaw routes chat completions through it.

Which environment variable should I use?

Either HUGGINGFACE_HUB_TOKEN or HF_TOKEN works. If both are set, HUGGINGFACE_HUB_TOKEN takes precedence — worth knowing when an old value in your shell profile quietly overrides the one you just added.

Why is my Hugging Face token rejected?

Almost always the permission. The token must have Make calls to Inference Providers enabled. A plain read token can browse model pages on the Hub and still be refused for inference, which makes the failure look like a model problem rather than a token problem.

What do the :fastest and :cheapest suffixes do?

They pick which inference provider serves the model. Append :fastest, :cheapest, or a named provider such as :together to the model id. The suffix is passed through verbatim and Hugging Face's router selects the matching provider.

Can OpenClaw use Hugging Face for images or embeddings?

No. This provider path covers the chat completions endpoint only. Text-to-image, embeddings, and speech need the Hugging Face inference clients directly rather than the OpenClaw model provider.