Перейти к основному содержанию
Поставщики инференса Hugging Face предлагают OpenAI-совместимые чат-завершения через единый API маршрутизатора. Вы получаете доступ ко множеству моделей (DeepSeek, Llama и другим) с одним токеном. OpenClaw использует OpenAI-совместимую конечную точку (только чат-завершения); для генерации изображений из текста, эмбеддингов или речи используйте клиенты HF inference напрямую.
  • Поставщик: huggingface
  • Аутентификация: HUGGINGFACE_HUB_TOKEN или HF_TOKEN (тонко настроенный токен с Make calls to Inference Providers)
  • API: OpenAI-совместимый (https://router.huggingface.co/v1)
  • Оплата: единый токен HF; цены следуют тарифам поставщика и включают бесплатный уровень.

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

1

Create a fine-grained token

Перейдите в Hugging Face Settings Tokens и создайте новый тонко настроенный токен.
Для токена должно быть включено разрешение Make calls to Inference Providers, иначе API-запросы будут отклонены.
2

Run onboarding

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

Select a default model

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

Verify the model is available

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). Список ниже получен из 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 к любому идентификатору модели. Задайте порядок по умолчанию в настройках Inference Provider; полный список см. в Inference Providers и GET https://router.huggingface.co/v1/models.

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

OpenClaw обнаруживает модели, вызывая конечную точку Inference напрямую:
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", ... }, ... ] }.Когда вы настраиваете API-ключ Hugging Face (через онбординг, HUGGINGFACE_HUB_TOKEN или HF_TOKEN), OpenClaw использует этот GET-запрос для обнаружения доступных моделей чат-завершений. Во время интерактивной настройки после ввода токена вы видите раскрывающийся список Default Hugging Face model, заполненный из этого списка (или из встроенного каталога, если запрос не удался). Во время выполнения (например, при запуске Gateway), когда ключ присутствует, OpenClaw снова вызывает GET https://router.huggingface.co/v1/models, чтобы обновить каталог. Список объединяется со встроенным каталогом (для метаданных, таких как контекстное окно и стоимость). Если запрос завершается неудачно или ключ не задан, используется только встроенный каталог.
  • Имя из API: отображаемое имя модели заполняется из GET /v1/models, когда API возвращает name, title или display_name; иначе оно выводится из идентификатора модели (например, deepseek-ai/DeepSeek-R1 становится “DeepSeek R1”).
  • Переопределение отображаемого имени: вы можете задать пользовательскую метку для каждой модели в конфигурации, чтобы она отображалась в CLI и UI так, как вам нужно:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • Суффиксы политики: встроенная документация и вспомогательные средства OpenClaw для Hugging Face сейчас рассматривают эти два суффикса как встроенные варианты политики:
    • :fastest — максимальная пропускная способность.
    • :cheapest — минимальная стоимость за выходной токен.
    Вы можете добавить их как отдельные записи в models.providers.huggingface.models или задать model.primary с суффиксом. Вы также можете задать порядок поставщиков по умолчанию в настройках Inference Provider (без суффикса = использовать этот порядок).
  • Слияние конфигурации: существующие записи в 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 имеет приоритет.
{
  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" },
      },
    },
  },
}

​
Связанные материалы

Model selection

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

Model selection

Как выбирать и настраивать модели.

Inference Providers docs

Официальная документация Hugging Face Inference Providers.

Configuration

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