Локальные сервисы моделей

models.providers.<id>.localService по запросу запускает локальный сервер моделей, принадлежащий провайдеру. Когда запрос к модели или эмбеддингу выбирает этого провайдера, OpenClaw проверяет конечную точку состояния, запускает процесс, если он не работает, ожидает готовности, а затем отправляет запрос. Используйте эту возможность, чтобы не держать ресурсоёмкие локальные серверы запущенными весь день.

Как это работает

Запрос к модели или эмбеддингу разрешается в настроенного провайдера.
Если у этого провайдера есть localService, OpenClaw проверяет healthUrl.
Если проверка успешна, OpenClaw использует уже запущенный сервер.
Если проверка завершается неудачно, OpenClaw запускает command с args.
OpenClaw опрашивает конечную точку состояния до истечения readyTimeoutMs.
Запрос проходит через обычный транспорт модели или эмбеддинга.
Если OpenClaw запустил процесс и задано idleStopMs, он останавливает процесс, когда после последнего активного запроса в течение указанного времени не было активности.

Для этого OpenClaw не устанавливает launchd, systemd, Docker или какой-либо демон. Сервер представляет собой обычный дочерний процесс того процесса OpenClaw, которому он потребовался первым. Запуск сериализуется для каждой комбинации настроенного провайдера, команды, аргументов и переменных окружения, поэтому параллельные запросы чата и эмбеддингов к одной службе не запускают дублирующиеся серверы. Каждый запрос удерживает собственную аренду до завершения обработки ответа, поэтому остановка при бездействии ожидает завершения всех активных запросов к моделям и эмбеддингам. Настроенные псевдонимы провайдеров остаются раздельными: два псевдонима могут указывать на разные узлы с GPU, не объединяясь под одним идентификатором адаптера Ollama, LM Studio или совместимого с OpenAI адаптера. Если другой процесс OpenClaw уже использует исправный сервер по тому же адресу healthUrl, этот процесс повторно использует его, не принимая под своё управление (каждый процесс управляет только тем дочерним процессом, который запустил сам). Журналы запуска и завершения содержат ограниченные по размеру отредактированные хвосты вывода дочернего процесса, а также сведения о времени и завершении; настроенные значения переменных окружения никогда не выводятся.

Структура конфигурации

{
  models: {
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "local-model",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/absolute/path/to/server",
          args: ["--host", "127.0.0.1", "--port", "8000"],
          cwd: "/absolute/path/to/working-dir",
          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },
          healthUrl: "http://127.0.0.1:8000/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "my-local-model",
            name: "My Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Задайте timeoutSeconds в записи провайдера (не localService), чтобы медленный холодный запуск и длительная генерация не достигали стандартного тайм-аута запроса к модели. Явно задавайте healthUrl, если сервер предоставляет состояние готовности не по адресу /models базового URL.

Поля

Поле	Обязательно	Описание
`command`	да	Абсолютный путь к исполняемому файлу. Поиск через PATH оболочки не выполняется.
`args`	нет	Аргументы процесса. Раскрытие средствами оболочки, каналы, шаблоны имён файлов и обработка кавычек не поддерживаются.
`cwd`	нет	Рабочий каталог процесса.
`env`	нет	Переменные окружения, накладываемые поверх окружения процесса OpenClaw.
`healthUrl`	нет	URL готовности. По умолчанию используется `baseUrl` с добавлением `/models` (`http://127.0.0.1:8000/v1` преобразуется в `http://127.0.0.1:8000/v1/models`).
`readyTimeoutMs`	нет	Крайний срок ожидания готовности при запуске. Значение по умолчанию: `120000`.
`idleStopMs`	нет	Задержка остановки при бездействии для процесса, запущенного OpenClaw. Значение `0` или отсутствие параметра сохраняет процесс запущенным до завершения OpenClaw.

Пример Inferrs

Inferrs — пользовательский сервер /v1, совместимый с OpenAI, поэтому тот же API localService работает с записью провайдера inferrs:

{
  agents: {
    defaults: {
      model: { primary: "inferrs/google/gemma-4-E2B-it" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      inferrs: {
        baseUrl: "http://127.0.0.1:8080/v1",
        apiKey: "inferrs-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "/opt/homebrew/bin/inferrs",
          args: [
            "serve",
            "google/gemma-4-E2B-it",
            "--host",
            "127.0.0.1",
            "--port",
            "8080",
            "--device",
            "metal",
          ],
          healthUrl: "http://127.0.0.1:8080/v1/models",
          readyTimeoutMs: 180000,
          idleStopMs: 0,
        },
        models: [
          {
            id: "google/gemma-4-E2B-it",
            name: "Gemma 4 E2B (inferrs)",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 131072,
            maxTokens: 4096,
            compat: { requiresStringContent: true },
          },
        ],
      },
    },
  },
}

Замените command результатом выполнения which inferrs на машине, где запущен OpenClaw. Полная настройка inferrs: Inferrs.

Пример ds4

{
  models: {
    providers: {
      ds4: {
        baseUrl: "http://127.0.0.1:18000/v1",
        apiKey: "ds4-local",
        api: "openai-completions",
        timeoutSeconds: 300,
        localService: {
          command: "<DS4_DIR>/ds4-server",
          args: [
            "--model",
            "<DS4_DIR>/ds4flash.gguf",
            "--host",
            "127.0.0.1",
            "--port",
            "18000",
            "--ctx",
            "32768",
            "--tokens",
            "128",
          ],
          cwd: "<DS4_DIR>",
          healthUrl: "http://127.0.0.1:18000/v1/models",
          readyTimeoutMs: 300000,
          idleStopMs: 0,
        },
        models: [],
      },
    },
  },
}

Полная настройка, выбор размера контекста и команды проверки: ds4.

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

Локальные модели

Настройка локальных моделей, выбор провайдера и рекомендации по безопасности.

Inferrs

Запуск OpenClaw через локальный сервер inferrs, совместимый с OpenAI.

Gateway

Remote access

Security

Nodes and media

Web interfaces

Локальные сервисы моделей

Как это работает

Структура конфигурации

Поля

Пример Inferrs

Пример ds4

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

Локальные модели

Inferrs

​Как это работает

​Структура конфигурации

​Поля

​Пример Inferrs

​Пример ds4

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

Локальные модели

Inferrs

Как это работает

Структура конфигурации

Поля

Пример Inferrs

Пример ds4

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