diff --git a/docs/uk/plugins/codex-computer-use.md b/docs/uk/plugins/codex-computer-use.md index 04d0fc603..78b5c3730 100644 --- a/docs/uk/plugins/codex-computer-use.md +++ b/docs/uk/plugins/codex-computer-use.md @@ -1,33 +1,33 @@ --- read_when: - - Ви хочете, щоб агенти OpenClaw у режимі Codex використовували використання комп’ютера Codex - - Ви налаштовуєте `computerUse` для вбудованого Plugin Codex - - Ви усуваєте проблеми зі станом або встановленням `/codex computer-use` -summary: Налаштуйте використання комп’ютера Codex для агентів OpenClaw у режимі Codex -title: Використання комп’ютера Codex + - Ви хочете, щоб агенти OpenClaw у режимі Codex використовували Codex Computer Use + - Ви налаштовуєте `computerUse` для вбудованого плагіна Codex + - Ви усуваєте неполадки зі станом або встановленням `/codex computer-use` +summary: Налаштуйте Codex Computer Use для агентів OpenClaw у режимі Codex +title: Codex Computer Use x-i18n: - generated_at: "2026-04-27T23:13:49Z" + generated_at: "2026-04-27T23:44:58Z" model: gpt-5.4 provider: openai - source_hash: e5ebd47014d64778c4c932e3fb73e5b48503fc2fe6fa7727199417ef902631b3 + source_hash: cc48252f6bc55a1aa9e10f5053d6daaa58787cabf9bcd45ce545a5c23e80e539 source_path: plugins/codex-computer-use.md workflow: 15 --- -Використання комп’ютера — це нативний MCP Plugin для Codex для локального керування робочим столом. OpenClaw -не постачає разом із собою програму для робочого столу, не виконує дії на робочому столі самостійно й не обходить -дозволи Codex. Вбудований Plugin `codex` лише готує app-server Codex: -він вмикає підтримку Plugin у Codex, знаходить або встановлює налаштований -Plugin Codex Computer Use, перевіряє, що MCP-сервер `computer-use` доступний, і -після цього дозволяє Codex керувати нативними викликами інструментів MCP під час кроків у режимі Codex. +Computer Use — це власний для Codex MCP-плагін для локального керування робочим столом. OpenClaw +не постачає застосунок для робочого столу, не виконує дії на робочому столі самостійно і не обходить +дозволи Codex. Вбудований плагін `codex` лише готує app-server Codex: +він вмикає підтримку плагінів Codex, знаходить або встановлює налаштований плагін Codex +Computer Use, перевіряє, що MCP-сервер `computer-use` доступний, а +потім дозволяє Codex керувати власними викликами інструментів MCP під час ходів у режимі Codex. -Використовуйте цю сторінку, коли OpenClaw уже використовує нативне середовище Codex. Для -самого налаштування середовища виконання див. [Середовище Codex](/uk/plugins/codex-harness). +Використовуйте цю сторінку, коли OpenClaw уже використовує нативний harness Codex. Щодо +самого налаштування середовища виконання див. [harness Codex](/uk/plugins/codex-harness). ## Швидке налаштування -Задайте `plugins.entries.codex.config.computerUse`, коли потрібно, щоб для кроків у режимі Codex -Computer Use був доступний до початку потоку: +Установіть `plugins.entries.codex.config.computerUse`, якщо для ходів у режимі Codex +Computer Use має бути доступний до початку потоку: ```json5 { @@ -46,24 +46,34 @@ Computer Use був доступний до початку потоку: agents: { defaults: { model: "openai/gpt-5.5", - embeddedHarness: { - runtime: "codex", + agentRuntime: { + id: "codex", + fallback: "none", }, }, }, } ``` -Із цією конфігурацією OpenClaw перевіряє app-server Codex перед кожним кроком у режимі Codex. +За такої конфігурації OpenClaw перевіряє app-server Codex перед кожним ходом у режимі Codex. Якщо Computer Use відсутній, але app-server Codex уже виявив -marketplace, з якого можна виконати встановлення, OpenClaw просить app-server Codex встановити або знову ввімкнути -Plugin і перезавантажити MCP-сервери. Якщо налаштування все одно не може зробити MCP-сервер -доступним, крок завершується помилкою ще до початку потоку. +маркетплейс, доступний для встановлення, OpenClaw просить app-server Codex встановити або знову ввімкнути +плагін і перезавантажити MCP-сервери. У macOS, коли не зареєстровано +відповідного маркетплейсу і стандартний пакет застосунку Codex існує, OpenClaw також намагається +зареєструвати вбудований маркетплейс Codex із +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, перш ніж +завершити роботу з помилкою. Якщо після налаштування MCP-сервер усе ще недоступний, +хід завершується помилкою ще до початку потоку. + +Наявні сеанси зберігають своє середовище виконання та прив’язку до потоку Codex. Після зміни +`agentRuntime` або конфігурації Computer Use використайте `/new` або `/reset` у відповідному +чаті перед перевіркою. ## Команди Використовуйте команди `/codex computer-use` з будь-якої поверхні чату, де доступна -поверхня команд Plugin `codex`: +поверхня команд плагіна `codex`. Це команди чату/середовища виконання OpenClaw, +а не підкоманди CLI `openclaw codex ...`: ```text /codex computer-use status @@ -73,41 +83,67 @@ Plugin і перезавантажити MCP-сервери. Якщо налаш /codex computer-use install --marketplace ``` -`status` — лише для читання. Він не додає джерела marketplace, не встановлює Plugins і -не вмикає підтримку Plugin у Codex. +`status` — лише для читання. Він не додає джерела маркетплейсу, не встановлює плагіни й +не вмикає підтримку плагінів Codex. -`install` вмикає підтримку Plugin в app-server Codex, за потреби додає налаштоване -джерело marketplace, встановлює або знову вмикає налаштований Plugin через Codex -app-server, перезавантажує MCP-сервери та перевіряє, що MCP-сервер надає інструменти. +`install` вмикає підтримку плагінів в app-server Codex, за потреби додає налаштоване +джерело маркетплейсу, встановлює або знову вмикає налаштований плагін через Codex +app-server, перезавантажує MCP-сервери й перевіряє, що MCP-сервер надає інструменти. -## Варіанти marketplace +## Варіанти маркетплейсу OpenClaw використовує той самий API app-server, який надає сам Codex. Поля -marketplace визначають, де Codex має шукати `computer-use`. +маркетплейсу визначають, де Codex має шукати `computer-use`. -| Поле | Використовуйте, коли | Підтримка встановлення | -| -------------------- | --------------------------------------------------------------- | ------------------------------------------------------ | -| Без поля marketplace | Ви хочете, щоб app-server Codex використовував уже відомі йому marketplace. | Так, коли app-server повертає локальний marketplace. | -| `marketplaceSource` | У вас є джерело marketplace Codex, яке app-server може додати. | Так, для явного `/codex computer-use install`. | -| `marketplacePath` | Ви вже знаєте шлях до локального файла marketplace на хості. | Так, для явного встановлення та автоінсталяції на старті кроку. | -| `marketplaceName` | Ви хочете вибрати вже зареєстрований marketplace за назвою. | Так, лише коли вибраний marketplace має локальний шлях. | +| Поле | Використовуйте, коли | Підтримка встановлення | +| -------------------- | ------------------------------------------------------------- | ---------------------------------------------------- | +| Без поля marketplace | Ви хочете, щоб app-server Codex використовував уже відомі йому маркетплейси. | Так, якщо app-server повертає локальний маркетплейс. | +| `marketplaceSource` | У вас є джерело маркетплейсу Codex, яке app-server може додати. | Так, для явного `/codex computer-use install`. | +| `marketplacePath` | Ви вже знаєте шлях до локального файла маркетплейсу на хості. | Так, для явного встановлення та autoInstall на початку ходу. | +| `marketplaceName` | Ви хочете вибрати вже зареєстрований маркетплейс за назвою. | Так, лише якщо вибраний маркетплейс має локальний шлях. | -Новим домашнім каталогам Codex може знадобитися трохи часу, щоб ініціалізувати їхні офіційні marketplace. -Під час встановлення OpenClaw опитує `plugin/list` до +Новим домашнім каталогам Codex може знадобитися трохи часу, щоб ініціалізувати офіційні +маркетплейси. Під час встановлення OpenClaw опитує `plugin/list` протягом `marketplaceDiscoveryTimeoutMs` мілісекунд. Значення за замовчуванням — 60 секунд. -Якщо кілька відомих marketplace містять Computer Use, OpenClaw надає перевагу +Якщо Computer Use міститься в кількох відомих маркетплейсах, OpenClaw надає перевагу `openai-bundled`, потім `openai-curated`, потім `local`. Невідомі неоднозначні збіги -завершуються безпечною відмовою та просять вас задати `marketplaceName` або `marketplacePath`. +завершуються безпечною відмовою і пропонують вам установити `marketplaceName` або `marketplacePath`. + +## Вбудований маркетплейс macOS + +У нещодавніх збірках Codex для робочого столу Computer Use постачається тут: + +```text +/Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use +``` + +Коли `computerUse.autoInstall` має значення true і жоден маркетплейс, що містить +`computer-use`, не зареєстрований, OpenClaw намагається автоматично додати стандартний +корінь вбудованого маркетплейсу: + +```text +/Applications/Codex.app/Contents/Resources/plugins/openai-bundled +``` + +Ви також можете зареєструвати його явно з оболонки разом із Codex: + +```bash +codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/openai-bundled +``` + +Якщо ви використовуєте нестандартний шлях до застосунку Codex, установіть `computerUse.marketplacePath` на +шлях до локального файла маркетплейсу або один раз виконайте `/codex computer-use install --source +`. ## Обмеження віддаленого каталогу -app-server Codex може перелічувати та читати записи лише з віддаленого каталогу, але наразі +app-server Codex може перелічувати й читати записи каталогу, доступні лише віддалено, але наразі не підтримує віддалений `plugin/install`. Це означає, що `marketplaceName` може -вибрати marketplace лише для віддаленого доступу для перевірок стану, але для встановлення й повторного ввімкнення -усе одно потрібен локальний marketplace через `marketplaceSource` або `marketplacePath`. +вибрати маркетплейс, доступний лише віддалено, для перевірок стану, але для встановлення й повторного ввімкнення +усе одно потрібен локальний маркетплейс через `marketplaceSource` або `marketplacePath`. -Якщо стан показує, що Plugin доступний у віддаленому marketplace Codex, але віддалене +Якщо стан показує, що плагін доступний у віддаленому маркетплейсі Codex, але віддалене встановлення не підтримується, виконайте встановлення з локальним джерелом або шляхом: ```text @@ -115,79 +151,90 @@ app-server Codex може перелічувати та читати запис /codex computer-use install --marketplace-path ``` -## Довідник із конфігурації +## Довідник конфігурації | Поле | За замовчуванням | Значення | | ------------------------------- | ---------------- | ---------------------------------------------------------------------------- | -| `enabled` | визначається автоматично | Вимагає Computer Use. За замовчуванням — true, коли задано інше поле Computer Use. | -| `autoInstall` | false | Встановити або знову ввімкнути з уже виявлених marketplace на старті кроку. | -| `marketplaceDiscoveryTimeoutMs` | 60000 | Скільки часу встановлення чекає на виявлення marketplace app-server Codex. | -| `marketplaceSource` | не задано | Рядок джерела, переданий у `marketplace/add` app-server Codex. | -| `marketplacePath` | не задано | Шлях до локального файла marketplace Codex, що містить Plugin. | -| `marketplaceName` | не задано | Назва зареєстрованого marketplace Codex для вибору. | -| `pluginName` | `computer-use` | Назва Plugin marketplace Codex. | -| `mcpServerName` | `computer-use` | Назва MCP-сервера, яку надає встановлений Plugin. | +| `enabled` | виводиться | Вимагати Computer Use. За замовчуванням дорівнює true, коли встановлено інше поле Computer Use. | +| `autoInstall` | false | Встановити або знову ввімкнути з уже виявлених маркетплейсів на початку ходу. | +| `marketplaceDiscoveryTimeoutMs` | 60000 | Скільки часу встановлення чекає на виявлення маркетплейсу app-server Codex. | +| `marketplaceSource` | не встановлено | Рядок джерела, переданий у `marketplace/add` app-server Codex. | +| `marketplacePath` | не встановлено | Шлях до локального файла маркетплейсу Codex, що містить плагін. | +| `marketplaceName` | не встановлено | Назва зареєстрованого маркетплейсу Codex для вибору. | +| `pluginName` | `computer-use` | Назва плагіна маркетплейсу Codex. | +| `mcpServerName` | `computer-use` | Назва MCP-сервера, який надає встановлений плагін. | -Автоінсталяція на старті кроку навмисно відхиляє налаштовані значення -`marketplaceSource`. Додавання нового джерела — це явна операція налаштування, тому один раз використайте -`/codex computer-use install --source `, а потім дозвольте -`autoInstall` обробляти майбутні повторні ввімкнення з виявлених локальних marketplace. +AutoInstall на початку ходу навмисно відхиляє налаштовані значення +`marketplaceSource`. Додавання нового джерела — це явна операція налаштування, тож +один раз використайте `/codex computer-use install --source `, а потім +дозвольте `autoInstall` обробляти майбутні повторні ввімкнення з виявлених локальних маркетплейсів. +AutoInstall на початку ходу може використовувати налаштований `marketplacePath`, оскільки це +вже локальний шлях на хості. ## Що перевіряє OpenClaw OpenClaw внутрішньо повідомляє стабільну причину стану налаштування й форматує -стан для користувача в чаті: +користувацький статус для чату: -| Причина | Значення | Наступний крок | -| ---------------------------- | ----------------------------------------------------- | ------------------------------------------------ | -| `disabled` | `computerUse.enabled` визначився як false. | Задайте `enabled` або інше поле Computer Use. | -| `marketplace_missing` | Відповідний marketplace недоступний. | Налаштуйте джерело, шлях або назву marketplace. | -| `plugin_not_installed` | Marketplace існує, але Plugin не встановлено. | Виконайте встановлення або ввімкніть `autoInstall`. | -| `plugin_disabled` | Plugin встановлено, але вимкнено в конфігурації Codex. | Виконайте встановлення, щоб знову ввімкнути його. | -| `remote_install_unsupported` | Вибраний marketplace доступний лише віддалено. | Використайте `marketplaceSource` або `marketplacePath`. | -| `mcp_missing` | Plugin увімкнено, але MCP-сервер недоступний. | Перевірте Codex Computer Use і дозволи ОС. | -| `ready` | Plugin та інструменти MCP доступні. | Почніть крок у режимі Codex. | -| `check_failed` | Під час перевірки стану не вдався запит до app-server Codex. | Перевірте підключення до app-server і журнали. | -| `auto_install_blocked` | Для налаштування на старті кроку потрібно додати нове джерело. | Спочатку виконайте явне встановлення. | +| Причина | Значення | Наступний крок | +| ---------------------------- | ---------------------------------------------------- | ----------------------------------------------- | +| `disabled` | `computerUse.enabled` розгорнулося в false. | Установіть `enabled` або інше поле Computer Use. | +| `marketplace_missing` | Відповідний маркетплейс був недоступний. | Налаштуйте джерело, шлях або назву маркетплейсу. | +| `plugin_not_installed` | Маркетплейс існує, але плагін не встановлено. | Виконайте install або ввімкніть `autoInstall`. | +| `plugin_disabled` | Плагін установлено, але вимкнено в конфігурації Codex. | Виконайте install, щоб знову його ввімкнути. | +| `remote_install_unsupported` | Вибраний маркетплейс доступний лише віддалено. | Використайте `marketplaceSource` або `marketplacePath`. | +| `mcp_missing` | Плагін увімкнено, але MCP-сервер недоступний. | Перевірте Codex Computer Use і дозволи ОС. | +| `ready` | Плагін та інструменти MCP доступні. | Почніть хід у режимі Codex. | +| `check_failed` | Під час перевірки стану не вдалося виконати запит до app-server Codex. | Перевірте підключення до app-server і журнали. | +| `auto_install_blocked` | Налаштування на початку ходу потребувало б додавання нового джерела. | Спочатку виконайте явне встановлення. | -Вивід у чаті містить стан Plugin, стан MCP-сервера, marketplace, інструменти, -коли вони доступні, і конкретне повідомлення для кроку налаштування, що завершився помилкою. +Вивід у чаті містить стан плагіна, стан MCP-сервера, маркетплейс, інструменти +за наявності, а також конкретне повідомлення для кроку налаштування, що завершився помилкою. ## Дозволи macOS -Computer Use специфічний для macOS. MCP-сервер, яким керує Codex, може потребувати локальних -дозволів ОС, перш ніж він зможе перевіряти або керувати програмами. Якщо OpenClaw повідомляє, що Computer Use -встановлено, але MCP-сервер недоступний, спочатку перевірте налаштування Computer -Use на стороні Codex: +Computer Use призначений лише для macOS. MCP-сервер під керуванням Codex може потребувати локальних +дозволів ОС, перш ніж зможе перевіряти або керувати застосунками. Якщо OpenClaw повідомляє, що Computer Use +установлено, але MCP-сервер недоступний, спочатку перевірте налаштування Computer +Use на боці Codex: -- app-server Codex запущено на тому самому хості, де має відбуватися керування - робочим столом. -- Plugin Computer Use увімкнено в конфігурації Codex. -- MCP-сервер `computer-use` відображається в стані MCP app-server Codex. -- macOS надала потрібні дозволи для програми керування робочим столом. -- Поточна сесія хоста має доступ до робочого столу, яким керують. +- app-server Codex працює на тому самому хості, де має відбуватися керування робочим столом. +- Плагін Computer Use увімкнено в конфігурації Codex. +- MCP-сервер `computer-use` з’являється в стані MCP app-server Codex. +- macOS надала необхідні дозволи для застосунку керування робочим столом. +- Поточний сеанс хоста має доступ до робочого столу, яким керують. -OpenClaw навмисно завершується безпечною відмовою, коли `computerUse.enabled` має значення true. Крок -у режимі Codex не повинен мовчки продовжуватися без нативних інструментів робочого столу, -які вимагає конфігурація. +OpenClaw навмисно безпечно завершує роботу з помилкою, коли `computerUse.enabled` має значення true. Хід +у режимі Codex не повинен непомітно продовжуватися без нативних інструментів робочого столу, +які вимагала конфігурація. -## Усунення проблем +## Усунення неполадок **Стан показує, що не встановлено.** Виконайте `/codex computer-use install`. Якщо -marketplace не виявлено, передайте `--source` або `--marketplace-path`. +маркетплейс не виявлено, передайте `--source` або `--marketplace-path`. **Стан показує, що встановлено, але вимкнено.** Знову виконайте `/codex computer-use install`. -Встановлення через app-server Codex знову записує конфігурацію Plugin як увімкнену. +Встановлення через app-server Codex знову записує конфігурацію плагіна як увімкнену. -**Стан показує, що віддалене встановлення не підтримується.** Використайте локальне джерело marketplace або -шлях. Записи каталогу лише для віддаленого доступу можна перевіряти, але не встановлювати через +**Стан показує, що віддалене встановлення не підтримується.** Використайте локальне джерело маркетплейсу або +шлях. Записи каталогу, доступні лише віддалено, можна перевіряти, але не можна встановлювати через поточний API app-server. -**Стан показує, що MCP-сервер недоступний.** Один раз повторно виконайте встановлення, щоб -MCP-сервери перезавантажилися. Якщо він усе ще недоступний, виправте програму Codex Computer Use, +**Стан показує, що MCP-сервер недоступний.** Повторно виконайте встановлення один раз, щоб +MCP-сервери перезавантажилися. Якщо він і далі недоступний, виправте застосунок Codex Computer Use, стан MCP app-server Codex або дозволи macOS. -**Автоінсталяція на старті кроку відхиляє джерело.** Це навмисно. Спочатку додайте +**Стан або перевірка перевищують час очікування на `computer-use.list_apps`.** Плагін і MCP- +сервер наявні, але локальний міст Computer Use не відповів. Закрийте або +перезапустіть Codex Computer Use, за потреби повторно запустіть Codex Desktop, а потім спробуйте знову в +новому сеансі OpenClaw. + +**Інструмент Computer Use повідомляє `Native hook relay unavailable`.** Нативний для Codex +перехоплювач інструментів звернувся до OpenClaw із застарілою або відсутньою реєстрацією relay. Почніть +новий сеанс OpenClaw за допомогою `/new` або `/reset`. Якщо це продовжує траплятися, перезапустіть +Gateway, щоб скинути старі потоки app-server і реєстрації перехоплювачів, а потім спробуйте ще раз. + +**AutoInstall на початку ходу відхиляє джерело.** Це навмисно. Спочатку додайте джерело явною командою `/codex computer-use install --source `, -а потім майбутня автоінсталяція на старті кроку зможе використовувати виявлений локальний -marketplace. +а потім у майбутньому autoInstall на початку ходу зможе використовувати виявлений локальний +маркетплейс. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index b976a01ec..fe1ba8143 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,61 +1,56 @@ --- read_when: - - Ви хочете використовувати вбудований app-server harness Codex - - Вам потрібні приклади конфігурації harness Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi -summary: Запускайте вбудовані ходи агента OpenClaw через вбудований app-server harness Codex -title: harness Codex + - Ви хочете використовувати комплектний каркас app-server Codex + - Вам потрібні приклади конфігурації каркаса Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до PI +summary: Запускайте ходи вбудованого агента OpenClaw через комплектний каркас app-server Codex +title: каркас Codex x-i18n: - generated_at: "2026-04-27T23:14:20Z" + generated_at: "2026-04-27T23:45:00Z" model: gpt-5.4 provider: openai - source_hash: d21933bd4646434fdd1d087eaf27e5f230c70df9515ebffd37e2b2ce8c1ab64c + source_hash: ef9654bdc6a2cb44726a53002f2735d823119d2e0379adc68907d8a0980ba4c2 source_path: plugins/codex-harness.md workflow: 15 --- -Вбудований Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness Pi. +Комплектний Plugin `codex` дає OpenClaw змогу запускати ходи вбудованого агента через app-server Codex замість вбудованого каркаса PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням thread, нативною Compaction і виконанням app-server. -OpenClaw як і раніше керує чат-каналами, файлами сесій, вибором моделі, інструментами, -схваленнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Якщо ви лише орієнтуєтесь у темі, почніть із -[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко: -`openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, +Якщо ви намагаєтеся зорієнтуватися, почніть із +[Середовища виконання агента](/uk/concepts/agent-runtimes). Коротка версія така: +`openai/gpt-5.5` — це посилання моделі, `codex` — це середовище виконання, а Telegram, Discord, Slack або інший канал лишається поверхнею комунікації. ## Що змінює цей Plugin -Вбудований Plugin `codex` додає кілька окремих можливостей: +Комплектний Plugin `codex` додає кілька окремих можливостей: -| Можливість | Як використовувати | Що вона робить | -| --------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- | -| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає вбудовані ходи агента OpenClaw через app-server Codex. | -| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує й керує threads app-server Codex із розмови в месенджері. | -| Провайдер/каталог app-server Codex | внутрішні компоненти `codex`, доступні через harness | Дозволяє середовищу виконання виявляти й перевіряти моделі app-server. | -| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | -| Нативна ретрансляція hook | Plugin hooks навколо нативних подій Codex | Дозволяє OpenClaw спостерігати/блокувати підтримувані нативні події інструментів/фіналізації Codex. | +| Можливість | Як її використовувати | Що вона робить | +| -------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- | +| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає ходи вбудованого агента OpenClaw через app-server Codex. | +| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками app-server Codex із розмови в месенджері. | +| Провайдер/каталог app-server Codex | внутрішні механізми `codex`, показані через каркас | Дає середовищу виконання змогу виявляти та перевіряти моделі app-server. | +| Шлях розуміння медіа Codex | шляхи сумісності з моделями зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | +| Нативна ретрансляція хуків | Хуки Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/фіналізації Codex. | Увімкнення Plugin робить ці можливості доступними. Воно **не**: - не починає використовувати Codex для кожної моделі OpenAI -- не перетворює посилання на моделі `openai-codex/*` на нативне середовище виконання +- не перетворює посилання моделей `openai-codex/*` на нативне середовище виконання - не робить ACP/acpx типовим шляхом Codex -- не перемикає на ходу наявні сесії, у яких уже зафіксовано середовище виконання Pi -- не замінює доставку каналів OpenClaw, файли сесій, сховище auth-profile або - маршрутизацію повідомлень +- не перемикає на льоту наявні сесії, у яких уже зафіксовано середовище виконання PI +- не замінює доставку каналів OpenClaw, файли сесій, зберігання профілів автентифікації або маршрутизацію повідомлень Той самий Plugin також керує нативною поверхнею команд керування чатом `/codex`. Якщо -Plugin увімкнено і користувач просить прив’язати, відновити, спрямувати, зупинити або переглянути -threads Codex із чату, агентам слід надавати перевагу `/codex ...` замість ACP. ACP лишається -явним резервним варіантом, коли користувач просить ACP/acpx або тестує ACP -адаптер Codex. +Plugin увімкнено і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити +потоки Codex із чату, агенти мають віддавати перевагу `/codex ...` замість ACP. ACP лишається +явним запасним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP +Codex. -Нативні ходи Codex зберігають Plugin hooks OpenClaw як публічний шар сумісності. -Це внутрішньопроцесні hooks OpenClaw, а не command hooks `hooks.json` Codex: +Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -65,136 +60,134 @@ threads Codex із чату, агентам слід надавати перев - `before_agent_finalize` через ретрансляцію Codex `Stop` - `agent_end` -Плагіни також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернено до Codex. Це окремо від публічного -Plugin hook `tool_result_persist`, який трансформує належні OpenClaw -записи результатів інструментів у транскрипті. +Plugins також можуть реєструвати нейтральне до середовища виконання проміжне програмне забезпечення для результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після виконання інструмента OpenClaw і до повернення результату в Codex. Це окремо від публічного хука Plugin +`tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, якими керує OpenClaw. -Про семантику самих Plugin hooks див. [Plugin hooks](/uk/plugins/hooks) -і [Поведінка guard плагінів](/uk/tools/plugin). +Щодо семантики самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks) +і [Поведінка захисту Plugin](/uk/tools/plugin). -harness вимкнено типово. У нових конфігураціях слід зберігати посилання на моделі OpenAI -канонічними як `openai/gpt-*` і явно примусово вказувати +Каркас вимкнено типово. Нові конфігурації мають зберігати посилання моделей OpenAI +канонічними як `openai/gpt-*` і явно примусово задавати `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають -harness для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, +потрібне нативне виконання app-server. Застарілі посилання моделей `codex/*` і далі автоматично вибирають +каркас для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, не показуються як звичайні варіанти моделі/провайдера. Якщо Plugin `codex` увімкнено, але основна модель усе ще -`openai-codex/*`, `openclaw doctor` показує попередження замість зміни маршруту. Це +`openai-codex/*`, `openclaw doctor` виводить попередження замість зміни маршруту. Це навмисно: `openai-codex/*` лишається шляхом OAuth/підписки PI Codex, а -нативне виконання app-server залишається явним вибором середовища виконання. +нативне виконання app-server лишається явним вибором середовища виконання. ## Карта маршрутів -Використовуйте цю таблицю перед зміною конфігурації: +Скористайтеся цією таблицею перед зміною конфігурації: -| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка стану | -| ------------------------------------------- | -------------------------- | -------------------------------------- | -------------------------- | ------------------------------ | -| OpenAI API через звичайний runner OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | -| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Змішані провайдери з консервативним режимом auto | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові Plugin-середовища виконання | Залежить від вибраного середовища виконання | -| Явна сесія адаптера Codex ACP | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Стан задачі/сесії ACP | +| Бажана поведінка | Посилання моделі | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка статусу | +| ------------------------------------------- | --------------------------- | -------------------------------------- | -------------------------- | ------------------------------- | +| API OpenAI через звичайний виконавець OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Змішані провайдери з консервативним автоматичним режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові середовища виконання Plugin | Залежить від вибраного середовища виконання | +| Явна сесія адаптера Codex ACP | залежить від запиту/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Статус задачі/сесії ACP | -Важливий поділ тут — між провайдером і середовищем виконання: +Важливий поділ — між провайдером і середовищем виконання: -- `openai-codex/*` відповідає на питання «який маршрут провайдера/автентифікації має використовувати PI?» -- `agentRuntime.id: "codex"` відповідає на питання «який цикл має виконувати цей +- `openai-codex/*` відповідає на запитання «який маршрут провайдера/автентифікації має використовувати PI?» +- `agentRuntime.id: "codex"` відповідає на запитання «який цикл має виконувати цей вбудований хід?» -- `/codex ...` відповідає на питання «до якої нативної розмови Codex цей чат має прив’язатися - або якою керувати?» -- ACP відповідає на питання «який зовнішній процес harness має запускати acpx?» +- `/codex ...` відповідає на запитання «до якої нативної розмови Codex має бути прив’язаний + або якою слід керувати в цьому чаті?» +- ACP відповідає на запитання «який зовнішній процес каркаса має запустити acpx?» ## Виберіть правильний префікс моделі Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете -OAuth Codex через PI; використовуйте `openai/*`, коли хочете прямий доступ до OpenAI API або -коли примусово використовуєте нативний harness app-server Codex: +OAuth Codex через PI; використовуйте `openai/*`, коли хочете прямий доступ до API OpenAI або +коли примусово вмикаєте нативний каркас app-server Codex: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| -------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex із типовим runner PI. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | +| Посилання моделі | Шлях середовища виконання | Використовуйте, коли | +| --------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через механізми OpenClaw/PI | Вам потрібен актуальний прямий доступ до API OpenAI Platform через `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex зі стандартним виконавцем PI. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Каркас app-server Codex | Вам потрібне нативне виконання app-server Codex для ходу вбудованого агента. | GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` разом із harness app-server Codex. -Прямий доступ через API key до `openai/gpt-5.5` підтримуватиметься, -щойно OpenAI ввімкне GPT-5.5 у публічному API. +`openai-codex/gpt-5.5` для OAuth PI або `openai/gpt-5.5` із каркасом +app-server Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` буде підтримуватися, +щойно OpenAI увімкне GPT-5.5 у публічному API. Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor -міграція сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання -моделей і записує політику середовища виконання окремо, тоді як застарілі посилання лише для резервного варіанта -залишаються без змін, бо середовище виконання налаштовується для всього контейнера агента. -У нових конфігураціях для PI Codex OAuth слід використовувати `openai-codex/gpt-*`; у нових конфігураціях для нативного -harness app-server слід використовувати `openai/gpt-*` разом із +під час міграції сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання моделей і окремо записує політику середовища виконання, тоді як застарілі посилання лише для запасного варіанта лишаються без змін, бо середовище виконання налаштовується для всього контейнера агента. +Нові конфігурації OAuth PI Codex мають використовувати `openai-codex/gpt-*`; нові конфігурації +каркаса нативного app-server мають використовувати `openai/gpt-*` плюс `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` дотримується того самого поділу за префіксом. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений хід app-server Codex. Модель app-server Codex -має оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до -початку ходу з медіа. +`agents.defaults.imageModel` дотримується того самого поділу префіксів. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OpenAI +Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має працювати +через обмежений хід app-server Codex. Модель app-server Codex має +заявляти підтримку введення зображень; текстові моделі Codex завершуються помилкою до початку +медіа-ходу. -Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо -вибір дивує, увімкніть debug-журналювання для підсистеми `agents/harness` -і перегляньте структурований запис gateway `agent harness selected`. Він -містить id вибраного harness, причину вибору, політику runtime/fallback і, +Використовуйте `/status`, щоб підтвердити фактичний каркас для поточної сесії. Якщо +вибір видається несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness` +і перевірте структурований запис шлюзу `agent harness selected`. Він +містить id вибраного каркаса, причину вибору, політику середовища виконання/запасного варіанта та, у режимі `auto`, результат підтримки для кожного кандидата Plugin. ### Що означають попередження doctor -`openclaw doctor` попереджає, коли всі ці умови істинні: +`openclaw doctor` виводить попередження, коли виконуються всі ці умови: -- вбудований Plugin `codex` увімкнено або дозволено +- комплектний Plugin `codex` увімкнено або дозволено - основна модель агента — `openai-codex/*` - фактичне середовище виконання цього агента — не `codex` Це попередження існує, тому що користувачі часто очікують, що «Plugin Codex увімкнено» означає -«нативне середовище виконання app-server Codex». OpenClaw не робить такого переходу. Попередження -означає: +«нативне середовище виконання app-server Codex». OpenClaw не робить такого переходу автоматично. Попередження означає: -- **Нічого змінювати не потрібно**, якщо ви свідомо використовуєте ChatGPT/Codex OAuth через PI. +- **Нічого змінювати не потрібно**, якщо вам був потрібен OAuth ChatGPT/Codex через PI. - Змініть модель на `openai/` і встановіть - `agentRuntime.id: "codex"`, якщо вам потрібне нативне виконання + `agentRuntime.id: "codex"`, якщо вам було потрібне нативне виконання app-server. -- Наявним сесіям усе одно потрібен `/new` або `/reset` після зміни середовища виконання, - тому що прив’язки середовища виконання сесії є sticky. +- Наявним сесіям усе одно потрібні `/new` або `/reset` після зміни середовища виконання, + тому що прив’язки середовища виконання сесії є фіксованими. -Вибір harness не є засобом керування живою сесією. Коли виконується вбудований хід, -OpenClaw записує id вибраного harness у цю сесію й продовжує використовувати його для -наступних ходів із тим самим id сесії. Змініть конфігурацію `agentRuntime` або -`OPENCLAW_AGENT_RUNTIME`, якщо хочете, щоб майбутні сесії використовували інший harness; +Вибір каркаса — це не механізм керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує id вибраного каркаса в цю сесію й надалі використовує його для +пізніших ходів у межах того самого id сесії. Змінюйте конфігурацію `agentRuntime` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший каркас; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI і Codex. Це запобігає відтворенню одного транскрипту через +розмови між PI і Codex. Це запобігає повторному програванню одного транскрипту через дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи прив’язок harness, вважаються прив’язаними до PI, щойно вони -мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на -Codex після зміни конфігурації. +Застарілі сесії, створені до появи прив’язок каркаса, вважаються прив’язаними до PI, щойно +в них з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести +цю розмову на Codex після зміни конфігурації. -`/status` показує фактичне середовище виконання моделі. Типовий harness Pi відображається як -`Runtime: OpenClaw Pi Default`, а harness app-server Codex — як +`/status` показує фактичне середовище виконання моделі. Стандартний каркас PI відображається як +`Runtime: OpenClaw Pi Default`, а каркас app-server Codex — як `Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- Codex app-server версії `0.125.0` або новішої. Вбудований Plugin типово керує - сумісним двійковим файлом app-server Codex, тож локальні команди `codex` у `PATH` - не впливають на звичайний запуск harness. -- Автентифікація Codex доступна для процесу app-server. +- OpenClaw із доступним комплектним Plugin `codex`. +- Codex app-server `0.125.0` або новіший. Комплектний Plugin типово керує сумісним + бінарним файлом app-server Codex, тому локальні команди `codex` у `PATH` + не впливають на звичайний запуск каркаса. +- Автентифікація Codex, доступна для процесу app-server. -Plugin блокує старіші або неверсіоновані handshake app-server. Це дозволяє -OpenClaw залишатися в межах поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані рукостискання app-server. Це дозволяє +OpenClaw лишатися в межах поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також, за потреби, із файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі дані автентифікації, що й ваш локальний app-server Codex. +Для live- і Docker-smoke-тестів автентифікація зазвичай походить із `OPENAI_API_KEY`, а також +з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте той самий автентифікаційний матеріал, що й ваш локальний +app-server Codex. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово задайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте каркас `codex`: ```json5 { @@ -232,27 +225,25 @@ OpenClaw залишатися в межах поверхні протоколу, ``` Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як -`codex/`, усе ще автоматично вмикають вбудований Plugin `codex`. У нових конфігураціях слід -надавати перевагу `openai/` разом із явним записом `agentRuntime`, наведеним вище. +`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають +віддавати перевагу `openai/` плюс явний запис `agentRuntime`, наведений вище. -## Додайте Codex поряд з іншими моделями +## Додайте Codex поруч з іншими моделями -Не встановлюйте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися +Не задавайте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися між Codex і моделями інших провайдерів. Примусове середовище виконання застосовується до кожного -вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки -це середовище виконання примусово задане, OpenClaw усе одно спробує harness Codex і завершиться помилкою -беззастережно, замість того щоб тихо маршрутизувати цей хід через PI. +вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, коли це середовище виконання примусово задано, OpenClaw все одно спробує каркас Codex і завершиться помилкою без тихого перенаправлення цього ходу через PI. -Натомість використовуйте одну з цих схем: +Замість цього використовуйте одну з таких форм: - Розмістіть Codex на окремому агенті з `agentRuntime.id: "codex"`. -- Залиште типовий агент на `agentRuntime.id: "auto"` і резервний перехід на Pi для звичайного змішаного +- Залиште типовий агент на `agentRuntime.id: "auto"` і запасному варіанті PI для звичайного змішаного використання провайдерів. -- Використовуйте застарілі посилання `codex/*` лише для сумісності. У нових конфігураціях слід надавати перевагу - `openai/*` разом із явною політикою середовища виконання Codex. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу + `openai/*` плюс явна політика середовища виконання Codex. -Наприклад, така конфігурація залишає типовий агент на звичайному автоматичному виборі й -додає окремого агента Codex: +Наприклад, це залишає типовий агент на звичайному автоматичному виборі та +додає окремий агент Codex: ```json5 { @@ -289,36 +280,36 @@ OpenClaw залишатися в межах поверхні протоколу, } ``` -За такої схеми: +У такій формі: -- Типовий агент `main` використовує звичайний шлях провайдера і резервну сумісність Pi. -- Агент `codex` використовує harness app-server Codex. +- Типовий агент `main` використовує звичайний шлях провайдера та запасний варіант сумісності PI. +- Агент `codex` використовує каркас app-server Codex. - Якщо Codex відсутній або не підтримується для агента `codex`, хід завершується - помилкою замість тихого використання Pi. + помилкою замість тихого використання PI. ## Маршрутизація команд агента Агенти мають маршрутизувати запити користувача за наміром, а не лише за словом "Codex": -| Користувач просить... | Агент має використати... | -| ---------------------------------------------------------- | -------------------------------------------------- | -| "Прив’яжи цей чат до Codex" | `/codex bind` | -| "Віднови тут thread Codex ``" | `/codex resume ` | -| "Покажи threads Codex" | `/codex threads` | -| "Використовуй Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | -| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | -| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Запусти Claude Code/Gemini/OpenCode/Cursor у thread" | ACP/acpx, не `/codex` і не нативні субагенти | +| Користувач просить... | Агент має використовувати... | +| ------------------------------------------------------ | ----------------------------------------------- | +| "Прив’яжи цей чат до Codex" | `/codex bind` | +| "Віднови тут потік Codex ``" | `/codex resume ` | +| "Покажи потоки Codex" | `/codex threads` | +| "Використовуй Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | +| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання моделей `openai-codex/*` | +| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, а не `/codex` і не нативні субагенти | -OpenClaw показує агентам підказки щодо запуску через ACP лише тоді, коли ACP увімкнено, +OpenClaw показує агентам рекомендації щодо запуску ACP лише тоді, коли ACP увімкнено, можна диспетчеризувати і він підкріплений завантаженим бекендом середовища виконання. Якщо ACP недоступний, -системний prompt і Skills Plugin не повинні навчати агента маршрутизації +системний запит і Skills Plugin не повинні навчати агента маршрутизації через ACP. ## Розгортання лише з Codex -Примусово використовуйте harness Codex, коли потрібно гарантувати, що кожен вбудований хід агента -використовує Codex. Явні Plugin-середовища виконання типово не мають резервного переходу на Pi, тож +Примусово використовуйте каркас Codex, коли потрібно підтвердити, що кожен хід вбудованого агента +використовує Codex. Явні середовища виконання Plugin типово не мають запасного варіанта PI, тому `fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 @@ -341,15 +332,15 @@ OpenClaw показує агентам підказки щодо запуску OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Якщо Codex примусово задано, OpenClaw завершується помилкою рано, якщо Plugin Codex вимкнено, -app-server застарілий або app-server не може запуститися. Установлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише тоді, коли свідомо хочете, щоб Pi обробляв -відсутній вибір harness. +Якщо Codex примусово ввімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, +app-server занадто старий або app-server не може запуститися. Встановлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв +відсутній вибір каркаса. ## Codex для окремого агента -Ви можете зробити одного агента лише для Codex, тоді як типовий агент збереже звичайний -автоматичний вибір: +Ви можете зробити один агент таким, що використовує тільки Codex, тоді як типовий агент зберігатиме звичайний +автовибір: ```json5 { @@ -380,15 +371,15 @@ app-server застарілий або app-server не може запустит } ``` -Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server -за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього thread -і дозволяє наступному ходу знову визначити harness з поточної конфігурації. +Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову +сесію OpenClaw, а каркас Codex створює або відновлює свій побічний потік app-server +за потреби. `/reset` очищує прив’язку сесії OpenClaw для цього потоку +і дає наступному ходу змогу знову визначити каркас із поточної конфігурації. ## Виявлення моделей -Типово Plugin Codex запитує в app-server список доступних моделей. Якщо -виявлення завершується помилкою або перевищує час очікування, він використовує вбудований резервний каталог для: +Типово Plugin Codex запитує app-server про доступні моделі. Якщо +виявлення завершується помилкою або перевищує час очікування, він використовує комплектний запасний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -414,8 +405,8 @@ app-server застарілий або app-server не може запустит } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося звернення до Codex і використовувався -резервний каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався +запасний каталог: ```json5 { @@ -434,27 +425,27 @@ app-server застарілий або app-server не може запустит } ``` -## Підключення до app-server і політика +## Підключення app-server і політика -Типово Plugin запускає локально керований OpenClaw двійковий файл Codex так: +Типово Plugin запускає локально бінарний файл Codex, яким керує OpenClaw, за допомогою: ```bash codex app-server --listen stdio:// ``` -Керований двійковий файл оголошено як вбудовану залежність середовища виконання Plugin і розміщується -разом з рештою залежностей Plugin `codex`. Це прив’язує версію app-server -до вбудованого Plugin, а не до якоїсь окремої Codex CLI, -яка випадково встановлена локально. Установлюйте `appServer.command` лише тоді, коли +Керований бінарний файл оголошується як комплектна залежність середовища виконання Plugin і розміщується +разом з рештою залежностей Plugin `codex`. Це зберігає версію app-server прив’язаною +до комплектного Plugin, а не до будь-якого окремого Codex CLI, +який випадково встановлено локально. Встановлюйте `appServer.command` лише тоді, коли свідомо хочете запускати інший виконуваний файл. -Типово OpenClaw запускає локальні сесії harness Codex у режимі YOLO: +Типово OpenClaw запускає локальні сесії каркаса Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена локальна позиція оператора, що використовується -для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без -зупинки на нативних запитах схвалення, на які нікому відповідати. +`sandbox: "danger-full-access"`. Це довірена локальна робоча модель оператора, яка використовується +для автономних Heartbeat: Codex може використовувати інструменти оболонки та мережі без +зупинки на нативних запитах підтвердження, на які нікому відповісти. -Щоб увімкнути схвалення з нативною перевіркою guardian Codex, установіть `appServer.mode: +Щоб увімкнути підтвердження Codex із переглядом guardian, задайте `appServer.mode: "guardian"`: ```json5 @@ -475,21 +466,19 @@ codex app-server --listen stdio:// } ``` -Режим guardian використовує нативний шлях автоперевірки схвалень Codex. Коли Codex просить -вийти із sandbox, писати поза робочим простором або додати дозволи, як-от доступ до мережі, -Codex спрямовує цей запит на схвалення до нативного reviewer замість -людського prompt. Reviewer застосовує модель ризиків Codex і схвалює або відхиляє -конкретний запит. Використовуйте Guardian, коли хочете більше захисних обмежень, ніж у режимі YOLO, -але все одно потребуєте, щоб агенти без нагляду могли просуватися далі. +Режим guardian використовує нативний шлях автоматичного перегляду підтверджень Codex. Коли Codex просить +вийти з пісочниці, записати поза робочим простором або додати дозволи, як-от доступ до мережі, +Codex спрямовує цей запит на підтвердження нативному рецензенту, а не людині через запит. Рецензент застосовує модель ризиків Codex і підтверджує або відхиляє конкретний запит. Використовуйте Guardian, коли потрібні додаткові запобіжники порівняно з режимом YOLO, +але водночас потрібно, щоб агенти без нагляду могли рухатися далі. -Preset `guardian` розгортається в `approvalPolicy: "on-request"`, +Налаштування `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. Окремі поля політики все одно перевизначають `mode`, тому розширені розгортання можуть поєднувати -preset з явними налаштуваннями. Старе значення reviewer `guardian_subagent` -і далі приймається як псевдонім сумісності, але в нових конфігураціях слід використовувати +цей шаблон з явними виборами. Старе значення рецензента `guardian_subagent` +і далі приймається як псевдонім сумісності, але нові конфігурації мають використовувати `auto_review`. -Для app-server, який уже запущено, використовуйте транспорт WebSocket: +Для вже запущеного app-server використовуйте транспорт WebSocket: ```json5 { @@ -513,22 +502,22 @@ preset з явними налаштуваннями. Старе значення Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | керований двійковий файл Codex | Виконуваний файл для stdio-транспорту. Залишайте порожнім, щоб використовувати керований двійковий файл; задавайте лише для явного перевизначення. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для stdio-транспорту. | -| `url` | не задано | URL app-server WebSocket. | -| `authToken` | не задано | Bearer token для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | -| `mode` | `"yolo"` | Preset для виконання YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика схвалення Codex, що надсилається під час запуску/відновлення/ходу thread. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення thread. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити на схвалення. `guardian_subagent` лишається застарілим псевдонімом. | +| Поле | Типове значення | Значення | +| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не задано | URL WebSocket app-server. | +| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | +| `mode` | `"yolo"` | Попередньо встановлений режим для виконання YOLO або guardian-reviewed. | +| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається на старт/відновлення потоку/хід. | +| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається на старт/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити підтвердження. `guardian_subagent` лишається застарілим псевдонімом. | | `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Перевизначення через змінні середовища залишаються доступними для локального тестування: +Перевизначення через середовище й далі доступні для локального тестування: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -536,21 +525,21 @@ preset з явними налаштуваннями. Старе значення - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` оминає керований двійковий файл, коли +`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований бінарний файл, коли `appServer.command` не задано. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` натомість, або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурації -слід надавати перевагу для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin -в тому самому перевіреному файлі, що й решту налаштування harness Codex. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` або +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація +є бажаною для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у тому самому +перевіреному файлі, що й решта налаштування каркаса Codex. -## Computer use +## Використання комп’ютера Computer Use описано в окремому посібнику з налаштування: [Codex Computer Use](/uk/plugins/codex-computer-use). -Коротко: OpenClaw не постачає настільний застосунок керування і не виконує +Коротка версія: OpenClaw не постачає застосунок для керування робочим столом і не виконує дії на робочому столі самостійно. Він готує app-server Codex, перевіряє, що MCP-сервер `computer-use` доступний, а потім дозволяє Codex обробляти нативні виклики інструментів MCP під час ходів у режимі Codex. @@ -574,8 +563,9 @@ MCP-сервер `computer-use` доступний, а потім дозволя agents: { defaults: { model: "openai/gpt-5.5", - embeddedHarness: { - runtime: "codex", + agentRuntime: { + id: "codex", + fallback: "none", }, }, }, @@ -590,11 +580,18 @@ MCP-сервер `computer-use` доступний, а потім дозволя - `/codex computer-use install --marketplace-path ` Computer Use специфічний для macOS і може вимагати локальних дозволів ОС, перш ніж -MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` дорівнює true і MCP- -сервер недоступний, ходи в режимі Codex завершуються помилкою ще до запуску thread, замість +MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true і MCP- +сервер недоступний, ходи в режимі Codex завершуються помилкою до запуску потоку замість тихого виконання без нативних інструментів Computer Use. Див. -[Codex Computer Use](/uk/plugins/codex-computer-use) для вибору marketplace, -обмежень віддаленого каталогу, причин статусів і порад з усунення проблем. +[Codex Computer Use](/uk/plugins/codex-computer-use) щодо вибору marketplace, +обмежень віддаленого каталогу, причин стану та усунення несправностей. + +Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати стандартний +комплектний marketplace Codex Desktop з +`/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, якщо Codex +ще не виявив локальний marketplace. Використовуйте `/new` або `/reset` після +зміни конфігурації середовища виконання або Computer Use, щоб наявні сесії не зберігали стару +прив’язку потоку PI або Codex. ## Поширені рецепти @@ -612,7 +609,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перевірка harness лише для Codex: +Перевірка каркаса лише з Codex: ```json5 { @@ -634,7 +631,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Схвалення Codex із перевіркою guardian: +Підтвердження Codex із переглядом guardian: ```json5 { @@ -679,190 +676,196 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перемикання моделей і далі контролює OpenClaw. Коли сесію OpenClaw приєднано -до наявного thread Codex, наступний хід знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику схвалення, sandbox і -рівень сервісу. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає -прив’язку до thread, але просить Codex продовжити з новою вибраною моделлю. +Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано +до наявного потоку Codex, наступний хід знову надсилає до +app-server поточно вибрані модель OpenAI, провайдера, політику підтверджень, пісочницю та рівень сервісу. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -загальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. +Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живий стан підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та Skills. -- `/codex models` виводить список актуальних моделей app-server Codex. -- `/codex threads [filter]` виводить список нещодавніх threads Codex. -- `/codex resume ` приєднує поточну сесію OpenClaw до наявного thread Codex. -- `/codex compact` просить app-server Codex виконати Compaction для приєднаного thread. -- `/codex review` запускає нативну перевірку Codex для приєднаного thread. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex models` перелічує живі моделі app-server Codex. +- `/codex threads [filter]` перелічує нещодавні потоки Codex. +- `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. +- `/codex compact` просить app-server Codex виконати Compaction приєднаного потоку. +- `/codex review` запускає нативну перевірку Codex для приєднаного потоку. - `/codex computer-use status` перевіряє налаштований Plugin Computer Use і MCP-сервер. -- `/codex computer-use install` встановлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. +- `/codex computer-use install` установлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` виводить стан MCP-серверів app-server Codex. -- `/codex skills` виводить Skills app-server Codex. +- `/codex mcp` перелічує стан MCP-сервера app-server Codex. +- `/codex skills` перелічує Skills app-server Codex. -`/codex resume` записує той самий файл sidecar-прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає -поточну вибрану модель OpenClaw до app-server і зберігає ввімкнену +`/codex resume` записує той самий побічний файл прив’язки, який каркас використовує для +звичайних ходів. На наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає увімкнену розширену історію. -Поверхня команд потребує app-server Codex версії `0.125.0` або новішої. Окремі +Поверхня команд вимагає Codex app-server `0.125.0` або новішої версії. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або нестандартний app-server не надає цей JSON-RPC-метод. +майбутній або нестандартний app-server не надає цей метод JSON-RPC. -## Межі hook +## Межі хуків -harness Codex має три шари hook: +Каркас Codex має три шари хуків: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | ----------------------------------------------------------------- | -| Plugin hooks OpenClaw | OpenClaw | Сумісність продукту/плагінів між harness Pi і Codex. | -| Middleware розширень app-server Codex | Вбудовані Plugin OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних інструментів OpenClaw. | -| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | +| Шар | Власник | Призначення | +| ------------------------------------- | ------------------------ | -------------------------------------------------------------------- | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між каркасами PI і Codex. | +| Проміжне ПЗ розширень app-server Codex | Комплектні Plugins OpenClaw | Поведінка адаптера на рівні ходу навколо динамічних інструментів OpenClaw. | +| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує файли `hooks.json` Codex рівня проєкту або глобального рівня для маршрутизації +OpenClaw не використовує файли `hooks.json` проєкту або глобальні файли Codex для маршрутизації поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів -OpenClaw впроваджує конфігурацію Codex для кожного thread для `PreToolUse`, `PostToolUse`, -`PermissionRequest` і `Stop`. Інші hooks Codex, як-от `SessionStart` і -`UserPromptSubmit`, лишаються механізмами керування рівня Codex; вони не надаються як -Plugin hooks OpenClaw у контракті v1. +OpenClaw впроваджує конфігурацію Codex для кожного потоку для `PreToolUse`, `PostToolUse`, +`PermissionRequest` і `Stop`. Інші хуки Codex, як-от `SessionStart` і +`UserPromptSubmit`, залишаються елементами керування на рівні Codex; вони не +експонуються як хуки Plugin OpenClaw у контракті v1. Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тож OpenClaw запускає поведінку Plugin і middleware, якою він володіє в -адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. -OpenClaw може віддзеркалювати окремі події, але не може переписувати нативний thread Codex, -якщо Codex не надає цю операцію через app-server або зворотні виклики нативних hook. +виклик, тож OpenClaw запускає поведінку Plugin і проміжного ПЗ, якою він володіє в +адаптері каркаса. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. +OpenClaw може віддзеркалювати вибрані події, але не може переписувати нативний потік Codex, +якщо Codex не відкриє цю операцію через app-server або зворотні виклики +нативних хуків. -Проєкції життєвого циклу Compaction і LLM надходять зі сповіщень app-server Codex -і стану адаптера OpenClaw, а не з команд нативних hook Codex. +Проєкції Compaction і життєвого циклу LLM походять із сповіщень app-server Codex +і стану адаптера OpenClaw, а не з команд нативних хуків Codex. Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` — це спостереження рівня адаптера, а не побайтні захоплення -внутрішнього запиту Codex або корисного навантаження Compaction. +`llm_output` — це спостереження на рівні адаптера, а не побайтні захоплення +внутрішнього запиту Codex або даних Compaction. Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. -Вони не викликають Plugin hooks OpenClaw. +Вони не викликають хуки Plugin OpenClaw. ## Контракт підтримки V1 -Режим Codex — це не Pi з іншим викликом моделі під капотом. Codex керує більшою частиною -нативного циклу моделі, а OpenClaw адаптує свої поверхні плагінів і сесій +Режим Codex — це не PI з іншим викликом моделі під ним. Codex володіє більшою частиною +нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесії навколо цієї межі. Підтримується в середовищі виконання Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл моделі OpenAI через Codex | Підтримується | App-server Codex керує ходом OpenAI, нативним відновленням thread і нативним продовженням інструментів. | -| Маршрутизація і доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали лишаються поза середовищем виконання моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається в шляху виконання. | -| Плагіни prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням thread. | -| Життєвий цикл механізму контексту | Підтримується | Збирання, ingest або післяходове обслуговування й координація Compaction механізму контексту виконуються для ходів Codex. | -| Hooks динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | -| Hooks життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують з коректними корисними навантаженнями для режиму Codex. | -| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних hook | `Stop` Codex ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | -| Блокування або спостереження за нативним shell, patch і MCP | Підтримується через ретрансляцію нативних hook | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з корисними навантаженнями MCP в app-server Codex `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | -| Нативна політика дозволів | Підтримується через ретрансляцію нативних hook | `PermissionRequest` Codex можна маршрутизувати через політику OpenClaw там, де це підтримує середовище виконання. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях схвалення guardian або користувача. | -| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які він отримує від app-server. | +| Поверхня | Підтримка | Чому | +| --------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Цикл моделі OpenAI через Codex | Підтримується | App-server Codex володіє ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза середовищем виконання моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається на шляху виконання. | +| Plugins запиту та контексту | Підтримується | OpenClaw будує накладки запиту та проєктує контекст у хід Codex перед запуском або відновленням потоку. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або супровід після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і проміжне ПЗ для результатів інструментів виконуються навколо динамічних інструментів OpenClaw. | +| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` запускаються з чесними даними режиму Codex. | +| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативного хука | Codex `Stop` ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | +| Блокування або спостереження нативної оболонки, patch і MCP | Підтримується через ретрансляцію нативного хука | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, включно з корисними навантаженнями MCP в Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Політика нативних дозволів | Підтримується через ретрансляцію нативного хука | Codex `PermissionRequest` можна маршрутизувати через політику OpenClaw там, де це надає середовище виконання. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях підтвердження guardian або користувача. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які він отримує. | Не підтримується в середовищі виконання Codex v1: -| Поверхня | Межа V1 | Майбутній шлях | -| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка hook/схеми Codex для заміни вхідних даних інструмента. | -| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного thread. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має змінювати непідтримувані внутрішні дані. | Додати явні API app-server Codex, якщо потрібна операція над нативним thread. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей hook трансформує записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна віддзеркалювати трансформовані записи, але канонічне переписування потребує підтримки Codex. | -| Багаті метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/видаленого, зміни кількості токенів або корисного навантаження зведення. | Потрібні багатші події Compaction від Codex. | -| Втручання в Compaction | Поточні hooks Compaction OpenClaw у режимі Codex мають рівень сповіщень. | Додати pre/post hooks Compaction Codex, якщо плагінам потрібно забороняти або переписувати нативну Compaction. | -| Побайтне захоплення запиту до API моделі | OpenClaw може захоплювати запити до app-server і сповіщення, але ядро Codex внутрішньо формує фінальний запит до OpenAI API. | Потрібна подія трасування запиту моделі Codex або API налагодження. | +| Поверхня | Межа V1 | Майбутній шлях | +| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка hook/schema Codex для заміни вхідних даних інструмента. | +| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібна хірургія нативного потоку. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей хук перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна було б віддзеркалювати перетворені записи, але канонічне переписування потребує підтримки Codex. | +| Багаті метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільний список збереженого/відкинутого, дельту токенів або дані зведення. | Потрібні багатші події Compaction Codex. | +| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post хуки Compaction Codex, якщо Plugins мають скасовувати або переписувати нативну Compaction. | +| Побайтне захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex внутрішньо будує фінальний запит до API OpenAI. | Потрібна подія трасування запиту моделі Codex або API налагодження. | ## Інструменти, медіа та Compaction -harness Codex змінює лише низькорівневий виконавець вбудованого агента. +Каркас Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw як і раніше будує список інструментів і отримує результати динамічних інструментів із -harness. Текст, зображення, відео, музика, TTS, схвалення і вивід інструментів обміну повідомленнями -й далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw, як і раніше, формує список інструментів і отримує результати динамічних інструментів від +каркаса. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів обміну повідомленнями +і далі проходять звичайним шляхом доставки OpenClaw. -Нативна ретрансляція hook навмисно є узагальненою, але контракт підтримки v1 +Ретрансляція нативних хуків навмисно є загальною, але контракт підтримки v1 обмежений шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У середовищі виконання Codex це включає корисні навантаження `PreToolUse`, `PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня -подія hook Codex є поверхнею Plugin OpenClaw, доки її не буде названо в контракті +подія хука Codex є поверхнею Plugin OpenClaw, доки її не буде названо в контракті середовища виконання. Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny -лише тоді, коли це визначає політика. Результат без рішення не є allow. Codex -сприймає його як відсутність рішення hook і переходить до власного шляху схвалення -guardian або користувача. +лише тоді, коли політика ухвалює рішення. Результат без рішення — це не allow. Codex +розглядає його як відсутність рішення хука і переходить до власного шляху підтвердження guardian або користувача. -Запити на схвалення інструментів MCP Codex маршрутизуються через потік схвалень Plugin OpenClaw, -коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Prompt `request_user_input` від Codex надсилаються назад до -вихідного чату, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний -запит сервера замість того, щоб додаватися як додатковий контекст. Інші запити -на уточнення MCP і далі завершуються помилкою беззастережно. +Запити на підтвердження інструментів MCP Codex маршрутизуються через потік +підтвердження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до +початкового чату, а наступне поставлене в чергу follow-up-повідомлення відповідає на цей нативний +запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити на elicitation MCP +і далі завершуються помилкою без небезпечного продовження. -Коли вибрана модель використовує harness Codex, нативна Compaction thread делегується +Коли вибрана модель використовує каркас Codex, нативна Compaction потоку делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає prompt користувача, фінальний текст асистента та полегшені записи -міркувань або плану Codex, коли їх надсилає app-server. Сьогодні OpenClaw лише -записує сигнали початку та завершення нативної Compaction. Він ще не надає -людинозрозумілого зведення Compaction або придатного для аудиту списку того, які записи Codex +пошуку, `/new`, `/reset` і майбутнього перемикання моделі або каркаса. Дзеркало +включає запит користувача, фінальний текст асистента та легковагові записи +міркування або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише +записує сигнали початку та завершення нативної Compaction. Він поки не показує +людинозрозуміле зведення Compaction або придатний для аудиту список того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним thread, `tool_result_persist` наразі не -переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, +Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі +не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. -Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як +Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення проблем +## Усунення несправностей -**Codex не з’являється як звичайний провайдер `/model`:** це очікувано для +**Codex не з’являється як звичайний провайдер `/model`:** це очікувана поведінка для нових конфігурацій. Виберіть модель `openai/gpt-*` з -`agentRuntime.id: "codex"` (або застарілим посиланням `codex/*`), увімкніть +`agentRuntime.id: "codex"` (або застаріле посилання `codex/*`), увімкніть `plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує Pi замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати Pi як -бекенд сумісності, коли жоден harness Codex не бере на себе запуск. Установіть -`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Примусово -задане середовище виконання Codex тепер завершується помилкою замість переходу до Pi, якщо ви +**OpenClaw використовує PI замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати PI як +бекенд сумісності, коли жоден каркас Codex не бере на себе цей запуск. Установіть +`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Примусове +середовище виконання Codex тепер завершується помилкою замість переходу до PI, якщо ви явно не встановите `agentRuntime.fallback: "pi"`. Щойно app-server Codex -вибрано, його помилки відображаються безпосередньо без додаткової конфігурації резервного переходу. +вибрано, його помилки відображаються напряму без додаткової конфігурації запасного варіанта. -**app-server відхиляється:** оновіть Codex так, щоб handshake app-server -повідомляв версію `0.125.0` або новішу. Пререлізи тієї самої версії або версії з суфіксом збірки, -такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки -стабільний поріг протоколу `0.125.0` — це те, що тестує OpenClaw. +**App-server відхиляється:** оновіть Codex, щоб рукостискання app-server +повідомляло версію `0.125.0` або новішу. Попередні випуски тієї ж версії або версії з суфіксом збірки, +такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, тому що саме стабільний +мінімум протоколу `0.125.0` тестує OpenClaw. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і що віддалений app-server використовує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Модель не Codex використовує Pi:** це очікувано, якщо ви не примусово задали +**Модель не Codex використовує PI:** це очікувана поведінка, якщо ви не примусово встановили `agentRuntime.id: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму -звичайному шляху провайдера в режимі `auto`. Якщо ви примусово задаєте `agentRuntime.id: "codex"`, кожен вбудований -хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. +посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму нормальному +шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований +хід для цього агента має бути моделлю OpenAI, підтримуваною Codex. -## Пов’язане +**Computer Use установлено, але інструменти не запускаються:** перевірте +`/codex computer-use status` з нової сесії. Якщо інструмент повідомляє +`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не зникає, перезапустіть +gateway, щоб очистити застарілі реєстрації нативних хуків. Якщо `computer-use.list_apps` +перевищує час очікування, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. -- [Плагіни harness агента](/uk/plugins/sdk-agent-harness) -- [Середовища виконання агентів](/uk/concepts/agent-runtimes) +## Пов’язані матеріали + +- [Plugins каркаса агента](/uk/plugins/sdk-agent-harness) +- [Середовища виконання агента](/uk/concepts/agent-runtimes) - [Провайдери моделей](/uk/concepts/model-providers) - [Провайдер OpenAI](/uk/providers/openai) -- [Статус](/uk/cli/status) -- [Plugin hooks](/uk/plugins/hooks) -- [Довідник із конфігурації](/uk/gateway/configuration-reference) +- [Стан](/uk/cli/status) +- [Хуки Plugin](/uk/plugins/hooks) +- [Довідник з конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/providers/ollama.md b/docs/uk/providers/ollama.md index 21f8b7906..8520ba5bc 100644 --- a/docs/uk/providers/ollama.md +++ b/docs/uk/providers/ollama.md @@ -1,15 +1,15 @@ --- read_when: - - Ви хочете запустити OpenClaw із хмарними або локальними моделями через Ollama - - Вам потрібні вказівки з налаштування та конфігурації Ollama - - Ви хочете використовувати візійні моделі Ollama для розуміння зображень -summary: Запустіть OpenClaw з Ollama (хмарні та локальні моделі) + - Ви хочете запустити OpenClaw з хмарними або локальними моделями через Ollama + - Вам потрібні вказівки щодо налаштування та конфігурації Ollama + - Ви хочете використовувати візуальні моделі Ollama для розуміння зображень +summary: Запуск OpenClaw з Ollama (хмарні та локальні моделі) title: Ollama x-i18n: - generated_at: "2026-04-27T22:38:18Z" + generated_at: "2026-04-27T23:44:58Z" model: gpt-5.4 provider: openai - source_hash: 80cde6774a3e62a2ab4f0c41480e94d3af8f8980b21e4a29280f99ea1c2f6fb0 + source_hash: 814d7e9380e31e7f5a8db7afd9230e42979d8bb1fcaf5473dd9bb1f415a8b2ac source_path: providers/ollama.md workflow: 15 --- @@ -17,40 +17,40 @@ x-i18n: OpenClaw інтегрується з нативним API Ollama (`/api/chat`) для розміщених хмарних моделей і локальних/self-hosted серверів Ollama. Ви можете використовувати Ollama у трьох режимах: `Cloud + Local` через доступний хост Ollama, `Cloud only` проти `https://ollama.com` або `Local only` проти доступного хоста Ollama. -**Користувачі віддаленого Ollama**: не використовуйте OpenAI-сумісний URL `/v1` (`http://host:11434/v1`) з OpenClaw. Це ламає виклик інструментів, і моделі можуть виводити необроблений JSON інструментів як звичайний текст. Натомість використовуйте URL нативного API Ollama: `baseUrl: "http://host:11434"` (без `/v1`). +**Користувачі віддаленого Ollama**: Не використовуйте OpenAI-сумісну URL-адресу `/v1` (`http://host:11434/v1`) з OpenClaw. Це ламає виклик інструментів, і моделі можуть виводити сирий JSON інструментів як звичайний текст. Натомість використовуйте URL нативного API Ollama: `baseUrl: "http://host:11434"` (без `/v1`). -Конфігурація провайдера Ollama використовує `baseUrl` як канонічний ключ. OpenClaw також приймає `baseURL` для сумісності з прикладами у стилі OpenAI SDK, але в новій конфігурації слід надавати перевагу `baseUrl`. +Конфігурація провайдера Ollama використовує `baseUrl` як канонічний ключ. OpenClaw також приймає `baseURL` для сумісності з прикладами в стилі OpenAI SDK, але в новій конфігурації слід віддавати перевагу `baseUrl`. ## Правила автентифікації - - Локальні хости Ollama та хости локальної мережі не потребують справжнього bearer token. OpenClaw використовує маркер `ollama-local` лише для loopback, private-network, `.local` і URL Ollama з bare hostname. + + Локальні та LAN-хости Ollama не потребують справжнього bearer-токена. OpenClaw використовує маркер `ollama-local` лише для loopback, приватної мережі, `.local` і базових URL Ollama з простим іменем хоста. - - Віддалені публічні хости та Ollama Cloud (`https://ollama.com`) потребують справжні облікові дані через `OLLAMA_API_KEY`, профіль автентифікації або `apiKey` провайдера. + + Віддалені публічні хости та Ollama Cloud (`https://ollama.com`) потребують справжніх облікових даних через `OLLAMA_API_KEY`, профіль автентифікації або `apiKey` провайдера. - - Власні ідентифікатори провайдерів, які встановлюють `api: "ollama"`, дотримуються тих самих правил. Наприклад, провайдер `ollama-remote`, який вказує на приватний хост Ollama у локальній мережі, може використовувати `apiKey: "ollama-local"`, і субагенти розв’яжуть цей маркер через хук провайдера Ollama, а не трактуватимуть його як відсутні облікові дані. + + Користувацькі id провайдерів, які задають `api: "ollama"`, дотримуються тих самих правил. Наприклад, провайдер `ollama-remote`, який вказує на приватний LAN-хост Ollama, може використовувати `apiKey: "ollama-local"`, і субагенти розв’яжуть цей маркер через хук провайдера Ollama замість того, щоб вважати його відсутніми обліковими даними. - - Коли Ollama використовується для embeddings пам’яті, bearer-автентифікація обмежується хостом, де її було оголошено: + + Коли Ollama використовується для embedding'ів пам’яті, bearer-автентифікація обмежується хостом, де її було оголошено: - Ключ на рівні провайдера надсилається лише на хост Ollama цього провайдера. - `agents.*.memorySearch.remote.apiKey` надсилається лише на його віддалений embedding-хост. - - Чисте значення env `OLLAMA_API_KEY` вважається угодою Ollama Cloud і за замовчуванням не надсилається на локальні або self-hosted хости. + - Чисте значення змінної середовища `OLLAMA_API_KEY` трактується як угода для Ollama Cloud і за замовчуванням не надсилається на локальні або self-hosted хости. ## Початок роботи -Оберіть бажаний спосіб налаштування та режим. +Виберіть бажаний спосіб налаштування та режим. - **Найкраще для:** найшвидшого шляху до робочого налаштування Ollama Cloud або локального Ollama. + **Найкраще для:** найшвидшого шляху до робочого налаштування Ollama cloud або local. @@ -60,15 +60,15 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) Виберіть **Ollama** зі списку провайдерів. - + - **Cloud + Local** — локальний хост Ollama плюс хмарні моделі, маршрутизовані через цей хост - **Cloud only** — розміщені моделі Ollama через `https://ollama.com` - **Local only** — лише локальні моделі - `Cloud only` запитує `OLLAMA_API_KEY` і пропонує стандартні хмарні значення за замовчуванням. `Cloud + Local` і `Local only` запитують базовий URL Ollama, виявляють доступні моделі та автоматично завантажують вибрану локальну модель, якщо вона ще недоступна. Коли Ollama повідомляє про встановлений тег `:latest`, наприклад `gemma4:latest`, налаштування показує цю встановлену модель один раз замість того, щоб показувати і `gemma4`, і `gemma4:latest` або знову завантажувати псевдонім без тега. `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для доступу до хмари. + `Cloud only` запитує `OLLAMA_API_KEY` і пропонує стандартні хмарні варіанти за замовчуванням. `Cloud + Local` і `Local only` запитують базовий URL Ollama, виявляють доступні моделі та автоматично завантажують вибрану локальну модель, якщо вона ще недоступна. Коли Ollama повідомляє про встановлений тег `:latest`, наприклад `gemma4:latest`, налаштування показує цю встановлену модель один раз замість того, щоб показувати і `gemma4`, і `gemma4:latest`, або знову завантажувати псевдонім без тегу. `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для доступу до cloud. - + ```bash openclaw models list --provider ollama ``` @@ -83,7 +83,7 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) --accept-risk ``` - За бажанням вкажіть власний базовий URL або модель: + За бажанням можна вказати користувацький базовий URL або модель: ```bash openclaw onboard --non-interactive \ @@ -96,15 +96,15 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) - **Найкраще для:** повного контролю над хмарним або локальним налаштуванням. + **Найкраще для:** повного контролю над cloud або local налаштуванням. - - - **Cloud + Local**: установіть Ollama, увійдіть через `ollama signin` і маршрутизуйте хмарні запити через цей хост + + - **Cloud + Local**: встановіть Ollama, увійдіть за допомогою `ollama signin` і маршрутизуйте хмарні запити через цей хост - **Cloud only**: використовуйте `https://ollama.com` з `OLLAMA_API_KEY` - - **Local only**: установіть Ollama з [ollama.com/download](https://ollama.com/download) + - **Local only**: встановіть Ollama з [ollama.com/download](https://ollama.com/download) - + ```bash ollama pull gemma4 # або @@ -114,20 +114,20 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) ``` - Для `Cloud only` використовуйте свій справжній `OLLAMA_API_KEY`. Для конфігурацій, що працюють через хост, підійде будь-яке значення-заповнювач: + Для `Cloud only` використовуйте свій справжній `OLLAMA_API_KEY`. Для конфігурацій із хостом підійде будь-яке значення-заповнювач: ```bash - # Хмара + # Cloud export OLLAMA_API_KEY="your-ollama-api-key" - # Лише локально + # Лише local export OLLAMA_API_KEY="ollama-local" # Або налаштуйте у своєму файлі конфігурації openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -154,25 +154,25 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) - `Cloud + Local` використовує доступний хост Ollama як точку керування як для локальних, так і для хмарних моделей. Це бажаний гібридний сценарій Ollama. + `Cloud + Local` використовує доступний хост Ollama як точку керування і для локальних, і для хмарних моделей. Це рекомендований Ollama гібридний сценарій. - Під час налаштування використовуйте **Cloud + Local**. OpenClaw запитує базовий URL Ollama, виявляє локальні моделі з цього хоста та перевіряє, чи хост увійшов у систему для доступу до хмари через `ollama signin`. Якщо хост увійшов у систему, OpenClaw також пропонує розміщені хмарні значення за замовчуванням, такі як `kimi-k2.5:cloud`, `minimax-m2.7:cloud` і `glm-5.1:cloud`. + Використовуйте **Cloud + Local** під час налаштування. OpenClaw запитує базовий URL Ollama, виявляє локальні моделі на цьому хості та перевіряє, чи хост увійшов у систему для cloud-доступу за допомогою `ollama signin`. Якщо хост увійшов у систему, OpenClaw також пропонує хмарні варіанти за замовчуванням, такі як `kimi-k2.5:cloud`, `minimax-m2.7:cloud` і `glm-5.1:cloud`. - Якщо хост іще не увійшов у систему, OpenClaw зберігає налаштування лише локальним, доки ви не виконаєте `ollama signin`. + Якщо хост ще не увійшов у систему, OpenClaw залишає налаштування в режимі лише local, доки ви не виконаєте `ollama signin`. - `Cloud only` працює через розміщений API Ollama за адресою `https://ollama.com`. + `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 повертається до попередніх жорстко закодованих пропозицій, щоб onboarding усе одно завершився. + Список cloud-моделей, який показується під час `openclaw onboard`, заповнюється в реальному часі з `https://ollama.com/api/tags`, з обмеженням до 500 записів, тому засіб вибору відображає поточний розміщений каталог, а не статичний початковий список. Якщо `ollama.com` недоступний або не повертає моделей під час налаштування, OpenClaw повертається до попередніх жорстко закодованих рекомендацій, щоб onboarding усе одно завершився. - У режимі лише локального використання OpenClaw виявляє моделі з налаштованого екземпляра Ollama. Цей шлях призначений для локальних або self-hosted серверів Ollama. + У режимі лише local OpenClaw виявляє моделі з налаштованого екземпляра Ollama. Цей шлях призначений для локальних або self-hosted серверів Ollama. Наразі OpenClaw пропонує `gemma4` як локальне значення за замовчуванням. @@ -181,26 +181,26 @@ OpenClaw інтегрується з нативним API Ollama (`/api/chat`) ## Виявлення моделей (неявний провайдер) -Коли ви встановлюєте `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 автоматично додає зображення до prompt | -| Виявлення reasoning | Позначає `reasoning` за допомогою евристики назви моделі (`r1`, `reasoning`, `think`) | -| Ліміти токенів | Установлює `maxTokens` на стандартне обмеження максимальних токенів Ollama, яке використовує OpenClaw | -| Вартість | Установлює всі вартості в `0` | +| Поведінка | Докладно | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Запит каталогу | Виконує запити до `/api/tags` | +| Виявлення можливостей | Використовує найкращі спроби запитів до `/api/show`, щоб зчитати `contextWindow`, розгорнуті параметри Modelfile `num_ctx` і можливості, зокрема vision/tools | +| Візуальні моделі | Моделі з можливістю `vision`, про яку повідомляє `/api/show`, позначаються як сумісні із зображеннями (`input: ["text", "image"]`), тому OpenClaw автоматично вставляє зображення в prompt | +| Виявлення reasoning | Позначає `reasoning` за допомогою евристики за назвою моделі (`r1`, `reasoning`, `think`) | +| Ліміти токенів | Встановлює `maxTokens` на стандартне обмеження максимальної кількості токенів Ollama, яке використовує OpenClaw | +| Вартість | Встановлює всі вартості в `0` | -Це дає змогу уникнути ручного додавання моделей, водночас зберігаючи каталог узгодженим із локальним екземпляром Ollama. Ви можете використовувати повне посилання, наприклад `ollama/:latest`, у локальному `infer model run`; OpenClaw розв’язує цю встановлену модель із живого каталогу Ollama без потреби в рукописному записі `models.json`. +Це дозволяє уникнути ручного додавання моделей, зберігаючи каталог узгодженим із локальним екземпляром Ollama. Ви можете використовувати повне посилання, наприклад `ollama/:latest`, у локальному `infer model run`; OpenClaw розв’язує цю встановлену модель із живого каталогу Ollama без потреби у вручну написаному записі `models.json`. ```bash -# Переглянути доступні моделі +# Перегляньте, які моделі доступні ollama list openclaw models list ``` -Для вузької smoke-перевірки генерації тексту, яка уникає повної поверхні інструментів агента, +Для вузького smoke-тесту генерації тексту, який обходить повну поверхню інструментів агента, використовуйте локальний `infer model run` із повним посиланням на модель Ollama: ```bash @@ -212,12 +212,11 @@ OLLAMA_API_KEY=ollama-local \ --json ``` -Цей шлях і далі використовує налаштований у OpenClaw провайдер, автентифікацію та нативний транспорт Ollama, але не запускає хід chat-agent і не завантажує контекст MCP/інструментів. Якщо це працює, а звичайні відповіді агента — ні, далі усувайте несправності можливостей моделі щодо агентних prompt/інструментів. +Цей шлях усе ще використовує налаштований у OpenClaw провайдер, автентифікацію та нативний транспорт Ollama, але не запускає хід chat-агента й не завантажує контекст MCP/tool. Якщо це спрацьовує, а звичайні відповіді агента — ні, далі слід діагностувати здатність моделі працювати з агентськими prompt/tool. -Коли ви перемикаєте розмову через `/model ollama/`, OpenClaw трактує це як точний вибір користувача. Якщо налаштований `baseUrl` Ollama недоступний, наступна відповідь завершується помилкою провайдера замість того, щоб мовчки відповідати з іншої налаштованої резервної моделі. +Коли ви перемикаєте розмову за допомогою `/model ollama/`, OpenClaw трактує це як точний вибір користувача. Якщо налаштований `baseUrl` Ollama недоступний, наступна відповідь завершиться помилкою провайдера замість того, щоб мовчки відповісти з іншої налаштованої резервної моделі. -Щоб виконати живу перевірку локального текстового шляху, нативного stream-шляху й embeddings -проти локального Ollama, використайте: +Виконайте живу перевірку локального текстового шляху, шляху нативного stream і embedding'ів із локальним Ollama за допомогою: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \ @@ -233,12 +232,12 @@ ollama pull mistral Нова модель буде автоматично виявлена й стане доступною для використання. -Якщо ви явно встановлюєте `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`, усе одно вважаються локальними. Дивіться розділ про явну конфігурацію нижче. ## Vision і опис зображень -Убудований Plugin Ollama реєструє Ollama як провайдера розуміння медіа, що підтримує зображення. Це дозволяє OpenClaw маршрутизувати явні запити на опис зображень і налаштовані значення image-model за замовчуванням через локальні або розміщені візійні моделі Ollama. +Вбудований Plugin Ollama реєструє Ollama як провайдера розуміння медіа, сумісного із зображеннями. Це дозволяє OpenClaw маршрутизувати явні запити на опис зображень і налаштовані значення image-model за замовчуванням через локальні або розміщені візуальні моделі Ollama. Для локального vision завантажте модель, яка підтримує зображення: @@ -247,7 +246,7 @@ ollama pull qwen2.5vl:7b export OLLAMA_API_KEY="ollama-local" ``` -Потім перевірте через CLI infer: +Потім перевірте через infer CLI: ```bash openclaw infer image describe \ @@ -256,7 +255,7 @@ openclaw infer image describe \ --json ``` -`--model` має бути повним посиланням у форматі ``. Коли його встановлено, `openclaw infer image describe` запускає цю модель безпосередньо замість того, щоб пропускати опис, оскільки модель підтримує нативне vision. +`--model` має бути повним посиланням у форматі ``. Якщо його задано, `openclaw infer image describe` запускає цю модель напряму замість того, щоб пропускати опис, оскільки модель підтримує нативний vision. Щоб зробити Ollama моделлю розуміння зображень за замовчуванням для вхідних медіа, налаштуйте `agents.defaults.imageModel`: @@ -272,7 +271,7 @@ openclaw infer image describe \ } ``` -Повільним локальним vision-моделям може знадобитися довший тайм-аут на розуміння зображень, ніж хмарним моделям. Вони також можуть аварійно завершуватися або зупинятися, коли Ollama намагається виділити весь заявлений vision-контекст на обладнанні з обмеженими ресурсами. Установіть тайм-аут для цієї можливості й обмежте `num_ctx` у записі моделі, коли вам потрібен лише звичайний хід опису зображення: +Повільним локальним vision-моделям може знадобитися довший таймаут для розуміння зображень, ніж хмарним моделям. Вони також можуть аварійно завершуватися або зупинятися, коли Ollama намагається виділити весь заявлений vision-контекст на обладнанні з обмеженими ресурсами. Установіть таймаут можливості та обмежте `num_ctx` у записі моделі, якщо вам потрібен лише звичайний хід опису зображення: ```json5 { @@ -301,16 +300,16 @@ openclaw infer image describe \ } ``` -Цей тайм-аут застосовується до вхідного розуміння зображень і до явного інструмента `image`, який агент може викликати під час ходу. `models.providers.ollama.timeoutSeconds` на рівні провайдера, як і раніше, керує базовим захистом HTTP-запиту Ollama для звичайних викликів моделі. +Цей таймаут застосовується до вхідного розуміння зображень і до явного інструмента `image`, який агент може викликати під час ходу. `models.providers.ollama.timeoutSeconds` на рівні провайдера, як і раніше, керує базовим захистом HTTP-запиту Ollama для звичайних викликів моделі. -Щоб виконати живу перевірку явного інструмента зображень проти локального Ollama, використайте: +Виконайте живу перевірку явного інструмента зображень із локальним 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` вручну, позначайте vision-моделі як такі, що підтримують вхідні зображення: +Якщо ви визначаєте `models.providers.ollama.models` вручну, позначайте vision-моделі як такі, що підтримують вхід зображень: ```json5 { @@ -322,26 +321,26 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \ } ``` -OpenClaw відхиляє запити на опис зображень для моделей, які не позначені як здатні працювати із зображеннями. За неявного виявлення OpenClaw читає це з Ollama, коли `/api/show` повідомляє про можливість vision. +OpenClaw відхиляє запити на опис зображень для моделей, які не позначені як сумісні із зображеннями. За неявного виявлення OpenClaw зчитує це з Ollama, коли `/api/show` повідомляє про можливість vision. ## Конфігурація - Найпростіший шлях увімкнення режиму лише локального використання — через змінну середовища: + Найпростіший шлях увімкнення лише local — через змінну середовища: ```bash export OLLAMA_API_KEY="ollama-local" ``` - Якщо `OLLAMA_API_KEY` встановлено, ви можете не вказувати `apiKey` у записі провайдера, і OpenClaw підставить його для перевірок доступності. + Якщо задано `OLLAMA_API_KEY`, ви можете не вказувати `apiKey` у записі провайдера, і OpenClaw підставить його для перевірок доступності. - Використовуйте явну конфігурацію, коли вам потрібне розміщене хмарне налаштування, Ollama працює на іншому хості/порту, ви хочете примусово встановити певні вікна контексту або списки моделей, або вам потрібні повністю ручні визначення моделей. + Використовуйте явну конфігурацію, коли вам потрібне налаштування hosted cloud, Ollama працює на іншому хості/порту, ви хочете примусово задати конкретні вікна контексту або списки моделей, або вам потрібні повністю ручні визначення моделей. ```json5 { @@ -370,8 +369,8 @@ OpenClaw відхиляє запити на опис зображень для - - Якщо Ollama працює на іншому хості або порту (явна конфігурація вимикає автоматичне виявлення, тому визначайте моделі вручну): + + Якщо Ollama працює на іншому хості або порту (явна конфігурація вимикає автовиявлення, тому визначайте моделі вручну): ```json5 { @@ -380,8 +379,8 @@ OpenClaw відхиляє запити на опис зображень для ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434", // Без /v1 — використовуйте URL нативного API Ollama - api: "ollama", // Укажіть явно, щоб гарантувати нативну поведінку виклику інструментів - timeoutSeconds: 300, // Необов’язково: дайте холодним локальним моделям більше часу на підключення й stream + api: "ollama", // Явно задайте для гарантованої нативної поведінки виклику інструментів + timeoutSeconds: 300, // Необов’язково: дайте холодним локальним моделям більше часу на підключення та stream models: [ { id: "qwen3:32b", @@ -404,12 +403,12 @@ OpenClaw відхиляє запити на опис зображень для -## Поширені рецепти +## Типові рецепти -Використовуйте їх як відправні точки й замінюйте ідентифікатори моделей на точні назви з `ollama list` або `openclaw models list --provider ollama`. +Використовуйте їх як відправні точки й замінюйте id моделей на точні назви з `ollama list` або `openclaw models list --provider ollama`. - + Використовуйте це, коли Ollama працює на тій самій машині, що й Gateway, і ви хочете, щоб OpenClaw автоматично виявляв установлені моделі. ```bash @@ -424,8 +423,8 @@ OpenClaw відхиляє запити на опис зображень для - - Для хостів локальної мережі використовуйте нативні URL Ollama. Не додавайте `/v1`. + + Для LAN-хостів використовуйте нативні URL Ollama. Не додавайте `/v1`. ```json5 { @@ -462,7 +461,7 @@ OpenClaw відхиляє запити на опис зображень для } ``` - `contextWindow` — це бюджет контексту на боці OpenClaw. `params.num_ctx` надсилається до Ollama для запиту. Тримайте їх узгодженими, коли ваше обладнання не може працювати з повним заявленим контекстом моделі. + `contextWindow` — це бюджет контексту на боці OpenClaw. `params.num_ctx` надсилається в Ollama для запиту. Узгоджуйте їх, коли ваше обладнання не може працювати з повним заявленим контекстом моделі. @@ -504,8 +503,8 @@ OpenClaw відхиляє запити на опис зображень для - - Використовуйте це, коли локальний daemon Ollama або daemon у локальній мережі увійшов через `ollama signin` і має обслуговувати як локальні моделі, так і моделі `:cloud`. + + Використовуйте це, коли локальний або LAN daemon Ollama увійшов у систему через `ollama signin` і має обслуговувати і локальні моделі, і моделі `:cloud`. ```bash ollama signin @@ -542,7 +541,7 @@ OpenClaw відхиляє запити на опис зображень для - Використовуйте власні ідентифікатори провайдерів, коли у вас більше ніж один сервер Ollama. Кожен провайдер отримує власний хост, моделі, автентифікацію, тайм-аут і посилання на моделі. + Використовуйте користувацькі id провайдерів, коли у вас більше ніж один сервер Ollama. Кожен провайдер отримує власні хост, моделі, автентифікацію, таймаут і посилання на моделі. ```json5 { @@ -577,12 +576,12 @@ OpenClaw відхиляє запити на опис зображень для } ``` - Коли OpenClaw надсилає запит, префікс активного провайдера прибирається, тож `ollama-large/qwen3.5:27b` потрапляє до Ollama як `qwen3.5:27b`. + Коли OpenClaw надсилає запит, активний префікс провайдера прибирається, тож `ollama-large/qwen3.5:27b` надходить до Ollama як `qwen3.5:27b`. - Деякі локальні моделі можуть відповідати на прості prompt, але погано справляються з повною поверхнею інструментів агента. Почніть з обмеження інструментів і контексту, перш ніж змінювати глобальні налаштування runtime. + Деякі локальні моделі можуть відповідати на прості запити, але мати труднощі з повною поверхнею інструментів агента. Почніть з обмеження інструментів і контексту, перш ніж змінювати глобальні налаштування runtime. ```json5 { @@ -616,15 +615,15 @@ OpenClaw відхиляє запити на опис зображень для } ``` - Використовуйте `compat.supportsTools: false` лише тоді, коли модель або сервер стабільно не справляється зі схемами інструментів. Це обмінює можливості агента на стабільність. - `localModelLean` прибирає browser, Cron і message-інструменти з поверхні агента, але не змінює runtime-контекст Ollama чи режим thinking. Поєднуйте його з явними `params.num_ctx` і `params.thinking: false` для невеликих thinking-моделей у стилі Qwen, які зациклюються або витрачають бюджет відповіді на приховане reasoning. + Використовуйте `compat.supportsTools: false` лише тоді, коли модель або сервер стабільно не справляються зі схемами інструментів. Це обмінює можливості агента на стабільність. + `localModelLean` прибирає browser, cron і message tools з поверхні агента, але не змінює runtime-контекст Ollama або режим thinking. Поєднуйте це з явними `params.num_ctx` і `params.thinking: false` для невеликих thinking-моделей у стилі Qwen, які зациклюються або витрачають бюджет відповіді на приховане reasoning. ### Вибір моделі -Після налаштування всі ваші моделі Ollama будуть доступні: +Після налаштування всі ваші моделі Ollama доступні: ```json5 { @@ -639,12 +638,12 @@ OpenClaw відхиляє запити на опис зображень для } ``` -Також підтримуються власні ідентифікатори провайдерів Ollama. Коли посилання -на модель використовує префікс активного провайдера, наприклад `ollama-spark/qwen3:32b`, -OpenClaw прибирає лише цей префікс перед викликом Ollama, тож сервер отримує `qwen3:32b`. +Також підтримуються користувацькі id провайдерів Ollama. Коли посилання на модель використовує активний +префікс провайдера, наприклад `ollama-spark/qwen3:32b`, OpenClaw прибирає лише цей +префікс перед викликом Ollama, щоб сервер отримав `qwen3:32b`. -Для повільних локальних моделей надавайте перевагу налаштуванню запитів у межах провайдера, перш ніж підвищувати -тайм-аут усього runtime агента: +Для повільних локальних моделей віддавайте перевагу налаштуванню запитів на рівні провайдера перед збільшенням +таймауту runtime всього агента: ```json5 { @@ -665,40 +664,40 @@ OpenClaw прибирає лише цей префікс перед виклик } ``` -`timeoutSeconds` застосовується до HTTP-запиту моделі, включно з налаштуванням з’єднання, -заголовками, stream-передачею тіла й загальним перериванням guarded-fetch. `params.keep_alive` -передається до Ollama як `keep_alive` верхнього рівня в нативних запитах `/api/chat`; -установлюйте його для кожної моделі, коли вузьким місцем є час завантаження на першому ході. +`timeoutSeconds` застосовується до HTTP-запиту моделі, включно з установленням з’єднання, +заголовками, stream тіла та повним перериванням guarded-fetch. `params.keep_alive` +передається в Ollama як `keep_alive` верхнього рівня в нативних запитах `/api/chat`; +задавайте це для кожної моделі, коли вузьким місцем є час завантаження першого ходу. ### Швидка перевірка ```bash -# Daemon Ollama доступний для цієї машини +# Ollama daemon видимий для цієї машини curl http://127.0.0.1:11434/api/tags # Каталог OpenClaw і вибрана модель openclaw models list --provider ollama openclaw models status -# Пряма smoke-перевірка моделі +# Прямий 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`. +OpenClaw підтримує **Ollama Web Search** як вбудований провайдер `web_search`. -| Властивість | Деталі | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Хост | Використовує налаштований вами хост 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 | +| Властивість | Докладно | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Хост | Використовує налаштований вами хост Ollama (`models.providers.ollama.baseUrl`, якщо задано, інакше `http://127.0.0.1:11434`); `https://ollama.com` використовує hosted API напряму | +| Автентифікація | Без ключа для локальних хостів Ollama з виконаним входом; `OLLAMA_API_KEY` або налаштована автентифікація провайдера для прямого пошуку через `https://ollama.com` або хостів із захищеною автентифікацією | +| Вимога | Локальні/self-hosted хости мають працювати та бути авторизованими через `ollama signin`; прямий hosted-пошук вимагає `baseUrl: "https://ollama.com"` плюс справжній ключ API Ollama | -Виберіть **Ollama Web Search** під час `openclaw onboard` або `openclaw configure --section web`, або встановіть: +Виберіть **Ollama Web Search** під час `openclaw onboard` або `openclaw configure --section web`, або задайте: ```json5 { @@ -712,7 +711,7 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` -Для прямого розміщеного пошуку через Ollama Cloud: +Для прямого hosted-пошуку через Ollama Cloud: ```json5 { @@ -734,10 +733,10 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` -Для локального daemon, у який виконано вхід, OpenClaw використовує проксі `/api/experimental/web_search` цього daemon. Для `https://ollama.com` він напряму викликає розміщену кінцеву точку `/api/web_search`. +Для локального daemon з виконаним входом OpenClaw використовує проксі daemon через `/api/experimental/web_search`. Для `https://ollama.com` він напряму викликає hosted endpoint `/api/web_search`. -Повні відомості про налаштування й поведінку див. у [Ollama Web Search](/uk/tools/ollama-search). +Повні відомості про налаштування та поведінку дивіться в [Ollama Web Search](/uk/tools/ollama-search). ## Розширена конфігурація @@ -745,10 +744,10 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр - **Виклик інструментів в OpenAI-сумісному режимі ненадійний.** Використовуйте цей режим лише тоді, коли вам потрібен формат OpenAI для проксі й ви не залежите від нативної поведінки виклику інструментів. + **Виклик інструментів у OpenAI-сумісному режимі ненадійний.** Використовуйте цей режим лише якщо вам потрібен формат OpenAI для проксі й ви не залежите від нативної поведінки виклику інструментів. - Якщо вам потрібно використовувати натомість OpenAI-сумісну кінцеву точку (наприклад, за проксі, який підтримує лише формат OpenAI), явно встановіть `api: "openai-completions"`: + Якщо вам потрібно натомість використовувати OpenAI-сумісний endpoint (наприклад, за проксі, який підтримує лише формат OpenAI), явно задайте `api: "openai-completions"`: ```json5 { @@ -757,7 +756,7 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", - injectNumCtxForOpenAICompat: true, // за замовчуванням: true + injectNumCtxForOpenAICompat: true, // default: true apiKey: "ollama-local", models: [...] } @@ -766,9 +765,9 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - У цьому режимі може не підтримуватися одночасно streaming і виклик інструментів. Можливо, вам доведеться вимкнути streaming через `params: { streaming: false }` у конфігурації моделі. + Цей режим може не підтримувати одночасно streaming і виклик інструментів. Може знадобитися вимкнути streaming через `params: { streaming: false }` у конфігурації моделі. - Коли `api: "openai-completions"` використовується з Ollama, OpenClaw за замовчуванням додає `options.num_ctx`, щоб Ollama не переходив мовчки до контекстного вікна 4096. Якщо ваш проксі/upstream відхиляє невідомі поля `options`, вимкніть цю поведінку: + Коли з Ollama використовується `api: "openai-completions"`, OpenClaw за замовчуванням додає `options.num_ctx`, щоб Ollama мовчки не повертався до вікна контексту 4096. Якщо ваш проксі/upstream відхиляє невідомі поля `options`, вимкніть цю поведінку: ```json5 { @@ -789,11 +788,11 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр - Для моделей, виявлених автоматично, OpenClaw використовує контекстне вікно, про яке повідомляє Ollama, коли воно доступне, включно з більшими значеннями `PARAMETER num_ctx` із власних Modelfile. Інакше він повертається до стандартного контекстного вікна Ollama, яке використовує OpenClaw. + Для автовиявлених моделей OpenClaw використовує вікно контексту, яке повідомляє Ollama, якщо воно доступне, зокрема більші значення `PARAMETER num_ctx` з користувацьких Modelfile. Інакше він повертається до типового вікна контексту Ollama, яке використовує OpenClaw. - Ви можете встановити типові значення `contextWindow`, `contextTokens` і `maxTokens` на рівні провайдера для кожної моделі в цьому провайдері Ollama, а потім за потреби перевизначати їх для окремих моделей. `contextWindow` — це бюджет prompt і Compaction у OpenClaw. У нативних запитах Ollama `options.num_ctx` залишається не встановленим, якщо ви явно не налаштуєте `params.num_ctx`, щоб Ollama міг застосувати власні типові значення моделі, `OLLAMA_CONTEXT_LENGTH` або значення на основі VRAM. Щоб обмежити або примусово встановити контекст runtime Ollama для окремого запиту без перебудови Modelfile, установіть `params.num_ctx`; некоректні, нульові, від’ємні й нескінченні значення ігноруються. OpenAI-сумісний адаптер Ollama, як і раніше, за замовчуванням додає `options.num_ctx` із налаштованих `params.num_ctx` або `contextWindow`; вимкніть це через `injectNumCtxForOpenAICompat: false`, якщо ваш upstream відхиляє `options`. + Ви можете задати значення за замовчуванням `contextWindow`, `contextTokens` і `maxTokens` на рівні провайдера для кожної моделі під цим провайдером Ollama, а потім перевизначити їх для окремих моделей за потреби. `contextWindow` — це бюджет prompt і Compaction у OpenClaw. Нативні запити Ollama залишають `options.num_ctx` незаданим, якщо ви явно не налаштуєте `params.num_ctx`, щоб Ollama міг застосувати власне значення за замовчуванням моделі, `OLLAMA_CONTEXT_LENGTH` або значення на основі VRAM. Щоб обмежити або примусово задати контекст runtime на запит в Ollama без перебудови Modelfile, установіть `params.num_ctx`; невалідні, нульові, від’ємні та нескінченні значення ігноруються. OpenAI-сумісний адаптер Ollama, як і раніше, за замовчуванням додає `options.num_ctx` із налаштованого `params.num_ctx` або `contextWindow`; вимкніть це через `injectNumCtxForOpenAICompat: false`, якщо ваш upstream відхиляє `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`, щоб надіслати top-level `think` Ollama; `false` вимикає thinking на рівні API для thinking-моделей у стилі Qwen. + Записи нативних моделей 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. ```json5 { @@ -820,19 +819,19 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - `agents.defaults.models["ollama/"].params.num_ctx` для окремої моделі теж працює. Якщо налаштовано обидва варіанти, явний запис моделі провайдера має пріоритет над типовим значенням агента. + `agents.defaults.models["ollama/"].params.num_ctx` для окремої моделі теж працює. Якщо налаштовано обидва варіанти, явний запис моделі провайдера має пріоритет над значенням за замовчуванням агента. - Для нативних моделей Ollama OpenClaw пересилає керування thinking так, як цього очікує Ollama: top-level `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 { @@ -848,51 +847,39 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - `params.think` або `params.thinking` для окремої моделі можуть вимкнути або примусово встановити thinking API Ollama для конкретної налаштованої моделі. Команди runtime, як-от `/think off`, усе одно застосовуються до активного запуску. + `params.think` або `params.thinking` для окремої моделі можуть вимкнути або примусово ввімкнути thinking API Ollama для конкретної налаштованої моделі. Команди runtime, такі як `/think off`, однаково застосовуються до активного запуску. - - OpenClaw за замовчуванням вважає моделі з назвами на кшталт `deepseek-r1`, `reasoning` або `think` здатними до reasoning. + + OpenClaw за замовчуванням вважає моделі з назвами на кшталт `deepseek-r1`, `reasoning` або `think` сумісними з reasoning. ```bash ollama pull deepseek-r1:32b ``` - Жодної додаткової конфігурації не потрібно. OpenClaw позначає їх автоматично. + Додаткова конфігурація не потрібна. OpenClaw позначає їх автоматично. - Ollama безплатний і працює локально, тому вартість усіх моделей встановлено на рівні $0. Це стосується як моделей, виявлених автоматично, так і моделей, визначених вручну. + Ollama є безплатним і працює локально, тому вартість усіх моделей встановлена на рівні $0. Це стосується як автовиявлених, так і вручну визначених моделей. - - Убудований Plugin Ollama реєструє провайдера embeddings пам’яті для - [пошуку в пам’яті](/uk/concepts/memory). Він використовує налаштовані базовий URL Ollama - і ключ API, викликає поточну кінцеву точку Ollama `/api/embed` та пакетно - обробляє кілька фрагментів пам’яті в одному запиті `input`, коли це можливо. + + Вбудований Plugin Ollama реєструє провайдера embedding'ів пам’яті для + [пошуку в пам’яті](/uk/concepts/memory). Він використовує налаштовані базовий URL + та API-ключ Ollama, викликає поточний endpoint Ollama `/api/embed` і групує + кілька фрагментів пам’яті в один запит `input`, коли це можливо. - | Властивість | Значення | - | ----------------- | ------------------- | + | Властивість | Значення | + | --------------- | ------------------- | | Модель за замовчуванням | `nomic-embed-text` | - | Автоматичне завантаження | Так — embedding-модель автоматично завантажується, якщо її немає локально | + | Auto-pull | Так — embedding-модель автоматично завантажується локально, якщо її немає | - Embeddings під час запиту використовують retrieval-префікси для моделей, які їх потребують або рекомендують, зокрема `nomic-embed-text`, `qwen3-embedding` і `mxbai-embed-large`. Пакети документів пам’яті залишаються сирими, тому наявним індексам не потрібна міграція формату. + Embedding'и під час запиту використовують retrieval-префікси для моделей, які їх вимагають або рекомендують, зокрема `nomic-embed-text`, `qwen3-embedding` і `mxbai-embed-large`. Пакети документів пам’яті залишаються сирими, тож наявним індексам не потрібна міграція формату. - Щоб вибрати Ollama як провайдера embeddings для пошуку в пам’яті: - - ```json5 - { - agents: { - defaults: { - memorySearch: { provider: "ollama" }, - }, - }, - } - ``` - - Для віддаленого embedding-хоста зберігайте автентифікацію в межах цього хоста: + Щоб вибрати Ollama як провайдера embedding'ів для пошуку в пам’яті: ```json5 { @@ -900,10 +887,29 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр defaults: { memorySearch: { provider: "ollama", + remote: { + // Default for Ollama. Raise on larger hosts if reindexing is too slow. + nonBatchConcurrency: 1, + }, + }, + }, + }, + } + ``` + + Для віддаленого embedding-хоста обмежуйте автентифікацію цим хостом: + + ```json5 + { + agents: { + defaults: { + memorySearch: { + provider: "ollama", + model: "nomic-embed-text", remote: { baseUrl: "http://gpu-box.local:11434", - model: "nomic-embed-text", apiKey: "ollama-local", + nonBatchConcurrency: 2, }, }, }, @@ -916,20 +922,20 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр Інтеграція Ollama в OpenClaw за замовчуванням використовує **нативний API Ollama** (`/api/chat`), який повністю підтримує одночасно streaming і виклик інструментів. Жодної спеціальної конфігурації не потрібно. - Для нативних запитів `/api/chat` OpenClaw також напряму передає керування thinking до Ollama: `/think off` і `openclaw agent --thinking off` надсилають top-level `think: false`, тоді як `/think low|medium|high` надсилають відповідний рядок зусилля top-level `think`. `/think max` відображається на найвищий нативний рівень зусиль 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"`. - Якщо вам потрібно використовувати OpenAI-сумісну кінцеву точку, див. розділ «Застарілий OpenAI-сумісний режим» вище. У цьому режимі streaming і виклик інструментів можуть не працювати одночасно. + Якщо вам потрібно використовувати OpenAI-сумісний endpoint, дивіться розділ «Застарілий OpenAI-сумісний режим» вище. У цьому режимі streaming і виклик інструментів можуть не працювати одночасно. -## Усунення несправностей +## Усунення проблем - У WSL2 з NVIDIA/CUDA офіційний інсталятор Ollama для Linux створює systemd-юніт `ollama.service` з `Restart=always`. Якщо цей сервіс автоматично запускається і завантажує модель з підтримкою GPU під час завантаження WSL2, Ollama може зафіксувати пам’ять хоста під час завантаження моделі. Механізм повернення пам’яті Hyper-V не завжди може повернути ці зафіксовані сторінки, тому Windows може завершити роботу віртуальної машини WSL2, systemd знову запустить Ollama — і цикл повториться. + У WSL2 з NVIDIA/CUDA офіційний інсталятор Ollama для Linux створює systemd unit `ollama.service` з `Restart=always`. Якщо цей сервіс автозапускається й завантажує модель з підтримкою GPU під час завантаження WSL2, Ollama може закріпити пам’ять хоста під час завантаження моделі. Hyper-V не завжди може вивільнити ці закріплені сторінки, тому Windows може завершити роботу ВМ WSL2, systemd знову запускає Ollama — і цикл повторюється. Типові ознаки: @@ -952,25 +958,25 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр autoMemoryReclaim=disabled ``` - Установіть коротший keep-alive у середовищі сервісу Ollama або запускайте Ollama вручну лише тоді, коли він вам потрібен: + Задайте коротший keep-alive у середовищі сервісу Ollama або запускайте Ollama вручну лише тоді, коли він вам потрібен: ```bash export OLLAMA_KEEP_ALIVE=5m ollama serve ``` - Див. [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317). + Дивіться [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317). - Переконайтеся, що Ollama запущено, що ви встановили `OLLAMA_API_KEY` (або профіль автентифікації), і що ви **не** визначили явний запис `models.providers.ollama`: + Переконайтеся, що Ollama запущено, що ви задали `OLLAMA_API_KEY` (або профіль автентифікації) і що ви **не** визначили явний запис `models.providers.ollama`: ```bash ollama serve ``` - Перевірте, що API доступний: + Переконайтеся, що API доступний: ```bash curl http://localhost:11434/api/tags @@ -979,7 +985,7 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр - Якщо вашої моделі немає в списку, або завантажте модель локально, або визначте її явно в `models.providers.ollama`. + Якщо вашої моделі немає у списку, або завантажте її локально, або явно визначте її в `models.providers.ollama`. ```bash ollama list # Переглянути, що встановлено @@ -990,7 +996,7 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр - + Перевірте, що Ollama працює на правильному порту: ```bash @@ -1004,26 +1010,26 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр - Перевірте з тієї самої машини й у тому самому runtime, де працює Gateway: + Перевірте з тієї самої машини й того самого runtime, де працює Gateway: ```bash openclaw gateway status --deep curl http://ollama-host:11434/api/tags ``` - Типові причини: + Поширені причини: - `baseUrl` вказує на `localhost`, але Gateway працює в Docker або на іншому хості. - URL використовує `/v1`, що вибирає OpenAI-сумісну поведінку замість нативного Ollama. - - Для віддаленого хоста потрібні зміни firewall або прив’язки до локальної мережі на боці Ollama. - - Модель присутня в daemon на вашому ноутбуці, але відсутня у віддаленому daemon. + - Віддаленому хосту потрібні зміни firewall або LAN-прив’язки на боці Ollama. + - Модель є в daemon на вашому ноутбуці, але відсутня у віддаленому daemon. Зазвичай це означає, що провайдер використовує OpenAI-сумісний режим або модель не може працювати зі схемами інструментів. - Надавайте перевагу нативному режиму Ollama: + Віддавайте перевагу нативному режиму Ollama: ```json5 { @@ -1038,12 +1044,12 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - Якщо невелика локальна модель і далі не справляється зі схемами інструментів, установіть `compat.supportsTools: false` у записі цієї моделі й перевірте знову. + Якщо невелика локальна модель усе ще не справляється зі схемами інструментів, задайте `compat.supportsTools: false` у записі цієї моделі та перевірте знову. - - Великим локальним моделям може знадобитися тривале початкове завантаження до початку streaming. Залишайте тайм-аут обмеженим провайдером Ollama й за бажанням попросіть Ollama тримати модель завантаженою між ходами: + + Великим локальним моделям може знадобитися довге перше завантаження, перш ніж почнеться streaming. Залишайте таймаут у межах провайдера Ollama і, за бажанням, попросіть Ollama тримати модель завантаженою між ходами: ```json5 { @@ -1064,12 +1070,12 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - Якщо сам хост повільно приймає з’єднання, `timeoutSeconds` також подовжує захищений тайм-аут підключення Undici для цього провайдера. + Якщо сам хост повільно приймає з’єднання, `timeoutSeconds` також подовжує захищений таймаут підключення Undici для цього провайдера. - Багато моделей Ollama заявляють контексти, які перевищують можливості вашого обладнання для комфортної роботи. Нативний Ollama використовує власний типовий runtime-контекст Ollama, якщо ви не встановите `params.num_ctx`. Обмежте як бюджет OpenClaw, так і контекст запиту Ollama, якщо вам потрібна передбачувана затримка до першого токена: + Багато моделей Ollama заявляють контекст, більший за той, який ваше обладнання може комфортно обробити. Нативний Ollama використовує власне значення контексту runtime за замовчуванням, якщо ви не задаєте `params.num_ctx`. Обмежуйте і бюджет OpenClaw, і контекст запиту Ollama, якщо хочете передбачувану затримку до першого токена: ```json5 { @@ -1091,28 +1097,28 @@ OpenClaw підтримує **Ollama Web Search** як убудований пр } ``` - Спочатку зменшуйте `contextWindow`, якщо OpenClaw надсилає надто великий prompt. Зменшуйте `params.num_ctx`, якщо Ollama завантажує runtime-контекст, який завеликий для машини. Зменшуйте `maxTokens`, якщо генерація триває надто довго. + Спочатку зменшуйте `contextWindow`, якщо OpenClaw надсилає занадто великий prompt. Зменшуйте `params.num_ctx`, якщо Ollama завантажує runtime-контекст, який завеликий для машини. Зменшуйте `maxTokens`, якщо генерація триває занадто довго. -Більше допомоги: [Усунення несправностей](/uk/help/troubleshooting) і [FAQ](/uk/help/faq). +Більше допомоги: [Усунення проблем](/uk/help/troubleshooting) і [FAQ](/uk/help/faq). -## Пов’язано +## Пов’язане - Огляд усіх провайдерів, посилань на моделі й поведінки failover. + Огляд усіх провайдерів, посилань на моделі та поведінки failover. - Як вибирати й налаштовувати моделі. + Як вибирати та налаштовувати моделі. - Повні відомості про налаштування й поведінку вебпошуку на базі Ollama. + Повні відомості про налаштування та поведінку для вебпошуку на базі Ollama. - Повний довідник конфігурації. + Повний довідник з конфігурації. diff --git a/docs/uk/reference/memory-config.md b/docs/uk/reference/memory-config.md index 3b083254d..bed5be3c4 100644 --- a/docs/uk/reference/memory-config.md +++ b/docs/uk/reference/memory-config.md @@ -1,17 +1,17 @@ --- read_when: - - Ви хочете налаштувати провайдерів пошуку в пам’яті або моделі embedding - - Ви хочете налаштувати backend QMD - - Ви хочете налаштувати hybrid search, MMR або temporal decay - - Ви хочете увімкнути multimodal indexing пам’яті + - Ви хочете налаштувати провайдерів пошуку в пам’яті або моделі ембедингів + - Ви хочете налаштувати бекенд QMD + - Ви хочете налаштувати гібридний пошук, MMR або часовий спад + - Ви хочете увімкнути мультимодальну індексацію пам’яті sidebarTitle: Memory config -summary: Усі параметри конфігурації для пошуку в пам’яті, провайдерів embedding, QMD, hybrid search і multimodal indexing -title: Довідник із конфігурації пам’яті +summary: Усі параметри конфігурації для пошуку в пам’яті, провайдерів ембедингів, QMD, гібридного пошуку та мультимодальної індексації +title: Довідник з конфігурації пам’яті x-i18n: - generated_at: "2026-04-27T14:21:00Z" + generated_at: "2026-04-27T23:44:59Z" model: gpt-5.4 provider: openai - source_hash: f22a728c26a4d7aba155c108b7aad719418fd2dedfa370f339907dc3325e24af + source_hash: c2daa2774b4c8aef5fea8994d9b6cc807b8318f24f1e5c977de5d2cad8aefbc7 source_path: reference/memory-config.md workflow: 15 --- @@ -23,102 +23,102 @@ x-i18n: Як працює пам’ять. - Типовий backend SQLite. + Стандартний бекенд SQLite. - Локальний sidecar із пріоритетом локальної роботи. + Локально-орієнтований sidecar. Конвеєр пошуку та налаштування. - Підлеглий агент пам’яті для інтерактивних сесій. + Підагент пам’яті для інтерактивних сеансів. -Усі налаштування пошуку в пам’яті знаходяться в `agents.defaults.memorySearch` у `openclaw.json`, якщо не зазначено інше. +Усі налаштування пошуку в пам’яті розміщені в `agents.defaults.memorySearch` у `openclaw.json`, якщо не зазначено інше. -Якщо ви шукаєте перемикач функції **active memory** і конфігурацію підлеглого агента, вони розміщені в `plugins.entries.active-memory`, а не в `memorySearch`. +Якщо ви шукаєте перемикач функції **active memory** і конфігурацію підагента, вони розміщені в `plugins.entries.active-memory`, а не в `memorySearch`. Active Memory використовує двоетапну модель: -1. plugin має бути ввімкнений і націлений на поточний ID агента -2. запит має належати до придатної інтерактивної постійної сесії чату +1. plugin має бути увімкнений і націлений на поточний ідентифікатор агента +2. запит має бути прийнятним інтерактивним постійним сеансом чату -Див. [Active Memory](/uk/concepts/active-memory) для моделі активації, конфігурації, що належить Plugin, збереження транскриптів і безпечного шаблону розгортання. +Дивіться [Active Memory](/uk/concepts/active-memory), щоб дізнатися про модель активації, конфігурацію, якою керує plugin, збереження транскриптів і безпечний шаблон розгортання. --- ## Вибір провайдера -| Key | Type | Default | Description | -| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | визначається автоматично | ID адаптера embedding: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | -| `model` | `string` | типове значення провайдера | Назва моделі embedding | -| `fallback` | `string` | `"none"` | ID fallback-адаптера, якщо основний не спрацьовує | -| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук у пам’яті | +| Ключ | Тип | Типове значення | Опис | +| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | автоматично визначається | Ідентифікатор адаптера ембедингів: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | +| `model` | `string` | типове значення провайдера | Назва моделі ембедингів | +| `fallback` | `string` | `"none"` | Ідентифікатор резервного адаптера, якщо основний завершується помилкою | +| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук у пам’яті | ### Порядок автовизначення -Коли `provider` не задано, OpenClaw вибирає перший доступний: +Коли `provider` не задано, OpenClaw вибирає перший доступний варіант: Вибирається, якщо налаштовано `memorySearch.local.modelPath` і файл існує. - Вибирається, якщо вдається отримати токен GitHub Copilot (змінна середовища або профіль автентифікації). + Вибирається, якщо можна визначити токен GitHub Copilot (змінна середовища або профіль автентифікації). - Вибирається, якщо вдається отримати ключ OpenAI. + Вибирається, якщо можна визначити ключ OpenAI. - Вибирається, якщо вдається отримати ключ Gemini. + Вибирається, якщо можна визначити ключ Gemini. - Вибирається, якщо вдається отримати ключ Voyage. + Вибирається, якщо можна визначити ключ Voyage. - Вибирається, якщо вдається отримати ключ Mistral. + Вибирається, якщо можна визначити ключ Mistral. - Вибирається, якщо вдається розв’язати ланцюжок облікових даних AWS SDK (роль інстансу, ключі доступу, профіль, SSO, web identity або shared config). + Вибирається, якщо ланцюжок облікових даних AWS SDK успішно визначається (роль екземпляра, ключі доступу, профіль, SSO, web identity або спільна конфігурація). -`ollama` підтримується, але не визначається автоматично (задайте його явно). +`ollama` підтримується, але не визначається автоматично (вкажіть його явно). -### Розв’язання API key +### Визначення API-ключа -Для віддалених embedding потрібен API key. Bedrock натомість використовує типовий ланцюжок облікових даних AWS SDK (ролі інстансу, SSO, ключі доступу). +Для віддалених ембедингів потрібен API-ключ. Натомість Bedrock використовує типовий ланцюжок облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу). -| Provider | Env var | Config key | -| -------------- | -------------------------------------------------- | --------------------------------- | -| Bedrock | ланцюжок облікових даних AWS | API key не потрібен | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Профіль автентифікації через вхід із пристрою | +| Провайдер | Змінна середовища | Ключ конфігурації | +| -------------- | -------------------------------------------------- | -------------------------------- | +| Bedrock | ланцюжок облікових даних AWS | API-ключ не потрібен | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Профіль автентифікації через вхід із пристрою | | Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY` (заповнювач) | -- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | +| Ollama | `OLLAMA_API_KEY` (заповнювач) | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -Codex OAuth охоплює лише chat/completions і не підходить для запитів embedding. +OAuth Codex покриває лише chat/completions і не задовольняє запити на ембединги. --- -## Конфігурація віддаленого endpoint +## Конфігурація віддаленої кінцевої точки -Для власних OpenAI-сумісних endpoint або перевизначення типових значень провайдера: +Для користувацьких OpenAI-сумісних кінцевих точок або перевизначення типових значень провайдера: - Власна базова URL-адреса API. + Користувацька базова URL-адреса API. - Перевизначити API key. + Перевизначити API-ключ. Додаткові HTTP-заголовки (об’єднуються з типовими значеннями провайдера). @@ -143,28 +143,28 @@ Codex OAuth охоплює лише chat/completions і не підходить --- -## Конфігурація для конкретних провайдерів +## Конфігурація для окремих провайдерів - | Key | Type | Default | Description | - | ---------------------- | -------- | ---------------------- | ------------------------------------------ | + | Ключ | Тип | Типове значення | Опис | + | ---------------------- | -------- | --------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | Також підтримує `gemini-embedding-2-preview` | - | `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | + | `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | - Зміна моделі або `outputDimensionality` запускає автоматичне повне переіндексування. + Зміна моделі або `outputDimensionality` запускає автоматичну повну повторну індексацію. - OpenAI-сумісні embedding-endpoint можуть опційно використовувати специфічні для провайдера поля запиту `input_type`. Це корисно для асиметричних embedding-моделей, які потребують різних міток для embedding запиту та embedding документа. + OpenAI-сумісні кінцеві точки ембедингів можуть використовувати специфічні для провайдера поля запиту `input_type`. Це корисно для асиметричних моделей ембедингів, які вимагають різних міток для ембедингів запитів і документів. - | Key | Type | Default | Description | - | ------------------- | -------- | ------- | ------------------------------------------------------- | - | `inputType` | `string` | не задано | Спільний `input_type` для embedding запиту й документа | - | `queryInputType` | `string` | не задано | `input_type` під час запиту; перевизначає `inputType` | - | `documentInputType` | `string` | не задано | `input_type` для індексу/документа; перевизначає `inputType` | + | Ключ | Тип | Типове значення | Опис | + | ------------------- | -------- | --------------- | ----------------------------------------------------- | + | `inputType` | `string` | не задано | Спільний `input_type` для ембедингів запитів і документів | + | `queryInputType` | `string` | не задано | `input_type` під час запиту; перевизначає `inputType` | + | `documentInputType` | `string` | не задано | `input_type` для індексу/документа; перевизначає `inputType` | ```json5 { @@ -185,11 +185,11 @@ Codex OAuth охоплює лише chat/completions і не підходить } ``` - Зміна цих значень впливає на ідентичність кешу embedding для пакетного індексування провайдера, і після цього слід виконати переіндексування пам’яті, якщо вихідна модель по-різному трактує ці мітки. + Зміна цих значень впливає на ідентичність кешу ембедингів для пакетної індексації провайдера, і після цього слід виконати повторну індексацію пам’яті, якщо висхідна модель по-різному обробляє ці мітки. - Bedrock використовує типовий ланцюжок облікових даних AWS SDK — API key не потрібні. Якщо OpenClaw працює на EC2 з роллю інстансу, у якій увімкнено Bedrock, просто задайте провайдера й модель: + Bedrock використовує типовий ланцюжок облікових даних AWS SDK — API-ключі не потрібні. Якщо OpenClaw працює на EC2 з роллю екземпляра, для якої ввімкнено Bedrock, достатньо просто вказати провайдера та модель: ```json5 { @@ -204,29 +204,29 @@ Codex OAuth охоплює лише chat/completions і не підходить } ``` - | Key | Type | Default | Description | - | ---------------------- | -------- | ------------------------------ | ------------------------------- | - | `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ID embedding-моделі Bedrock | - | `outputDimensionality` | `number` | типове значення моделі | Для Titan V2: 256, 512 або 1024 | + | Ключ | Тип | Типове значення | Опис | + | ---------------------- | -------- | ----------------------------- | ----------------------------- | + | `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ідентифікатор моделі ембедингів Bedrock | + | `outputDimensionality` | `number` | типове значення моделі | Для Titan V2: 256, 512 або 1024 | - **Підтримувані моделі** (із визначенням сімейства та типовими розмірностями): + **Підтримувані моделі** (з визначенням сімейства та типовими розмірностями): - | Model ID | Provider | Default Dims | Configurable Dims | - | ------------------------------------------ | ---------- | ------------ | -------------------- | - | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | - | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | - | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | - | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | - | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | - | `cohere.embed-english-v3` | Cohere | 1024 | -- | - | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | - | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | - | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | - | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | + | Model ID | Провайдер | Типові розмірності | Налаштовувані розмірності | + | ------------------------------------------ | ---------- | ------------------ | ------------------------- | + | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | + | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | + | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | + | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | + | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | + | `cohere.embed-english-v3` | Cohere | 1024 | -- | + | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | + | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | + | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | + | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | - Варіанти із суфіксом пропускної здатності (наприклад, `amazon.titan-embed-text-v1:2:8k`) успадковують конфігурацію базової моделі. + Варіанти з суфіксом пропускної здатності (наприклад, `amazon.titan-embed-text-v1:2:8k`) успадковують конфігурацію базової моделі. - **Автентифікація:** автентифікація Bedrock використовує стандартний порядок розв’язання облікових даних AWS SDK: + **Автентифікація:** автентифікація Bedrock використовує стандартний порядок визначення облікових даних AWS SDK: 1. Змінні середовища (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Кеш токенів SSO @@ -234,7 +234,7 @@ Codex OAuth охоплює лише chat/completions і не підходить 4. Спільні файли облікових даних і конфігурації 5. Облікові дані метаданих ECS або EC2 - Регіон визначається з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` провайдера `amazon-bedrock` або типово дорівнює `us-east-1`. + Регіон визначається з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` провайдера `amazon-bedrock` або за замовчуванням використовується `us-east-1`. **Дозволи IAM:** роль IAM або користувач повинні мати: @@ -253,14 +253,14 @@ Codex OAuth охоплює лише chat/completions і не підходить ``` - - | Key | Type | Default | Description | - | --------------------- | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `local.modelPath` | `string` | завантажується автоматично | Шлях до файлу моделі GGUF | - | `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей | - | `local.contextSize` | `number \| "auto"` | `4096` | Розмір контекстного вікна для embedding-контексту. 4096 покриває типові фрагменти (128–512 токенів), водночас обмежуючи VRAM, що не належить вагам моделі. Зменшуйте до 1024–2048 на хостах з обмеженими ресурсами. `"auto"` використовує натренований максимум моделі — не рекомендовано для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 ГБ VRAM проти ~8.8 ГБ при 4096). | + + | Ключ | Тип | Типове значення | Опис | + | --------------------- | ------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `local.modelPath` | `string` | автоматично завантажується | Шлях до файлу моделі GGUF | + | `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей | + | `local.contextSize` | `number \| "auto"` | `4096` | Розмір вікна контексту для контексту ембедингів. 4096 покриває типові фрагменти (128–512 токенів), водночас обмежуючи VRAM, не пов’язану з вагами. На обмежених хостах зменшуйте до 1024–2048. `"auto"` використовує натренований максимум моделі — не рекомендовано для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 ГБ VRAM проти ~8.8 ГБ при 4096). | - Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 ГБ, завантажується автоматично). Потребує нативного збирання: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`. + Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 ГБ, завантажується автоматично). Потрібна нативна збірка: `pnpm approve-builds`, а потім `pnpm rebuild node-llama-cpp`. Використовуйте окремий CLI, щоб перевірити той самий шлях провайдера, який використовує Gateway: @@ -269,46 +269,46 @@ Codex OAuth охоплює лише chat/completions і не підходить openclaw memory index --force --agent main ``` - Якщо `provider` має значення `auto`, `local` вибирається лише тоді, коли `local.modelPath` вказує на наявний локальний файл. Посилання на моделі `hf:` і HTTP(S) усе ще можна явно використовувати з `provider: "local"`, але вони не змусять `auto` вибрати local, доки модель не стане доступною на диску. + Якщо `provider` має значення `auto`, `local` вибирається лише тоді, коли `local.modelPath` вказує на наявний локальний файл. Посилання на моделі `hf:` і HTTP(S) усе ще можна використовувати явно з `provider: "local"`, але вони не змушують `auto` вибрати local, доки модель не стане доступною на диску. -### Тайм-аут вбудованого embedding +### Тайм-аут вбудованих ембедингів - Перевизначити тайм-аут для вбудованих пакетів embedding під час індексування пам’яті. + Перевизначити тайм-аут для вбудованих пакетів ембедингів під час індексації пам’яті. -Якщо не задано, використовується типове значення провайдера: 600 секунд для локальних/self-hosted провайдерів, таких як `local`, `ollama` і `lmstudio`, та 120 секунд для хостованих провайдерів. Збільшуйте це значення, коли локальні CPU-bound пакети embedding працюють справно, але повільно. +Якщо значення не задано, використовується типове значення провайдера: 600 секунд для локальних/самостійно розміщених провайдерів, таких як `local`, `ollama` і `lmstudio`, та 120 секунд для хостингових провайдерів. Збільшіть це значення, якщо локальні CPU-обмежені пакети ембедингів працюють коректно, але повільно. --- -## Конфігурація hybrid search +## Конфігурація гібридного пошуку -Усе міститься в `memorySearch.query.hybrid`: +Усе знаходиться в `memorySearch.query.hybrid`: -| Key | Type | Default | Description | -| --------------------- | --------- | ------- | ---------------------------------- | -| `enabled` | `boolean` | `true` | Увімкнути hybrid BM25 + vector search | -| `vectorWeight` | `number` | `0.7` | Вага для оцінок vector (0-1) | -| `textWeight` | `number` | `0.3` | Вага для оцінок BM25 (0-1) | -| `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів | +| Ключ | Тип | Типове значення | Опис | +| --------------------- | --------- | --------------- | ----------------------------------- | +| `enabled` | `boolean` | `true` | Увімкнути гібридний пошук BM25 + векторний пошук | +| `vectorWeight` | `number` | `0.7` | Вага для векторних оцінок (0-1) | +| `textWeight` | `number` | `0.3` | Вага для оцінок BM25 (0-1) | +| `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів | - | Key | Type | Default | Description | - | ------------- | --------- | ------- | ------------------------------------ | - | `mmr.enabled` | `boolean` | `false` | Увімкнути MMR re-ranking | - | `mmr.lambda` | `number` | `0.7` | 0 = максимальна різноманітність, 1 = максимальна релевантність | + | Ключ | Тип | Типове значення | Опис | + | ------------- | --------- | --------------- | ---------------------------------------- | + | `mmr.enabled` | `boolean` | `false` | Увімкнути повторне ранжування MMR | + | `mmr.lambda` | `number` | `0.7` | 0 = максимальна різноманітність, 1 = максимальна релевантність | - - | Key | Type | Default | Description | - | ---------------------------- | --------- | ------- | ------------------------- | - | `temporalDecay.enabled` | `boolean` | `false` | Увімкнути підсилення за давністю | - | `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів | + + | Ключ | Тип | Типове значення | Опис | + | ---------------------------- | --------- | --------------- | ----------------------------- | + | `temporalDecay.enabled` | `boolean` | `false` | Увімкнути буст за актуальністю | + | `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів | - Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ніколи не піддаються згасанню. + Для evergreen-файлів (`MEMORY.md`, файлів без дати в `memory/`) спад ніколи не застосовується. @@ -338,9 +338,9 @@ Codex OAuth охоплює лише chat/completions і не підходить ## Додаткові шляхи пам’яті -| Key | Type | Description | -| ------------ | ---------- | ---------------------------------------- | -| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексування | +| Ключ | Тип | Опис | +| ----------- | ---------- | -------------------------------------- | +| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексації | ```json5 { @@ -354,21 +354,21 @@ Codex OAuth охоплює лише chat/completions і не підходить } ``` -Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги скануються рекурсивно на наявність файлів `.md`. Обробка symlink залежить від активного backend: вбудований рушій ігнорує symlink, тоді як QMD дотримується поведінки базового сканера QMD. +Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги скануються рекурсивно на наявність файлів `.md`. Обробка символьних посилань залежить від активного бекенда: вбудований рушій ігнорує символьні посилання, тоді як QMD дотримується поведінки базового сканера QMD. -Для пошуку транскриптів між агентами в межах конкретного агента використовуйте `agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`. Ці додаткові колекції мають ту саму форму `{ path, name, pattern? }`, але об’єднуються для кожного агента окремо й можуть зберігати явні спільні назви, коли шлях указує за межі поточного робочого простору. Якщо той самий розв’язаний шлях з’являється і в `memory.qmd.paths`, і в `memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає дублікат. +Для пошуку транскриптів між агентами в межах агента використовуйте `agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`. Ці додаткові колекції мають ту саму форму `{ path, name, pattern? }`, але об’єднуються для кожного агента й можуть зберігати явно задані спільні назви, коли шлях вказує за межі поточного робочого простору. Якщо той самий визначений шлях з’являється і в `memory.qmd.paths`, і в `memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає дублікат. --- -## Multimodal memory (Gemini) +## Мультимодальна пам’ять (Gemini) -Індексуйте зображення та аудіо разом із Markdown за допомогою Gemini Embedding 2: +Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2: -| Key | Type | Default | Description | -| ------------------------- | ---------- | ---------- | -------------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Увімкнути multimodal indexing | -| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файлу для індексування | +| Ключ | Тип | Типове значення | Опис | +| ------------------------- | ---------- | --------------- | ----------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | Увімкнути мультимодальну індексацію | +| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` | +| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файлу для індексації | Застосовується лише до файлів у `extraPaths`. Типові корені пам’яті залишаються лише для Markdown. Потрібен `gemini-embedding-2-preview`. `fallback` має бути `"none"`. @@ -378,115 +378,118 @@ Codex OAuth охоплює лише chat/completions і не підходить --- -## Кеш embedding +## Кеш ембедингів -| Key | Type | Default | Description | -| ------------------ | --------- | ------- | -------------------------------- | -| `cache.enabled` | `boolean` | `false` | Кешувати embedding фрагментів у SQLite | -| `cache.maxEntries` | `number` | `50000` | Максимальна кількість кешованих embedding | +| Ключ | Тип | Типове значення | Опис | +| ------------------ | --------- | --------------- | -------------------------------- | +| `cache.enabled` | `boolean` | `false` | Кешувати ембединги фрагментів у SQLite | +| `cache.maxEntries` | `number` | `50000` | Максимальна кількість кешованих ембедингів | -Запобігає повторному створенню embedding для незміненого тексту під час переіндексації або оновлення транскриптів. +Запобігає повторному створенню ембедингів для незмінного тексту під час повторної індексації або оновлень транскриптів. --- -## Пакетне індексування +## Пакетна індексація -| Key | Type | Default | Description | -| ----------------------------- | --------- | ------- | -------------------------- | -| `remote.batch.enabled` | `boolean` | `false` | Увімкнути пакетний embedding API | -| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | -| `remote.batch.wait` | `boolean` | `true` | Очікувати завершення пакета | -| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | -| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | +| Ключ | Тип | Типове значення | Опис | +| ----------------------------- | --------- | --------------- | ------------------------- | +| `remote.nonBatchConcurrency` | `number` | `4` | Паралельні вбудовані ембединги | +| `remote.batch.enabled` | `boolean` | `false` | Увімкнути API пакетних ембедингів | +| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | +| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета | +| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | +| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | -Доступно для `openai`, `gemini` і `voyage`. Пакетний режим OpenAI зазвичай найшвидший і найдешевший для великих зворотних заповнень. +Доступно для `openai`, `gemini` і `voyage`. Пакетний режим OpenAI зазвичай є найшвидшим і найдешевшим для великих зворотних заповнень. -Це окремо від `sync.embeddingBatchTimeoutSeconds`, який керує вбудованими викликами embedding, що використовуються локальними/self-hosted провайдерами та хостованими провайдерами, коли пакетні API провайдера не активні. +`remote.nonBatchConcurrency` керує вбудованими викликами ембедингів, які використовуються локальними/самостійно розміщеними провайдерами та хостинговими провайдерами, коли пакетні API провайдера не активні. Для непакетної індексації Ollama типово використовує `1`, щоб не перевантажувати менші локальні хости; на потужніших машинах встановіть вище значення. + +Це окремо від `sync.embeddingBatchTimeoutSeconds`, який керує тайм-аутом для вбудованих викликів ембедингів. --- -## Пошук у пам’яті сесій (експериментально) +## Пошук у пам’яті сеансів (експериментально) -Індексуйте транскрипти сесій і показуйте їх через `memory_search`: +Індексуйте транскрипти сеансів і показуйте їх через `memory_search`: -| Key | Type | Default | Description | -| ----------------------------- | ---------- | ------------ | --------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексування сесій | -| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти | -| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для переіндексації | -| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для переіндексації | +| Ключ | Тип | Типове значення | Опис | +| ----------------------------- | ---------- | --------------- | -------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексацію сеансів | +| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти | +| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для повторної індексації | +| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для повторної індексації | -Індексація сесій є опційною і виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сесій зберігаються на диску, тому вважайте доступ до файлової системи межею довіри. +Індексація сеансів є опціональною та виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сеансів зберігаються на диску, тому вважайте доступ до файлової системи межею довіри. --- ## Прискорення векторів SQLite (sqlite-vec) -| Key | Type | Default | Description | -| ---------------------------- | --------- | ------- | --------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів | -| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec | +| Ключ | Тип | Типове значення | Опис | +| ---------------------------- | --------- | --------------- | ------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів | +| `store.vector.extensionPath` | `string` | вбудовано | Перевизначити шлях до sqlite-vec | -Коли sqlite-vec недоступний, OpenClaw автоматично повертається до in-process cosine similarity. +Коли sqlite-vec недоступний, OpenClaw автоматично переходить на косинусну схожість у процесі. --- -## Зберігання індексу +## Сховище індексу -| Key | Type | Default | Description | -| --------------------- | -------- | ------------------------------------- | ------------------------------------------- | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | +| Ключ | Тип | Типове значення | Опис | +| ------------------- | -------- | ------------------------------------ | ----------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | --- -## Конфігурація backend QMD +## Конфігурація бекенда QMD -Щоб увімкнути, задайте `memory.backend = "qmd"`. Усі налаштування QMD знаходяться в `memory.qmd`: +Установіть `memory.backend = "qmd"`, щоб увімкнути його. Усі налаштування QMD розміщені в `memory.qmd`: -| Key | Type | Default | Description | -| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- | -| `command` | `string` | `qmd` | Шлях до виконуваного файлу QMD; задайте абсолютний шлях, якщо `PATH` служби відрізняється від вашої оболонки | -| `searchMode` | `string` | `search` | Команда пошуку: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сесій | -| `sessions.retentionDays` | `number` | -- | Зберігання транскриптів | -| `sessions.exportDir` | `string` | -- | Каталог експорту | +| Ключ | Тип | Типове значення | Опис | +| ------------------------ | --------- | --------------- | ------------------------------------------------------------------------------------ | +| `command` | `string` | `qmd` | Шлях до виконуваного файла QMD; вкажіть абсолютний шлях, якщо `PATH` сервісу відрізняється від вашої оболонки | +| `searchMode` | `string` | `search` | Команда пошуку: `search`, `vsearch`, `query` | +| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сеансів | +| `sessions.retentionDays` | `number` | -- | Термін зберігання транскриптів | +| `sessions.exportDir` | `string` | -- | Каталог експорту | -`searchMode: "search"` — це лише лексичний/BM25-режим. OpenClaw не запускає перевірки готовності семантичного вектора або обслуговування embedding QMD для цього режиму, зокрема під час `memory status --deep`; `vsearch` і `query` як і раніше потребують готовності векторів QMD та embedding. +`searchMode: "search"` є лише лексичним/BM25-режимом. Для цього режиму OpenClaw не виконує перевірки готовності семантичних векторів або обслуговування ембедингів QMD, зокрема під час `memory status --deep`; для `vsearch` і `query`, як і раніше, потрібні готовність векторів QMD та ембединги. -OpenClaw віддає перевагу поточним формам колекцій QMD і запитів MCP, але зберігає працездатність старіших випусків QMD, за потреби пробуючи сумісні прапорці шаблонів колекцій і старіші назви інструментів MCP. Коли QMD повідомляє про підтримку кількох фільтрів колекцій, колекції з однаковим джерелом шукаються одним процесом QMD; старіші збірки QMD зберігають сумісний шлях із пошуком по одній колекції. Однакове джерело означає, що колекції довготривалої пам’яті групуються разом, а колекції транскриптів сесій залишаються окремою групою, щоб диверсифікація джерел усе ще мала обидва входи. +OpenClaw надає перевагу актуальним формам колекцій QMD і запитів MCP, але зберігає сумісність зі старішими випусками QMD, за потреби намагаючись використовувати сумісні прапорці шаблонів колекцій і старіші назви інструментів MCP. Коли QMD повідомляє про підтримку кількох фільтрів колекцій, колекції з тим самим джерелом шукаються одним процесом QMD; старіші збірки QMD зберігають сумісний шлях із поодинокою колекцією. Те саме джерело означає, що довготривалі колекції пам’яті групуються разом, тоді як колекції транскриптів сеансів залишаються окремою групою, щоб диверсифікація джерел і далі мала обидва входи. -Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно глобально перевизначити моделі QMD, задайте змінні середовища, як-от `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у середовищі runtime gateway. +Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно глобально перевизначити моделі QMD, установіть змінні середовища, такі як `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у середовищі виконання Gateway. - | Key | Type | Default | Description | - | ------------------------- | --------- | ------- | ------------------------------------- | - | `update.interval` | `string` | `5m` | Інтервал оновлення | - | `update.debounceMs` | `number` | `15000` | Debounce змін файлів | - | `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску | - | `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення | - | `update.embedInterval` | `string` | -- | Окрема частота embedding | - | `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD | - | `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD | - | `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій embedding QMD | + | Ключ | Тип | Типове значення | Опис | + | ------------------------- | --------- | --------------- | ------------------------------------ | + | `update.interval` | `string` | `5m` | Інтервал оновлення | + | `update.debounceMs` | `number` | `15000` | Затримка згладжування змін файлів | + | `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску | + | `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення | + | `update.embedInterval` | `string` | -- | Окрема частота ембедингів | + | `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD | + | `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD | + | `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій ембедингів QMD | - | Key | Type | Default | Description | - | ------------------------- | -------- | ------- | -------------------------- | - | `limits.maxResults` | `number` | `6` | Максимальна кількість результатів пошуку | - | `limits.maxSnippetChars` | `number` | -- | Обмежити довжину фрагмента | - | `limits.maxInjectedChars` | `number` | -- | Обмежити загальну кількість вставлених символів | - | `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку | + | Ключ | Тип | Типове значення | Опис | + | ------------------------- | -------- | --------------- | ---------------------------- | + | `limits.maxResults` | `number` | `6` | Максимальна кількість результатів пошуку | + | `limits.maxSnippetChars` | `number` | -- | Обмеження довжини фрагмента | + | `limits.maxInjectedChars` | `number` | -- | Обмеження загальної кількості вставлених символів | + | `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку | - Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й у [`session.sendPolicy`](/uk/gateway/config-agents#session): + Керує тим, які сеанси можуть отримувати результати пошуку QMD. Та сама схема, що й у [`session.sendPolicy`](/uk/gateway/config-agents#session): ```json5 { @@ -501,18 +504,18 @@ OpenClaw віддає перевагу поточним формам колек } ``` - Типове значення в постачанні дозволяє direct і channel-сесії, водночас усе ще забороняючи групи. + Типова конфігурація в постачанні дозволяє прямі сеанси та сеанси каналів, водночас і далі забороняючи групи. - Типове значення — лише DM. `match.keyPrefix` відповідає нормалізованому ключу сесії; `match.rawKeyPrefix` відповідає сирому ключу, включно з `agent::`. + Типове значення — лише DM. `match.keyPrefix` відповідає нормалізованому ключу сеансу; `match.rawKeyPrefix` відповідає сирому ключу, включно з `agent::`. - `memory.citations` застосовується до всіх backend: + `memory.citations` застосовується до всіх бекендів: - | Value | Behavior | + | Значення | Поведінка | | ---------------- | --------------------------------------------------- | - | `auto` (типово) | Додавати нижній колонтитул `Source: ` до фрагментів | - | `on` | Завжди додавати нижній колонтитул | + | `auto` (типово) | Додавати нижній колонтитул `Source: ` у фрагменти | + | `on` | Завжди додавати нижній колонтитул | | `off` | Пропускати нижній колонтитул (шлях усе одно внутрішньо передається агенту) | @@ -545,17 +548,17 @@ OpenClaw віддає перевагу поточним формам колек Dreaming налаштовується в `plugins.entries.memory-core.config.dreaming`, а не в `agents.defaults.memorySearch`. -Dreaming запускається як один запланований прохід і використовує внутрішні фази light/deep/REM як деталь реалізації. +Dreaming працює як один запланований прохід і використовує внутрішні фази light/deep/REM як деталь реалізації. -Для концептуальної поведінки та slash-команд див. [Dreaming](/uk/concepts/dreaming). +Щоб дізнатися про концептуальну поведінку та slash-команди, дивіться [Dreaming](/uk/concepts/dreaming). ### Налаштування користувача -| Key | Type | Default | Description | -| ----------- | --------- | ------------- | ------------------------------------------------- | -| `enabled` | `boolean` | `false` | Повністю увімкнути або вимкнути Dreaming | -| `frequency` | `string` | `0 3 * * *` | Необов’язкова частота Cron для повного проходу Dreaming | -| `model` | `string` | типова модель | Необов’язкове перевизначення моделі підлеглого агента Dream Diary | +| Ключ | Тип | Типове значення | Опис | +| ---------- | --------- | --------------- | --------------------------------------------------- | +| `enabled` | `boolean` | `false` | Повністю увімкнути або вимкнути Dreaming | +| `frequency` | `string` | `0 3 * * *` | Необов’язкова Cron-частота для повного проходу Dreaming | +| `model` | `string` | типова модель | Необов’язкове перевизначення моделі підагента Dream Diary | ### Приклад @@ -584,8 +587,8 @@ Dreaming запускається як один запланований про - Dreaming записує машинний стан у `memory/.dreams/`. - Dreaming записує зрозумілий людині наративний вивід у `DREAMS.md` (або наявний `dreams.md`). -- `dreaming.model` використовує наявний trust gate підлеглого агента Plugin; перед увімкненням задайте `plugins.entries.memory-core.subagent.allowModelOverride: true`. -- Політика та пороги фаз light/deep/REM є внутрішньою поведінкою, а не користувацькою конфігурацією. +- `dreaming.model` використовує наявний trust gate підагента plugin; перед увімкненням установіть `plugins.entries.memory-core.subagent.allowModelOverride: true`. +- Політика фаз light/deep/REM і пороги є внутрішньою поведінкою, а не користувацькою конфігурацією. ## Пов’язане