> ## 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.

# Провайдер llama.cpp

`llama-cpp` — официальный внешний плагин провайдера для локальных
эмбеддингов GGUF. Он регистрирует идентификатор провайдера эмбеддингов `local` и владеет
зависимостью среды выполнения `node-llama-cpp`, используемой `memorySearch.provider: "local"`.

Установите его перед использованием локальных эмбеддингов памяти:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/llama-cpp-provider
```

Основной npm-пакет `openclaw` не включает `node-llama-cpp`. Размещение
нативной зависимости в этом плагине предотвращает удаление вручную установленной
среды выполнения внутри каталога пакета OpenClaw при обычных обновлениях OpenClaw через npm.

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

Задайте для `memorySearch.provider` значение `local`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        local: {
          modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
        },
      },
    },
  },
}
```

По умолчанию `local.modelPath` использует показанный выше URI `hf:` (`embeddinggemma-300m-qat-Q8_0.gguf`).
Чтобы использовать другую модель, укажите другой URI `hf:` или локальный файл `.gguf`.
`local.modelCacheDir` переопределяет расположение кеша загруженных моделей
(по умолчанию: `~/.node-llama-cpp/models`), а `local.contextSize` принимает
целое число или `"auto"`.

Если `local.contextSize` имеет числовое значение, провайдер также передаёт это требование
механизму автоматического размещения слоёв на GPU в node-llama-cpp. Это позволяет node-llama-cpp
совместно разместить модель и контекст эмбеддингов, сохраняя проверки безопасности
памяти. При `"auto"` node-llama-cpp использует обычное автоматическое размещение.

## Нативная среда выполнения

Для наиболее беспроблемной установки нативных компонентов используйте Node 24. В исходных
копиях проекта, использующих pnpm, может потребоваться разрешить и пересобрать нативную зависимость:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm approve-builds
pnpm rebuild node-llama-cpp
```

## Диагностика среды выполнения

После загрузки провайдера выполните `openclaw memory status --deep`, чтобы проверить
выбранный бэкенд и сборку, имена устройств, количество слоёв, выгруженных на GPU, запрошенный
размер контекста и последний зарегистрированный снимок VRAM или унифицированной памяти. Значения VRAM
содержат временную метку наблюдения, поскольку пассивное чтение состояния не
перезагружает модель и не опрашивает устройство.

Те же последние известные данные могут отображаться в `openclaw doctor`, если работающий
Gateway уже использовал локальный провайдер. Обычная команда проверки состояния или doctor
не загружает модель только для сбора диагностических данных.

## Устранение неполадок

Если `node-llama-cpp` отсутствует или не загружается, OpenClaw сообщает об ошибке
и предлагает:

1. Установить плагин: `openclaw plugins install @openclaw/llama-cpp-provider`.
2. Использовать Node 24 для установки и обновления нативных компонентов.
3. В исходной копии проекта с pnpm: `pnpm approve-builds`, затем `pnpm rebuild node-llama-cpp`.

Чтобы упростить использование локальных эмбеддингов без этапа нативной сборки,
вместо этого задайте для `memorySearch.provider` удалённый провайдер эмбеддингов, например
`lmstudio`, `ollama`, `openai` или `voyage`.