Gateway
Локальні сервіси моделей
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 — це власний сумісний з OpenAI серверний компонент /v1, тому той самий 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.
