Hugging Face (inference)

OpenClaw discovers models with:

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

The response is OpenAI-style: { "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 are merged 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

• 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.

If the Gateway runs as a daemon (launchd/systemd), make sure HUGGINGFACE_HUB_TOKEN or HF_TOKEN is available to that process (for example, in ~/.openclaw/.env or via env.shellEnv).