Перейти до основного вмісту

​
Hugging Face (Inference)

Провайдери Hugging Face Inference пропонують OpenAI-сумісні chat completions через єдиний router API. Ви отримуєте доступ до багатьох моделей (DeepSeek, Llama та інших) з одним токеном. OpenClaw використовує OpenAI-сумісний endpoint (лише chat completions); для text-to-image, embeddings або speech використовуйте HF inference clients напряму.
  • Провайдер: huggingface
  • Автентифікація: HUGGINGFACE_HUB_TOKEN або HF_TOKEN (fine-grained token з дозволом Make calls to Inference Providers)
  • API: OpenAI-сумісний (https://router.huggingface.co/v1)
  • Оплата: один токен HF; тарифи відповідають ставкам провайдерів і мають безкоштовний рівень.

​
Початок роботи

1

Створіть fine-grained token

Перейдіть до Hugging Face Settings Tokens і створіть новий fine-grained token.
Для токена має бути ввімкнено дозвіл Make calls to Inference Providers, інакше API-запити буде відхилено.
2

Запустіть онбординг

Виберіть Hugging Face у випадаючому списку провайдера, а потім введіть свій API-ключ, коли з’явиться запит:
openclaw onboard --auth-choice huggingface-api-key
3

Виберіть модель за замовчуванням

У випадаючому списку Default Hugging Face model виберіть потрібну модель. Список завантажується з Inference API, якщо у вас є дійсний токен; інакше показується вбудований список. Ваш вибір зберігається як модель за замовчуванням.Ви також можете встановити або змінити модель за замовчуванням пізніше в config:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
4

Перевірте, що модель доступна

openclaw models list --provider huggingface

​
Неінтерактивне налаштування

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
Це встановить huggingface/deepseek-ai/DeepSeek-R1 як модель за замовчуванням.

​
ID моделей

Посилання на моделі використовують формат huggingface/<org>/<model> (Hub-style ID). Список нижче взято з GET https://router.huggingface.co/v1/models; ваш каталог може містити більше.
МодельRef (додайте префікс 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
Ви можете додати :fastest або :cheapest до будь-якого ID моделі. Установіть порядок за замовчуванням у налаштуваннях Inference Provider; див. Inference Providers і GET https://router.huggingface.co/v1/models для повного списку.

​
Додаткові подробиці

OpenClaw виявляє моделі, викликаючи endpoint Inference напряму:
GET https://router.huggingface.co/v1/models
(Необов’язково: надсилайте Authorization: Bearer $HUGGINGFACE_HUB_TOKEN або $HF_TOKEN для повного списку; деякі endpoint без автентифікації повертають лише підмножину.) Відповідь має формат OpenAI { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Коли ви налаштовуєте API-ключ Hugging Face (через онбординг, HUGGINGFACE_HUB_TOKEN або HF_TOKEN), OpenClaw використовує цей GET для виявлення доступних моделей chat-completion. Під час інтерактивного налаштування, після введення токена, ви побачите випадаючий список Default Hugging Face model, заповнений із цього списку (або з вбудованого каталогу, якщо запит не вдасться). Під час виконання (наприклад, під час запуску Gateway), якщо ключ наявний, OpenClaw знову викликає GET https://router.huggingface.co/v1/models, щоб оновити каталог. Список об’єднується з вбудованим каталогом (для метаданих, як-от context window і вартість). Якщо запит не вдається або ключ не задано, використовується лише вбудований каталог.
  • Назва з API: Відображувана назва моделі заповнюється з GET /v1/models, коли API повертає name, title або display_name; інакше вона виводиться з ID моделі (наприклад, deepseek-ai/DeepSeek-R1 стає “DeepSeek R1”).
  • Перевизначення відображуваної назви: Ви можете задати власну мітку для кожної моделі в config, щоб вона відображалася в CLI та UI так, як вам потрібно:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • Суфікси політик: У вбудованій документації та helper-утилітах Hugging Face в OpenClaw ці два суфікси наразі розглядаються як вбудовані варіанти політик:
    • :fastest — найвища пропускна здатність.
    • :cheapest — найнижча вартість за вихідний токен.
    Ви можете додати їх як окремі записи в models.providers.huggingface.models або встановити model.primary із суфіксом. Ви також можете задати порядок провайдерів за замовчуванням у налаштуваннях Inference Provider (без суфікса = використовувати цей порядок).
  • Об’єднання config: Наявні записи в models.providers.huggingface.models (наприклад, у models.json) зберігаються під час об’єднання config. Тож будь-які власні name, alias або параметри моделі, які ви там задали, буде збережено.
Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що HUGGINGFACE_HUB_TOKEN або HF_TOKEN доступні цьому процесу (наприклад, у ~/.openclaw/.env або через env.shellEnv).
OpenClaw приймає і HUGGINGFACE_HUB_TOKEN, і HF_TOKEN як псевдоніми змінних середовища. Працює будь-яка з них; якщо задано обидві, пріоритет має HUGGINGFACE_HUB_TOKEN.
{
  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" },
      },
    },
  },
}

​
Пов’язане

Провайдери моделей

Огляд усіх провайдерів, посилань на моделі та поведінки резервного перемикання.

Вибір моделі

Як вибирати й налаштовувати моделі.

Документація Inference Providers

Офіційна документація Hugging Face Inference Providers.

Конфігурація

Повний довідник із config.