> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

[Провайдеры инференса Hugging Face](https://huggingface.co/docs/inference-providers) предоставляют совместимый с OpenAI маршрутизатор завершений чата для множества размещённых моделей (DeepSeek, Llama и других), доступных по одному токену. OpenClaw взаимодействует **только с конечной точкой завершений чата**; для преобразования текста в изображение, создания эмбеддингов или синтеза речи используйте напрямую [клиенты инференса HF](https://huggingface.co/docs/api-inference/quicktour).

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

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

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

Перейдите в [настройки токенов Hugging Face](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write\&tokenType=fineGrained) и создайте новый токен с детализированными разрешениями.

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --auth-choice huggingface-api-key
```

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw models list --provider huggingface
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` |

> [!TIP]
>
> Если токен действителен, OpenClaw также обнаруживает любые другие модели с помощью запроса **GET** к `https://router.huggingface.co/v1/models` во время первоначальной настройки и запуска Gateway, поэтому каталог может содержать гораздо больше четырёх указанных выше моделей. К идентификатору любой модели можно добавить `:fastest` или `:cheapest`; маршрутизатор HF направит запрос соответствующему провайдеру инференса. Задайте порядок провайдеров по умолчанию в [настройках провайдеров инференса](https://hf.co/settings/inference-providers).

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

> [accordion] Обнаружение моделей и раскрывающийся список первоначальной настройки
>
> OpenClaw обнаруживает модели с помощью следующего запроса:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> 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 использует только встроенный каталог.
>
> Чтобы отключить обнаружение, не удаляя провайдера:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw config set plugins.entries.huggingface.config.discovery.enabled false
> ```

> [accordion] Названия моделей, псевдонимы и суффиксы политик
>
> * **Название из API:** для обнаруженных моделей используются значения `name`, `title` или `display_name` из API, если они присутствуют; в противном случае OpenClaw формирует название из идентификатора модели (например, `deepseek-ai/DeepSeek-R1` преобразуется в «DeepSeek R1»).
> * **Переопределение отображаемого названия:** задайте пользовательскую метку для каждой модели в конфигурации:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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` и параметры моделей сохраняются после перезапусков.

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

> [accordion] Конфигурация: DeepSeek R1 с резервной моделью
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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" },
>       },
>     },
>   },
> }
> ```

> [accordion] Конфигурация: DeepSeek с самым дешёвым и самым быстрым вариантами
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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)" },
>       },
>     },
>   },
> }
> ```

> [accordion] Конфигурация: DeepSeek + Llama + GPT-OSS с псевдонимами
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   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" },
>       },
>     },
>   },
> }
> ```

## См. также

> [card] [Выбор модели](https://docs2.openclaw.ai/ru/concepts/model-providers.md)
>
> Обзор всех провайдеров, ссылок на модели и поведения при переключении на резервные модели.

> [card] [Выбор модели](https://docs2.openclaw.ai/ru/concepts/models.md)
>
> Выбор и настройка моделей.

> [card] [Документация по провайдерам инференса](https://huggingface.co/docs/inference-providers)
>
> Официальная документация по провайдерам инференса Hugging Face.

> [card] [Конфигурация](https://docs2.openclaw.ai/ru/gateway/configuration.md)
>
> Полный справочник по конфигурации.