openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-27 06:48:05 +00:00
parent 5e063c4cc5
commit 9c5fbbdc9f
2 changed files with 292 additions and 290 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

286
docs/uk/plugins/voice-call.md
View File

@ -2,31 +2,32 @@
read_when:
- Ви хочете здійснити вихідний голосовий виклик з OpenClaw
- Ви налаштовуєте або розробляєте плагін voice-call
- Вам потрібен голосовий зв’язок у реальному часі або потокова транскрипція в телефонії
- Вам потрібен голос у реальному часі або потокова транскрипція в телефонії
sidebarTitle: Voice call
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з необов’язковою голосовою взаємодією в реальному часі та потоковою транскрипцією
summary: Здійснюйте вихідні та приймайте вхідні голосові виклики через Twilio, Telnyx або Plivo, з додатковою підтримкою голосу в реальному часі та потокової транскрипції
title: Плагін голосових викликів
x-i18n:
generated_at: "2026-04-26T05:46:13Z"
generated_at: "2026-04-27T06:45:54Z"
model: gpt-5.4
provider: openai
source_hash: 77b5e4b338b0c39c71accea7065af70fab695c8f34488ba0fbf7023f2f36f377
source_hash: fd99495159acbf1d520eed9adca19801f012adcd902a5d826a3d5f6f7b5a26b1
source_path: plugins/voice-call.md
workflow: 15
---
Голосові виклики для OpenClaw через Plugin. Підтримує вихідні сповіщення,
багатокрокові розмови, повнодуплексний голосовий зв’язок у реальному часі, потокову
транскрипцію та вхідні виклики з політиками списку дозволених номерів.
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
транскрипцію та вхідні виклики з політиками allowlist.
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
speech), `mock` (розробка/без мережі).
speech), `mock` (dev/без мережі).
<Note>
Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
віддалений Gateway, установіть і налаштуйте Plugin на машині, де працює
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
Plugin Voice Call працює **всередині процесу Gateway**. Якщо ви
використовуєте віддалений Gateway, установіть і налаштуйте Plugin на
машині, де працює Gateway, а потім перезапустіть Gateway, щоб
завантажити його.
</Note>
## Швидкий старт
@ -39,7 +40,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
openclaw plugins install @openclaw/voice-call
```
</Tab>
<Tab title="З локальної папки (розробка)">
<Tab title="З локальної папки (dev)">
```bash
PLUGIN_SRC=./path/to/local/voice-call-plugin
openclaw plugins install "$PLUGIN_SRC"
@ -52,30 +53,30 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Step>
<Step title="Налаштуйте провайдера та Webhook">
Укажіть конфігурацію в `plugins.entries.voice-call.config` (див.
[Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні:
`provider`, облікові дані провайдера, `fromNumber` і
публічно доступна URL-адреса Webhook.
Задайте конфігурацію в `plugins.entries.voice-call.config` (див.
[Configuration](#configuration) нижче для повної структури). Мінімально
потрібні: `provider`, облікові дані провайдера, `fromNumber` і
загальнодоступний URL Webhook.
</Step>
<Step title="Перевірте налаштування">
```bash
openclaw voicecall setup
```
Типовий вивід зручно читати в журналах чату та терміналах. Команда перевіряє
увімкнення Plugin, облікові дані провайдера, доступність Webhook і те,
що активний лише один аудіорежим (`streaming` або `realtime`). Для
скриптів використовуйте `--json`.
Типовий вивід зручно читати в журналах чату та терміналах. Команда
перевіряє, чи увімкнений Plugin, облікові дані провайдера, доступність
Webhook і те, що активний лише один аудіорежим (`streaming` або
`realtime`). Для скриптів використовуйте `--json`.
</Step>
<Step title="Виконайте smoke test">
<Step title="Виконайте smoke-тест">
```bash
openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
```
За замовчуванням обидві команди виконуються як dry run. Додайте `--yes`, щоб
справді здійснити короткий вихідний дзвінок-сповіщення:
Обидві команди типово виконуються як dry run. Додайте `--yes`, щоб
справді здійснити короткий вихідний виклик-сповіщення:
```bash
openclaw voicecall smoke --to "+15555550123" --yes
@ -85,18 +86,25 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Steps>
<Warning>
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічна URL-адреса Webhook**.
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
визначається як loopback або приватний мережевий простір, налаштування завершиться помилкою замість
запуску провайдера, який не зможе отримувати carrier Webhook.
Для Twilio, Telnyx і Plivo налаштування має визначатися як **публічний URL Webhook**.
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний URL від serve
вказує на loopback чи приватний мережевий простір, налаштування
завершується помилкою замість запуску провайдера, який не може
приймати Webhook від оператора.
</Warning>
## Конфігурація
## Configuration
Якщо `enabled: true`, але для вибраного провайдера відсутні облікові дані,
під час запуску Gateway у журналі з’явиться попередження про неповне налаштування з відсутніми ключами, а
запуск runtime буде пропущено. Команди, RPC-виклики та інструменти агента все одно
повертатимуть точну відсутню конфігурацію провайдера під час використання.
під час запуску Gateway у журналах з’являється попередження про
незавершене налаштування з переліком відсутніх ключів, і середовище
виконання не запускається. Команди, RPC-виклики та інструменти агента
все одно повертають точну інформацію про відсутню конфігурацію провайдера
під час використання.
<Note>
Облікові дані voice-call підтримують SecretRefs. `plugins.entries.voice-call.config.twilio.authToken` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` визначаються через стандартну поверхню SecretRef; див. [SecretRef credential surface](/uk/reference/secretref-credential-surface).
</Note>
```json5
{
@ -137,7 +145,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
trustedProxyIPs: ["100.64.0.1"],
},
// Публічний доступ (виберіть один)
// Публічна доступність (виберіть один варіант)
// publicUrl: "https://example.ngrok.app/voice/webhook",
// tunnel: { provider: "ngrok" },
// tailscale: { mode: "funnel", path: "/voice/webhook" },
@ -147,7 +155,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
},
streaming: { enabled: true /* див. Потокова транскрипція */ },
realtime: { enabled: false /* див. Голосовий зв’язок у реальному часі */ },
realtime: { enabled: false /* див. Голос у реальному часі */ },
},
},
},
@ -156,29 +164,28 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
```
<AccordionGroup>
<Accordion title="Примітки щодо публічного доступу провайдера та безпеки">
- Twilio, Telnyx і Plivo усі потребують **публічно доступної** URL-адреси Webhook.
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
- Для Telnyx потрібен `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо лише `skipSignatureVerification` не має значення true.
- `skipSignatureVerification` призначено лише для локального тестування.
- На безкоштовному тарифі ngrok установіть `publicUrl` на точну URL-адресу ngrok; перевірка підпису завжди примусово увімкнена.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` — це loopback (локальний агент ngrok). Лише для локальної розробки.
- URL-адреси безкоштовного тарифу ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio перестануть проходити перевірку. Для production: надавайте перевагу стабільному домену або funnel у Tailscale.
<Accordion title="Нотатки про публічну доступність і безпеку провайдера">
- Twilio, Telnyx і Plivo усі потребують **публічно доступного** URL Webhook.
- `mock` — це локальний dev-провайдер (без мережевих викликів).
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо тільки `skipSignatureVerification` не має значення true.
- `skipSignatureVerification` призначений лише для локального тестування.
- У безкоштовному тарифі ngrok задавайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусово виконується.
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
- URL ngrok на безкоштовному тарифі можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio перестануть проходити перевірку. Для production краще використовувати стабільний домен або funnel Tailscale.
</Accordion>
<Accordion title="Обмеження підключень для потокової передачі">
- `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають коректний кадр `start`.
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до початку роботи.
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до початку роботи на одну вихідну IP-адресу.
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікування + активні).
<Accordion title="Ліміти з’єднань для streaming">
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають коректний кадр `start`.
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до початку.
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до початку на одну вихідну IP-адресу.
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувальні + активні).
</Accordion>
<Accordion title="Міграції застарілої конфігурації">
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
ключі OpenAI у `streaming.*`, переписуються за допомогою `openclaw doctor --fix`.
Резервна сумісність runtime поки що все ще приймає старі ключі voice-call, але
шлях переписування — це `openclaw doctor --fix`, а shim сумісності —
тимчасовий.
Старіші конфігурації, які використовують `provider: "log"`, `twilio.from` або застарілі ключі OpenAI у `streaming.*`, переписуються командою `openclaw doctor --fix`.
Резервна сумісність середовища виконання поки що все ще приймає старі ключі voice-call, але
шлях переписування — це `openclaw doctor --fix`, а shim сумісності є
тимчасовим.
Ключі потокової передачі, що мігруються автоматично:
Автоматично мігровані ключі streaming:
- `streaming.sttProvider` → `streaming.provider`
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
@ -189,26 +196,26 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Accordion>
</AccordionGroup>
## Голосові розмови в реальному часі
## Розмови голосом у реальному часі
`realtime` вибирає повнодуплексного провайдера голосового зв’язку в реальному часі для живого аудіо виклику.
Він відокремлений від `streaming`, який лише пересилає аудіо
`realtime` вибирає повнодуплексного провайдера голосу в реальному часі для
живого аудіо виклику. Це окремо від `streaming`, який лише пересилає аудіо
провайдерам транскрипції в реальному часі.
<Warning>
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
аудіорежим на виклик.
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Вибирайте
лише один аудіорежим на виклик.
</Warning>
Поточна поведінка runtime:
Поточна поведінка середовища виконання:
- `realtime.enabled` підтримується для Twilio Media Streams.
- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера голосового зв’язку в реальному часі.
- Вбудовані провайдери голосового зв’язку в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми Plugin провайдерів.
- Необроблена конфігурація, що належить провайдеру, зберігається в `realtime.providers.<providerId>`.
- Voice Call за замовчуванням надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абоненту потрібні глибші міркування, актуальна інформація або звичайні інструменти OpenClaw.
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано жодного провайдера голосового зв’язку в реальному часі, Voice Call записує попередження в журнал і пропускає медіа реального часу замість помилки для всього Plugin.
- Ключі сеансу consult повторно використовують наявний голосовий сеанс, коли це можливо, а потім повертаються до номера телефону того, хто дзвонить/кому дзвонять, щоб наступні consult-виклики зберігали контекст під час дзвінка.
- `realtime.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми Plugin провайдерів.
- Необроблена конфігурація, що належить провайдеру, розміщується в `realtime.providers.<providerId>`.
- Voice Call типово надає спільний інструмент реального часу `openclaw_agent_consult`. Модель реального часу може викликати його, коли абоненту потрібні глибші міркування, поточна інформація або звичайні інструменти OpenClaw.
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або якщо взагалі не зареєстровано жодного провайдера голосу в реальному часі, Voice Call записує попередження в журнал і пропускає медіа реального часу замість того, щоб зламати весь Plugin.
- Ключі сесії consult повторно використовують наявну голосову сесію, коли це можливо, а потім переходять до номера телефону абонента, який телефонує або приймає дзвінок, щоб подальші виклики consult зберігали контекст під час дзвінка.
### Політика інструментів
@ -217,8 +224,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
| Політика | Поведінка |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента інструментами `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати стандартну політику інструментів агента. |
| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` усе одно передаються провайдеру реального часу. |
| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати стандартну політику інструментів агента. |
| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` усе одно передаються провайдеру реального часу. |
### Приклади провайдерів реального часу
@ -240,7 +247,7 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
realtime: {
enabled: true,
provider: "google",
instructions: "Говори коротко. Викликай openclaw_agent_consult перед використанням глибших інструментів.",
instructions: "Говоріть коротко. Викликайте openclaw_agent_consult перед використанням глибших інструментів.",
toolPolicy: "safe-read-only",
providers: {
google: {
@ -282,21 +289,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
</Tabs>
Див. [Google provider](/uk/providers/google) і
[OpenAI provider](/uk/providers/openai) для параметрів голосового зв’язку в реальному часі,
[OpenAI provider](/uk/providers/openai) для параметрів голосу в реальному часі,
специфічних для провайдера.
## Потокова транскрипція
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
Поточна поведінка runtime:
Поточна поведінка середовища виконання:
- `streaming.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
- `streaming.provider` є необов’язковим. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми Plugin провайдерів.
- Необроблена конфігурація, що належить провайдеру, зберігається в `streaming.providers.<providerId>`.
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або не зареєстровано жодного, Voice Call записує попередження в журнал і пропускає медіапотік замість помилки для всього Plugin.
- Необроблена конфігурація, що належить провайдеру, розміщується в `streaming.providers.<providerId>`.
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або якщо жодного не зареєстровано, Voice Call записує попередження в журнал і пропускає потокову передачу медіа замість того, щоб зламати весь Plugin.
### Приклади провайдерів потокової передачі
### Приклади провайдерів streaming
<Tabs>
<Tab title="OpenAI">
@ -367,8 +374,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
## TTS для викликів
Voice Call використовує базову конфігурацію `messages.tts` для потокового
синтезу мовлення під час викликів. Її можна перевизначити в конфігурації Plugin із
**тією самою структурою** — вона глибоко об’єднується з `messages.tts`.
відтворення мовлення під час викликів. Ви можете перевизначити її в
конфігурації Plugin із **тією самою структурою** — вона глибоко зливається з `messages.tts`.
```json5
{
@ -386,16 +393,16 @@ Voice Call використовує базову конфігурацію `messa
<Warning>
**Microsoft speech ігнорується для голосових викликів.** Аудіо телефонії потребує PCM;
поточний транспорт Microsoft не надає телекомунікаційний PCM-вивід.
поточний транспорт Microsoft не надає телекомунікаційний вихід PCM.
</Warning>
Примітки щодо поведінки:
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються за допомогою `openclaw doctor --fix`; збережена конфігурація має використовувати `tts.providers.<provider>`.
- Базовий TTS використовується, коли увімкнено потокову передачу медіа Twilio; інакше виклики повертаються до голосів, вбудованих у провайдера.
- Якщо потік медіа Twilio уже активний, Voice Call не повертається до TwiML `<Say>`. Якщо TTS для телефонії недоступний у цьому стані, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення.
- Коли TTS для телефонії повертається до вторинного провайдера, Voice Call записує попередження в журнал із ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
- Коли barge-in Twilio або завершення потоку очищає чергу TTS, що очікує, запити на відтворення в черзі завершуються замість того, щоб змушувати абонентів чекати завершення відтворення.
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `tts.providers.<provider>`.
- Базовий TTS використовується, коли ввімкнено потокову передачу медіа Twilio; в інших випадках виклики повертаються до голосів, вбудованих у провайдера.
- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML `<Say>`. Якщо TTS телефонії недоступний у такому стані, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення.
- Коли TTS телефонії повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
- Коли barge-in Twilio або завершення потоку очищає чергу TTS, що очікує, запити на відтворення з черги завершуються, а не зависають, поки абоненти чекають завершення відтворення.
### Приклади TTS
@ -438,7 +445,7 @@ Voice Call використовує базову конфігурацію `messa
}
```
</Tab>
<Tab title="Перевизначення моделі OpenAI (глибоке об’єднання)">
<Tab title="Перевизначення моделі OpenAI (глибоке злиття)">
```json5
{
plugins: {
@ -464,69 +471,70 @@ Voice Call використовує базову конфігурацію `messa
## Вхідні виклики
Політика вхідних викликів за замовчуванням має значення `disabled`. Щоб увімкнути вхідні виклики, задайте:
Політика вхідних викликів типово має значення `disabled`. Щоб увімкнути вхідні виклики, задайте:
```json5
{
inboundPolicy: "allowlist",
allowFrom: ["+15550001234"],
inboundGreeting: "Привіт! Чим я можу допомогти?",
inboundGreeting: "Hello! How can I help?",
}
```
<Warning>
`inboundPolicy: "allowlist"` — це екранування caller ID з низьким рівнем достовірності.
Plugin нормалізує значення `From`, надане провайдером, і порівнює його з
`allowFrom`. Перевірка Webhook автентифікує доставку провайдера та
цілісність payload, але **не** доводить право власності на номер
того, хто телефонує, у PSTN/VoIP. Розглядайте `allowFrom` як фільтрацію caller ID, а не як надійну
ідентичність абонента.
`inboundPolicy: "allowlist"` — це перевірка caller ID з низьким рівнем
довіри. Plugin нормалізує значення `From`, надане провайдером, і
порівнює його з `allowFrom`. Перевірка Webhook автентифікує доставку від
провайдера й цілісність корисного навантаження, але **не** доводить
володіння номером абонента PSTN/VoIP. Розглядайте `allowFrom` як
фільтрацію caller ID, а не як сильну ідентифікацію абонента.
</Warning>
Автовідповіді використовують систему агента. Налаштовуйте їх за допомогою `responseModel`,
Автовідповіді використовують систему агента. Налаштовуйте їх через `responseModel`,
`responseSystemPrompt` і `responseTimeoutMs`.
### Контракт озвученого виводу
### Контракт голосового виводу
Для автовідповідей Voice Call додає до системного промпту строгий контракт
озвученого виводу:
Для автовідповідей Voice Call додає до системного prompt суворий контракт
голосового виводу:
```text
{"spoken":"..."}
```
Voice Call захищено витягує текст мовлення:
Voice Call витягує текст мовлення захисним способом:
- Ігнорує payload, позначені як reasoning/error content.
- Аналізує прямий JSON, JSON в огородженому блоці або вбудовані ключі `"spoken"`.
- Повертається до звичайного тексту та видаляє ймовірні вступні абзаци з плануванням/метаінформацією.
- Ігнорує корисні навантаження, позначені як reasoning/error content.
- Розбирає прямий JSON, JSON в огороджених блоках або вбудовані ключі `"spoken"`.
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням/метаданими.
Це допомагає зосередити озвучене відтворення на тексті для абонента й уникати
потрапляння тексту планування в аудіо.
Це дозволяє зосередити голосове відтворення на тексті для абонента й
уникати витоку тексту планування в аудіо.
### Поведінка запуску розмови
### Поведінка під час запуску розмови
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до стану
живого відтворення:
Для вихідних викликів у режимі `conversation` обробка першого повідомлення
прив’язана до стану живого відтворення:
- Очищення черги через barge-in і автовідповідь пригнічуються лише поки початкове привітання активно озвучується.
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
- Початкове відтворення для потокової передачі Twilio запускається після підключення потоку без додаткової затримки.
- Barge-in перериває активне відтворення й очищає записи TTS Twilio, що стоять у черзі, але ще не почали відтворюватися. Очищені записи завершуються як пропущені, тож подальша логіка відповіді може продовжитися без очікування аудіо, яке ніколи не буде відтворене.
- Голосові розмови в реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сеанси `<Connect><Stream>` залишаються підключеними.
- Очищення черги через barge-in і автовідповідь пригнічуються лише поки активно відтворюється початкове привітання.
- Якщо початкове відтворення завершується помилкою, виклик повертається до стану `listening`, а початкове повідомлення лишається в черзі для повторної спроби.
- Початкове відтворення для потокової передачі Twilio запускається під час підключення потоку без додаткової затримки.
- Barge-in перериває активне відтворення й очищає записи Twilio TTS, які стоять у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тому подальша логіка відповіді може продовжитися без очікування аудіо, яке ніколи не буде відтворено.
- Розмови голосом у реальному часі використовують власний початковий хід потоку реального часу. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сесії `<Connect><Stream>` залишаються підключеними.
### Пільговий період при від’єднанні потоку Twilio
### Пільговий період відключення потоку Twilio
Коли медіапотік Twilio від’єднується, Voice Call чекає **2000 мс** перед
Коли медіапотік Twilio відключається, Voice Call чекає **2000 ms** перед
автоматичним завершенням виклику:
- Якщо потік повторно підключається протягом цього вікна, авто-завершення скасовується.
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб запобігти зависанню активних викликів.
- Якщо після пільгового періоду жоден потік не реєструється повторно, виклик завершується, щоб не допустити завислих активних викликів.
## Очищувач застарілих викликів
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінального
Webhook (наприклад, виклики в режимі notify, які ніколи не завершуються). Значення за замовчуванням —
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які
ніколи не отримують фінальний Webhook (наприклад, виклики в режимі notify,
які ніколи не завершуються). Типове значення —
`0` (вимкнено).
Рекомендовані діапазони:
@ -552,25 +560,25 @@ Webhook (наприклад, виклики в режимі notify, які ні
## Безпека Webhook
Коли перед Gateway розташовано проксі або тунель, Plugin
відновлює публічну URL-адресу для перевірки підпису. Ці параметри
керують тим, яким forwarded headers довіряти:
реконструює публічний URL для перевірки підпису. Ці параметри
керують тим, яким пересланим заголовкам довіряти:
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
Список дозволених хостів із forwarding headers.
Дозволені хости з заголовків переспрямування.
</ParamField>
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
Довіряти forwarded headers без списку дозволених.
Довіряти пересланим заголовкам без allowlist.
</ParamField>
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
Довіряти forwarded headers лише коли віддалена IP-адреса запиту збігається зі списком.
Довіряти пересланим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком.
</ParamField>
Додатковий захист:
Додаткові засоби захисту:
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені коректні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
- Ходи розмови Twilio включають токен на кожен хід у callback ` <Gather>`, тож застарілі/повторно відтворені callback мовлення не можуть задовольнити новіший хід транскрипції, що очікує.
- Неавтентифіковані запити Webhook відхиляються ще до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера.
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) плюс обмеження на кількість одночасних запитів з однієї IP-адреси до перевірки підпису.
- Ходи розмови Twilio містять токен для кожного ходу у зворотних викликах `<Gather>`, тому застарілі/повторно відтворені зворотні виклики мовлення не можуть задовольнити новіший очікувальний хід транскрипції.
- Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні потрібні заголовки підпису провайдера.
- Webhook voice-call використовує спільний профіль тіла до автентифікації (64 KB / 5 секунд) плюс обмеження одночасних запитів на одну IP-адресу до перевірки підпису.
Приклад зі стабільним публічним хостом:
@ -602,14 +610,14 @@ openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall latency # зведення затримки ходів із журналів
openclaw voicecall latency # підсумувати затримку ходу з журналів
openclaw voicecall expose --mode funnel
```
`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call.
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
для затримки ходу та часу очікування прослуховування.
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб
обмежити аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
для затримки ходу й часу очікування прослуховування.
## Інструмент агента
@ -618,27 +626,27 @@ openclaw voicecall expose --mode funnel
| Дія | Аргументи |
| --------------- | ------------------------ |
| `initiate_call` | `message`, `to?`, `mode?` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
| `continue_call` | `callId`, `message` |
| `speak_to_user` | `callId`, `message` |
| `send_dtmf` | `callId`, `digits` |
| `end_call` | `callId` |
| `get_status` | `callId` |
Цей репозиторій містить відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
Цей репозиторій містить відповідний документ Skills у `skills/voice-call/SKILL.md`.
## Gateway RPC
| Метод | Аргументи |
| ------------------- | ------------------------ |
| `voicecall.initiate` | `to?`, `message`, `mode?` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
| `voicecall.continue` | `callId`, `message` |
| `voicecall.speak` | `callId`, `message` |
| `voicecall.dtmf` | `callId`, `digits` |
| `voicecall.end` | `callId` |
| `voicecall.status` | `callId` |
## Пов’язане
- [Режим розмови](/uk/nodes/talk)
- [Перетворення тексту на мовлення](/uk/tools/tts)
- [Голосове пробудження](/uk/nodes/voicewake)
- [Синтез мовлення](/uk/tools/tts)
- [Голосова активація](/uk/nodes/voicewake)

296
docs/uk/providers/ollama.md
View File

@ -1,56 +1,56 @@
---
read_when:
- Ви хочете запускати OpenClaw із хмарними або локальними моделями через Ollama
- Ви хочете запустити OpenClaw із хмарними або локальними моделями через Ollama
- Вам потрібні вказівки з налаштування та конфігурації Ollama
- Ви хочете використовувати візійні моделі Ollama для розуміння зображень
summary: Запуск OpenClaw з Ollama (хмарні та локальні моделі)
- Ви хочете використовувати візуальні моделі Ollama для розуміння зображень
summary: Запустіть OpenClaw з Ollama (хмарні та локальні моделі)
title: Ollama
x-i18n:
generated_at: "2026-04-27T06:27:50Z"
generated_at: "2026-04-27T06:45:55Z"
model: gpt-5.4
provider: openai
source_hash: 961eef2ec5a31be72b035cbfa35295fe5de808e870240bf5b87297ad4774638f
source_hash: 6a65b227d881c08050807d1a8f1cbc774b7da5b343f0c77d9f264cdfd9ea5714
source_path: providers/ollama.md
workflow: 15
---
OpenClaw інтегрується з нативним API Ollama (`/api/chat`) для хмарних розміщених моделей і локальних/self-hosted серверів Ollama. Ви можете використовувати Ollama у трьох режимах: `Cloud + Local` через доступний хост Ollama, `Cloud only` проти `https://ollama.com` або `Local only` проти доступного хоста Ollama.
OpenClaw інтегрується з нативним API Ollama (`/api/chat`) для розміщених хмарних моделей і локальних/власнорозміщених серверів Ollama. Ви можете використовувати Ollama у трьох режимах: `Cloud + Local` через доступний хост Ollama, `Cloud only` проти `https://ollama.com` або `Local only` проти доступного хоста Ollama.
<Warning>
**Користувачі віддаленого Ollama**: не використовуйте URL `/v1`, сумісний з OpenAI (`http://host:11434/v1`), з OpenClaw. Це ламає виклики інструментів, і моделі можуть виводити сирий JSON інструментів як звичайний текст. Замість цього використовуйте URL нативного API Ollama: `baseUrl: "http://host:11434"` (без `/v1`).
**Користувачі віддаленого Ollama**: Не використовуйте URL `/v1`, сумісний з OpenAI (`http://host:11434/v1`), з OpenClaw. Це ламає виклики інструментів, і моделі можуть виводити необроблений JSON інструментів як звичайний текст. Натомість використовуйте URL нативного API Ollama: `baseUrl: "http://host:11434"` (без `/v1`).
</Warning>
Конфігурація провайдера Ollama використовує `baseUrl` як канонічний ключ. OpenClaw також приймає `baseURL` для сумісності з прикладами в стилі OpenAI SDK, але в новій конфігурації слід надавати перевагу `baseUrl`.
Конфігурація провайдера Ollama використовує `baseUrl` як канонічний ключ. OpenClaw також приймає `baseURL` для сумісності з прикладами у стилі OpenAI SDK, але в новій конфігурації слід надавати перевагу `baseUrl`.
## Правила автентифікації
<AccordionGroup>
<Accordion title="Локальні хости та хости LAN">
Локальні хости Ollama і хости LAN не потребують справжнього bearer token. OpenClaw використовує локальний маркер `ollama-local` лише для loopback, private-network, `.local` і Ollama base URL з простими іменами хостів.
Локальні хости Ollama та хости LAN не потребують справжнього bearer-токена. OpenClaw використовує локальний маркер `ollama-local` лише для URL бази Ollama типу loopback, private-network, `.local` і bare-hostname.
</Accordion>
<Accordion title="Віддалені хости та Ollama Cloud">
<Accordion title="Віддалені хости та хости Ollama Cloud">
Віддалені публічні хости та Ollama Cloud (`https://ollama.com`) потребують справжніх облікових даних через `OLLAMA_API_KEY`, профіль автентифікації або `apiKey` провайдера.
</Accordion>
<Accordion title="Користувацькі id провайдера">
Користувацькі id провайдера, які встановлюють `api: "ollama"`, дотримуються тих самих правил. Наприклад, провайдер `ollama-remote`, який вказує на приватний хост Ollama у LAN, може використовувати `apiKey: "ollama-local"`, і субагенти розв’язуватимуть цей маркер через хук провайдера Ollama замість того, щоб вважати його відсутніми обліковими даними.
<Accordion title="Власні ідентифікатори провайдерів">
Власні ідентифікатори провайдерів, які задають `api: "ollama"`, дотримуються тих самих правил. Наприклад, провайдер `ollama-remote`, який вказує на приватний хост Ollama у LAN, може використовувати `apiKey: "ollama-local"`, і субагенти розв’язуватимуть цей маркер через хук провайдера Ollama замість того, щоб вважати його відсутніми обліковими даними.
</Accordion>
<Accordion title="Область пам’яті embeddings">
Коли Ollama використовується для memory embeddings, bearer-автентифікація обмежується хостом, де її було оголошено:
<Accordion title="Область дії вбудовування пам’яті">
Коли Ollama використовується для вбудовувань пам’яті, bearer-автентифікація обмежується хостом, де її було оголошено:
- Ключ на рівні провайдера надсилається лише до хоста Ollama цього провайдера.
- `agents.*.memorySearch.remote.apiKey` надсилається лише до його віддаленого embedding-хоста.
- Чисте значення env `OLLAMA_API_KEY` розглядається як угода для Ollama Cloud і типово не надсилається до локальних або self-hosted хостів.
- Ключ рівня провайдера надсилається лише до хоста Ollama цього провайдера.
- `agents.*.memorySearch.remote.apiKey` надсилається лише до його віддаленого хоста вбудовувань.
- Чисте значення змінної середовища `OLLAMA_API_KEY` розглядається як домовленість для Ollama Cloud і типово не надсилається до локальних або власнорозміщених хостів.
</Accordion>
</AccordionGroup>
## Початок роботи
Виберіть бажаний спосіб налаштування та режим.
Виберіть бажаний спосіб і режим налаштування.
<Tabs>
<Tab title="Onboarding (рекомендовано)">
**Найкраще для:** найшвидшого шляху до робочого хмарного або локального налаштування Ollama.
<Tab title="Онбординг (рекомендовано)">
**Найкраще для:** найшвидшого способу налаштувати робочий Ollama у хмарі або локально.
<Steps>
<Step title="Запустіть онбординг">
@ -60,13 +60,13 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`)
Виберіть **Ollama** зі списку провайдерів.
</Step>
<Step title="Виберіть свій режим">
<Step title="Виберіть режим">
- **Cloud + Local** — локальний хост Ollama плюс хмарні моделі, маршрутизовані через цей хост
- **Cloud only** — хмарні моделі Ollama через `https://ollama.com`
- **Cloud only** — розміщені моделі Ollama через `https://ollama.com`
- **Local only** — лише локальні моделі
</Step>
<Step title="Виберіть модель">
`Cloud only` запитує `OLLAMA_API_KEY` і пропонує типові хмарні значення. `Cloud + Local` і `Local only` запитують base URL Ollama, виявляють доступні моделі та автоматично виконують pull вибраної локальної моделі, якщо вона ще недоступна. `Cloud + Local` також перевіряє, чи виконано вхід на цьому хості Ollama для доступу до хмари.
`Cloud only` запитує `OLLAMA_API_KEY` і пропонує типові розміщені хмарні значення. `Cloud + Local` і `Local only` запитують базовий URL Ollama, виявляють доступні моделі й автоматично завантажують вибрану локальну модель, якщо вона ще недоступна. `Cloud + Local` також перевіряє, чи виконано вхід на цьому хості Ollama для доступу до хмари.
</Step>
<Step title="Переконайтеся, що модель доступна">
```bash
@ -83,7 +83,7 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`)
--accept-risk
```
За потреби вкажіть користувацький base URL або модель:
За потреби вкажіть власний базовий URL або модель:
```bash
openclaw onboard --non-interactive \
@ -99,17 +99,17 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`)
**Найкраще для:** повного контролю над хмарним або локальним налаштуванням.
<Steps>
<Step title="Виберіть хмарний чи локальний режим">
- **Cloud + Local**: встановіть Ollama, увійдіть через `ollama signin` і маршрутизуйте хмарні запити через цей хост
<Step title="Виберіть хмарний або локальний режим">
- **Cloud + Local**: встановіть Ollama, виконайте вхід за допомогою `ollama signin` і маршрутизуйте хмарні запити через цей хост
- **Cloud only**: використовуйте `https://ollama.com` з `OLLAMA_API_KEY`
- **Local only**: встановіть Ollama з [ollama.com/download](https://ollama.com/download)
</Step>
<Step title="Завантажте локальну модель (лише local)">
<Step title="Завантажте локальну модель (лише локальний режим)">
```bash
ollama pull gemma4
# or
# або
ollama pull gpt-oss:20b
# or
# або
ollama pull llama3.3
```
</Step>
@ -117,23 +117,23 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`)
Для `Cloud only` використовуйте свій справжній `OLLAMA_API_KEY`. Для налаштувань на основі хоста підійде будь-яке значення-заповнювач:
```bash
# Cloud
# Хмара
export OLLAMA_API_KEY="your-ollama-api-key"
# Local-only
# Лише локально
export OLLAMA_API_KEY="ollama-local"
# Or configure in your config file
# Або налаштуйте у своєму файлі конфігурації
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
```
</Step>
<Step title="Перегляньте й встановіть свою модель">
<Step title="Перегляньте та встановіть свою модель">
```bash
openclaw models list
openclaw models set ollama/gemma4
```
Або встановіть типове значення в конфігурації:
Або встановіть типове значення у конфігурації:
```json5
{
@ -156,46 +156,46 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`)
<Tab title="Cloud + Local">
`Cloud + Local` використовує доступний хост Ollama як контрольну точку і для локальних, і для хмарних моделей. Це рекомендований Ollama гібридний сценарій.
Під час налаштування використовуйте **Cloud + Local**. OpenClaw запитує base URL Ollama, виявляє локальні моделі з цього хоста і перевіряє, чи виконано вхід на хості для хмарного доступу через `ollama signin`. Коли на хості виконано вхід, OpenClaw також пропонує типові хмарні значення, такі як `kimi-k2.5:cloud`, `minimax-m2.7:cloud` і `glm-5.1:cloud`.
Використовуйте **Cloud + Local** під час налаштування. OpenClaw запитує базовий URL Ollama, виявляє локальні моделі з цього хоста та перевіряє, чи виконано вхід на хості для доступу до хмари через `ollama signin`. Якщо вхід на хості виконано, OpenClaw також пропонує типові розміщені хмарні значення, як-от `kimi-k2.5:cloud`, `minimax-m2.7:cloud` і `glm-5.1:cloud`.
Якщо на хості ще не виконано вхід, OpenClaw залишає налаштування в режимі лише local, доки ви не виконаєте `ollama signin`.
Якщо вхід на хості ще не виконано, OpenClaw залишає налаштування лише локальним, доки ви не запустите `ollama signin`.
</Tab>
<Tab title="Cloud only">
`Cloud only` працює з розміщеним API Ollama за адресою `https://ollama.com`.
Під час налаштування використовуйте **Cloud only**. OpenClaw запитує `OLLAMA_API_KEY`, встановлює `baseUrl: "https://ollama.com"` і заповнює список хмарних розміщених моделей. Цей шлях **не** потребує локального сервера Ollama або `ollama signin`.
Використовуйте **Cloud only** під час налаштування. OpenClaw запитує `OLLAMA_API_KEY`, встановлює `baseUrl: "https://ollama.com"` і заповнює список розміщених хмарних моделей. Цей шлях **не** потребує локального сервера Ollama або `ollama signin`.
Список хмарних моделей, показаний під час `openclaw onboard`, заповнюється в реальному часі з `https://ollama.com/api/tags` і обмежується 500 записами, тому засіб вибору відображає поточний розміщений каталог, а не статичний початковий список. Якщо `ollama.com` недоступний або не повертає моделей під час налаштування, OpenClaw повертається до попередніх жорстко закодованих пропозицій, щоб онбординг усе одно завершився.
Список хмарних моделей, який показується під час `openclaw onboard`, заповнюється в реальному часі з `https://ollama.com/api/tags` з обмеженням у 500 записів, тому засіб вибору відображає поточний розміщений каталог, а не статичний початковий список. Якщо `ollama.com` недоступний або не повертає жодної моделі під час налаштування, OpenClaw повертається до попередніх жорстко закодованих пропозицій, щоб онбординг усе одно завершився.
</Tab>
<Tab title="Local only">
У режимі лише local OpenClaw виявляє моделі з налаштованого екземпляра Ollama. Цей шлях призначений для локальних або self-hosted серверів Ollama.
У режимі лише локального використання OpenClaw виявляє моделі з налаштованого екземпляра Ollama. Цей шлях призначений для локальних або власнорозміщених серверів Ollama.
Наразі OpenClaw пропонує `gemma4` як типове локальне значення.
OpenClaw наразі пропонує `gemma4` як локальне типове значення.
</Tab>
</Tabs>
## Виявлення моделей (неявний провайдер)
Коли ви встановлюєте `OLLAMA_API_KEY` (або профіль автентифікації) і **не** визначаєте `models.providers.ollama` або інший користувацький віддалений провайдер з `api: "ollama"`, OpenClaw виявляє моделі з локального екземпляра Ollama за адресою `http://127.0.0.1:11434`.
Коли ви задаєте `OLLAMA_API_KEY` (або профіль автентифікації) і **не** визначаєте `models.providers.ollama` або інший власний віддалений провайдер з `api: "ollama"`, OpenClaw виявляє моделі з локального екземпляра Ollama за адресою `http://127.0.0.1:11434`.
| Поведінка | Деталі |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Запит каталогу | Запитує `/api/tags` |
| Виявлення можливостей | Використовує best-effort запити `/api/show`, щоб читати `contextWindow`, розгорнуті параметри Modelfile `num_ctx` і можливості, зокрема vision/tools |
| Візійні моделі | Моделі з можливістю `vision`, про яку повідомляє `/api/show`, позначаються як здатні працювати із зображеннями (`input: ["text", "image"]`), тому OpenClaw автоматично додає зображення в запит |
| Виявлення reasoning | Позначає `reasoning` за допомогою евристики назви моделі (`r1`, `reasoning`, `think`) |
| Ліміти токенів | Встановлює `maxTokens` на типовий ліміт токенів Ollama, який використовує OpenClaw |
| Вартість | Встановлює всю вартість в `0` |
| Поведінка | Докладно |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Запит до каталогу | Виконує запит до `/api/tags` |
| Виявлення можливостей | Використовує best-effort-запити `/api/show` для читання `contextWindow`, розгорнутих параметрів Modelfile `num_ctx` і можливостей, зокрема vision/tools |
| Візуальні моделі | Моделі з можливістю `vision`, про яку повідомляє `/api/show`, позначаються як здатні працювати із зображеннями (`input: ["text", "image"]`), тож OpenClaw автоматично додає зображення до запиту |
| Виявлення reasoning | Позначає `reasoning` за допомогою евристики імені моделі (`r1`, `reasoning`, `think`) |
| Обмеження токенів | Встановлює `maxTokens` на типове обмеження максимальної кількості токенів Ollama, яке використовує OpenClaw |
| Вартість | Встановлює всі значення вартості на `0` |
Це дає змогу уникнути ручного додавання моделей, водночас зберігаючи каталог узгодженим із локальним екземпляром Ollama.
Це дає змогу уникнути ручного додавання моделей і водночас зберігати каталог узгодженим із локальним екземпляром Ollama.
```bash
# See what models are available
# Переглянути, які моделі доступні
ollama list
openclaw models list
```
@ -206,15 +206,15 @@ openclaw models list
ollama pull mistral
```
Нова модель буде автоматично виявлена та стане доступною для використання.
Нова модель буде автоматично виявлена й доступна для використання.
<Note>
Якщо ви явно задаєте `models.providers.ollama` або налаштовуєте користувацький віддалений провайдер, наприклад `models.providers.ollama-cloud` з `api: "ollama"`, автоматичне виявлення пропускається, і ви маєте визначати моделі вручну. Користувацькі loopback-провайдери, такі як `http://127.0.0.2:11434`, усе ще вважаються локальними. Див. розділ із явною конфігурацією нижче.
Якщо ви явно задаєте `models.providers.ollama` або налаштовуєте власний віддалений провайдер, наприклад `models.providers.ollama-cloud`, з `api: "ollama"`, автоматичне виявлення пропускається, і ви повинні визначати моделі вручну. Власні loopback-провайдери, як-от `http://127.0.0.2:11434`, усе ще вважаються локальними. Див. розділ явної конфігурації нижче.
</Note>
## Vision і опис зображень
Вбудований плагін Ollama реєструє Ollama як провайдера розуміння медіа, здатного працювати із зображеннями. Це дозволяє OpenClaw маршрутизувати явні запити на опис зображень і налаштовані типові значення моделей зображень через локальні або розміщені візійні моделі Ollama.
Вбудований Plugin Ollama реєструє Ollama як провайдера розуміння медіа, здатного працювати із зображеннями. Це дає OpenClaw змогу маршрутизувати явні запити на опис зображень і налаштовані типові значення моделей зображень через локальні або розміщені візуальні моделі Ollama.
Для локального vision завантажте модель, яка підтримує зображення:
@ -223,7 +223,7 @@ ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
```
Потім перевірте через CLI infer:
Потім перевірте за допомогою CLI infer:
```bash
openclaw infer image describe \
@ -232,7 +232,7 @@ openclaw infer image describe \
--json
```
`--model` має бути повним ref у форматі `<provider/model>`. Якщо його встановлено, `openclaw infer image describe` запускає цю модель безпосередньо замість пропуску опису через те, що модель підтримує нативний vision.
`--model` має бути повним посиланням у форматі `<provider/model>`. Якщо його задано, `openclaw infer image describe` запускає цю модель безпосередньо замість того, щоб пропускати опис, оскільки модель підтримує нативний vision.
Щоб зробити Ollama типовою моделлю розуміння зображень для вхідних медіа, налаштуйте `agents.defaults.imageModel`:
@ -248,7 +248,7 @@ openclaw infer image describe \
}
```
Повільним локальним візійним моделям може знадобитися довший тайм-аут розуміння зображень, ніж хмарним моделям. Вони також можуть аварійно завершуватися або зупинятися, коли Ollama намагається виділити весь заявлений контекст vision на обмеженому обладнанні. Встановіть тайм-аут можливості та обмежте `num_ctx` у записі моделі, коли вам потрібен лише звичайний хід опису зображення:
Повільним локальним візуальним моделям може знадобитися довший тайм-аут розуміння зображень, ніж хмарним моделям. Вони також можуть аварійно завершуватися або зупинятися, коли Ollama намагається виділити весь заявлений vision-контекст на обладнанні з обмеженими ресурсами. Задайте тайм-аут можливості та обмежте `num_ctx` у записі моделі, якщо вам потрібен лише звичайний хід опису зображення:
```json5
{
@ -277,16 +277,16 @@ openclaw infer image describe \
}
```
Цей тайм-аут застосовується до розуміння вхідних зображень і до явного інструмента `image`, який агент може викликати під час ходу. `models.providers.ollama.timeoutSeconds` на рівні провайдера й надалі керує базовим захистом HTTP-запиту Ollama для звичайних викликів моделей.
Цей тайм-аут застосовується до розуміння вхідних зображень і до явного інструмента `image`, який агент може викликати під час ходу. Рівень провайдера `models.providers.ollama.timeoutSeconds` усе ще керує захистом HTTP-запиту до Ollama для звичайних викликів моделі.
Щоб виконати live-перевірку явного інструмента image проти локального Ollama, запустіть:
Щоб виконати live-перевірку явного інструмента зображення проти локального Ollama, використайте:
```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
```
Якщо ви визначаєте `models.providers.ollama.models` вручну, позначайте візійні моделі підтримкою введення зображень:
Якщо ви визначаєте `models.providers.ollama.models` вручну, позначайте візуальні моделі підтримкою введення зображень:
```json5
{
@ -303,21 +303,21 @@ OpenClaw відхиляє запити на опис зображень для
## Конфігурація
<Tabs>
<Tab title="Basic (неявне виявлення)">
Найпростіший шлях увімкнення лише local — через змінну середовища:
<Tab title="Базове (неявне виявлення)">
Найпростіший спосіб увімкнення лише локального режиму — через змінну середовища:
```bash
export OLLAMA_API_KEY="ollama-local"
```
<Tip>
Якщо `OLLAMA_API_KEY` встановлено, ви можете не вказувати `apiKey` у записі провайдера, і OpenClaw підставить його для перевірок доступності.
Якщо задано `OLLAMA_API_KEY`, ви можете не вказувати `apiKey` у записі провайдера, і OpenClaw підставить його для перевірок доступності.
</Tip>
</Tab>
<Tab title="Explicit (ручні моделі)">
Використовуйте явну конфігурацію, коли вам потрібне хмарне розміщене налаштування, Ollama працює на іншому хості/порті, ви хочете примусово задати конкретні context windows або списки моделей, або вам потрібні повністю ручні визначення моделей.
<Tab title="Явне (ручні моделі)">
Використовуйте явну конфігурацію, якщо вам потрібне розміщене хмарне налаштування, Ollama працює на іншому хості або порту, ви хочете примусово задати певні контекстні вікна чи списки моделей, або вам потрібні повністю ручні визначення моделей.
```json5
{
@ -346,7 +346,7 @@ OpenClaw відхиляє запити на опис зображень для
</Tab>
<Tab title="Користувацький base URL">
<Tab title="Власний базовий URL">
Якщо Ollama працює на іншому хості або порту (явна конфігурація вимикає автоматичне виявлення, тому визначайте моделі вручну):
```json5
@ -357,7 +357,7 @@ OpenClaw відхиляє запити на опис зображень для
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // Без /v1 — використовуйте URL нативного API Ollama
api: "ollama", // Задайте явно, щоб гарантувати нативну поведінку виклику інструментів
timeoutSeconds: 300, // Необов’язково: дайте холодним локальним моделям більше часу на підключення й потокову передачу
timeoutSeconds: 300, // Необов’язково: дайте холодним локальним моделям більше часу на підключення та потокову передачу
models: [
{
id: "qwen3:32b",
@ -374,7 +374,7 @@ OpenClaw відхиляє запити на опис зображень для
```
<Warning>
Не додавайте `/v1` до URL. Шлях `/v1` використовує режим сумісності з OpenAI, де виклик інструментів працює ненадійно. Використовуйте базовий URL Ollama без суфікса шляху.
Не додавайте `/v1` до URL. Шлях `/v1` використовує режим сумісності з OpenAI, де виклик інструментів ненадійний. Використовуйте базовий URL Ollama без суфікса шляху.
</Warning>
</Tab>
@ -382,7 +382,7 @@ OpenClaw відхиляє запити на опис зображень для
## Поширені рецепти
Використовуйте це як відправні точки й замінюйте ID моделей на точні назви з `ollama list` або `openclaw models list --provider ollama`.
Використовуйте це як відправні точки й замінюйте ідентифікатори моделей на точні назви з `ollama list` або `openclaw models list --provider ollama`.
<AccordionGroup>
<Accordion title="Локальна модель з автоматичним виявленням">
@ -401,7 +401,7 @@ OpenClaw відхиляє запити на опис зображень для
</Accordion>
<Accordion title="Хост Ollama у LAN з ручними моделями">
Для хостів Ollama у LAN використовуйте нативні URL Ollama. Не додавайте `/v1`.
Використовуйте нативні URL Ollama для хостів у LAN. Не додавайте `/v1`.
```json5
{
@ -437,12 +437,12 @@ OpenClaw відхиляє запити на опис зображень для
}
```
`contextWindow` — це бюджет контексту на боці OpenClaw. `params.num_ctx` надсилається Ollama для запиту. Тримайте їх узгодженими, якщо ваше обладнання не може працювати з повним заявленим контекстом моделі.
`contextWindow` — це бюджет контексту на боці OpenClaw. `params.num_ctx` надсилається до Ollama для запиту. Узгоджуйте їх, коли ваше обладнання не може запустити повний заявлений контекст моделі.
</Accordion>
<Accordion title="Лише Ollama Cloud">
Використовуйте це, коли ви не запускаєте локальний демон і хочете безпосередньо використовувати розміщені моделі Ollama.
Використовуйте це, коли ви не запускаєте локальний демон і хочете використовувати розміщені моделі Ollama напряму.
```bash
export OLLAMA_API_KEY="your-ollama-api-key"
@ -479,8 +479,8 @@ OpenClaw відхиляє запити на опис зображень для
</Accordion>
<Accordion title="Хмара плюс local через демон із виконаним входом">
Використовуйте це, коли локальний або LAN-демон Ollama виконав вхід через `ollama signin` і має обслуговувати і локальні моделі, і моделі `:cloud`.
<Accordion title="Хмара плюс локально через демон із виконаним входом">
Використовуйте це, коли локальний демон Ollama або демон у LAN має виконаний вхід через `ollama signin` і повинен обслуговувати і локальні моделі, і моделі `:cloud`.
```bash
ollama signin
@ -517,7 +517,7 @@ OpenClaw відхиляє запити на опис зображень для
</Accordion>
<Accordion title="Кілька хостів Ollama">
Використовуйте користувацькі id провайдера, коли у вас є більше ніж один сервер Ollama. Кожен провайдер отримує власний хост, моделі, автентифікацію, тайм-аут і refs моделей.
Використовуйте власні ідентифікатори провайдерів, якщо у вас більше одного сервера Ollama. Кожен провайдер отримує власний хост, моделі, автентифікацію, тайм-аут і посилання на моделі.
```json5
{
@ -552,12 +552,12 @@ OpenClaw відхиляє запити на опис зображень для
}
```
Коли OpenClaw надсилає запит, префікс активного провайдера знімається, тож `ollama-large/qwen3.5:27b` надходить до Ollama як `qwen3.5:27b`.
Коли OpenClaw надсилає запит, префікс активного провайдера прибирається, тому `ollama-large/qwen3.5:27b` надходить до Ollama як `qwen3.5:27b`.
</Accordion>
<Accordion title="Полегшений профіль локальної моделі">
Деякі локальні моделі можуть відповідати на прості запити, але погано справляються з повною поверхнею інструментів агента. Почніть з обмеження інструментів і контексту, перш ніж змінювати глобальні параметри runtime.
Деякі локальні моделі можуть відповідати на прості запити, але мати труднощі з повною поверхнею інструментів агента. Почніть з обмеження інструментів і контексту, перш ніж змінювати глобальні налаштування середовища виконання.
```json5
{
@ -613,12 +613,9 @@ OpenClaw відхиляє запити на опис зображень для
}
```
Також підтримуються користувацькі id провайдера Ollama. Коли ref моделі використовує префікс активного
провайдера, наприклад `ollama-spark/qwen3:32b`, OpenClaw знімає лише цей
префікс перед викликом Ollama, тож сервер отримує `qwen3:32b`.
Також підтримуються власні ідентифікатори провайдерів Ollama. Коли посилання на модель використовує префікс активного провайдера, наприклад `ollama-spark/qwen3:32b`, OpenClaw прибирає лише цей префікс перед викликом Ollama, щоб сервер отримав `qwen3:32b`.
Для повільних локальних моделей надавайте перевагу налаштуванню запитів у межах провайдера перед збільшенням
тайм-ауту всього runtime агента:
Для повільних локальних моделей краще спершу використовувати налаштування запитів на рівні провайдера, а не підвищувати тайм-аут усього середовища виконання агента:
```json5
{
@ -639,38 +636,35 @@ OpenClaw відхиляє запити на опис зображень для
}
```
`timeoutSeconds` застосовується до HTTP-запиту моделі, включно з налаштуванням з’єднання,
заголовками, потоковою передачею тіла й повним guarded-fetch abort. `params.keep_alive`
передається Ollama як верхньорівневий `keep_alive` у нативних запитах `/api/chat`;
задавайте його для кожної моделі, коли вузьким місцем є час завантаження під час першого ходу.
`timeoutSeconds` застосовується до HTTP-запиту моделі, включно з налаштуванням з’єднання, заголовками, потоковою передачею тіла й загальним перериванням guarded-fetch. `params.keep_alive` пересилається до Ollama як верхньорівневий `keep_alive` у нативних запитах `/api/chat`; задавайте його для кожної моделі, коли вузьким місцем є час завантаження під час першого ходу.
### Швидка перевірка
```bash
# Ollama daemon visible to this machine
# Демон Ollama видимий для цієї машини
curl http://127.0.0.1:11434/api/tags
# OpenClaw catalog and selected model
# Каталог OpenClaw і вибрана модель
openclaw models list --provider ollama
openclaw models status
# Direct model smoke
# Пряма перевірка моделі
openclaw infer model run \
--model ollama/gemma4 \
--prompt "Reply with exactly: ok"
```
Для віддалених хостів замініть `127.0.0.1` на хост, використаний у `baseUrl`. Якщо `curl` працює, а OpenClaw — ні, перевірте, чи Gateway працює на іншій машині, у контейнері або під іншим сервісним акаунтом.
Для віддалених хостів замініть `127.0.0.1` на хост, використаний у `baseUrl`. Якщо `curl` працює, а OpenClaw — ні, перевірте, чи Gateway не працює на іншій машині, у контейнері або під іншим службовим обліковим записом.
## Вебпошук Ollama
## Ollama Web Search
OpenClaw підтримує **Ollama Web Search** як вбудований провайдер `web_search`.
| Властивість | Деталі |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Хост | Використовує ваш налаштований хост Ollama (`models.providers.ollama.baseUrl`, якщо задано, інакше `http://127.0.0.1:11434`); `https://ollama.com` напряму використовує розміщений API |
| Властивість | Докладно |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Хост | Використовує налаштований хост Ollama (`models.providers.ollama.baseUrl`, якщо задано, інакше `http://127.0.0.1:11434`); для `https://ollama.com` напряму використовується розміщений API |
| Автентифікація | Без ключа для локальних хостів Ollama з виконаним входом; `OLLAMA_API_KEY` або налаштована автентифікація провайдера для прямого пошуку через `https://ollama.com` або хостів, захищених автентифікацією |
| Вимога | Локальні/self-hosted хости мають бути запущені та мати виконаний вхід через `ollama signin`; прямий розміщений пошук потребує `baseUrl: "https://ollama.com"` плюс справжній Ollama API key |
| Вимога | Локальні/власнорозміщені хости мають бути запущені й мати виконаний вхід через `ollama signin`; прямий розміщений пошук потребує `baseUrl: "https://ollama.com"` плюс справжній ключ API Ollama |
Виберіть **Ollama Web Search** під час `openclaw onboard` або `openclaw configure --section web`, або задайте:
@ -708,10 +702,10 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
Для локального демона з виконаним входом OpenClaw використовує проксі `/api/experimental/web_search` демона. Для `https://ollama.com` він напряму викликає розміщену кінцеву точку `/api/web_search`.
Для локального демона з виконаним входом OpenClaw використовує проксі демона `/api/experimental/web_search`. Для `https://ollama.com` він викликає розміщену кінцеву точку `/api/web_search` напряму.
<Note>
Повні відомості про налаштування й поведінку див. у [Ollama Web Search](/uk/tools/ollama-search).
Повні відомості про налаштування й поведінку див. у розділі [Ollama Web Search](/uk/tools/ollama-search).
</Note>
## Розширена конфігурація
@ -719,10 +713,10 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
<AccordionGroup>
<Accordion title="Застарілий режим сумісності з OpenAI">
<Warning>
**Виклик інструментів ненадійний у режимі сумісності з OpenAI.** Використовуйте цей режим лише тоді, коли вам потрібен формат OpenAI для проксі й ви не залежите від нативної поведінки виклику інструментів.
**Виклик інструментів ненадійний у режимі сумісності з OpenAI.** Використовуйте цей режим лише якщо вам потрібен формат OpenAI для проксі й ви не залежите від нативної поведінки виклику інструментів.
</Warning>
Якщо вам потрібно використовувати натомість кінцеву точку, сумісну з OpenAI (наприклад, за проксі, який підтримує лише формат OpenAI), явно встановіть `api: "openai-completions"`:
Якщо вам потрібно використовувати натомість кінцеву точку, сумісну з OpenAI (наприклад, за проксі, який підтримує лише формат OpenAI), явно задайте `api: "openai-completions"`:
```json5
{
@ -731,7 +725,7 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // default: true
injectNumCtxForOpenAICompat: true, // типово: true
apiKey: "ollama-local",
models: [...]
}
@ -740,9 +734,9 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
У цьому режимі потокова передача й виклик інструментів можуть не підтримуватися одночасно. Можливо, вам доведеться вимкнути потокову передачу через `params: { streaming: false }` у конфігурації моделі.
У цьому режимі потокова передача й виклик інструментів можуть не підтримуватися одночасно. Можливо, вам доведеться вимкнути потокову передачу за допомогою `params: { streaming: false }` у конфігурації моделі.
Коли `api: "openai-completions"` використовується з Ollama, OpenClaw типово вставляє `options.num_ctx`, щоб Ollama тихо не повертався до context window 4096. Якщо ваш проксі/upstream відхиляє невідомі поля `options`, вимкніть цю поведінку:
Коли `api: "openai-completions"` використовується з Ollama, OpenClaw типово додає `options.num_ctx`, щоб Ollama мовчки не повертався до контекстного вікна 4096. Якщо ваш проксі/вищестояча система відхиляє невідомі поля `options`, вимкніть цю поведінку:
```json5
{
@ -762,12 +756,12 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
</Accordion>
<Accordion title="Context windows">
Для моделей із автоматичним виявленням OpenClaw використовує context window, про який повідомляє Ollama, коли він доступний, зокрема більші значення `PARAMETER num_ctx` із користувацьких Modelfile. В іншому разі він повертається до типового context window Ollama, який використовує OpenClaw.
<Accordion title="Контекстні вікна">
Для моделей з автоматичним виявленням OpenClaw використовує контекстне вікно, про яке повідомляє Ollama, коли воно доступне, зокрема більші значення `PARAMETER num_ctx` із власних Modelfile. В іншому разі він повертається до типового контекстного вікна Ollama, яке використовує OpenClaw.
Ви можете задати типові значення `contextWindow`, `contextTokens` і `maxTokens` на рівні провайдера для кожної моделі під цим провайдером Ollama, а потім за потреби перевизначати їх для окремих моделей. Щоб обмежити runtime-контекст Ollama для окремого запиту без перебудови Modelfile, встановіть `params.num_ctx`; OpenClaw надсилає його як `options.num_ctx` і для нативного Ollama, і для адаптера Ollama, сумісного з OpenAI. Неприпустимі, нульові, від’ємні та нескінченні значення ігноруються й повертаються до `contextWindow`.
Ви можете задати типові значення `contextWindow`, `contextTokens` і `maxTokens` на рівні провайдера для кожної моделі в межах цього провайдера Ollama, а потім за потреби перевизначати їх для окремих моделей. `contextWindow` — це бюджет запиту й Compaction у OpenClaw. Нативні запити Ollama залишають `options.num_ctx` незаданим, якщо ви явно не налаштуєте `params.num_ctx`, тож Ollama може застосувати власне типове значення моделі, `OLLAMA_CONTEXT_LENGTH` або значення за замовчуванням на основі VRAM. Щоб обмежити або примусово задати контекст виконання Ollama для кожного запиту без перебудови Modelfile, задайте `params.num_ctx`; некоректні, нульові, від’ємні та нескінченні значення ігноруються. Адаптер Ollama, сумісний з OpenAI, усе ще типово додає `options.num_ctx` із налаштованого `params.num_ctx` або `contextWindow`; вимкніть це за допомогою `injectNumCtxForOpenAICompat: false`, якщо ваша вищестояща система відхиляє `options`.
Нативні записи моделей Ollama також приймають поширені параметри runtime Ollama в `params`, зокрема `temperature`, `top_p`, `top_k`, `min_p`, `num_predict`, `stop`, `repeat_penalty`, `num_batch`, `num_thread` і `use_mmap`. OpenClaw пересилає лише ключі запиту Ollama, тому параметри runtime OpenClaw, такі як `streaming`, не витікають до Ollama. Використовуйте `params.think` або `params.thinking`, щоб надіслати верхньорівневий `think` Ollama; `false` вимикає thinking на рівні API для thinking-моделей у стилі Qwen.
Нативні записи моделей Ollama також приймають поширені параметри виконання Ollama в `params`, зокрема `temperature`, `top_p`, `top_k`, `min_p`, `num_predict`, `stop`, `repeat_penalty`, `num_batch`, `num_thread` і `use_mmap`. OpenClaw пересилає лише ключі запиту Ollama, тож параметри середовища виконання OpenClaw, як-от `streaming`, не витікають у Ollama. Використовуйте `params.think` або `params.thinking`, щоб надіслати верхньорівневий параметр Ollama `think`; `false` вимикає thinking на рівні API для thinking-моделей у стилі Qwen.
```json5
{
@ -794,19 +788,19 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
`agents.defaults.models["ollama/<model>"].params.num_ctx` на рівні окремої моделі також працює. Якщо налаштовано обидва варіанти, явний запис моделі провайдера має пріоритет над типовим значенням агента.
Працює також `agents.defaults.models["ollama/<model>"].params.num_ctx` для окремої моделі. Якщо налаштовано обидва варіанти, явний запис моделі провайдера має пріоритет над типовим значенням агента.
</Accordion>
<Accordion title="Керування thinking">
Для нативних моделей Ollama OpenClaw пересилає керування thinking так, як очікує Ollama: верхньорівневий `think`, а не `options.think`.
Для нативних моделей Ollama OpenClaw пересилає керування thinking так, як цього очікує Ollama: верхньорівневий `think`, а не `options.think`.
```bash
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
```
Ви також можете встановити типове значення для моделі:
Ви також можете задати типове значення для моделі:
```json5
{
@ -822,37 +816,37 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
`params.think` або `params.thinking` для окремої моделі може вимкнути або примусово ввімкнути thinking API Ollama для конкретної налаштованої моделі. Команди runtime, такі як `/think off`, і надалі застосовуються до активного запуску.
`params.think` або `params.thinking` для окремої моделі можуть вимкнути або примусово ввімкнути thinking API Ollama для конкретної налаштованої моделі. Команди середовища виконання, як-от `/think off`, усе одно застосовуються до активного запуску.
</Accordion>
<Accordion title="Reasoning-моделі">
OpenClaw типово вважає моделі з назвами на кшталт `deepseek-r1`, `reasoning` або `think` reasoning-здатними.
<Accordion title="Моделі reasoning">
OpenClaw типово вважає моделі з назвами на кшталт `deepseek-r1`, `reasoning` або `think` такими, що підтримують reasoning.
```bash
ollama pull deepseek-r1:32b
```
Додаткова конфігурація не потрібна. OpenClaw позначає їх автоматично.
Жодної додаткової конфігурації не потрібно. OpenClaw позначає їх автоматично.
</Accordion>
<Accordion title="Вартість моделей">
Ollama є безкоштовним і працює локально, тому для всіх моделей вартість встановлено в $0. Це стосується і моделей з автоматичним виявленням, і визначених вручну.
Ollama є безкоштовним і працює локально, тому вартість усіх моделей встановлюється в $0. Це стосується як моделей з автоматичним виявленням, так і моделей, визначених вручну.
</Accordion>
<Accordion title="Memory embeddings">
Вбудований плагін Ollama реєструє провайдера memory embeddings для
[пошуку в пам’яті](/uk/concepts/memory). Він використовує налаштований base URL
та API key Ollama, викликає поточну кінцеву точку Ollama `/api/embed` і,
коли можливо, об’єднує кілька memory chunks в один запит `input`.
<Accordion title="Вбудовування пам’яті">
Вбудований Plugin Ollama реєструє провайдера вбудовування пам’яті для
[пошуку в пам’яті](/uk/concepts/memory). Він використовує налаштований базовий URL Ollama
і ключ API, викликає поточну кінцеву точку Ollama `/api/embed` та
за можливості об’єднує кілька фрагментів пам’яті в один запит `input`.
| Властивість | Значення |
| ------------- | ------------------- |
| Типова модель | `nomic-embed-text` |
| Auto-pull | Так — embedding-модель автоматично завантажується, якщо її немає локально |
| Автозавантаження | Так — модель вбудовування автоматично завантажується, якщо її ще немає локально |
Щоб вибрати Ollama як провайдера embeddings для memory search:
Щоб вибрати Ollama як провайдера вбудовувань для пошуку в пам’яті:
```json5
{
@ -864,7 +858,7 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
Для віддаленого embedding-хоста тримайте автентифікацію обмеженою цим хостом:
Для віддаленого хоста вбудовувань зберігайте автентифікацію в межах цього хоста:
```json5
{
@ -886,12 +880,12 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
</Accordion>
<Accordion title="Конфігурація потокової передачі">
Інтеграція OpenClaw з Ollama типово використовує **нативний API Ollama** (`/api/chat`), який повністю підтримує одночасно потокову передачу і виклик інструментів. Жодної спеціальної конфігурації не потрібно.
Інтеграція Ollama в OpenClaw типово використовує **нативний API Ollama** (`/api/chat`), який повністю підтримує одночасно і потокову передачу, і виклик інструментів. Жодної спеціальної конфігурації не потрібно.
Для нативних запитів `/api/chat` OpenClaw також напряму пересилає керування thinking до Ollama: `/think off` і `openclaw agent --thinking off` надсилають верхньорівневий `think: false`, тоді як `/think low|medium|high` надсилають відповідний верхньорівневий рядок effort у `think`. `/think max` зіставляється з найвищим нативним effort Ollama, `think: "high"`.
Для нативних запитів `/api/chat` OpenClaw також напряму пересилає керування thinking до Ollama: `/think off` і `openclaw agent --thinking off` надсилають верхньорівневий `think: false`, а `/think low|medium|high` надсилають відповідний рядок зусилля у верхньому рівні `think`. `/think max` зіставляється з найвищим нативним рівнем зусилля Ollama, `think: "high"`.
<Tip>
Якщо вам потрібно використовувати кінцеву точку, сумісну з OpenAI, дивіться розділ "Застарілий режим сумісності з OpenAI" вище. У цьому режимі потокова передача й виклик інструментів можуть не працювати одночасно.
Якщо вам потрібно використовувати кінцеву точку, сумісну з OpenAI, див. розділ "Застарілий режим сумісності з OpenAI" вище. У цьому режимі потокова передача й виклик інструментів можуть не працювати одночасно.
</Tip>
</Accordion>
@ -900,14 +894,14 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
## Усунення несправностей
<AccordionGroup>
<Accordion title="Ollama не виявляється">
Переконайтеся, що Ollama запущено, що ви встановили `OLLAMA_API_KEY` (або профіль автентифікації), і що ви **не** визначили явний запис `models.providers.ollama`:
<Accordion title="Ollama не виявлено">
Переконайтеся, що Ollama запущено, що ви задали `OLLAMA_API_KEY` (або профіль автентифікації), і що ви **не** визначили явний запис `models.providers.ollama`:
```bash
ollama serve
```
Перевірте, що API доступний:
Переконайтеся, що API доступний:
```bash
curl http://localhost:11434/api/tags
@ -916,48 +910,48 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
</Accordion>
<Accordion title="Немає доступних моделей">
Якщо вашої моделі немає в списку, або завантажте її локально, або визначте її явно в `models.providers.ollama`.
Якщо вашої моделі немає у списку, або завантажте її локально, або визначте її явно в `models.providers.ollama`.
```bash
ollama list # See what's installed
ollama list # Переглянути, що встановлено
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # Or another model
ollama pull llama3.3 # Або іншу модель
```
</Accordion>
<Accordion title="Підключення відхилено">
<Accordion title="У з’єднанні відмовлено">
Перевірте, що Ollama працює на правильному порту:
```bash
# Check if Ollama is running
# Перевірити, чи запущено Ollama
ps aux | grep ollama
# Or restart Ollama
# Або перезапустити Ollama
ollama serve
```
</Accordion>
<Accordion title="Віддалений хост працює з curl, але не з OpenClaw">
Перевірте з тієї самої машини й того самого runtime, де працює Gateway:
Перевірте з тієї самої машини й у тому самому середовищі виконання, де працює Gateway:
```bash
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags
```
Типові причини:
Поширені причини:
- `baseUrl` вказує на `localhost`, але Gateway працює у Docker або на іншому хості.
- URL використовує `/v1`, що вибирає поведінку, сумісну з OpenAI, замість нативного Ollama.
- Віддаленому хосту потрібні зміни firewall або прив’язки LAN на боці Ollama.
- Модель є в демоні на вашому ноутбуці, але її немає у віддаленому демоні.
- `baseUrl` вказує на `localhost`, але Gateway працює в Docker або на іншому хості.
- URL використовує `/v1`, що вибирає поведінку сумісності з OpenAI замість нативного Ollama.
- Віддаленому хосту потрібні зміни firewall або прив’язки до LAN на боці Ollama.
- Модель є в демоні вашого ноутбука, але відсутня у віддаленому демоні.
</Accordion>
<Accordion title="Модель виводить JSON інструментів як текст">
<Accordion title="Модель виводить JSON інструменту як текст">
Зазвичай це означає, що провайдер використовує режим сумісності з OpenAI або модель не може працювати зі схемами інструментів.
Надавайте перевагу нативному режиму Ollama:
@ -975,12 +969,12 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
Якщо невелика локальна модель усе ще не справляється зі схемами інструментів, встановіть `compat.supportsTools: false` для запису цієї моделі й повторно перевірте.
Якщо невелика локальна модель усе ще не справляється зі схемами інструментів, задайте `compat.supportsTools: false` у записі цієї моделі та перевірте ще раз.
</Accordion>
<Accordion title="Холодна локальна модель завершується за тайм-аутом">
Великим локальним моделям може знадобитися довге початкове завантаження, перш ніж почнеться потокова передача. Тримайте тайм-аут обмеженим провайдером Ollama й за потреби попросіть Ollama тримати модель завантаженою між ходами:
<Accordion title="Холодна локальна модель перевищує тайм-аут">
Великим локальним моделям може знадобитися тривале початкове завантаження перед початком потокової передачі. Залишайте тайм-аут у межах провайдера Ollama й за потреби попросіть Ollama тримати модель завантаженою між ходами:
```json5
{
@ -1005,8 +999,8 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
</Accordion>
<Accordion title="Модель з великим контекстом надто повільна або їй бракує пам’яті">
Багато моделей Ollama заявляють контексти, більші, ніж ваше обладнання може комфортно обробляти. Обмежте і бюджет OpenClaw, і контекст запиту Ollama:
<Accordion title="Модель з великим контекстом надто повільна або бракує пам’яті">
Багато моделей Ollama оголошують контексти, більші за ті, які ваше обладнання може комфортно підтримувати. Нативний Ollama використовує власне типове значення контексту виконання Ollama, якщо ви не задасте `params.num_ctx`. Обмежуйте і бюджет OpenClaw, і контекст запиту Ollama, якщо вам потрібна передбачувана затримка до першого токена:
```json5
{
@ -1028,28 +1022,28 @@ OpenClaw підтримує **Ollama Web Search** як вбудований пр
}
```
Спочатку зменшуйте `contextWindow`, якщо повільною є фаза обробки запиту. Зменшуйте `maxTokens`, якщо занадто довго триває генерація.
Спочатку зменшуйте `contextWindow`, якщо OpenClaw надсилає надто великий запит. Зменшуйте `params.num_ctx`, якщо Ollama завантажує контекст виконання, надто великий для машини. Зменшуйте `maxTokens`, якщо генерація триває надто довго.
</Accordion>
</AccordionGroup>
<Note>
Більше допомоги: [Усунення несправностей](/uk/help/troubleshooting) і [FAQ](/uk/help/faq).
Більше довідки: [Усунення несправностей](/uk/help/troubleshooting) і [FAQ](/uk/help/faq).
</Note>
## Пов’язане
<CardGroup cols={2}>
<Card title="Провайдери моделей" href="/uk/concepts/model-providers" icon="layers">
Огляд усіх провайдерів, refs моделей і поведінки failover.
Огляд усіх провайдерів, посилань на моделі та поведінки failover.
</Card>
<Card title="Вибір моделі" href="/uk/concepts/models" icon="brain">
Як вибирати та налаштовувати моделі.
Як вибирати й налаштовувати моделі.
</Card>
<Card title="Ollama Web Search" href="/uk/tools/ollama-search" icon="magnifying-glass">
Повні відомості про налаштування й поведінку вебпошуку на базі Ollama.
</Card>
<Card title="Конфігурація" href="/uk/gateway/configuration" icon="gear">
Повна довідка з конфігурації.
Повний довідник з конфігурації.
</Card>
</CardGroup>