Przejdź do głównej treści

​
Hugging Face (Inference)

Hugging Face Inference Providers oferują zgodne z OpenAI chat completions przez pojedyncze API routera. Otrzymujesz dostęp do wielu modeli (DeepSeek, Llama i innych) za pomocą jednego tokena. OpenClaw używa endpointu zgodnego z OpenAI (tylko chat completions); do text-to-image, embeddingów lub mowy użyj bezpośrednio klientów HF inference.
  • Provider: huggingface
  • Uwierzytelnianie: HUGGINGFACE_HUB_TOKEN lub HF_TOKEN (token o szczegółowych uprawnieniach z uprawnieniem Make calls to Inference Providers)
  • API: zgodne z OpenAI (https://router.huggingface.co/v1)
  • Rozliczenia: jeden token HF; cennik opiera się na stawkach providerów i obejmuje darmowy poziom.

​
Szybki start

  1. Utwórz token o szczegółowych uprawnieniach na stronie Hugging Face → Settings → Tokens z uprawnieniem Make calls to Inference Providers.
  2. Uruchom onboarding i wybierz Hugging Face z listy rozwijanej providerów, a następnie wprowadź klucz API, gdy pojawi się monit:
openclaw onboard --auth-choice huggingface-api-key
  1. Na liście rozwijanej Default Hugging Face model wybierz model, którego chcesz używać (lista jest ładowana z Inference API, gdy masz prawidłowy token; w przeciwnym razie wyświetlana jest wbudowana lista). Twój wybór zostanie zapisany jako model domyślny.
  2. Możesz też ustawić lub zmienić model domyślny później w konfiguracji:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

​
Przykład nieinteraktywny

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
To ustawi huggingface/deepseek-ai/DeepSeek-R1 jako model domyślny.

​
Uwaga dotycząca środowiska

Jeśli Gateway działa jako demon (launchd/systemd), upewnij się, że HUGGINGFACE_HUB_TOKEN lub HF_TOKEN jest dostępny dla tego procesu (na przykład w ~/.openclaw/.env lub przez env.shellEnv).

​
Wykrywanie modeli i lista rozwijana onboardingu

OpenClaw wykrywa modele, wywołując endpoint Inference bezpośrednio: 
GET https://router.huggingface.co/v1/models
(Opcjonalnie: wyślij Authorization: Bearer $HUGGINGFACE_HUB_TOKEN lub $HF_TOKEN, aby uzyskać pełną listę; niektóre endpointy bez uwierzytelniania zwracają tylko podzbiór.) Odpowiedź ma styl OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }. Gdy skonfigurujesz klucz API Hugging Face (przez onboarding, HUGGINGFACE_HUB_TOKEN lub HF_TOKEN), OpenClaw użyje tego żądania GET do wykrycia dostępnych modeli chat-completion. Podczas konfiguracji interaktywnej, po wprowadzeniu tokena zobaczysz listę rozwijaną Default Hugging Face model wypełnioną na podstawie tej listy (lub wbudowanego katalogu, jeśli żądanie się nie powiedzie). W czasie działania (np. przy uruchamianiu Gateway), gdy klucz jest dostępny, OpenClaw ponownie wywołuje GET https://router.huggingface.co/v1/models, aby odświeżyć katalog. Lista jest scalana z wbudowanym katalogiem (dla metadanych, takich jak okno kontekstu i koszt). Jeśli żądanie się nie powiedzie lub nie ustawiono klucza, używany jest tylko wbudowany katalog.

​
Nazwy modeli i opcje edytowalne

  • Nazwa z API: Wyświetlana nazwa modelu jest uzupełniana z GET /v1/models, gdy API zwraca name, title lub display_name; w przeciwnym razie jest wyprowadzana z identyfikatora modelu (np. deepseek-ai/DeepSeek-R1 → „DeepSeek R1”).
  • Nadpisanie nazwy wyświetlanej: Możesz ustawić własną etykietę dla każdego modelu w konfiguracji, aby był wyświetlany tak, jak chcesz w CLI i UI:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • Sufiksy polityk: Dołączona dokumentacja i helpery Hugging Face w OpenClaw obecnie traktują te dwa sufiksy jako wbudowane warianty polityk:
    • :fastest — najwyższa przepustowość.
    • :cheapest — najniższy koszt na token wyjściowy.
    Możesz dodać je jako osobne wpisy w models.providers.huggingface.models lub ustawić model.primary z tym sufiksem. Możesz też ustawić domyślną kolejność providerów w ustawieniach Inference Providers (brak sufiksu = użyj tej kolejności).
  • Scalanie konfiguracji: Istniejące wpisy w models.providers.huggingface.models (np. w models.json) są zachowywane podczas scalania konfiguracji. Oznacza to, że wszystkie ustawione tam własne name, alias lub opcje modelu zostaną zachowane.

​
Identyfikatory modeli i przykłady konfiguracji

Odwołania do modeli mają postać huggingface/<org>/<model> (identyfikatory w stylu Hub). Lista poniżej pochodzi z GET https://router.huggingface.co/v1/models; Twój katalog może zawierać więcej pozycji. Przykładowe identyfikatory (z endpointu inference):
ModelRef (z prefiksem huggingface/)
DeepSeek R1deepseek-ai/DeepSeek-R1
DeepSeek V3.2deepseek-ai/DeepSeek-V3.2
Qwen3 8BQwen/Qwen3-8B
Qwen2.5 7B InstructQwen/Qwen2.5-7B-Instruct
Qwen3 32BQwen/Qwen3-32B
Llama 3.3 70B Instructmeta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instructmeta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120Bopenai/gpt-oss-120b
GLM 4.7zai-org/GLM-4.7
Kimi K2.5moonshotai/Kimi-K2.5
Możesz dodać :fastest lub :cheapest do identyfikatora modelu. Ustaw domyślną kolejność w ustawieniach Inference Providers; pełną listę znajdziesz w Inference Providers oraz pod GET https://router.huggingface.co/v1/models.

​
Pełne przykłady konfiguracji

Główny model DeepSeek R1 z fallbackiem do Qwen: 
{
  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" },
      },
    },
  },
}
Qwen jako domyślny, z wariantami :cheapest i :fastest: 
{
  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)" },
      },
    },
  },
}
DeepSeek + Llama + GPT-OSS z aliasami: 
{
  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" },
      },
    },
  },
}
Wiele modeli Qwen i DeepSeek z sufiksami polityk: 
{
  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" },
      },
    },
  },
}