Hugging Face (инференс)

Провайдеры инференса Hugging Face предоставляют совместимый с OpenAI маршрутизатор завершений чата для множества размещённых моделей (DeepSeek, Llama и других), доступных по одному токену. OpenClaw взаимодействует только с конечной точкой завершений чата; для преобразования текста в изображение, создания эмбеддингов или синтеза речи используйте напрямую клиенты инференса HF.

Свойство	Значение
Идентификатор провайдера	`huggingface`
Плагин	встроенный (включён по умолчанию, установка не требуется)
Переменная среды авторизации	`HUGGINGFACE_HUB_TOKEN` или `HF_TOKEN` (токен с детализированными разрешениями)
API	совместимый с OpenAI (`https://router.huggingface.co/v1`)
Оплата	единый токен HF; цены соответствуют тарифам провайдера и включают бесплатный уровень

Начало работы

Создайте токен с детализированными разрешениями

Перейдите в настройки токенов Hugging Face и создайте новый токен с детализированными разрешениями.

Для токена необходимо включить разрешение Make calls to Inference Providers, иначе запросы к API будут отклонены.

Запустите первоначальную настройку

Выберите Hugging Face в раскрывающемся списке провайдеров, затем по запросу введите ключ API:

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

Выберите модель по умолчанию

В раскрывающемся списке Модель Hugging Face по умолчанию выберите модель. Если токен действителен, список загружается из Inference API; в противном случае OpenClaw отображает приведённый ниже встроенный каталог. Ваш выбор сохраняется как agents.defaults.model.primary:

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

Убедитесь, что модель доступна

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 в качестве модели по умолчанию.

Идентификаторы моделей

Ссылки на модели имеют формат huggingface/<org>/<model> (идентификаторы в стиле Hub). Встроенный каталог OpenClaw:

Модель	Ссылка (с префиксом `huggingface/`)
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.1	`deepseek-ai/DeepSeek-V3.1`
GPT-OSS 120B	`openai/gpt-oss-120b`
Llama 3.3 70B Instruct Turbo	`meta-llama/Llama-3.3-70B-Instruct-Turbo`

Если токен действителен, OpenClaw также обнаруживает любые другие модели с помощью запроса GET к https://router.huggingface.co/v1/models во время первоначальной настройки и запуска Gateway, поэтому каталог может содержать гораздо больше четырёх указанных выше моделей. К идентификатору любой модели можно добавить :fastest или :cheapest; маршрутизатор HF направит запрос соответствующему провайдеру инференса. Задайте порядок провайдеров по умолчанию в настройках провайдеров инференса.

Расширенная конфигурация

Обнаружение моделей и раскрывающийся список первоначальной настройки

OpenClaw обнаруживает модели с помощью следующего запроса:

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # или $HF_TOKEN

Ответ имеет формат OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.Если ключ настроен (через первоначальную настройку, HUGGINGFACE_HUB_TOKEN или HF_TOKEN), раскрывающийся список Модель Hugging Face по умолчанию при интерактивной настройке заполняется данными из этой конечной точки. При запуске Gateway тот же запрос выполняется повторно для обновления каталога. Обнаруженные модели объединяются с приведённым выше встроенным каталогом, который используется для метаданных, например размера контекстного окна и стоимости, если идентификаторы совпадают. Если запрос завершается ошибкой, не возвращает данных или ключ не задан, OpenClaw использует только встроенный каталог.Чтобы отключить обнаружение, не удаляя провайдера:

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

Названия моделей, псевдонимы и суффиксы политик

Название из API: для обнаруженных моделей используются значения name, title или display_name из API, если они присутствуют; в противном случае OpenClaw формирует название из идентификатора модели (например, deepseek-ai/DeepSeek-R1 преобразуется в «DeepSeek R1»).
Переопределение отображаемого названия: задайте пользовательскую метку для каждой модели в конфигурации:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

Суффиксы политик: :fastest и :cheapest — это соглашения маршрутизатора HF, которые OpenClaw не изменяет: суффикс передаётся дословно как часть идентификатора модели, а маршрутизатор HF выбирает соответствующего провайдера инференса. Если для каждого суффикса требуется отдельный псевдоним, добавьте каждый вариант как отдельную запись в models.providers.huggingface.models (или в model.primary).
Объединение конфигурации: существующие записи в models.providers.huggingface.models (например, в models.json) сохраняются при объединении конфигурации, поэтому заданные там пользовательские значения name, alias и параметры моделей сохраняются после перезапусков.

Настройка среды и фоновой службы

Если Gateway работает как фоновая служба (launchd/systemd), убедитесь, что HUGGINGFACE_HUB_TOKEN или HF_TOKEN доступны этому процессу (например, через ~/.openclaw/.env или env.shellEnv).

OpenClaw принимает как HUGGINGFACE_HUB_TOKEN, так и HF_TOKEN. Если заданы обе переменные, приоритет имеет HUGGINGFACE_HUB_TOKEN.

Конфигурация: DeepSeek R1 с резервной моделью

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

Конфигурация: DeepSeek с самым дешёвым и самым быстрым вариантами

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },
      },
    },
  },
}

Конфигурация: DeepSeek + Llama + GPT-OSS с псевдонимами

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
        fallbacks: [
          "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo",
          "huggingface/openai/gpt-oss-120b",
        ],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
        "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo": { alias: "Llama 3.3 70B Turbo" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

См. также

Выбор модели

Обзор всех провайдеров, ссылок на модели и поведения при переключении на резервные модели.

Выбор модели

Выбор и настройка моделей.

Документация по провайдерам инференса

Официальная документация по провайдерам инференса Hugging Face.

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

Полный справочник по конфигурации.

Overview

Concepts and configuration

Providers

Hugging Face (инференс)

Начало работы

Неинтерактивная настройка

Идентификаторы моделей

Расширенная конфигурация

См. также

Выбор модели

Выбор модели

Документация по провайдерам инференса

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

​Начало работы

​Неинтерактивная настройка

​Идентификаторы моделей

​Расширенная конфигурация

​См. также

Выбор модели

Выбор модели

Документация по провайдерам инференса

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

Начало работы

Неинтерактивная настройка

Идентификаторы моделей

Расширенная конфигурация

См. также