OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

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 и создайте новый токен с детализированными разрешениями.

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

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

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

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

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

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

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

    bash
    openclaw models list --provider huggingface

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

    bash
    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 обнаруживает модели с помощью следующего запроса:

    bash
    GET https://router.huggingface.co/v1/modelsAuthorization: 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 использует только встроенный каталог.

    Чтобы отключить обнаружение, не удаляя провайдера:

    bash
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    Названия моделей, псевдонимы и суффиксы политик
    • Название из API: для обнаруженных моделей используются значения name, title или display_name из API, если они присутствуют; в противном случае OpenClaw формирует название из идентификатора модели (например, deepseek-ai/DeepSeek-R1 преобразуется в «DeepSeek R1»).
    • Переопределение отображаемого названия: задайте пользовательскую метку для каждой модели в конфигурации:
    json5
    {  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).

    Конфигурация: DeepSeek R1 с резервной моделью
    json5
    {  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 с самым дешёвым и самым быстрым вариантами
    json5
    {  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 с псевдонимами
    json5
    {  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.
    Конфигурация

    Полный справочник по конфигурации.
    Was this useful?
    On this page

    On this page