chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
eabf6db73b
commit
b9eee9973e
153
docs/uk/ci.md
153
docs/uk/ci.md
@ -1,47 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося
|
||||
- Вам потрібно зрозуміти, чому завдання CI було або не було запущене
|
||||
- Ви налагоджуєте збої перевірок GitHub Actions
|
||||
summary: Граф завдань CI, перевірки за областю змін і локальні еквіваленти команд
|
||||
title: CI pipeline
|
||||
summary: Граф завдань CI, шлюзи області змін і локальні еквіваленти команд
|
||||
title: Конвеєр CI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:45:42Z"
|
||||
generated_at: "2026-04-23T21:58:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f06d3bec8a44402afb3aeec252105d3e3c985307deb3fcc0859c2d1df50f2612
|
||||
source_hash: d2aa581f173b7171373a9292cef3da20621b845d81a8550bd8b4c8e743d27a4b
|
||||
source_path: ci.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
CI запускається при кожному push до `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані частини.
|
||||
CI запускається для кожного push до `main` і кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки.
|
||||
|
||||
QA Lab має окремі lane-и CI поза основним smart-scoped workflow. Workflow
|
||||
`Parity gate` запускається для відповідних змін у PR і через manual dispatch; він
|
||||
збирає приватне runtime QA і порівнює agentic pack-и mock GPT-5.4 та Opus 4.6.
|
||||
Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через
|
||||
manual dispatch; він розпаралелює mock parity gate, live lane Matrix і live
|
||||
lane Telegram як паралельні завдання. Live-завдання використовують environment
|
||||
`qa-live-shared`, а lane Telegram використовує lease-и Convex. `OpenClaw Release
|
||||
Checks` також запускає ті самі lane-и QA Lab перед схваленням релізу.
|
||||
QA Lab має окремі CI-лінії поза основним workflow з розумним визначенням області. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний dispatch; він збирає приватне QA runtime і порівнює agentic pack-и mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний dispatch; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram lane використовує lease-и Convex. `OpenClaw Release Checks` також запускає ті самі лінії QA Lab перед затвердженням релізу.
|
||||
|
||||
Workflow `Duplicate PRs After Merge` — це ручний workflow супровідника для
|
||||
очищення дублікатів після приземлення змін. За замовчуванням він працює в режимі dry-run і
|
||||
закриває лише явно вказані PR, коли `apply=true`. Перш ніж змінювати GitHub,
|
||||
він перевіряє, що приземлений PR уже merged, і що кожен дублікат має або спільну
|
||||
issue, на яку є посилання, або перекривані змінені hunks.
|
||||
Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільну пов’язану issue, або перетин змінених hunks.
|
||||
|
||||
Workflow `Test Performance Agent` — це event-driven lane супроводу Codex
|
||||
для повільних тестів. Він не має суто планового запуску: його може запустити
|
||||
успішний небоговий запуск push CI на `main`, але він пропускається, якщо того UTC-дня
|
||||
інше workflow-run викликання вже виконалося або ще виконується.
|
||||
Manual dispatch обходить це денне обмеження активності. Цей lane будує grouped report
|
||||
продуктивності Vitest для повного набору тестів, дозволяє Codex вносити лише
|
||||
невеликі виправлення продуктивності тестів без втрати покриття, потім повторно запускає
|
||||
повний report і відхиляє зміни, які зменшують базову кількість тестів, що проходять.
|
||||
Якщо в базовому стані є тести, що не проходять, Codex може виправляти лише очевидні
|
||||
помилки, а підсумковий повний report після агента має пройти повністю, перш ніж
|
||||
щось буде закомічено. Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла
|
||||
зберігати ту саму безпечну політику drop-sudo, що й агент документації.
|
||||
Workflow `Test Performance Agent` — це event-driven лінія обслуговування Codex для повільних тестів. Вона не має окремого розкладу: її може запустити успішний неблокований push CI на `main`, але вона пропускається, якщо того ж дня за UTC вже був або виконується інший виклик workflow-run. Ручний dispatch обходить це денне обмеження активності. Лінія збирає grouped Vitest performance report для повного набору тестів, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору тестів і відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а after-agent звіт для повного набору тестів має пройти, перш ніж щось буде закомічено. Коли `main` просувається вперед до того, як bot push буде застосовано, лінія перебазовує перевірений patch, повторно запускає `pnpm check:changed` і повторює push; застарілі patch-і з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й docs agent.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -52,84 +30,87 @@ gh workflow run duplicate-after-merge.yml \
|
||||
|
||||
## Огляд завдань
|
||||
|
||||
| Завдання | Призначення | Коли запускається |
|
||||
| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ |
|
||||
| `preflight` | Виявляє зміни лише в docs, змінені області, змінені extensions і будує CI manifest | Завжди для non-draft push і PR |
|
||||
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR |
|
||||
| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR |
|
||||
| `security-fast` | Обов’язковий aggregate для швидких завдань безпеки | Завжди для non-draft push і PR |
|
||||
| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні Node |
|
||||
| `checks-fast-core` | Швидкі lane-и коректності Linux, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні Node |
|
||||
| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним aggregate результатом перевірки | Зміни, релевантні Node |
|
||||
| `checks-node-extensions` | Повні шардовані тести bundled-plugin для всього набору extension | Зміни, релевантні Node |
|
||||
| `checks-node-core-test` | Шарди core Node tests, за винятком lane-ів channel, bundled, contract і extension | Зміни, релевантні Node |
|
||||
| `extension-fast` | Фокусні тести лише для змінених bundled plugin | Pull request-и зі змінами в extension |
|
||||
| `check` | Шардований еквівалент основного локального gate: production types, lint, guards, test types і strict smoke | Зміни, релевантні Node |
|
||||
| `check-additional` | Architecture, boundary, guards поверхні extension, package-boundary і шарди gateway-watch | Зміни, релевантні Node |
|
||||
| `build-smoke` | Smoke-тести built-CLI і smoke перевірка пам’яті під час запуску | Зміни, релевантні Node |
|
||||
| `checks` | Верифікатор для channel tests built-artifact плюс compat з Node 22 лише для push | Зміни, релевантні Node |
|
||||
| `check-docs` | Форматування docs, lint і перевірки битих посилань | Змінено docs |
|
||||
| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills |
|
||||
| `checks-windows` | Специфічні для Windows test lane-и | Зміни, релевантні Windows |
|
||||
| `macos-node` | Lane тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні macOS |
|
||||
| `macos-swift` | Swift lint, build і tests для застосунку macOS | Зміни, релевантні macOS |
|
||||
| `android` | Android unit tests для обох flavor-ів плюс одна debug APK build | Зміни, релевантні Android |
|
||||
| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або manual dispatch |
|
||||
| Завдання | Призначення | Коли запускається |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| `preflight` | Визначає зміни лише в docs, змінені області, змінені extensions і будує CI manifest | Завжди для недрафтових push і PR |
|
||||
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для недрафтових push і PR |
|
||||
| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для недрафтових push і PR |
|
||||
| `security-fast` | Обов’язковий агрегатор для швидких security-завдань | Завжди для недрафтових push і PR |
|
||||
| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні для Node |
|
||||
| `checks-fast-core` | Швидкі Linux-лінії коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node |
|
||||
| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node |
|
||||
| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extensions | Зміни, релевантні для Node |
|
||||
| `checks-node-core-test` | Шарди основних Node-тестів, без channel, bundled, contract і extension-ліній | Зміни, релевантні для Node |
|
||||
| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request-и зі змінами extensions |
|
||||
| `check` | Шардований еквівалент основного локального шлюзу: production types, lint, guards, test types і strict smoke | Зміни, релевантні для Node |
|
||||
| `check-additional` | Шарди для архітектури, меж, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node |
|
||||
| `build-smoke` | Smoke-тести built-CLI і smoke стартової пам’яті | Зміни, релевантні для Node |
|
||||
| `checks` | Верифікатор для built-artifact тестів каналів плюс сумісність Node 22 лише для push | Зміни, релевантні для Node |
|
||||
| `check-docs` | Форматування docs, lint і перевірки битих посилань | Змінено docs |
|
||||
| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills |
|
||||
| `checks-windows` | Специфічні для Windows тестові лінії | Зміни, релевантні для Windows |
|
||||
| `macos-node` | Лінія TypeScript-тестів для macOS з використанням спільних built artifacts | Зміни, релевантні для macOS |
|
||||
| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS |
|
||||
| `android` | Android unit-тести для обох flavor-ів плюс одна debug APK збірка | Зміни, релевантні для Android |
|
||||
| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний CI на main або ручний dispatch |
|
||||
|
||||
## Порядок Fail-Fast
|
||||
|
||||
Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запускаються дорогі:
|
||||
Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі:
|
||||
|
||||
1. `preflight` вирішує, які lane-и взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих matrix-завдань для artifacts і platform.
|
||||
3. `build-artifacts` виконується паралельно зі швидкими Linux lane-ами, щоб downstream-споживачі могли стартувати, щойно спільна збірка буде готова.
|
||||
4. Після цього розгалужуються важчі lane-и platform і runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR-only `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
|
||||
1. `preflight` вирішує, які лінії взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих artifact- і platform matrix-завдань.
|
||||
3. `build-artifacts` перекривається з швидкими Linux-лініями, щоб downstream-споживачі могли стартувати, щойно буде готова спільна збірка.
|
||||
4. Після цього розгалужуються важчі platform- і runtime-лінії: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` лише для PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
|
||||
|
||||
Логіка області змін живе в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`.
|
||||
Редагування workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують запускати native build-и Windows, Android або macOS; ці platform lane-и залишаються прив’язаними до змін у платформному коді.
|
||||
Перевірки Windows Node обмежені специфічними для Windows wrapper-ами process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цей lane; непов’язані зміни вихідного коду, plugin, install-smoke і test-only зміни залишаються в Linux Node lane-ах, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними test shard-ами.
|
||||
Окремий workflow `install-smoke` повторно використовує той самий скрипт області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` з вужчого сигналу changed-smoke, тож Docker/install smoke запускається для змін, пов’язаних із встановленням, пакуванням, контейнерами, production-змін bundled extension, а також для основних поверхонь plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише в tests і docs не резервують Docker workers. Його QR package smoke примушує шар Docker `pnpm install` перезапускатися, зберігаючи кеш BuildKit pnpm store, тож він усе одно перевіряє встановлення без повторного завантаження залежностей у кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах того самого завдання, тож додає реальне покриття WebSocket між контейнерами без ще однієї Docker build. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім паралельно запускає live/E2E smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний aggregate за замовчуванням припиняє планувати нові pooled lane-и після першого збою, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane-и, чутливі до запуску або provider-а, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний workflow live/E2E віддзеркалює шаблон shared-image: він збирає та пушить один GHCR Docker E2E image з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Плановий workflow live/E2E щодня запускає повний набір Docker suite для шляху релізу. Docker-тести QR та installer зберігають власні Dockerfile, сфокусовані на встановленні. Окреме завдання `docker-e2e-fast` запускає обмежений Docker profile bundled-plugin під тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс ізоляцію synthetic bundled-loader failure. Повна matrix для bundled update/channel залишається ручною/повного набору, оскільки виконує повторні реальні проходи npm update і doctor repair.
|
||||
Логіка області змін міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`.
|
||||
Зміни workflow CI перевіряють Node CI graph плюс lint workflow, але самі по собі не примушують запускати нативні збірки для Windows, Android або macOS; ці platform-лінії залишаються прив’язаними до змін у коді відповідної платформи.
|
||||
Перевірки Windows Node прив’язані до специфічних для Windows process/path wrappers, npm/pnpm/UI runner helpers, конфігурації package manager і поверхонь CI workflow, які виконують цю лінію; не пов’язані зміни вихідного коду, plugins, install-smoke і зміни лише тестів залишаються на Linux Node-лініях, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже перевіряється звичайними test shard-ами.
|
||||
Окремий workflow `install-smoke` повторно використовує той самий скрипт визначення області через власне завдання `preflight`. Він обчислює `run_install_smoke` із вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з установленням, пакуванням, контейнерами, production-змін bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише тестів і лише docs не резервують Docker workers. Його QR package smoke примушує Docker-шар `pnpm install` виконатися повторно, водночас зберігаючи кеш BuildKit pnpm store, тож установка все одно перевіряється без повторного завантаження залежностей у кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в цьому завданні, тож додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локально `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-лінії паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled lanes після першого збою, а кожна лінія має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Лінії, чутливі до запуску або provider-ів, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний live/E2E workflow відтворює шаблон спільного image, збираючи й публікуючи один SHA-tagged GHCR Docker E2E image перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний релізний Docker-набір. QR і installer Docker-тести зберігають власні Dockerfile, орієнтовані на встановлення. Окреме завдання `docker-e2e-fast` запускає обмежений профіль bundled-plugin у Docker з тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс synthetic bundled-loader failure isolation. Повна matrix для оновлення bundled і channel залишається ручною/для повного набору, оскільки виконує повторні реальні проходи `npm update` і `doctor repair`.
|
||||
|
||||
Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо architecture boundary, ніж широка CI-область платформ: production-зміни core запускають typecheck core prod плюс core tests, зміни лише в core tests запускають лише typecheck/tests для core test, production-зміни extension запускають typecheck extension prod плюс extension tests, а зміни лише в extension tests запускають лише typecheck/tests для extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extension, оскільки extension залежать від цих core contract. Version bump-и лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно розширюються до всіх lane-ів.
|
||||
Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний шлюз суворіший щодо архітектурних меж, ніж широка platform-область у CI: production-зміни core запускають production typecheck core плюс тести core, зміни лише test-коду core запускають лише typecheck/tests для тестів core, production-зміни extensions запускають production typecheck extensions плюс тести extensions, а зміни лише test-коду extensions запускають лише typecheck/tests для тестів extensions. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extensions, тому що extensions залежать від цих core-контрактів. Версійні зміни лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно переводять у всі лінії.
|
||||
|
||||
Для push matrix `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, і matrix зосереджується на звичайних test/channel lane-ах.
|
||||
Для push matrix `checks` додає лінію `compat-node22`, що запускається лише для push. Для pull request-ів ця лінія пропускається, і matrix залишається зосередженою на звичайних test/channel-лініях.
|
||||
|
||||
Найповільніші сімейства Node tests поділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contract-и запускаються у трьох зважених shard-ах, bundled plugin tests балансуються між шістьма worker-ами extension, невеликі core unit lane-и об’єднуються в пари, auto-reply запускається у трьох збалансованих worker-ах замість шести крихітних worker-ів, а agentic gateway/plugin config-и розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media та різні plugin tests використовують свої окремі конфігурації Vitest замість спільного універсального plugin catch-all. Завдання shard-ів extension запускають групи конфігурацій plugin послідовно з одним worker-ом Vitest і більшим heap Node, щоб import-heavy пакети plugin-ів не перевантажували малі CI runner-и. Широкий lane agents використовує спільний file-parallel scheduler Vitest, оскільки в ньому домінують import/scheduling, а не один повільний test file. `runtime-config` запускається разом із shard-ом infra core-runtime, щоб спільний runtime shard не залишався найдовшим. `check-additional` тримає compile/canary-роботи package-boundary разом і відокремлює архітектуру topology runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard-и паралельно всередині одного завдання. Gateway watch, channel tests і shard support-boundary core запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі імена перевірок як легкі завдання-верифікатори й водночас уникаючи двох додаткових worker-ів Blacksmith і другої черги споживачів artifact-ів.
|
||||
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-test усе одно компілює цей flavor із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK при кожному Android-релевантному push.
|
||||
`extension-fast` виконується лише для PR, оскільки push-запуски вже виконують повні shard-и bundled plugin. Це зберігає зворотний зв’язок для reviews щодо змінених plugin-ів, не резервуючи додатковий worker Blacksmith на `main` для покриття, яке вже є в `checks-node-extensions`.
|
||||
Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів виконуються як три зважені шарди, тести bundled plugin розподіляються між шістьма worker-ами extension, малі core unit-лінії об’єднуються в пари, auto-reply працює на трьох збалансованих worker-ах замість шести дрібних, а конфігурації agentic gateway/plugin розподіляються по наявних source-only agentic Node-завданнях замість очікування built artifacts. Широкі browser-, QA-, media- та miscellaneous plugin-тести використовують свої виділені конфігурації Vitest замість спільного універсального plugin-набору. Завдання shard-ів extensions запускають групи конфігурацій plugin послідовно з одним Vitest worker-ом і більшим Node heap, щоб import-інтенсивні пакети plugin-ів не перевантажували малі CI runner-и. Широка лінія agents використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують import-и/планування, а не один повільний тестовий файл. `runtime-config` виконується разом із shard-ом infra core-runtime, щоб спільний runtime-shard не утримував tail. `check-additional` тримає package-boundary compile/canary-перевірки разом і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard-и паралельно в межах одного завдання. Gateway watch, channel-тести та shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви перевірок як легкі verifier-завдання та водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги artifact-consumer.
|
||||
|
||||
GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тож вони все ще повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений.
|
||||
Ключ concurrency CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запускі `main`.
|
||||
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює цей flavor із прапорцями SMS/call-log BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK при кожному Android-релевантному push.
|
||||
|
||||
`extension-fast` доступний лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це зберігає зворотний зв’язок для змінених plugin-ів під час review без резервування додаткового Blacksmith worker-а на `main` для покриття, яке вже є в `checks-node-extensions`.
|
||||
|
||||
GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений.
|
||||
|
||||
Ключ concurrency CI має версіонування (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій queue group не міг безстроково блокувати новіші запуски `main`.
|
||||
|
||||
## Runner-и
|
||||
|
||||
| Runner | Завдання |
|
||||
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та aggregate-и (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, shard-и `check`, крім lint, shard-и й aggregate-и `check-additional`, aggregate-верифікатори Node tests, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб matrix Blacksmith могла раніше ставати в чергу |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard-и Linux Node tests, shard-и bundled plugin tests, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, тож 8 vCPU коштували дорожче, ніж давали вигоду; Docker build-и install-smoke, де час очікування в черзі на 32 vCPU коштував дорожче, ніж давав вигоду |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` |
|
||||
| Runner | Завдання |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, швидкі security-завдання й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, aggregate verifier-и Node-тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла ставати в чергу раніше |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди Linux Node-тестів, шарди тестів bundled plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який і надалі достатньо чутливий до CPU, так що 8 vCPU коштували дорожче, ніж заощаджували; Docker-збірки install-smoke, де вартість часу очікування 32-vCPU перевищувала виграш |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для fork-ів відбувається fallback до `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork-ів відбувається fallback до `macos-latest` |
|
||||
|
||||
## Локальні еквіваленти
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD
|
||||
pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane
|
||||
pnpm check # швидкий локальний gate: production tsgo + sharded lint + parallel fast guards
|
||||
pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD
|
||||
pnpm check:changed # розумний локальний шлюз: changed typecheck/lint/tests за boundary lane
|
||||
pnpm check # швидкий локальний шлюз: production tsgo + шардований lint + паралельні швидкі guard-и
|
||||
pnpm check:test-types
|
||||
pnpm check:timed # той самий gate з вимірюванням часу по етапах
|
||||
pnpm check:timed # той самий шлюз із таймінгами для кожного етапу
|
||||
pnpm build:strict-smoke
|
||||
pnpm check:architecture
|
||||
pnpm test:gateway:watch-regression
|
||||
pnpm test # тести vitest
|
||||
pnpm test:channels
|
||||
pnpm test:contracts:channels
|
||||
pnpm check:docs # формат docs + lint + биті посилання
|
||||
pnpm build # зібрати dist, коли важливі lane-и CI artifact/build-smoke
|
||||
node scripts/ci-run-timings.mjs <run-id> # підсумувати wall time, queue time і найповільніші завдання
|
||||
node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запускі main CI
|
||||
pnpm check:docs # форматування docs + lint + биті посилання
|
||||
pnpm build # зібрати dist, коли важливі CI artifact/build-smoke лінії
|
||||
node scripts/ci-run-timings.mjs <run-id> # підсумувати загальний час, час у черзі та найповільніші завдання
|
||||
node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI
|
||||
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
|
||||
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
|
||||
```
|
||||
|
||||
@ -1,48 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете надійний fallback, коли API-провайдери виходять з ладу
|
||||
- Вам потрібен надійний резервний варіант, коли API-провайдери не працюють
|
||||
- Ви запускаєте Codex CLI або інші локальні AI CLI і хочете використовувати їх повторно
|
||||
- Ви хочете зрозуміти міст MCP loopback для доступу інструментів backend CLI
|
||||
summary: 'CLI backends: локальний fallback AI CLI з необов’язковим мостом інструментів MCP'
|
||||
title: CLI backends
|
||||
- Ви хочете зрозуміти міст local loopback MCP для доступу CLI-бекенда до інструментів
|
||||
summary: 'CLI-бекенди: локальний резервний варіант AI CLI з необов’язковим мостом інструментів MCP'
|
||||
title: CLI-бекенди
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:52:25Z"
|
||||
generated_at: "2026-04-23T21:58:47Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 86594b886c259df68591223e106c7507ab802321aaedebc9b243793c4f453388
|
||||
source_hash: d4f3f2f0a02539455de1a9f3982590e507e5ccd1e4cc354658118eadf522150a
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI backends (fallback runtime)
|
||||
# CLI-бекенди (резервне середовище виконання)
|
||||
|
||||
OpenClaw може запускати **локальні AI CLI** як **text-only fallback**, коли API-провайдери недоступні,
|
||||
обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний режим:
|
||||
OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні, обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід:
|
||||
|
||||
- **Інструменти OpenClaw не впроваджуються напряму**, але backends із `bundleMcp: true`
|
||||
можуть отримувати інструменти gateway через loopback MCP bridge.
|
||||
- **JSONL Streaming** для CLI, які це підтримують.
|
||||
- **Підтримуються сесії** (щоб подальші ходи залишалися узгодженими).
|
||||
- **Інструменти OpenClaw не інжектуються безпосередньо**, але бекенди з `bundleMcp: true` можуть отримувати інструменти шлюзу через міст loopback MCP.
|
||||
- **JSONL-стримінг** для CLI, які його підтримують.
|
||||
- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими).
|
||||
- **Зображення можна передавати наскрізно**, якщо CLI приймає шляхи до зображень.
|
||||
|
||||
Це задумано як **страхувальна сітка**, а не основний шлях. Використовуйте це, коли вам
|
||||
потрібні відповіді у форматі «працює завжди» без залежності від зовнішніх API.
|
||||
Це розроблено як **страхувальну опцію**, а не як основний шлях. Використовуйте це, коли вам потрібні текстові відповіді, які «завжди працюють», без залежності від зовнішніх API.
|
||||
|
||||
Якщо вам потрібен повноцінний runtime harness із керуванням сесіями ACP, фоновими завданнями,
|
||||
прив’язкою до thread/conversation і постійними зовнішніми coding sessions, використовуйте
|
||||
[ACP Agents](/uk/tools/acp-agents). CLI backends — це не ACP.
|
||||
Якщо вам потрібне повноцінне середовище виконання з керуванням сесіями ACP, фоновими завданнями, прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, натомість використовуйте [ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP.
|
||||
|
||||
## Швидкий старт для початківців
|
||||
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (bundled OpenAI Plugin
|
||||
реєструє типовий backend):
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований Plugin OpenAI реєструє типовий бекенд):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише
|
||||
шлях до команди:
|
||||
Якщо ваш Gateway працює під launchd/systemd і `PATH` мінімальний, додайте лише шлях до команди:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -58,16 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
}
|
||||
```
|
||||
|
||||
І все. Не потрібні ні ключі, ні додаткова конфігурація auth, окрім тієї, що вже є в самому CLI.
|
||||
І це все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI.
|
||||
|
||||
Якщо ви використовуєте bundled CLI backend як **основного провайдера повідомлень** на
|
||||
хості gateway, OpenClaw тепер автоматично завантажує Plugin-власник, коли ваша конфігурація
|
||||
явно посилається на цей backend у model ref або в
|
||||
`agents.defaults.cliBackends`.
|
||||
Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на хості Gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація явно посилається на цей бекенд у посиланні моделі або в `agents.defaults.cliBackends`.
|
||||
|
||||
## Використання як fallback
|
||||
## Використання як резервного варіанта
|
||||
|
||||
Додайте CLI backend до списку fallback, щоб він запускався лише тоді, коли основні моделі дають збій:
|
||||
Додайте CLI-бекенд до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не спрацьовують:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -88,20 +78,19 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
|
||||
Примітки:
|
||||
|
||||
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого CLI backend.
|
||||
- Якщо основний провайдер виходить з ладу (auth, rate limits, timeouts), OpenClaw
|
||||
спробує наступним саме CLI backend.
|
||||
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі вашого CLI-бекенда.
|
||||
- Якщо основний провайдер не спрацьовує (автентифікація, обмеження швидкості, тайм-аути), OpenClaw далі спробує CLI-бекенд.
|
||||
|
||||
## Огляд конфігурації
|
||||
|
||||
Усі CLI backends розміщуються в:
|
||||
Усі CLI-бекенди розміщуються в:
|
||||
|
||||
```
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Кожен запис має ключ у вигляді **provider id** (наприклад, `codex-cli`, `my-cli`).
|
||||
provider id стає лівою частиною вашого model ref:
|
||||
Кожен запис має ключ у вигляді **id провайдера** (наприклад, `codex-cli`, `my-cli`).
|
||||
Id провайдера стає лівою частиною посилання моделі:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -131,7 +120,7 @@ provider id стає лівою частиною вашого model ref:
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
// CLI у стилі Codex можуть замість цього вказувати на файл prompt:
|
||||
// CLI у стилі Codex можуть натомість вказувати на файл промпта:
|
||||
// systemPromptFileConfigArg: "-c",
|
||||
// systemPromptFileConfigKey: "model_instructions_file",
|
||||
systemPromptWhen: "first",
|
||||
@ -147,33 +136,34 @@ provider id стає лівою частиною вашого model ref:
|
||||
|
||||
## Як це працює
|
||||
|
||||
1. **Вибирає backend** на основі префікса провайдера (`codex-cli/...`).
|
||||
2. **Будує системний prompt** з використанням того самого prompt OpenClaw + контексту робочого простору.
|
||||
3. **Виконує CLI** з ID сесії (якщо це підтримується), щоб історія залишалася узгодженою.
|
||||
Bundled backend `claude-cli` підтримує процес Claude stdio активним для кожної
|
||||
сесії OpenClaw і надсилає подальші ходи через stdin stream-json.
|
||||
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
|
||||
2. **Будує системний промпт** із використанням того самого промпта OpenClaw і контексту робочого простору.
|
||||
3. **Виконує CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
Вбудований бекенд `claude-cli` підтримує процес Claude stdio живим для кожної
|
||||
сесії OpenClaw і надсилає наступні ходи через stream-json stdin.
|
||||
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
|
||||
5. **Зберігає ID сесій** для кожного backend, тож подальші ходи повторно використовують ту саму CLI-сесію.
|
||||
5. **Зберігає id сесій** для кожного бекенда, щоб наступні звернення повторно використовували ту саму CLI-сесію.
|
||||
|
||||
<Note>
|
||||
Bundled backend Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw розглядає
|
||||
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає
|
||||
використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує
|
||||
нову політику.
|
||||
</Note>
|
||||
|
||||
Bundled backend OpenAI `codex-cli` передає системний prompt OpenClaw через
|
||||
перевизначення конфігурації Codex `model_instructions_file` (`-c
|
||||
model_instructions_file="..."`). Codex не надає прапорця
|
||||
`--append-system-prompt` у стилі Claude, тому OpenClaw записує зібраний prompt у
|
||||
Вбудований бекенд OpenAI `codex-cli` передає системний промпт OpenClaw через
|
||||
перевизначення конфігурації `model_instructions_file` у Codex (`-c
|
||||
model_instructions_file="..."`). Codex не надає прапорця у стилі Claude
|
||||
`--append-system-prompt`, тому OpenClaw записує зібраний промпт у
|
||||
тимчасовий файл для кожної нової сесії Codex CLI.
|
||||
|
||||
Bundled backend Anthropic `claude-cli` отримує snapshot Skills OpenClaw
|
||||
двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і
|
||||
Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw
|
||||
двома способами: компактний каталог Skills OpenClaw у доданому системному промпті та
|
||||
тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить
|
||||
лише придатні Skills для цього агента/сесії, тож вбудований засіб визначення Skills у Claude Code бачить той самий відфільтрований набір, який OpenClaw інакше показав би в prompt. Перевизначення env/API key для Skills усе одно застосовуються OpenClaw до середовища дочірнього процесу для цього запуску.
|
||||
лише ті Skills, які дозволені для цього агента/сесії, тож власний резолвер Skills у Claude Code
|
||||
бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в промпті. Перевизначення env/API-ключів для Skills усе ще застосовуються OpenClaw до середовища дочірнього процесу під час запуску.
|
||||
|
||||
Перш ніж OpenClaw зможе використовувати bundled backend `claude-cli`, сам Claude Code
|
||||
Перш ніж OpenClaw зможе використовувати вбудований бекенд `claude-cli`, сам Claude Code
|
||||
має вже бути авторизований на тому самому хості:
|
||||
|
||||
```bash
|
||||
@ -188,67 +178,66 @@ openclaw models auth login --provider anthropic --method cli --set-default
|
||||
## Сесії
|
||||
|
||||
- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або
|
||||
`sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити
|
||||
`sessionArgs` (placeholder `{sessionId}`), коли id потрібно вставляти
|
||||
в кілька прапорців.
|
||||
- Якщо CLI використовує **resume subcommand** з іншими прапорцями, задайте
|
||||
- Якщо CLI використовує **підкоманду відновлення** з іншими прапорцями, задайте
|
||||
`resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput`
|
||||
(для відновлень не у форматі JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: завжди надсилати ID сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: надсилати ID сесії лише якщо його було збережено раніше.
|
||||
- `none`: ніколи не надсилати ID сесії.
|
||||
- `claude-cli` типово використовує `liveSession: "claude-stdio"`, `output: "jsonl"`
|
||||
і `input: "stdin"`, щоб подальші ходи повторно використовували активний процес Claude, поки
|
||||
він працює. Тепле stdio тепер є типовим, включно з користувацькими конфігураціями,
|
||||
які не вказують полів транспорту. Якщо Gateway перезапускається або процес у стані idle
|
||||
завершується, OpenClaw відновлюється зі збереженого ID сесії Claude. Збережені ID сесій
|
||||
перевіряються на наявність доступного для читання transcript проєкту перед
|
||||
відновленням, тож фантомні прив’язки очищуються з `reason=transcript-missing`
|
||||
замість тихого запуску нової сесії Claude CLI через `--resume`.
|
||||
- `always`: завжди надсилати id сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: надсилати id сесії лише якщо його вже було збережено.
|
||||
- `none`: ніколи не надсилати id сесії.
|
||||
- `claude-cli` типово використовує `liveSession: "claude-stdio"`, `output: "jsonl"`,
|
||||
і `input: "stdin"`, тому наступні ходи повторно використовують живий процес Claude, поки
|
||||
він активний. Тепле stdio тепер використовується за замовчуванням, зокрема для користувацьких конфігурацій,
|
||||
які не вказують поля транспорту. Якщо Gateway перезапуститься або процес простою
|
||||
завершиться, OpenClaw відновить роботу зі збереженого id сесії Claude. Збережені id сесій
|
||||
перевіряються на наявність доступного для читання наявного транскрипту проєкту перед
|
||||
відновленням, тож фантомні прив’язки очищаються з `reason=transcript-missing`,
|
||||
а не непомітно запускають нову сесію Claude CLI під `--resume`.
|
||||
- Збережені CLI-сесії — це безперервність, якою володіє провайдер. Неявне щоденне
|
||||
скидання сесії не розриває їх; `/reset` і явні політики `session.reset` усе ж розривають.
|
||||
скидання їх не обриває; `/reset` і явні політики `session.reset` — обривають.
|
||||
|
||||
Примітки щодо серіалізації:
|
||||
|
||||
- `serialize: true` зберігає порядок запусків у тій самій доріжці.
|
||||
- Більшість CLI серіалізуються в межах однієї доріжки провайдера.
|
||||
- OpenClaw відмовляється від повторного використання збереженої CLI-сесії, коли змінюється вибрана auth-ідентичність,
|
||||
зокрема при зміні ID auth profile, статичного API key, статичного token або OAuth-ідентичності
|
||||
облікового запису, якщо CLI її надає. Ротація OAuth access і refresh token
|
||||
не розриває збережену CLI-сесію. Якщо CLI не надає стабільного ID облікового запису OAuth,
|
||||
OpenClaw дозволяє цьому CLI самому застосовувати дозволи на відновлення.
|
||||
- `serialize: true` зберігає порядок виконання в одній lane.
|
||||
- Більшість CLI серіалізуються в одній lane провайдера.
|
||||
- OpenClaw відкидає повторне використання збереженої CLI-сесії, коли змінюється вибрана identity автентифікації,
|
||||
зокрема у разі зміни id профілю автентифікації, статичного API-ключа, статичного токена або OAuth-
|
||||
identity облікового запису, якщо CLI її надає. Ротація OAuth access і refresh token не
|
||||
обриває збережену CLI-сесію. Якщо CLI не надає стабільний OAuth account id, OpenClaw дозволяє цій CLI самій контролювати дозволи на відновлення.
|
||||
|
||||
## Зображення (наскрізна передача)
|
||||
|
||||
Якщо ваш CLI приймає шляхи до зображень, задайте `imageArg`:
|
||||
Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`:
|
||||
|
||||
```json5
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw записуватиме base64-зображення в тимчасові файли. Якщо задано `imageArg`, ці
|
||||
шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
|
||||
шляхи до файлів у prompt (впровадження шляху), чого достатньо для CLI, які автоматично
|
||||
завантажують локальні файли за звичайними шляхами.
|
||||
OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці
|
||||
шляхи передаватимуться як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
|
||||
шляхи до файлів у промпт (інжекція шляху), чого достатньо для CLI, які автоматично
|
||||
завантажують локальні файли зі звичайних шляхів.
|
||||
|
||||
## Входи / виходи
|
||||
|
||||
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ID сесії.
|
||||
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + id сесії.
|
||||
- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а
|
||||
usage — зі `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента плюс ідентифікатори сесії, коли вони присутні.
|
||||
- `output: "text"` трактує stdout як фінальну відповідь.
|
||||
usage — з `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає JSONL-потоки (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента та ідентифікатори сесії, коли вони присутні.
|
||||
- `output: "text"` розглядає stdout як фінальну відповідь.
|
||||
|
||||
Режими входу:
|
||||
Режими введення:
|
||||
|
||||
- `input: "arg"` (типово) передає prompt як останній аргумент CLI.
|
||||
- `input: "stdin"` надсилає prompt через stdin.
|
||||
- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin.
|
||||
- `input: "arg"` (типово) передає промпт як останній аргумент CLI.
|
||||
- `input: "stdin"` надсилає промпт через stdin.
|
||||
- Якщо промпт дуже довгий і задано `maxPromptArgChars`, використовується stdin.
|
||||
|
||||
## Типові значення (належать Plugin)
|
||||
## Значення за замовчуванням (керуються Plugin)
|
||||
|
||||
Bundled OpenAI Plugin також реєструє типове значення для `codex-cli`:
|
||||
Вбудований Plugin OpenAI також реєструє типові значення для `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -259,7 +248,7 @@ Bundled OpenAI Plugin також реєструє типове значення
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
Bundled Google Plugin також реєструє типове значення для `google-gemini-cli`:
|
||||
Вбудований Plugin Google також реєструє типові значення для `google-gemini-cli`:
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -277,25 +266,25 @@ Bundled Google Plugin також реєструє типове значення
|
||||
Примітки щодо JSON Gemini CLI:
|
||||
|
||||
- Текст відповіді читається з поля JSON `response`.
|
||||
- Usage повертається до `stats`, коли `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується в `cacheRead` OpenClaw.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
|
||||
- Usage резервно береться з `stats`, коли `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів з
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`).
|
||||
Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`).
|
||||
|
||||
## Типові значення, що належать Plugin
|
||||
## Значення за замовчуванням, що належать Plugin
|
||||
|
||||
Типові значення CLI backend тепер є частиною поверхні Plugin:
|
||||
Типові значення CLI-бекендів тепер є частиною поверхні Plugin:
|
||||
|
||||
- Plugins реєструють їх через `api.registerCliBackend(...)`.
|
||||
- `id` backend стає префіксом провайдера в model refs.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` усе ще перевизначає типове значення Plugin.
|
||||
- Очищення конфігурації, специфічної для backend, і далі належить Plugin через необов’язковий
|
||||
- `id` бекенда стає префіксом провайдера в посиланнях моделей.
|
||||
- Користувацька конфігурація в `agents.defaults.cliBackends.<id>` усе ще перевизначає типове значення Plugin.
|
||||
- Очищення конфігурації, специфічне для бекенда, залишається у власності Plugin через необов’язковий
|
||||
hook `normalizeConfig`.
|
||||
|
||||
Plugins, яким потрібні невеликі сумісні shim-перетворення prompt/повідомлень, можуть оголошувати
|
||||
двобічні текстові перетворення без заміни провайдера чи CLI backend:
|
||||
Plugins, яким потрібні невеликі шими сумісності промптів/повідомлень, можуть оголошувати
|
||||
двоспрямовані текстові трансформації без заміни провайдера або CLI-бекенда:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -312,52 +301,54 @@ api.registerTextTransforms({
|
||||
});
|
||||
```
|
||||
|
||||
`input` переписує системний prompt і prompt користувача, що передаються до CLI. `output`
|
||||
переписує потокові assistant deltas і розібраний фінальний текст до того, як OpenClaw обробить
|
||||
власні control markers і доставку в канали.
|
||||
`input` переписує системний промпт і користувацький промпт, що передаються до CLI. `output`
|
||||
переписує стримінгові дельти асистента та розібраний фінальний текст до того, як OpenClaw обробить
|
||||
власні керівні маркери та доставку в канал.
|
||||
|
||||
Для CLI, які надсилають JSONL, сумісний зі stream-json Claude Code, встановіть
|
||||
`jsonlDialect: "claude-stream-json"` у конфігурації цього backend.
|
||||
Для CLI, які виводять JSONL, сумісний із Claude Code stream-json, задайте
|
||||
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда.
|
||||
|
||||
## Bundle MCP overlays
|
||||
## Накладки bundle MCP
|
||||
|
||||
CLI backends **не** отримують виклики інструментів OpenClaw напряму, але backend може
|
||||
добровільно ввімкнути згенерований накладний MCP-конфіг через `bundleMcp: true`.
|
||||
CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
|
||||
увімкнути згенеровану накладку конфігурації MCP через `bundleMcp: true`.
|
||||
|
||||
Поточна bundled-поведінка:
|
||||
Поточна вбудована поведінка:
|
||||
|
||||
- `claude-cli`: згенерований строгий MCP config file
|
||||
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`
|
||||
- `claude-cli`: згенерований строгий конфігураційний файл MCP
|
||||
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`; згенерований
|
||||
loopback-сервер OpenClaw позначається режимом схвалення інструментів Codex для кожного сервера,
|
||||
щоб виклики MCP не зависали через локальні запити на схвалення
|
||||
- `google-gemini-cli`: згенерований файл системних налаштувань Gemini
|
||||
|
||||
Коли bundle MCP увімкнено, OpenClaw:
|
||||
|
||||
- запускає loopback HTTP MCP server, який надає gateway tools процесу CLI
|
||||
- автентифікує bridge токеном для конкретної сесії (`OPENCLAW_MCP_TOKEN`)
|
||||
- запускає loopback HTTP MCP-сервер, який надає інструменти шлюзу процесу CLI
|
||||
- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`)
|
||||
- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
|
||||
- завантажує увімкнені bundle-MCP server для поточного робочого простору
|
||||
- об’єднує їх з будь-якою наявною MCP config/settings-структурою backend
|
||||
- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить backend, із розширення-власника
|
||||
- завантажує увімкнені bundle-MCP сервери для поточного робочого простору
|
||||
- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенда
|
||||
- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду, з відповідного extension
|
||||
|
||||
Якщо жоден MCP server не ввімкнено, OpenClaw усе одно впроваджує сувору конфігурацію, коли
|
||||
backend добровільно використовує bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно інжектує строгий конфіг, коли
|
||||
бекенд використовує bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у
|
||||
протокол CLI backend. Backends бачать інструменти gateway лише тоді, коли добровільно ввімкнули
|
||||
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у
|
||||
протокол CLI-бекенда. Бекенди бачать інструменти шлюзу лише тоді, коли використовують
|
||||
`bundleMcp: true`.
|
||||
- **Streaming залежить від backend.** Деякі backends передають JSONL потоком; інші буферизують
|
||||
усе до завершення.
|
||||
- **Структуровані виходи** залежать від формату JSON конкретного CLI.
|
||||
- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
|
||||
структуровано, ніж початковий запуск із `--json`. Сесії OpenClaw при цьому все одно працюють
|
||||
- **Стримінг залежить від бекенда.** Деякі бекенди стримлять JSONL; інші буферизують
|
||||
дані до завершення.
|
||||
- **Структуровані виходи** залежать від JSON-формату CLI.
|
||||
- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що є менш
|
||||
структурованим, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють
|
||||
нормально.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
- **CLI не знайдено**: задайте `command` як повний шлях.
|
||||
- **Неправильна назва моделі**: використовуйте `modelAliases` для зіставлення `provider/model` → моделі CLI.
|
||||
- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не має значення
|
||||
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
|
||||
- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює
|
||||
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,30 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати вбудований harness app-server Codex
|
||||
- Вам потрібні model refs Codex і приклади конфігурації
|
||||
- Ви хочете вимкнути fallback PI для розгортань лише з Codex
|
||||
summary: Запуск вбудованих ходів агента OpenClaw через вбудований harness app-server Codex
|
||||
title: Harness Codex
|
||||
- Ви хочете використовувати комплектний harness app-server Codex.
|
||||
- Вам потрібні посилання на модель Codex і приклади конфігурації.
|
||||
- Ви хочете вимкнути резервне перемикання на PI для розгортань лише з Codex.
|
||||
summary: Запускайте вбудовані ходи агента OpenClaw через комплектний harness app-server Codex.
|
||||
title: harness Codex
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:02:22Z"
|
||||
generated_at: "2026-04-23T21:58:44Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 65e96ac709a7996878037da3ffb8903cdd3ad83bb5de75c47ab2f0a08882098c
|
||||
source_hash: 27b7b662c5eb2002fed8d2c752c4227a46a89d767ac838138327e64df84e4919
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Вбудований Plugin `codex` дозволяє OpenClaw виконувати вбудовані ходи агента через
|
||||
app-server Codex замість вбудованого harness PI.
|
||||
Комплектний Plugin `codex` дозволяє OpenClaw виконувати вбудовані ходи агента через app-server Codex замість вбудованого harness PI.
|
||||
|
||||
Використовуйте це, коли хочете, щоб Codex володів низькорівневою сесією агента: виявленням
|
||||
моделей, native thread resume, native compaction і виконанням app-server.
|
||||
OpenClaw усе ще володіє chat channels, файлами сесій, вибором моделі, tools,
|
||||
approvals, доставкою медіа та видимим дзеркалом transcript.
|
||||
Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативним Compaction і виконанням через app-server.
|
||||
OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами,
|
||||
погодженнями, доставкою медіа та видимим дзеркалом транскрипту.
|
||||
|
||||
Native-ходи Codex також поважають спільні plugin hooks, тож prompt shim-и,
|
||||
автоматизація з урахуванням compaction, middleware tools і lifecycle observers
|
||||
залишаються узгодженими з harness PI:
|
||||
Нативні ходи Codex також поважають спільні хуки Plugin, тож shim-и промптів,
|
||||
автоматизація з урахуванням Compaction, middleware інструментів і спостерігачі життєвого циклу залишаються
|
||||
узгодженими з harness PI:
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
@ -33,59 +31,65 @@ Native-ходи Codex також поважають спільні plugin hooks,
|
||||
- `before_message_write`
|
||||
- `agent_end`
|
||||
|
||||
Вбудовані plugins також можуть реєструвати factory розширення app-server Codex для додавання
|
||||
асинхронного middleware `tool_result`.
|
||||
Комплектні plugins також можуть реєструвати factory розширення app-server Codex, щоб додавати
|
||||
асинхронний middleware `tool_result`.
|
||||
|
||||
Harness типово вимкнений. Нові конфігурації мають залишати refs моделей OpenAI
|
||||
канонічними як `openai/gpt-*` і явно примусово задавати
|
||||
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли
|
||||
потрібне native-виконання через app-server. Legacy refs моделей `codex/*` усе ще автоматично вибирають
|
||||
harness вимкнено за замовчуванням. Нові конфігурації мають зберігати посилання на моделі OpenAI
|
||||
канонічними як `openai/gpt-*` і явно примусово встановлювати
|
||||
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм
|
||||
потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*` усе ще автоматично вибирають
|
||||
harness для сумісності.
|
||||
|
||||
## Виберіть правильний префікс моделі
|
||||
|
||||
Тепер OpenClaw зберігає refs моделей OpenAI GPT канонічними як `openai/*`:
|
||||
Тепер OpenClaw зберігає посилання на моделі OpenAI GPT канонічними як `openai/*`:
|
||||
|
||||
| Ref моделі | Шлях runtime | Використовуйте, коли |
|
||||
| ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| `openai/gpt-5.5` | provider OpenAI через OpenClaw/PI plumbing | Вам потрібен прямий доступ до OpenAI Platform API через `OPENAI_API_KEY`. |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне native-виконання через app-server Codex для вбудованого ходу агента. |
|
||||
| Посилання на модель | Шлях runtime | Використовуйте, коли |
|
||||
| --------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.5` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Ви хочете прямий доступ до OpenAI Platform API за допомогою `OPENAI_API_KEY`. |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Ви хочете нативне виконання через app-server Codex для вбудованого ходу агента. |
|
||||
|
||||
Legacy refs `openai-codex/gpt-*` і `codex/gpt-*` усе ще приймаються як
|
||||
compatibility alias-и, але нові приклади документації/конфігурації мають використовувати `openai/gpt-*`.
|
||||
Застарілі посилання `openai-codex/gpt-*` і `codex/gpt-*` як і раніше приймаються як
|
||||
аліаси сумісності, але нові приклади в документації/конфігурації мають використовувати `openai/gpt-*`.
|
||||
|
||||
Вибір harness — це не механізм керування live session. Коли виконується вбудований хід,
|
||||
OpenClaw записує id вибраного harness у цій сесії й продовжує використовувати його для
|
||||
наступних ходів у тому самому id сесії. Змінюйте конфігурацію `embeddedHarness` або
|
||||
Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо
|
||||
вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness`
|
||||
і перегляньте структурований запис gateway `agent harness selected`. Він
|
||||
містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і,
|
||||
у режимі `auto`, результат підтримки кожного кандидата Plugin.
|
||||
|
||||
Вибір harness не є елементом керування живою сесією. Коли виконується вбудований хід,
|
||||
OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для
|
||||
наступних ходів у тому самому ідентифікаторі сесії. Змінюйте конфігурацію `embeddedHarness` або
|
||||
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness;
|
||||
використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням уже наявної
|
||||
розмови між PI і Codex. Це запобігає повторному програванню одного transcript через
|
||||
дві несумісні native session systems.
|
||||
використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної
|
||||
розмови між PI і Codex. Це дозволяє уникнути відтворення одного транскрипту через
|
||||
дві несумісні нативні системи сесій.
|
||||
|
||||
Legacy sessions, створені до появи pins harness, вважаються прив’язаними до PI, щойно
|
||||
мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на
|
||||
Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них
|
||||
з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на
|
||||
Codex після зміни конфігурації.
|
||||
|
||||
`/status` показує ефективний non-PI harness поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Типовий harness PI лишається `Runner: pi (embedded)` і
|
||||
не додає окремий badge harness.
|
||||
`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад
|
||||
`Fast · codex`. harness PI за замовчуванням і далі відображається як `Runner: pi (embedded)` і
|
||||
не додає окремого бейджа harness.
|
||||
|
||||
## Вимоги
|
||||
|
||||
- OpenClaw із доступним вбудованим Plugin `codex`.
|
||||
- Codex app-server `0.118.0` або новіший.
|
||||
- Auth Codex, доступна для процесу app-server.
|
||||
- OpenClaw із доступним комплектним Plugin `codex`.
|
||||
- app-server Codex `0.118.0` або новіший.
|
||||
- Автентифікація Codex, доступна процесу app-server.
|
||||
|
||||
Plugin блокує старіші або безверсійні handshakes app-server. Це тримає
|
||||
OpenClaw у межах тієї поверхні протоколу, з якою його було протестовано.
|
||||
Plugin блокує старіші або безверсійні handshake app-server. Це гарантує, що
|
||||
OpenClaw працює з поверхнею протоколу, на якій його було протестовано.
|
||||
|
||||
Для live- і Docker smoke tests auth зазвичай надходить із `OPENAI_API_KEY`, плюс
|
||||
необов’язкові файли Codex CLI, такі як `~/.codex/auth.json` і
|
||||
`~/.codex/config.toml`. Використовуйте той самий auth material, який використовує ваш локальний Codex app-server.
|
||||
Для 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 і примусово встановіть harness `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -108,7 +112,7 @@ OpenClaw у межах тієї поверхні протоколу, з якою
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ваша конфігурація використовує `plugins.allow`, включіть туди й `codex`:
|
||||
Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -123,15 +127,15 @@ OpenClaw у межах тієї поверхні протоколу, з якою
|
||||
}
|
||||
```
|
||||
|
||||
Legacy-конфігурації, які задають `agents.defaults.model` або модель агента як
|
||||
`codex/<model>`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають
|
||||
надавати перевагу `openai/<model>` плюс явному запису `embeddedHarness` вище.
|
||||
Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента як
|
||||
`codex/<model>`, як і раніше автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають
|
||||
надавати перевагу `openai/<model>` разом із явним записом `embeddedHarness`, наведеним вище.
|
||||
|
||||
## Додати Codex без заміни інших моделей
|
||||
## Додайте Codex, не замінюючи інші моделі
|
||||
|
||||
Залишайте `runtime: "auto"`, коли хочете, щоб legacy refs `codex/*` вибирали Codex, а
|
||||
PI — усе інше. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для
|
||||
агентів, які мають використовувати harness.
|
||||
Зберігайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а
|
||||
PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для
|
||||
агентів, які мають використовувати цей harness.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -161,15 +165,15 @@ PI — усе інше. Для нових конфігурацій надава
|
||||
}
|
||||
```
|
||||
|
||||
За такої форми:
|
||||
За такої структури:
|
||||
|
||||
- `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації.
|
||||
- `/model opus` використовує шлях provider-а Anthropic.
|
||||
- Якщо вибрано non-Codex model, PI лишається harness сумісності.
|
||||
- `/model opus` використовує шлях провайдера Anthropic.
|
||||
- Якщо вибрано не-Codex модель, PI залишається harness сумісності.
|
||||
|
||||
## Розгортання лише з Codex
|
||||
|
||||
Вимкніть fallback PI, коли потрібно довести, що кожен вбудований хід агента використовує
|
||||
Вимкніть fallback на PI, коли вам потрібно гарантувати, що кожен вбудований хід агента використовує
|
||||
harness Codex:
|
||||
|
||||
```json5
|
||||
@ -186,7 +190,7 @@ harness Codex:
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення через середовище:
|
||||
Перевизначення через змінні середовища:
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -194,13 +198,13 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Коли fallback вимкнено, OpenClaw одразу завершується з помилкою, якщо Plugin Codex вимкнено,
|
||||
app-server занадто старий або app-server не вдається запустити.
|
||||
Якщо fallback вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено,
|
||||
app-server занадто старий або app-server не може запуститися.
|
||||
|
||||
## Codex для окремого агента
|
||||
|
||||
Ви можете зробити одного агента Codex-only, тоді як типовий агент зберігатиме звичайне
|
||||
автовибрання:
|
||||
Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний
|
||||
автовибір:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -231,15 +235,15 @@ app-server занадто старий або app-server не вдається
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює свіжу
|
||||
Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову
|
||||
сесію OpenClaw, а harness Codex створює або відновлює свій sidecar app-server
|
||||
thread за потреби. `/reset` очищає прив’язку сесії OpenClaw до цього thread
|
||||
і дозволяє наступному ходу знову розв’язати harness з поточної конфігурації.
|
||||
потік за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку
|
||||
і дозволяє наступному ходу знову визначити harness із поточної конфігурації.
|
||||
|
||||
## Виявлення моделей
|
||||
|
||||
Типово Plugin Codex запитує app-server про доступні моделі. Якщо
|
||||
виявлення не вдається або спливає timeout, він використовує вбудований fallback catalog для:
|
||||
За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо
|
||||
виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для:
|
||||
|
||||
- GPT-5.5
|
||||
- GPT-5.4 mini
|
||||
@ -265,8 +269,8 @@ thread за потреби. `/reset` очищає прив’язку сесії
|
||||
}
|
||||
```
|
||||
|
||||
Вимкніть виявлення, якщо хочете, щоб startup не виконував probe Codex і лишався на
|
||||
fallback catalog:
|
||||
Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався
|
||||
резервний каталог:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -287,19 +291,19 @@ fallback catalog:
|
||||
|
||||
## Підключення app-server і політика
|
||||
|
||||
Типово Plugin запускає Codex локально так:
|
||||
За замовчуванням Plugin запускає Codex локально за допомогою:
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
Типово OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
|
||||
За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
|
||||
`approvalPolicy: "never"`, `approvalsReviewer: "user"` і
|
||||
`sandbox: "danger-full-access"`. Це довірена локальна операторська позиція, яка використовується
|
||||
для автономних heartbeat: Codex може користуватися shell і network tools без
|
||||
зупинки на native approval prompts, на які нікому відповідати.
|
||||
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується
|
||||
для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без
|
||||
зупинки на нативних запитах на погодження, на які нікому відповідати.
|
||||
|
||||
Щоб увімкнути перевірювані Guardian approvals у Codex, задайте `appServer.mode:
|
||||
Щоб увімкнути погодження Codex, які перевіряє Guardian, встановіть `appServer.mode:
|
||||
"guardian"`:
|
||||
|
||||
```json5
|
||||
@ -320,9 +324,9 @@ codex app-server --listen stdio://
|
||||
}
|
||||
```
|
||||
|
||||
Guardian — це native reviewer approvals у Codex. Коли Codex просить вийти із sandbox, писати поза workspace або додати дозволи на кшталт доступу до мережі, Codex спрямовує цей approval request до reviewer subagent-а, а не до prompt людини. Reviewer застосовує risk framework Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але все ще потрібно, щоб unattended agents могли просуватися далі.
|
||||
Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти з sandbox, записати за межі workspace або додати дозволи, як-от доступ до мережі, Codex надсилає цей запит на погодження рецензенту-підагенту замість запиту людині. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібні суворіші запобіжники, ніж у режимі YOLO, але ви все одно хочете, щоб агенти без нагляду могли просуватися далі.
|
||||
|
||||
Preset `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики все одно перевизначають `mode`, тому в розширених розгортаннях можна змішувати preset з явними виборами.
|
||||
Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, перевизначають `mode`, тож у розширених розгортаннях можна поєднувати цей пресет із явними параметрами.
|
||||
|
||||
Для вже запущеного app-server використовуйте транспорт WebSocket:
|
||||
|
||||
@ -348,22 +352,22 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`,
|
||||
|
||||
Підтримувані поля `appServer`:
|
||||
|
||||
| Поле | Типове значення | Значення |
|
||||
| ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` породжує Codex; `"websocket"` підключається до `url`. |
|
||||
| `command` | `"codex"` | Executable для транспорту stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
|
||||
| `url` | не задано | URL WebSocket app-server. |
|
||||
| `authToken` | не задано | Bearer token для транспорту WebSocket. |
|
||||
| `headers` | `{}` | Додаткові заголовки WebSocket. |
|
||||
| `requestTimeoutMs` | `60000` | Timeout для викликів control-plane app-server. |
|
||||
| `mode` | `"yolo"` | Preset для YOLO або виконання з approvals, перевірюваними Guardian. |
|
||||
| `approvalPolicy` | `"never"` | Native approval policy Codex, що надсилається під час start/resume/turn thread. |
|
||||
| `sandbox` | `"danger-full-access"` | Native sandbox mode Codex, що надсилається під час start/resume. |
|
||||
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Codex Guardian перевіряв prompts. |
|
||||
| `serviceTier` | не задано | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Невалідні legacy values ігноруються. |
|
||||
| Поле | За замовчуванням | Значення |
|
||||
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
|
||||
| `command` | `"codex"` | Виконуваний файл для транспорту stdio. |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
|
||||
| `url` | не задано | URL app-server WebSocket. |
|
||||
| `authToken` | не задано | Bearer-токен для транспорту WebSocket. |
|
||||
| `headers` | `{}` | Додаткові заголовки WebSocket. |
|
||||
| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. |
|
||||
| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою Guardian. |
|
||||
| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час запуску/відновлення потоку/ходу. |
|
||||
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. |
|
||||
| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Guardian Codex перевіряв запити. |
|
||||
| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
|
||||
|
||||
Старіші змінні середовища все ще працюють як fallback для локального тестування, коли
|
||||
Старіші змінні середовища, як і раніше, працюють як fallback для локального тестування, коли
|
||||
відповідне поле конфігурації не задано:
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
@ -372,15 +376,15 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`,
|
||||
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
|
||||
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Використовуйте
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"` натомість, або
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація
|
||||
є кращою для повторюваних розгортань, оскільки зберігає поведінку plugin у тому самому
|
||||
перевіреному файлі, що й решта налаштування harness Codex.
|
||||
є кращим варіантом для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у
|
||||
тому самому перевіреному файлі, що й решта налаштування harness Codex.
|
||||
|
||||
## Поширені рецепти
|
||||
|
||||
Локальний Codex з типовим транспортом stdio:
|
||||
Локальний Codex із транспортом stdio за замовчуванням:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -394,7 +398,7 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`,
|
||||
}
|
||||
```
|
||||
|
||||
Перевірка harness лише з Codex, з вимкненим fallback PI:
|
||||
Перевірка harness лише для Codex із вимкненим fallback на PI:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -411,7 +415,7 @@ Preset `guardian` розгортається в `approvalPolicy: "on-request"`,
|
||||
}
|
||||
```
|
||||
|
||||
Approvals Codex, перевірювані Guardian:
|
||||
Погодження Codex, перевірені Guardian:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -433,7 +437,7 @@ Approvals Codex, перевірювані Guardian:
|
||||
}
|
||||
```
|
||||
|
||||
Віддалений app-server з явними headers:
|
||||
Віддалений app-server із явними заголовками:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -457,86 +461,91 @@ Approvals Codex, перевірювані Guardian:
|
||||
```
|
||||
|
||||
Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано
|
||||
до наявного thread Codex, наступний хід знову надсилає до
|
||||
app-server поточні вибрані OpenClaw модель OpenAI, provider, approval policy, sandbox і service tier.
|
||||
Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до thread, але просить Codex продовжити з новою вибраною моделлю.
|
||||
до наявного потоку Codex, наступний хід знову надсилає до
|
||||
app-server поточну вибрану модель OpenAI, провайдера, політику погодження, sandbox і service tier.
|
||||
Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку
|
||||
до потоку, але просить Codex продовжити з новою вибраною моделлю.
|
||||
|
||||
## Команда Codex
|
||||
|
||||
Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона
|
||||
загальна й працює на будь-якому каналі, який підтримує текстові команди OpenClaw.
|
||||
Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є
|
||||
універсальною та працює в будь-якому каналі, який підтримує текстові команди OpenClaw.
|
||||
|
||||
Поширені форми:
|
||||
|
||||
- `/codex status` показує live-підключення до app-server, моделі, обліковий запис, rate limits, MCP servers і skills.
|
||||
- `/codex models` показує live-моделі app-server Codex.
|
||||
- `/codex threads [filter]` показує список недавніх thread-ів Codex.
|
||||
- `/codex resume <thread-id>` прив’язує поточну сесію OpenClaw до наявного thread Codex.
|
||||
- `/codex compact` просить app-server Codex виконати compaction для прив’язаного thread.
|
||||
- `/codex review` запускає native review Codex для прив’язаного thread.
|
||||
- `/codex account` показує стан облікового запису й rate-limit.
|
||||
- `/codex mcp` показує стан MCP server app-server Codex.
|
||||
- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills.
|
||||
- `/codex models` показує список поточних моделей app-server Codex.
|
||||
- `/codex threads [filter]` показує список нещодавніх потоків Codex.
|
||||
- `/codex resume <thread-id>` прив’язує поточну сесію OpenClaw до наявного потоку Codex.
|
||||
- `/codex compact` просить app-server Codex виконати Compaction прив’язаного потоку.
|
||||
- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку.
|
||||
- `/codex account` показує стан облікового запису та лімітів швидкості.
|
||||
- `/codex mcp` показує стан MCP-сервера app-server Codex.
|
||||
- `/codex skills` показує skills app-server Codex.
|
||||
|
||||
`/codex resume` записує той самий файл прив’язки sidecar, який harness використовує для
|
||||
звичайних ходів. У наступному повідомленні OpenClaw відновить цей thread Codex, передасть
|
||||
поточну вибрану в OpenClaw модель `codex/*` в app-server і збереже
|
||||
розширену історію ввімкненою.
|
||||
`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для
|
||||
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає
|
||||
поточну вибрану модель OpenClaw до app-server і зберігає
|
||||
увімкнену розширену історію.
|
||||
|
||||
Поверхня команд вимагає Codex app-server `0.118.0` або новішого. Окремі
|
||||
control-методи показуються як `unsupported by this Codex app-server`, якщо
|
||||
майбутній або custom app-server не відкриває цей JSON-RPC method.
|
||||
Поверхня команд вимагає app-server Codex `0.118.0` або новішої версії. Окремі
|
||||
методи керування повідомляються як `unsupported by this Codex app-server`, якщо
|
||||
майбутній або кастомний app-server не надає цей метод JSON-RPC.
|
||||
|
||||
## Tools, media і Compaction
|
||||
## Інструменти, медіа та Compaction
|
||||
|
||||
Harness Codex змінює лише низькорівневий виконавець вбудованого агента.
|
||||
harness Codex змінює лише низькорівневий виконавець вбудованого агента.
|
||||
|
||||
OpenClaw і далі будує список tools і отримує динамічні результати tools від
|
||||
harness. Текст, зображення, відео, музика, TTS, approvals і вивід messaging-tool
|
||||
продовжують проходити звичайним шляхом доставки OpenClaw.
|
||||
OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від
|
||||
harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями
|
||||
і далі проходять через звичайний шлях доставки OpenClaw.
|
||||
|
||||
Elicitation approval для інструментів MCP Codex маршрутизується через потік
|
||||
approval plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
|
||||
`"mcp_tool_call"`; інші elicitation- і free-form input-запити все ще завершуються в закритий спосіб.
|
||||
Запити на погодження інструментів MCP Codex маршрутизуються через потік
|
||||
погодження Plugin в OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
|
||||
`"mcp_tool_call"`; інші запити на підтвердження та запити на довільне введення, як і раніше, завершуються
|
||||
безпечною відмовою.
|
||||
|
||||
Коли вибрана модель використовує harness Codex, native compaction thread
|
||||
делегується app-server Codex. OpenClaw зберігає transcript mirror для історії каналів,
|
||||
пошуку, `/new`, `/reset` і майбутнього перемикання моделей або harness. Mirror
|
||||
містить prompt користувача, фінальний текст асистента та полегшені записи reasoning або plan від Codex, коли app-server їх генерує. Наразі OpenClaw записує лише сигнали початку й завершення native compaction. Він ще не показує
|
||||
людинозрозуміле зведення compaction або придатний до аудиту список того, які записи Codex
|
||||
залишив після compaction.
|
||||
Коли вибрана модель використовує harness Codex, нативний Compaction потоку
|
||||
делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу,
|
||||
пошуку, `/new`, `/reset` і майбутнього перемикання моделей або harness. Дзеркало
|
||||
включає промпт користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли їх генерує app-server. Наразі OpenClaw записує лише сигнали початку та завершення нативного Compaction. Він поки що не показує
|
||||
людинозрозумілий підсумок Compaction або перевірний список того, які записи Codex
|
||||
зберіг після Compaction.
|
||||
|
||||
Генерація медіа не потребує PI. Зображення, відео, музика, PDF, TTS і розуміння медіа
|
||||
і далі використовують відповідні налаштування provider/model, як-от
|
||||
Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і
|
||||
розуміння медіа, як і раніше, використовує відповідні налаштування провайдера/моделі, такі як
|
||||
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і
|
||||
`messages.tts`.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`,
|
||||
задайте ref моделі `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`.
|
||||
виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або
|
||||
застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`.
|
||||
|
||||
**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не взяв на себе цей запуск,
|
||||
OpenClaw може використати PI як backend сумісності. Задайте
|
||||
`embeddedHarness.runtime: "codex"`, щоб примусово вибирати Codex під час тестування, або
|
||||
`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден harness plugin не підходить. Щойно вибрано app-server Codex, його збої показуються напряму без додаткової
|
||||
конфігурації fallback.
|
||||
**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не заявляє про запуск,
|
||||
OpenClaw може використовувати PI як backend сумісності. Установіть
|
||||
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або
|
||||
`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли не підходить жоден harness Plugin. Щойно
|
||||
буде вибрано app-server Codex, його помилки відображатимуться безпосередньо без додаткового
|
||||
налаштування fallback.
|
||||
|
||||
**App-server відхиляється:** оновіть Codex так, щоб handshake app-server
|
||||
**app-server відхиляється:** оновіть Codex, щоб handshake app-server
|
||||
повідомляв версію `0.118.0` або новішу.
|
||||
|
||||
**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
або вимкніть виявлення.
|
||||
|
||||
**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken`
|
||||
і що віддалений app-server говорить тією самою версією протоколу app-server Codex.
|
||||
і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex.
|
||||
|
||||
**Non-Codex model використовує PI:** це очікувано. Harness Codex бере на себе
|
||||
лише refs моделей `codex/*`.
|
||||
**Не-Codex модель використовує PI:** це очікувана поведінка, якщо ви не примусово встановили
|
||||
`embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні
|
||||
`openai/gpt-*` та посилання інших провайдерів залишаються на своєму стандартному шляху провайдера.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Agent Harness Plugins](/uk/plugins/sdk-agent-harness)
|
||||
- [Model Providers](/uk/concepts/model-providers)
|
||||
- [Configuration Reference](/uk/gateway/configuration-reference)
|
||||
- [Testing](/uk/help/testing#live-codex-app-server-harness-smoke)
|
||||
- [Plugins harness агента](/uk/plugins/sdk-agent-harness)
|
||||
- [Провайдери моделей](/uk/concepts/model-providers)
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference)
|
||||
- [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,56 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви змінюєте вбудований runtime агента або реєстр harness
|
||||
- Ви реєструєте agent harness із вбудованого або довіреного Plugin
|
||||
- Вам потрібно зрозуміти, як Plugin Codex пов’язаний із provider моделей
|
||||
- Ви змінюєте вбудоване середовище виконання агента або реєстр каркаса агента
|
||||
- Ви реєструєте каркас агента з комплектного або довіреного плагіна
|
||||
- Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей
|
||||
sidebarTitle: Agent Harness
|
||||
summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневий вбудований виконавець агента
|
||||
title: Plugins для agent harness
|
||||
summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента
|
||||
title: Плагіни каркаса агента
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:02:42Z"
|
||||
generated_at: "2026-04-23T21:58:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 69d0c4febbc0f0397d4fc8a212039a2d78764798b82f48e600daf68626826904
|
||||
source_hash: 966d685627b11651fbd0c7fe00a7e3e412c14b39511845ecfcdc4366fa9f8767
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Agent harness — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не provider моделі, не канал і не реєстр tools.
|
||||
**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів.
|
||||
|
||||
Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт
|
||||
усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний
|
||||
вбудований runner.
|
||||
Використовуйте цю поверхню лише для комплектних або довірених native-плагінів. Контракт усе ще є експериментальним, тому що типи параметрів навмисно віддзеркалюють поточний вбудований раннер.
|
||||
|
||||
## Коли використовувати harness
|
||||
## Коли використовувати каркас
|
||||
|
||||
Реєструйте agent harness, коли сімейство моделей має власний нативний runtime
|
||||
сесії, а звичайний транспорт provider OpenClaw є неправильною абстракцією.
|
||||
Реєструйте каркас агента, коли сімейство моделей має власне native-середовище виконання сесії, а звичайний транспорт постачальника OpenClaw є неправильною абстракцією.
|
||||
|
||||
Приклади:
|
||||
|
||||
- нативний сервер coding-agent, який володіє threads і Compaction
|
||||
- локальний CLI або daemon, який має передавати нативні події plan/reasoning/tool через streaming
|
||||
- runtime моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw
|
||||
- native-сервер агента для кодування, який керує потоками та Compaction
|
||||
- локальний CLI або демон, який має транслювати native-події плану/міркування/інструментів
|
||||
- середовище виконання моделі, якому потрібен власний resume id на додачу до стенограми сесії OpenClaw
|
||||
|
||||
**Не** реєструйте harness лише для додавання нового LLM API. Для звичайних HTTP- або
|
||||
WebSocket-API моделей створюйте [provider plugin](/uk/plugins/sdk-provider-plugins).
|
||||
**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP- або WebSocket-API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins).
|
||||
|
||||
## Чим і далі володіє core
|
||||
## Чим усе ще керує ядро
|
||||
|
||||
До вибору harness OpenClaw уже розв’язав:
|
||||
Перш ніж буде вибрано каркас, OpenClaw уже визначив:
|
||||
|
||||
- provider і model
|
||||
- стан auth runtime
|
||||
- рівень thinking і бюджет контексту
|
||||
- транскрипт/файл сесії OpenClaw
|
||||
- робочий простір, sandbox і політику tools
|
||||
- callback для відповідей каналу й callback для streaming
|
||||
- fallback моделі та політику перемикання live-моделі
|
||||
- постачальника та модель
|
||||
- стан автентифікації середовища виконання
|
||||
- рівень міркування та бюджет контексту
|
||||
- файл стенограми/сесії OpenClaw
|
||||
- робочий простір, sandbox і політику інструментів
|
||||
- зворотні виклики відповіді каналу та зворотні виклики потокової передачі
|
||||
- політику резервного переходу моделі та перемикання live-моделей
|
||||
|
||||
Такий розподіл є навмисним. Harness виконує підготовлену спробу; він не вибирає
|
||||
providers, не замінює доставку каналом і не перемикає моделі мовчки.
|
||||
Цей розподіл навмисний. Каркас виконує підготовлену спробу; він не вибирає постачальників, не замінює доставку каналу і не перемикає моделі непомітно.
|
||||
|
||||
## Реєстрація harness
|
||||
## Зареєструвати каркас
|
||||
|
||||
**Імпорт:** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -88,96 +83,54 @@ export default definePluginEntry({
|
||||
|
||||
## Політика вибору
|
||||
|
||||
OpenClaw вибирає harness після розв’язання provider/model:
|
||||
OpenClaw вибирає каркас після визначення постачальника/моделі:
|
||||
|
||||
1. Зафіксований id harness у наявній сесії має пріоритет, щоб зміни config/env
|
||||
не перемикали цей транскрипт гарячим способом на інший runtime.
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово задає зареєстрований harness з цим id для
|
||||
сесій, які ще не закріплені.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований harness PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness, чи підтримують вони
|
||||
розв’язаний provider/model.
|
||||
5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback PI
|
||||
не вимкнено.
|
||||
1. Записаний id каркаса наявної сесії має пріоритет, щоб зміни config/env не перемикали цю стенограму на інше середовище виконання «на гарячу».
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово задає зареєстрований каркас із цим id для сесій, які ще не закріплені.
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI.
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони визначеного постачальника/модель.
|
||||
5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено.
|
||||
|
||||
Збої harness Plugin проявляються як збої запуску. У режимі `auto` fallback PI
|
||||
використовується лише тоді, коли жоден зареєстрований Plugin harness не підтримує розв’язаний
|
||||
provider/model. Щойно Plugin harness узяв run, OpenClaw не
|
||||
програє той самий хід через PI, оскільки це може змінити семантику auth/runtime
|
||||
або дублювати побічні ефекти.
|
||||
Збої каркаса плагіна відображаються як збої виконання. У режимі `auto` резервний перехід на PI використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного постачальника/модель. Щойно каркас плагіна взяв на себе виконання, OpenClaw не відтворює той самий хід через PI, тому що це може змінити семантику автентифікації/середовища виконання або спричинити дублювання побічних ефектів.
|
||||
|
||||
Вибраний id harness зберігається разом з id сесії після вбудованого запуску.
|
||||
Застарілі сесії, створені до закріплення harness, трактуються як закріплені за PI, щойно
|
||||
в них з’являється історія транскрипту. Використовуйте нову/скинуту сесію під час перемикання між PI і
|
||||
нативним Plugin harness. `/status` показує нетипові id harness, такі як `codex`,
|
||||
поруч із `Fast`; PI не показується, бо це типовий сумісний шлях.
|
||||
Вибраний id каркаса зберігається разом з id сесії після вбудованого виконання. Застарілі сесії, створені до закріплення каркасів, вважаються закріпленими за PI, щойно в них з’являється історія стенограми. Використовуйте нову/скинуту сесію під час перемикання між PI та native-каркасом плагіна. `/status` показує нестандартні id каркасів, такі як `codex`, поруч із `Fast`; PI приховано, тому що це стандартний шлях сумісності. Якщо вибраний каркас виглядає неочікуваним, увімкніть журналювання налагодження `agents/harness` і перевірте структурований запис шлюзу `agent harness selected`. Він містить id вибраного каркаса, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата-плагіна.
|
||||
|
||||
Вбудований Plugin Codex реєструє `codex` як свій id harness. Core трактує це
|
||||
як звичайний id harness Plugin; псевдоніми, специфічні для Codex, мають належати в Plugin
|
||||
або в конфігурацію оператора, а не в спільний selector runtime.
|
||||
Комплектний плагін Codex реєструє `codex` як свій id каркаса. Ядро розглядає його як звичайний id каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну або config оператора, а не спільному селектору середовища виконання.
|
||||
|
||||
## Поєднання provider і harness
|
||||
## Поєднання постачальника й каркаса
|
||||
|
||||
Більшість harness також мають реєструвати provider. Provider робить refs моделей,
|
||||
стан auth, метадані моделі та вибір `/model` видимими для решти
|
||||
OpenClaw. Потім harness заявляє цей provider у `supports(...)`.
|
||||
Більшість каркасів також мають реєструвати постачальника. Постачальник робить посилання на моделі, статус автентифікації, метадані моделі та вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє підтримку цього постачальника в `supports(...)`.
|
||||
|
||||
Вбудований Plugin Codex дотримується цього шаблону:
|
||||
Комплектний плагін Codex дотримується цього шаблону:
|
||||
|
||||
- id provider: `codex`
|
||||
- refs моделей для користувача: канонічний `openai/gpt-5.5` плюс
|
||||
`embeddedHarness.runtime: "codex"`; застарілі refs `codex/gpt-*` і далі приймаються
|
||||
для сумісності
|
||||
- id harness: `codex`
|
||||
- auth: синтетична доступність provider, оскільки harness Codex володіє
|
||||
нативним входом/сесією Codex
|
||||
- запит app-server: OpenClaw надсилає до Codex чистий id моделі й дозволяє
|
||||
harness спілкуватися з нативним протоколом app-server
|
||||
- id постачальника: `codex`
|
||||
- користувацькі посилання на моделі: канонічне `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; застарілі посилання `codex/gpt-*` усе ще приймаються для сумісності
|
||||
- id каркаса: `codex`
|
||||
- автентифікація: синтетична доступність постачальника, оскільки каркас Codex керує native-входом/сесією Codex
|
||||
- запит до app-server: OpenClaw надсилає в Codex лише bare id моделі та дозволяє каркасу працювати з native-протоколом app-server
|
||||
|
||||
Plugin Codex є додатковим. Звичайні refs `openai/gpt-*` і далі використовують
|
||||
нормальний шлях provider OpenClaw, якщо ви примусово не задасте harness Codex через
|
||||
`embeddedHarness.runtime: "codex"`. Старіші refs `codex/gpt-*` і далі вибирають
|
||||
provider і harness Codex для сумісності.
|
||||
Плагін Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують стандартний шлях постачальника OpenClaw, якщо ви не примусите використання каркаса Codex через `embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` усе ще вибирають постачальника і каркас Codex для сумісності.
|
||||
|
||||
Налаштування для оператора, приклади префіксів моделей і конфігурації лише для Codex див.
|
||||
у [Codex Harness](/uk/plugins/codex-harness).
|
||||
Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і config лише для Codex, див. [Каркас Codex](/uk/plugins/codex-harness).
|
||||
|
||||
OpenClaw вимагає Codex app-server `0.118.0` або новіший. Plugin Codex перевіряє
|
||||
initialize handshake app-server і блокує старіші або безверсійні сервери, щоб
|
||||
OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано.
|
||||
OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Плагін Codex перевіряє initialize-handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано.
|
||||
|
||||
### Middleware результатів tools для Codex app-server
|
||||
### Middleware результатів інструментів Codex app-server
|
||||
|
||||
Вбудовані Plugin також можуть підключати middleware `tool_result`, специфічне для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній
|
||||
маніфест оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`.
|
||||
Це seam довіреного Plugin для асинхронних перетворень результатів tools, які потрібно
|
||||
виконувати всередині нативного harness Codex до того, як вивід tool буде спроєктовано назад
|
||||
у транскрипт OpenClaw.
|
||||
Комплектні плагіни також можуть приєднувати middleware `tool_result`, специфічне для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній маніфест оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`.
|
||||
Це seam довіреного плагіна для асинхронних перетворень результатів інструментів, які мають виконуватися всередині native-каркаса Codex, перш ніж вивід інструмента буде спроєктовано назад у стенограму OpenClaw.
|
||||
|
||||
### Режим нативного harness Codex
|
||||
### Режим native-каркаса Codex
|
||||
|
||||
Вбудований harness `codex` — це нативний режим Codex для вбудованих ходів
|
||||
агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex`, а також включіть `codex` у
|
||||
`plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Нові конфігурації мають
|
||||
використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Застарілі
|
||||
refs моделей `openai-codex/*` і `codex/*` і далі залишаються псевдонімами сумісності.
|
||||
Комплектний каркас `codex` — це native-режим Codex для вбудованих ходів агента OpenClaw. Спочатку ввімкніть комплектний плагін `codex` і додайте `codex` до `plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Нові config мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Застарілі посилання на моделі `openai-codex/*` і `codex/*` залишаються псевдонімами сумісності.
|
||||
|
||||
Коли цей режим працює, Codex володіє нативним thread id, поведінкою resume,
|
||||
Compaction і виконанням app-server. OpenClaw і далі володіє каналом чату,
|
||||
видимим дзеркалом транскрипту, політикою tools, approvals, доставкою медіа та
|
||||
вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із
|
||||
`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях
|
||||
Codex app-server може взяти run. Ця конфігурація є лише запобіжником вибору:
|
||||
збої Codex app-server вже напряму завершуються помилкою без повторної спроби через PI.
|
||||
Коли цей режим працює, Codex керує native-id потоку, поведінкою відновлення, Compaction і виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом стенограми, політикою інструментів, підтвердженнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що виконання може взяти на себе лише шлях Codex app-server. Цей config є лише запобіжником вибору: збої Codex app-server уже напряму спричиняють збій замість повторної спроби через PI.
|
||||
|
||||
## Вимкнення fallback PI
|
||||
## Вимкнути резервний перехід на PI
|
||||
|
||||
Типово OpenClaw запускає вбудованих агентів з `agents.defaults.embeddedHarness`,
|
||||
установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані Plugin
|
||||
harness можуть узяти пару provider/model. Якщо жоден не підходить, OpenClaw повертається до PI.
|
||||
За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси плагінів можуть заявляти підтримку пари постачальник/модель. Якщо жоден не підходить, OpenClaw виконує резервний перехід на PI.
|
||||
|
||||
Установіть `fallback: "none"`, якщо вам потрібно, щоб відсутність вибору Plugin harness
|
||||
призводила до помилки замість використання PI. Збої вже вибраного Plugin harness і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору каркаса плагіна спричиняла збій замість використання PI. Збої вибраного каркаса плагіна вже спричиняють жорсткий збій. Це не блокує явне `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`.
|
||||
|
||||
Для вбудованих запусків лише з Codex:
|
||||
|
||||
@ -195,7 +148,7 @@ harness можуть узяти пару provider/model. Якщо жоден н
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ви хочете, щоб будь-який зареєстрований Plugin harness міг брати відповідні моделі, але не хочете, щоб OpenClaw мовчки повертався до PI, залиште `runtime: "auto"` і вимкніть fallback:
|
||||
Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг заявити підтримку відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть fallback:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -210,7 +163,7 @@ harness можуть узяти пару provider/model. Якщо жоден н
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення для конкретного агента використовують ту саму форму:
|
||||
Перевизначення для окремих агентів використовують ту саму форму:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -235,9 +188,7 @@ harness можуть узяти пару provider/model. Якщо жоден н
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback PI із
|
||||
середовища.
|
||||
`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI із середовища.
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -245,53 +196,40 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Коли fallback вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний harness не
|
||||
зареєстрований, не підтримує розв’язаний provider/model або завершується помилкою до
|
||||
створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і
|
||||
для live-тестів, які мають довести, що шлях Codex app-server справді використовується.
|
||||
Коли fallback вимкнено, сесія завершується збоєм рано, якщо запитаний каркас не зареєстровано, не підтримує визначеного постачальника/модель або завершується збоєм до створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях Codex app-server.
|
||||
|
||||
Цей параметр керує лише вбудованим agent harness. Він не вимикає
|
||||
маршрутизацію моделей, специфічну для image, video, music, TTS, PDF або інших provider.
|
||||
Це налаштування керує лише каркасом вбудованого агента. Воно не вимикає маршрутизацію моделей, специфічну для постачальника, для зображень, відео, музики, TTS, PDF або інших типів.
|
||||
|
||||
## Нативні сесії та дзеркало транскрипту
|
||||
## Native-сесії та дзеркало стенограми
|
||||
|
||||
Harness може зберігати нативний session id, thread id або токен resume на стороні daemon.
|
||||
Тримайте це прив’язування явно пов’язаним із сесією OpenClaw і продовжуйте
|
||||
дзеркалити видимий для користувача вивід assistant/tool у транскрипт OpenClaw.
|
||||
Каркас може зберігати native-id сесії, id потоку або токен відновлення на боці демона. Явно пов’язуйте цей зв’язок із сесією OpenClaw і продовжуйте дзеркалити видимий для користувача вивід асистента/інструментів у стенограму OpenClaw.
|
||||
|
||||
Транскрипт OpenClaw залишається шаром сумісності для:
|
||||
Стенограма OpenClaw залишається шаром сумісності для:
|
||||
|
||||
- видимої в каналі історії сесій
|
||||
- пошуку й індексації транскриптів
|
||||
- повернення до вбудованого harness PI на пізнішому ході
|
||||
- видимої в каналі історії сесії
|
||||
- пошуку та індексації стенограми
|
||||
- перемикання назад на вбудований каркас PI у пізнішому ході
|
||||
- загальної поведінки `/new`, `/reset` і видалення сесії
|
||||
|
||||
Якщо ваш harness зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг
|
||||
очистити її, коли пов’язану сесію OpenClaw буде скинуто.
|
||||
Якщо ваш каркас зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли відповідну сесію OpenClaw буде скинуто.
|
||||
|
||||
## Результати tools і медіа
|
||||
## Результати інструментів і медіа
|
||||
|
||||
Core будує список tools OpenClaw і передає його в підготовлену спробу.
|
||||
Коли harness виконує динамічний виклик tool, повертайте результат tool назад через
|
||||
форму результату harness, а не надсилайте медіа каналу самостійно.
|
||||
Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу.
|
||||
Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату каркаса замість того, щоб самостійно надсилати медіа в канал.
|
||||
|
||||
Це зберігає text, image, video, music, TTS, approval і виводи tools обміну повідомленнями
|
||||
в тому самому шляху доставки, що й запуски, підкріплені PI.
|
||||
Це зберігає текст, зображення, відео, музику, TTS, підтвердження та виводи інструментів обміну повідомленнями на тому самому шляху доставки, що й у запусків на базі PI.
|
||||
|
||||
## Поточні обмеження
|
||||
|
||||
- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі
|
||||
містять назви `Pi` для сумісності.
|
||||
- Встановлення сторонніх harness усе ще експериментальне. Надавайте перевагу provider plugins,
|
||||
доки вам не знадобиться нативний runtime сесії.
|
||||
- Перемикання harness між ходами підтримується. Не перемикайте harness
|
||||
посеред ходу після того, як уже почалися нативні tools, approvals, текст assistant або
|
||||
надсилання повідомлень.
|
||||
- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі містять назви `Pi` для сумісності.
|
||||
- Установлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників, доки вам не знадобиться native-середовище виконання сесії.
|
||||
- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися native-інструменти, підтвердження, текст асистента або надсилання повідомлень.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [SDK Overview](/uk/plugins/sdk-overview)
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime)
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
- [Codex Harness](/uk/plugins/codex-harness)
|
||||
- [Model Providers](/uk/concepts/model-providers)
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview)
|
||||
- [Допоміжні засоби runtime](/uk/plugins/sdk-runtime)
|
||||
- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins)
|
||||
- [Каркас Codex](/uk/plugins/codex-harness)
|
||||
- [Постачальники моделей](/uk/concepts/model-providers)
|
||||
|
||||
@ -1,54 +1,54 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі OpenAI в OpenClaw
|
||||
- Вам потрібна автентифікація підписки Codex замість API keys
|
||||
- Вам потрібна суворіша агентна поведінка виконання GPT-5
|
||||
summary: Використання OpenAI через API keys або підписку Codex в OpenClaw
|
||||
- Ви хочете автентифікацію за підпискою Codex замість API-ключів
|
||||
- Вам потрібні суворіші правила виконання агента GPT-5
|
||||
summary: Використовуйте OpenAI через API-ключі або підписку Codex у OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:07:15Z"
|
||||
generated_at: "2026-04-23T21:58:43Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39f5259ef82bb95bb7a94cf36a33c4a3ea2b9ba06f5355dc7abf256167d7a4b9
|
||||
source_hash: 7cbe3f548cc53ca50c5e76dea0a940c4e0a807dce7f777cd1692280a820c1f29
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI надає developer API для моделей GPT. OpenClaw підтримує два шляхи автентифікації за одними й тими самими канонічними посиланнями на моделі OpenAI:
|
||||
OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два способи автентифікації за одними й тими самими канонічними посиланнями на моделі OpenAI:
|
||||
|
||||
- **API key** — прямий доступ до OpenAI Platform з білінгом за використанням (моделі `openai/*`)
|
||||
- **Підписка Codex** — вхід через ChatGPT/Codex із доступом за підпискою. Внутрішній id auth/provider-а — `openai-codex`, але нові посилання на моделі все одно мають використовувати `openai/*`.
|
||||
- **API-ключ** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`)
|
||||
- **Підписка Codex** — вхід через ChatGPT/Codex із доступом за підпискою. Внутрішній ідентифікатор автентифікації/провайдера — `openai-codex`, але для нових посилань на моделі все одно слід використовувати `openai/*`.
|
||||
|
||||
OpenAI явно підтримує використання OAuth-підписки у зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
OpenAI явно підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw.
|
||||
|
||||
## Покриття можливостей OpenAI в OpenClaw
|
||||
## Покриття можливостей OpenClaw
|
||||
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ----------------------- | --------------------------------------- | --------------------------------------------------------- |
|
||||
| Chat / Responses | provider моделей `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai/<model>` з auth `openai-codex` | Так |
|
||||
| Server-side web search | Нативний інструмент OpenAI Responses | Так, коли web search увімкнено і provider не зафіксовано |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Batch speech-to-text | `tools.media.audio` / media understanding | Так |
|
||||
| Streaming speech-to-text| Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Realtime voice | Voice Call `realtime.provider: "openai"` | Так |
|
||||
| Embeddings | provider embeddings для memory | Так |
|
||||
| Можливість OpenAI | Поверхня OpenClaw | Статус |
|
||||
| ----------------------- | ---------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | провайдер моделі `openai/<model>` | Так |
|
||||
| Моделі підписки Codex | `openai/<model>` з автентифікацією `openai-codex` | Так |
|
||||
| Пошук у вебі на боці сервера | Нативний інструмент OpenAI Responses | Так, якщо вебпошук увімкнено і провайдера не зафіксовано |
|
||||
| Зображення | `image_generate` | Так |
|
||||
| Відео | `video_generate` | Так |
|
||||
| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так |
|
||||
| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так |
|
||||
| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так |
|
||||
| Голос у реальному часі | Voice Call `realtime.provider: "openai"` | Так |
|
||||
| Embeddings | провайдер embedding для пам’яті | Так |
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний метод автентифікації та виконайте кроки налаштування.
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key (OpenAI Platform)">
|
||||
**Найкраще для:** прямого доступу до API та білінгу за використанням.
|
||||
<Tab title="API-ключ (OpenAI Platform)">
|
||||
**Найкраще для:** прямого доступу до API та оплати за використання.
|
||||
|
||||
<Steps>
|
||||
<Step title="Отримайте свій API key">
|
||||
Створіть або скопіюйте API key з [dashboard OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
<Step title="Отримайте API-ключ">
|
||||
Створіть або скопіюйте API-ключ на [панелі керування OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Запустіть onboarding">
|
||||
<Step title="Запустіть онбординг">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
@ -59,25 +59,25 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Підсумок маршрутизації
|
||||
### Підсумок маршрутів
|
||||
|
||||
| Посилання на модель | Маршрут | Auth |
|
||||
|-----------|-------|------|
|
||||
| Model ref | Маршрут | Автентифікація |
|
||||
|-----------|---------|----------------|
|
||||
| `openai/gpt-5.5` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5-pro` | Прямий API OpenAI Platform | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
`openai-codex/*` усе ще приймається як застарілий псевдонім сумісності, але нові конфігурації мають використовувати `openai/*`.
|
||||
`openai-codex/*` і далі приймається як застарілий сумісний псевдонім, але в нових конфігураціях слід використовувати `openai/*`.
|
||||
</Note>
|
||||
|
||||
### Приклад config
|
||||
### Приклад конфігурації
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -87,13 +87,13 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не показує.
|
||||
OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Підписка Codex">
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Хмарний Codex вимагає входу через ChatGPT.
|
||||
**Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть Codex OAuth">
|
||||
@ -107,35 +107,35 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Для безголових конфігурацій або конфігурацій, де callback браузера не підходить, додайте `--device-code`, щоб увійти через потік ChatGPT device-code замість localhost browser callback:
|
||||
Для headless-середовищ або налаштувань, де callback працює ненадійно, додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
```
|
||||
</Step>
|
||||
<Step title="Задайте типову модель">
|
||||
<Step title="Установіть модель за замовчуванням">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai/gpt-5.5
|
||||
```
|
||||
</Step>
|
||||
<Step title="Перевірте, що модель доступна">
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Підсумок маршрутизації
|
||||
### Підсумок маршрутів
|
||||
|
||||
| Посилання на модель | Маршрут | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.5` | ChatGPT/Codex OAuth | Вхід Codex |
|
||||
| Model ref | Маршрут | Автентифікація |
|
||||
|-----------|---------|----------------|
|
||||
| `openai/gpt-5.5` | ChatGPT/Codex OAuth | вхід Codex |
|
||||
|
||||
<Note>
|
||||
Посилання на моделі `openai-codex/*` і `codex/*` — це застарілі псевдоніми сумісності. Для команд auth/profile і далі використовуйте id provider-а `openai-codex`.
|
||||
Посилання на моделі `openai-codex/*` і `codex/*` — це застарілі сумісні псевдоніми. Для команд автентифікації/профілю продовжуйте використовувати ідентифікатор провайдера `openai-codex`.
|
||||
</Note>
|
||||
|
||||
### Приклад config
|
||||
### Приклад конфігурації
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -144,27 +144,27 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Onboarding більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через браузерний OAuth (типово) або через device-code flow вище — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента.
|
||||
Онбординг більше не імпортує матеріали OAuth із `~/.codex`. Увійдіть через OAuth у браузері (типово) або через наведений вище потік коду пристрою — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів.
|
||||
</Note>
|
||||
|
||||
### Індикатор стану
|
||||
|
||||
Чат-команда `/status` показує, який вбудований harness активний для поточної
|
||||
session. Типовий harness PI відображається як `Runner: pi (embedded)` і не
|
||||
додає окремого badge. Коли вибрано bundled harness app-server Codex,
|
||||
`/status` додає id не-PI harness поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Наявні sessions зберігають свій записаний id harness, тож використовуйте
|
||||
Chat `/status` показує, яка вбудована обв’язка активна для поточної
|
||||
сесії. Обв’язка PI за замовчуванням відображається як `Runner: pi (embedded)` і
|
||||
не додає окремого значка. Якщо вибрано вбудовану обв’язку app-server Codex,
|
||||
`/status` додає ідентифікатор не-PI обв’язки поруч із `Fast`, наприклад
|
||||
`Fast · codex`. Наявні сесії зберігають записаний ідентифікатор обв’язки, тому використовуйте
|
||||
`/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status`
|
||||
відображав новий вибір PI/Codex.
|
||||
|
||||
### Обмеження вікна контексту
|
||||
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту runtime як окремі значення.
|
||||
OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення.
|
||||
|
||||
Для `openai/gpt-5.5` через Codex OAuth:
|
||||
|
||||
- Нативний `contextWindow`: `1000000`
|
||||
- Типове обмеження runtime `contextTokens`: `272000`
|
||||
- Типове обмеження `contextTokens` під час виконання: `272000`
|
||||
|
||||
Менше типове обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`:
|
||||
|
||||
@ -181,7 +181,7 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime.
|
||||
Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -190,14 +190,18 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`.
|
||||
Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію
|
||||
зображень через Codex OAuth за тим самим посиланням на модель `openai/gpt-image-2`.
|
||||
|
||||
| Можливість | Значення |
|
||||
| ------------------------- | ------------------------------------ |
|
||||
| Типова модель | `openai/gpt-image-2` |
|
||||
| Макс. зображень на запит | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 reference image) |
|
||||
| Перевизначення size | Підтримуються, включно з розмірами 2K/4K |
|
||||
| Aspect ratio / resolution | Не пересилаються до OpenAI Images API |
|
||||
| Можливість | API-ключ OpenAI | Codex OAuth |
|
||||
| ----------------------- | ---------------------------------- | ------------------------------------ |
|
||||
| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth |
|
||||
| Транспорт | OpenAI Images API | бекенд Codex Responses |
|
||||
| Макс. зображень на запит | 4 | 4 |
|
||||
| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) |
|
||||
| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K |
|
||||
| Співвідношення сторін / роздільність | Не передається до OpenAI Images API | Зіставляється з підтримуваним розміром, коли це безпечно |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -210,15 +214,19 @@ OpenAI явно підтримує використання OAuth-підписк
|
||||
```
|
||||
|
||||
<Note>
|
||||
Спільні параметри інструмента, вибір provider-а та поведінку failover див. в [Генерація зображень](/uk/tools/image-generation).
|
||||
Див. [Image Generation](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки резервного перемикання.
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` є типовим значенням і для текст-у-зображення OpenAI, і для
|
||||
редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`.
|
||||
`gpt-image-2` — це модель за замовчуванням як для генерації зображень із тексту OpenAI, так і для
|
||||
редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але для нових
|
||||
робочих процесів OpenAI із зображеннями слід використовувати `openai/gpt-image-2`.
|
||||
|
||||
Provider `openai-codex` також надає `gpt-image-2` для генерації зображень і
|
||||
редагування reference-image через OpenAI Codex OAuth. Використовуйте
|
||||
`openai-codex/gpt-image-2`, коли агент увійшов через Codex OAuth, але не має `OPENAI_API_KEY`.
|
||||
Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Якщо
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен
|
||||
доступу OAuth і надсилає запити на зображення через бекенд Codex Responses. Він
|
||||
не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихий перехід до API-ключа для цього
|
||||
запиту. Явно налаштуйте `models.providers.openai` за допомогою API-ключа,
|
||||
власного base URL або кінцевої точки Azure, якщо вам потрібен прямий маршрут через OpenAI Images API.
|
||||
|
||||
Генерація:
|
||||
|
||||
@ -226,12 +234,6 @@ Provider `openai-codex` також надає `gpt-image-2` для генера
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Генерація з Codex OAuth:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai-codex/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Редагування:
|
||||
|
||||
```
|
||||
@ -242,13 +244,13 @@ Provider `openai-codex` також надає `gpt-image-2` для генера
|
||||
|
||||
Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`.
|
||||
|
||||
| Можливість | Значення |
|
||||
| ---------------- | ----------------------------------------------------------------------------------- |
|
||||
| Типова модель | `openai/sora-2` |
|
||||
| Режими | Текст-у-відео, зображення-у-відео, редагування одного відео |
|
||||
| Reference inputs | 1 зображення або 1 відео |
|
||||
| Перевизначення size | Підтримуються |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з warning від інструмента |
|
||||
| Можливість | Значення |
|
||||
| --------------- | --------------------------------------------------------------------------------- |
|
||||
| Типова модель | `openai/sora-2` |
|
||||
| Режими | Текст у відео, зображення у відео, редагування одного відео |
|
||||
| Еталонні входи | 1 зображення або 1 відео |
|
||||
| Перевизначення розміру | Підтримується |
|
||||
| Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -261,22 +263,22 @@ Provider `openai-codex` також надає `gpt-image-2` для генера
|
||||
```
|
||||
|
||||
<Note>
|
||||
Спільні параметри інструмента, вибір provider-а та поведінку failover див. в [Генерація відео](/uk/tools/video-generation).
|
||||
Див. [Video Generation](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки резервного перемикання.
|
||||
</Note>
|
||||
|
||||
## Внесок у prompt для GPT-5
|
||||
## Внесок у промпт GPT-5
|
||||
|
||||
OpenClaw додає спільний внесок у prompt для GPT-5 для запусків сімейства GPT-5 у різних provider-ів. Він застосовується за model id, тож `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання на GPT-5 отримують той самий overlay. Старіші моделі GPT-4.x — ні.
|
||||
OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні.
|
||||
|
||||
Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і overlay Heartbeat через developer instructions app-server Codex, тож sessions `openai/gpt-5.x`, примусово проведені через `embeddedHarness.runtime: "codex"`, зберігають ті самі настанови щодо доведення справи до кінця та проактивного Heartbeat, навіть якщо рештою prompt harness володіє Codex.
|
||||
Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції для розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення справ до кінця й проактивного Heartbeat, навіть якщо Codex керує рештою промпта обв’язки.
|
||||
|
||||
Внесок GPT-5 додає tagged-контракт поведінки для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналів поведінка reply і silent-message залишається в спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Дружній interaction-style layer є окремим і налаштовуваним.
|
||||
Внесок GPT-5 додає тегований поведінковий контракт для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей і тихих повідомлень, специфічна для каналу, залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Рівень дружнього стилю взаємодії відокремлений і налаштовується.
|
||||
|
||||
| Значення | Ефект |
|
||||
| ---------------------- | ------------------------------------------ |
|
||||
| `"friendly"` (типово) | Увімкнути дружній interaction-style layer |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише friendly style layer |
|
||||
| Значення | Ефект |
|
||||
| --------------------- | -------------------------------------------- |
|
||||
| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії |
|
||||
| `"on"` | Псевдонім для `"friendly"` |
|
||||
| `"off"` | Вимкнути лише рівень дружнього стилю |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Config">
|
||||
@ -300,11 +302,11 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
Під час runtime значення нечутливі до регістру, тож і `"Off"`, і `"off"` вимикають friendly style layer.
|
||||
Під час виконання значення не чутливі до регістру, тож і `"Off"`, і `"off"` вимикають рівень дружнього стилю.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Застарілий `plugins.entries.openai.config.personality` усе ще читається як compatibility fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано.
|
||||
Застарілий параметр `plugins.entries.openai.config.personality` усе ще зчитується як сумісний запасний варіант, якщо спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не встановлено.
|
||||
</Note>
|
||||
|
||||
## Голос і мовлення
|
||||
@ -313,17 +315,17 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для
|
||||
<Accordion title="Синтез мовлення (TTS)">
|
||||
Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`.
|
||||
|
||||
| Налаштування | Шлях config | Типове значення |
|
||||
|-------------|-------------|-----------------|
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| Voice | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| Швидкість | `messages.tts.providers.openai.speed` | (не задано) |
|
||||
| Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для voice note, `mp3` для файлів |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | Fallback на `OPENAI_API_KEY` |
|
||||
| Голос | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| Швидкість | `messages.tts.providers.openai.speed` | (не встановлено) |
|
||||
| Інструкції | `messages.tts.providers.openai.instructions` | (не встановлено, лише `gpt-4o-mini-tts`) |
|
||||
| Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів |
|
||||
| API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні voice: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -338,23 +340,23 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для
|
||||
```
|
||||
|
||||
<Note>
|
||||
Задайте `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS, не впливаючи на endpoint chat API.
|
||||
Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS без впливу на кінцеву точку chat API.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Speech-to-text">
|
||||
Вбудований Plugin `openai` реєструє пакетний speech-to-text через
|
||||
поверхню транскрибування для media-understanding в OpenClaw.
|
||||
<Accordion title="Перетворення мовлення на текст">
|
||||
Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через
|
||||
поверхню транскрибування розуміння медіа OpenClaw.
|
||||
|
||||
- Типова модель: `gpt-4o-transcribe`
|
||||
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Шлях входу: multipart-завантаження audio-файла
|
||||
- Підтримується в OpenClaw всюди, де транскрибування вхідного audio використовує
|
||||
`tools.media.audio`, включно з сегментами voice-channel у Discord і
|
||||
audio-вкладеннями каналів
|
||||
- Кінцева точка: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Шлях входу: multipart-завантаження аудіофайлу
|
||||
- Підтримується в OpenClaw всюди, де транскрибування вхідного аудіо використовує
|
||||
`tools.media.audio`, зокрема для сегментів голосових каналів Discord і
|
||||
аудіовкладень каналів
|
||||
|
||||
Щоб примусово використовувати OpenAI для транскрибування вхідного audio:
|
||||
Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -374,71 +376,72 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для
|
||||
}
|
||||
```
|
||||
|
||||
Підказки щодо мови й prompt пересилаються до OpenAI, коли вони надані
|
||||
спільною конфігурацією audio media або запитом транскрибування для конкретного виклику.
|
||||
Підказки щодо мови та промпта передаються до OpenAI, коли вони задані у
|
||||
спільній конфігурації аудіомедіа або в запиті на транскрибування для окремого виклику.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Транскрибування в реальному часі">
|
||||
Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin-а Voice Call.
|
||||
Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях config | Типове значення |
|
||||
|-------------|-------------|-----------------|
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| Мова | `...openai.language` | (не задано) |
|
||||
| Prompt | `...openai.prompt` | (не задано) |
|
||||
| Мова | `...openai.language` | (не встановлено) |
|
||||
| Промпт | `...openai.prompt` | (не встановлено) |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `800` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | Fallback на `OPENAI_API_KEY` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант |
|
||||
|
||||
<Note>
|
||||
Використовує WebSocket-з’єднання до `wss://api.openai.com/v1/realtime` з audio у форматі G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей streaming provider призначений для шляху транскрибування в реальному часі в Voice Call; Discord voice наразі записує короткі сегменти й використовує пакетний шлях транскрибування `tools.media.audio`.
|
||||
Використовує WebSocket-з’єднання до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі у Voice Call; голос у Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрибування `tools.media.audio`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Голос у реальному часі">
|
||||
Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin-а Voice Call.
|
||||
Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call.
|
||||
|
||||
| Налаштування | Шлях config | Типове значення |
|
||||
|-------------|-------------|-----------------|
|
||||
| Параметр | Шлях конфігурації | Типове значення |
|
||||
|---------|------------|---------|
|
||||
| Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
|
||||
| Voice | `...openai.voice` | `alloy` |
|
||||
| Голос | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| Поріг VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Тривалість тиші | `...openai.silenceDurationMs` | `500` |
|
||||
| API key | `...openai.apiKey` | Fallback на `OPENAI_API_KEY` |
|
||||
| API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як запасний варіант |
|
||||
|
||||
<Note>
|
||||
Підтримує Azure OpenAI через ключі config `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує audio-формат G.711 u-law.
|
||||
Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує формат аудіо G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Endpoint-и Azure OpenAI
|
||||
## Кінцеві точки Azure OpenAI
|
||||
|
||||
Вбудований provider `openai` може націлюватися на ресурс Azure OpenAI для генерації
|
||||
зображень через перевизначення base URL. На шляху генерації зображень OpenClaw
|
||||
визначає Azure-hostname-и в `models.providers.openai.baseUrl` і автоматично перемикається на
|
||||
форму запиту Azure.
|
||||
Вбудований провайдер `openai` може працювати з ресурсом Azure OpenAI для
|
||||
генерації зображень через перевизначення base URL. На шляху генерації зображень OpenClaw
|
||||
визначає імена хостів Azure у `models.providers.openai.baseUrl` і автоматично перемикається на
|
||||
формат запиту Azure.
|
||||
|
||||
<Note>
|
||||
Для голосу в реальному часі використовується окремий шлях конфігурації
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`),
|
||||
на який `models.providers.openai.baseUrl` не впливає. Налаштування Azure для нього див. в accordion **Голос і мовлення** під [Голос і мовлення](#voice-and-speech).
|
||||
Голос у реальному часі використовує окремий шлях конфігурації
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||||
і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному
|
||||
часі** в розділі [Голос і мовлення](#voice-and-speech) для його параметрів Azure.
|
||||
</Note>
|
||||
|
||||
Використовуйте Azure OpenAI, коли:
|
||||
Використовуйте Azure OpenAI, якщо:
|
||||
|
||||
- у вас уже є підписка Azure OpenAI, quota або enterprise agreement
|
||||
- вам потрібні регіональна резидентність даних або механізми compliance, які надає Azure
|
||||
- ви хочете, щоб трафік залишався в межах наявного tenancy Azure
|
||||
- У вас уже є підписка Azure OpenAI, квота або корпоративна угода
|
||||
- Вам потрібна регіональна локалізація даних або засоби відповідності вимогам, які надає Azure
|
||||
- Ви хочете зберігати трафік у межах наявного середовища Azure
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Для генерації зображень Azure через вбудований provider `openai` спрямуйте
|
||||
`models.providers.openai.baseUrl` на свій ресурс Azure і задайте `apiKey` як
|
||||
Для генерації зображень через Azure за допомогою вбудованого провайдера `openai`, укажіть
|
||||
`models.providers.openai.baseUrl` для вашого ресурсу Azure і встановіть `apiKey` як
|
||||
ключ Azure OpenAI (а не ключ OpenAI Platform):
|
||||
|
||||
```json5
|
||||
@ -454,100 +457,99 @@ OpenClaw додає спільний внесок у prompt для GPT-5 для
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw розпізнає такі Azure host suffix для
|
||||
шляху генерації зображень Azure:
|
||||
OpenClaw розпізнає такі суфікси хостів Azure для маршруту генерації зображень Azure:
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
- `*.cognitiveservices.azure.com`
|
||||
|
||||
Для запитів генерації зображень на розпізнаному Azure host OpenClaw:
|
||||
Для запитів на генерацію зображень на розпізнаному хості Azure OpenClaw:
|
||||
|
||||
- Надсилає заголовок `api-key` замість `Authorization: Bearer`
|
||||
- Використовує deployment-scoped-шляхи (`/openai/deployments/{deployment}/...`)
|
||||
- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`)
|
||||
- Додає `?api-version=...` до кожного запиту
|
||||
|
||||
Інші base URL (публічний OpenAI, OpenAI-сумісні proxy) зберігають стандартну
|
||||
форму запиту до OpenAI для зображень.
|
||||
Інші base URL (публічний OpenAI, сумісні з OpenAI проксі) зберігають стандартний
|
||||
формат запиту зображень OpenAI.
|
||||
|
||||
<Note>
|
||||
Маршрутизація Azure для шляху генерації зображень provider-а `openai` потребує
|
||||
OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який кастомний
|
||||
`openai.baseUrl` як публічний endpoint OpenAI і завершуються помилкою при роботі з Azure
|
||||
image deployment-ами.
|
||||
Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує
|
||||
OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який власний
|
||||
`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із deployment генерації
|
||||
зображень Azure.
|
||||
</Note>
|
||||
|
||||
### Версія API
|
||||
### Версія API
|
||||
|
||||
Задайте `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview або GA-версію Azure
|
||||
для шляху генерації зображень Azure:
|
||||
Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure
|
||||
для шляху генерації зображень Azure:
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
Типове значення — `2024-12-01-preview`, якщо змінну не задано.
|
||||
Типове значення — `2024-12-01-preview`, якщо змінну не встановлено.
|
||||
|
||||
### Назви моделей — це назви deployment
|
||||
|
||||
Azure OpenAI прив’язує моделі до deployment-ів. Для запитів генерації зображень Azure,
|
||||
маршрутизованих через вбудований provider `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою deployment Azure**, яку ви налаштували в Azure portal, а не
|
||||
публічним model id OpenAI.
|
||||
Azure OpenAI прив’язує моделі до deployment. Для запитів на генерацію зображень Azure,
|
||||
маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw
|
||||
має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не
|
||||
публічним ідентифікатором моделі OpenAI.
|
||||
|
||||
Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`:
|
||||
Якщо ви створили deployment під назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
Те саме правило назви deployment застосовується до викликів генерації зображень,
|
||||
маршрутизованих через вбудований provider `openai`.
|
||||
маршрутизованих через вбудований провайдер `openai`.
|
||||
|
||||
### Регіональна доступність
|
||||
|
||||
Генерація зображень Azure наразі доступна лише в підмножині регіонів
|
||||
Генерація зображень Azure наразі доступна лише в обмеженій кількості регіонів
|
||||
(наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||||
`uaenorth`). Перевірте поточний список регіонів Microsoft перед створенням
|
||||
deployment і підтвердьте, що конкретна модель пропонується у вашому регіоні.
|
||||
`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням
|
||||
deployment і підтвердьте, що конкретна модель доступна у вашому регіоні.
|
||||
|
||||
### Відмінності параметрів
|
||||
|
||||
Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень.
|
||||
Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні
|
||||
значення `background` для `gpt-image-2`) або надавати їх лише для конкретних
|
||||
версій моделі. Ці відмінності походять від Azure і базової моделі, а не від
|
||||
значення `background` для `gpt-image-2`) або надавати їх лише для певних версій
|
||||
моделі. Ці відмінності походять від Azure та базової моделі, а не від
|
||||
OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте
|
||||
набір параметрів, який підтримується вашим конкретним deployment і версією API в
|
||||
Azure portal.
|
||||
набір параметрів, які підтримує ваш конкретний deployment і версія API, у
|
||||
порталі Azure.
|
||||
|
||||
<Note>
|
||||
Azure OpenAI використовує нативний transport і compat-поведінку, але не отримує
|
||||
приховані заголовки attribution OpenClaw — див. accordion **Нативні vs OpenAI-compatible
|
||||
маршрути** у розділі [Розширена конфігурація](#advanced-configuration).
|
||||
Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує
|
||||
приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та маршрути, сумісні з OpenAI**
|
||||
в розділі [Розширена конфігурація](#advanced-configuration).
|
||||
|
||||
Для трафіку chat або Responses на Azure (поза генерацією зображень) використовуйте
|
||||
потік onboarding або окрему конфігурацію provider-а Azure — одного лише
|
||||
`openai.baseUrl` недостатньо, щоб підхопити форму API/auth Azure. Існує окремий
|
||||
provider `azure-openai-responses/*`; див.
|
||||
accordion про Server-side Compaction нижче.
|
||||
потік онбордингу або окрему конфігурацію провайдера Azure — самого лише
|
||||
`openai.baseUrl` недостатньо, щоб застосувати форму API/автентифікації Azure. Існує окремий
|
||||
провайдер `azure-openai-responses/*`; див.
|
||||
акордеон Server-side Compaction нижче.
|
||||
</Note>
|
||||
|
||||
## Розширена конфігурація
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Transport (WebSocket vs SSE)">
|
||||
OpenClaw використовує підхід WebSocket-first із fallback на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
<Accordion title="Транспорт (WebSocket чи SSE)">
|
||||
OpenClaw використовує спочатку WebSocket із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`.
|
||||
|
||||
У режимі `"auto"` OpenClaw:
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на fallback через SSE
|
||||
- Після збою позначає WebSocket як degraded приблизно на 60 секунд і використовує SSE під час cool-down
|
||||
- Додає стабільні заголовки identity для session і ходу для retry та reconnect
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами transport
|
||||
- Повторює одну ранню помилку WebSocket перед переходом на SSE
|
||||
- Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження
|
||||
- Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і перепідключень
|
||||
- Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту
|
||||
|
||||
| Значення | Поведінка |
|
||||
|----------|-----------|
|
||||
| `"auto"` (типово) | Спочатку WebSocket, fallback на SSE |
|
||||
|-------|----------|
|
||||
| `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE |
|
||||
| `"sse"` | Примусово лише SSE |
|
||||
| `"websocket"` | Примусово лише WebSocket |
|
||||
|
||||
@ -591,13 +593,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Fast mode">
|
||||
OpenClaw надає спільний перемикач fast mode для `openai/*`:
|
||||
<Accordion title="Швидкий режим">
|
||||
OpenClaw надає спільний перемикач швидкого режиму для `openai/*`:
|
||||
|
||||
- **Chat/UI:** `/fast status|on|off`
|
||||
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
- **Конфігурація:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Коли його ввімкнено, OpenClaw відображає fast mode на priority processing OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, і fast mode не переписує `reasoning` або `text.verbosity`.
|
||||
Коли ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` чи `text.verbosity`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -612,13 +614,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
<Note>
|
||||
Перевизначення на рівні session мають пріоритет над config. Очищення перевизначення session в UI Sessions повертає session до налаштованого типового значення.
|
||||
Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Priority processing (service_tier)">
|
||||
API OpenAI надає priority processing через `service_tier`. Задавайте його для кожної моделі в OpenClaw:
|
||||
<Accordion title="Пріоритетна обробка (service_tier)">
|
||||
API OpenAI надає пріоритетну обробку через `service_tier`. Установіть її для кожної моделі в OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -635,7 +637,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
Підтримувані значення: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`serviceTier` пересилається лише до нативних endpoint-ів OpenAI (`api.openai.com`) і нативних endpoint-ів Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих provider-ів через proxy, OpenClaw залишає `service_tier` без змін.
|
||||
`serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -643,13 +645,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
<Accordion title="Server-side Compaction (Responses API)">
|
||||
Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) OpenClaw автоматично вмикає Server-side Compaction:
|
||||
|
||||
- Примусово задає `store: true` (якщо тільки compat моделі не задає `supportsStore: false`)
|
||||
- Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`)
|
||||
- Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, коли воно недоступне)
|
||||
- Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо недоступно)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Явно увімкнути">
|
||||
Корисно для сумісних endpoint-ів, таких як Azure OpenAI Responses:
|
||||
<Tab title="Явно ввімкнути">
|
||||
Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -665,7 +667,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Кастомний поріг">
|
||||
<Tab title="Власний поріг">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -701,12 +703,12 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово задають `store: true`, якщо тільки compat не задає `supportsStore: false`.
|
||||
`responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses однаково примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Strict-agentic GPT mode">
|
||||
<Accordion title="Суворий агентний режим GPT">
|
||||
Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання:
|
||||
|
||||
```json5
|
||||
@ -719,33 +721,33 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
}
|
||||
```
|
||||
|
||||
Із `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним прогресом, коли доступна дія з інструментом
|
||||
- Повторює хід зі steer «дій зараз»
|
||||
З `strict-agentic` OpenClaw:
|
||||
- Більше не вважає хід лише з планом успішним поступом, якщо доступна дія інструмента
|
||||
- Повторює хід із вказівкою діяти зараз
|
||||
- Автоматично вмикає `update_plan` для суттєвої роботи
|
||||
- Показує явний blocked state, якщо модель продовжує планувати без дії
|
||||
- Показує явний заблокований стан, якщо модель продовжує планувати без дії
|
||||
|
||||
<Note>
|
||||
Обмежено лише запусками OpenAI і Codex сімейства GPT-5. Інші provider-и та старіші сімейства моделей зберігають типову поведінку.
|
||||
Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні vs OpenAI-compatible маршрути">
|
||||
OpenClaw по-різному трактує прямі endpoint-и OpenAI, Codex і Azure OpenAI та загальні OpenAI-compatible `/v1` proxy:
|
||||
<Accordion title="Нативні маршрути та маршрути, сумісні з OpenAI">
|
||||
OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні проксі `/v1`, сумісні з OpenAI:
|
||||
|
||||
**Нативні маршрути** (`openai/*`, Azure OpenAI):
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort
|
||||
- Пропускають вимкнений reasoning для моделей або proxy, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово задають strict mode для tool schema
|
||||
- Додають приховані attribution headers лише на перевірених нативних host-ах
|
||||
- Зберігають request shaping лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки prompt-cache)
|
||||
- Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI effort `none`
|
||||
- Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"`
|
||||
- Типово встановлюють суворий режим для схем інструментів
|
||||
- Додають приховані заголовки атрибуції лише на перевірених нативних хостах
|
||||
- Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів)
|
||||
|
||||
**Маршрути proxy/compatible:**
|
||||
- Використовують м’якшу compat-поведінку
|
||||
- Не примушують strict tool schema або заголовки лише для native
|
||||
**Проксі/сумісні маршрути:**
|
||||
- Використовують м’якшу сумісну поведінку
|
||||
- Не примушують суворі схеми інструментів або заголовки лише для нативних маршрутів
|
||||
|
||||
Azure OpenAI використовує нативний transport і compat-поведінку, але не отримує прихованих attribution headers.
|
||||
Azure OpenAI використовує нативний транспорт і сумісну поведінку, але не отримує прихованих заголовків атрибуції.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -754,15 +756,15 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір provider-ів, посилань на моделі та поведінки failover.
|
||||
Вибір провайдерів, посилань на моделі та поведінки резервного перемикання.
|
||||
</Card>
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри image-інструмента та вибір provider-а.
|
||||
Спільні параметри інструмента зображень і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри video-інструмента та вибір provider-а.
|
||||
Спільні параметри інструмента відео та вибір провайдера.
|
||||
</Card>
|
||||
<Card title="OAuth і auth" href="/uk/gateway/authentication" icon="key">
|
||||
Деталі auth і правила повторного використання облікових даних.
|
||||
<Card title="OAuth і автентифікація" href="/uk/gateway/authentication" icon="key">
|
||||
Відомості про автентифікацію та правила повторного використання облікових даних.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,95 +1,96 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете налаштувати провайдерів memory search або embedding-моделі
|
||||
- Ви хочете налаштувати backend QMD
|
||||
- Ви хочете налаштувати hybrid search, MMR або temporal decay
|
||||
- Ви хочете ввімкнути multimodal indexing для memory
|
||||
summary: Усі параметри конфігурації для memory search, embedding providers, QMD, hybrid search і multimodal indexing
|
||||
title: Довідник конфігурації Memory
|
||||
- Ви хочете налаштувати постачальників пошуку в пам’яті або моделі ембедингів
|
||||
- Ви хочете налаштувати бекенд QMD
|
||||
- Ви хочете налаштувати гібридний пошук, MMR або часовий спад
|
||||
- Ви хочете ввімкнути мультимодальне індексування пам’яті
|
||||
summary: Усі параметри конфігурації для пошуку в пам’яті, постачальників ембедингів, QMD, гібридного пошуку та мультимодального індексування
|
||||
title: Довідник із конфігурації пам’яті
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:09:47Z"
|
||||
generated_at: "2026-04-23T21:58:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e179b955ee0532805ee254d79217b66c093def534c2ef3952d955b3b05de8ca
|
||||
source_hash: e8f91c15c149feb1a351585d246f3155ce56164cbda3e773dd63ebfa6c1b63b7
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Ця сторінка перелічує всі параметри конфігурації для memory search в OpenClaw. Для
|
||||
концептуальних оглядів див.:
|
||||
На цій сторінці наведено всі параметри конфігурації для пошуку в пам’яті OpenClaw. Для концептуальних оглядів дивіться:
|
||||
|
||||
- [Memory Overview](/uk/concepts/memory) -- як працює memory
|
||||
- [Builtin Engine](/uk/concepts/memory-builtin) -- типовий backend SQLite
|
||||
- [QMD Engine](/uk/concepts/memory-qmd) -- локально-орієнтований sidecar
|
||||
- [Memory Search](/uk/concepts/memory-search) -- конвеєр пошуку та налаштування
|
||||
- [Active Memory](/uk/concepts/active-memory) -- увімкнення субагента memory для інтерактивних сесій
|
||||
- [Огляд пам’яті](/uk/concepts/memory) -- як працює пам’ять
|
||||
- [Вбудований рушій](/uk/concepts/memory-builtin) -- типовий бекенд SQLite
|
||||
- [Рушій QMD](/uk/concepts/memory-qmd) -- локальний sidecar із local-first підходом
|
||||
- [Пошук у пам’яті](/uk/concepts/memory-search) -- конвеєр пошуку та налаштування
|
||||
- [Active Memory](/uk/concepts/active-memory) -- увімкнення субагента пам’яті для інтерактивних сесій
|
||||
|
||||
Усі параметри memory search розміщуються в `agents.defaults.memorySearch` у
|
||||
Усі налаштування пошуку в пам’яті розміщені в `agents.defaults.memorySearch` у
|
||||
`openclaw.json`, якщо не зазначено інше.
|
||||
|
||||
Якщо ви шукаєте перемикач функції **active memory** і конфігурацію субагента,
|
||||
вона розміщена в `plugins.entries.active-memory`, а не в `memorySearch`.
|
||||
вона розташована в `plugins.entries.active-memory`, а не в `memorySearch`.
|
||||
|
||||
Active memory використовує модель із двома шлюзами:
|
||||
Active Memory використовує двоетапну модель перевірки:
|
||||
|
||||
1. Plugin має бути увімкнений і націлений на поточний id агента
|
||||
2. Запит має бути придатною інтерактивною постійною чат-сесією
|
||||
1. plugin має бути ввімкнений і націлений на поточний id агента
|
||||
2. запит має бути відповідною інтерактивною постійною сесією чату
|
||||
|
||||
Модель активації, конфігурацію, якою володіє Plugin, збереження транскриптів і безпечний шаблон упровадження див. у [Active Memory](/uk/concepts/active-memory).
|
||||
Дивіться [Active Memory](/uk/concepts/active-memory) щодо моделі активації,
|
||||
конфігурації, якою володіє plugin, збереження транскриптів і безпечної схеми розгортання.
|
||||
|
||||
---
|
||||
|
||||
## Вибір provider
|
||||
## Вибір постачальника
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| --------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `provider` | `string` | auto-detected | id адаптера embedding: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` |
|
||||
| `model` | `string` | provider default | Назва embedding-моделі |
|
||||
| `fallback` | `string` | `"none"` | id резервного адаптера, якщо основний завершується помилкою |
|
||||
| `enabled` | `boolean` | `true` | Увімкнути або вимкнути memory search |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | автоматично визначається | ID адаптера ембедингів: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` |
|
||||
| `model` | `string` | типове значення постачальника | Назва моделі ембедингів |
|
||||
| `fallback` | `string` | `"none"` | ID резервного адаптера, якщо основний завершується невдачею |
|
||||
| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук у пам’яті |
|
||||
|
||||
### Порядок автовизначення
|
||||
### Порядок автоматичного визначення
|
||||
|
||||
Коли `provider` не задано, OpenClaw вибирає перший доступний варіант:
|
||||
Коли `provider` не задано, OpenClaw вибирає перший доступний:
|
||||
|
||||
1. `local` -- якщо налаштовано `memorySearch.local.modelPath` і файл існує.
|
||||
2. `github-copilot` -- якщо можна розв’язати токен GitHub Copilot (env var або auth profile).
|
||||
3. `openai` -- якщо можна розв’язати ключ OpenAI.
|
||||
4. `gemini` -- якщо можна розв’язати ключ Gemini.
|
||||
5. `voyage` -- якщо можна розв’язати ключ Voyage.
|
||||
6. `mistral` -- якщо можна розв’язати ключ Mistral.
|
||||
7. `bedrock` -- якщо ланцюг облікових даних AWS SDK розв’язується (роль екземпляра, ключі доступу, profile, SSO, web identity або спільна конфігурація).
|
||||
2. `github-copilot` -- якщо вдається визначити токен GitHub Copilot (змінна середовища або профіль автентифікації).
|
||||
3. `openai` -- якщо вдається визначити ключ OpenAI.
|
||||
4. `gemini` -- якщо вдається визначити ключ Gemini.
|
||||
5. `voyage` -- якщо вдається визначити ключ Voyage.
|
||||
6. `mistral` -- якщо вдається визначити ключ Mistral.
|
||||
7. `bedrock` -- якщо вдається визначити облікові дані через стандартний ланцюжок AWS SDK (роль екземпляра, ключі доступу, профіль, SSO, web identity або спільна конфігурація).
|
||||
|
||||
`ollama` підтримується, але не визначається автоматично (задайте його явно).
|
||||
`ollama` підтримується, але не визначається автоматично (вкажіть його явно).
|
||||
|
||||
### Розв’язання API-ключа
|
||||
### Визначення API-ключа
|
||||
|
||||
Віддалені embeddings потребують API-ключа. Натомість Bedrock використовує типовий
|
||||
ланцюг облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу).
|
||||
Для віддалених ембедингів потрібен API-ключ. Натомість Bedrock використовує
|
||||
стандартний ланцюжок облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу).
|
||||
|
||||
| Provider | Env var | Ключ конфігурації |
|
||||
| -------------- | -------------------------------------------------- | --------------------------------- |
|
||||
| Bedrock | ланцюг облікових даних AWS | API-ключ не потрібен |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Auth profile через device login |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Ollama | `OLLAMA_API_KEY` (placeholder) | -- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Постачальник | Змінна середовища | Ключ конфігурації |
|
||||
| ------------ | ------------------------------------------------- | --------------------------------- |
|
||||
| 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` |
|
||||
|
||||
Codex OAuth покриває лише chat/completions і не задовольняє embedding-запити.
|
||||
Codex OAuth охоплює лише chat/completions і не задовольняє запити на
|
||||
ембединги.
|
||||
|
||||
---
|
||||
|
||||
## Конфігурація віддаленого endpoint
|
||||
## Конфігурація віддаленої кінцевої точки
|
||||
|
||||
Для власних OpenAI-сумісних endpoint або перевизначення типових значень provider:
|
||||
Для користувацьких OpenAI-сумісних кінцевих точок або перевизначення типових значень постачальника:
|
||||
|
||||
| Ключ | Тип | Опис |
|
||||
| ---------------- | -------- | -------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | Власний API base URL |
|
||||
| `remote.apiKey` | `string` | Перевизначення API-ключа |
|
||||
| `remote.headers` | `object` | Додаткові HTTP headers (зливаються з типовими значеннями provider) |
|
||||
| Ключ | Тип | Опис |
|
||||
| ---------------- | -------- | ------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | Користувацька базова URL-адреса API |
|
||||
| `remote.apiKey` | `string` | Перевизначити API-ключ |
|
||||
| `remote.headers` | `object` | Додаткові HTTP-заголовки (об’єднуються з типовими значеннями постачальника) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -110,24 +111,24 @@ Codex OAuth покриває лише chat/completions і не задоволь
|
||||
|
||||
---
|
||||
|
||||
## Конфігурація, специфічна для Gemini
|
||||
## Конфігурація Gemini
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------- | -------- | ----------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Також підтримує `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------- | -------- | --------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Також підтримується `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 |
|
||||
|
||||
<Warning>
|
||||
Зміна моделі або `outputDimensionality` запускає автоматичне повне повторне індексування.
|
||||
Зміна моделі або `outputDimensionality` запускає автоматичне повне переіндексування.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Конфігурація embedding для Bedrock
|
||||
## Конфігурація ембедингів Bedrock
|
||||
|
||||
Bedrock використовує типовий ланцюг облікових даних AWS SDK -- API-ключі не потрібні.
|
||||
Якщо OpenClaw працює на EC2 з роллю екземпляра, у якої ввімкнено Bedrock, просто задайте
|
||||
provider і модель:
|
||||
Bedrock використовує стандартний ланцюжок облікових даних AWS SDK -- API-ключі не потрібні.
|
||||
Якщо OpenClaw працює на EC2 з роллю екземпляра, у якій увімкнено Bedrock, просто задайте
|
||||
постачальника та модель:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -142,47 +143,48 @@ provider і модель:
|
||||
}
|
||||
```
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------- | -------- | ----------------------------- | --------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який id embedding-моделі Bedrock |
|
||||
| `outputDimensionality` | `number` | model default | Для Titan V2: 256, 512 або 1024 |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------- | -------- | ----------------------------- | ---------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ID моделі ембедингів Bedrock |
|
||||
| `outputDimensionality` | `number` | типове значення моделі | Для Titan V2: 256, 512 або 1024 |
|
||||
|
||||
### Підтримувані моделі
|
||||
|
||||
Підтримуються такі моделі (з визначенням сімейства та типовими значеннями розмірностей):
|
||||
Підтримуються такі моделі (з визначенням сімейства та типовими
|
||||
значеннями розмірності):
|
||||
|
||||
| Model ID | Provider | Типові розмірності | Налаштовувані розмірності |
|
||||
| ------------------------------------------ | ---------- | ------------------ | ------------------------- |
|
||||
| `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 | -- |
|
||||
| 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`) успадковують
|
||||
конфігурацію базової моделі.
|
||||
|
||||
### Автентифікація
|
||||
|
||||
Auth Bedrock використовує стандартний порядок розв’язання облікових даних AWS SDK:
|
||||
Автентифікація Bedrock використовує стандартний порядок визначення облікових даних AWS SDK:
|
||||
|
||||
1. Змінні середовища (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. Кеш токенів SSO
|
||||
3. Облікові дані web identity token
|
||||
3. Облікові дані токена web identity
|
||||
4. Спільні файли облікових даних і конфігурації
|
||||
5. Облікові дані ECS або EC2 metadata
|
||||
5. Облікові дані метаданих ECS або EC2
|
||||
|
||||
Регіон розв’язується з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` provider
|
||||
`amazon-bedrock` або типово задається як `us-east-1`.
|
||||
Регіон визначається з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl`
|
||||
постачальника `amazon-bedrock` або за замовчуванням використовується `us-east-1`.
|
||||
|
||||
### IAM permissions
|
||||
### Дозволи IAM
|
||||
|
||||
Роль або користувач IAM потребують:
|
||||
Ролі або користувачу IAM потрібно:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -192,7 +194,7 @@ Auth Bedrock використовує стандартний порядок ро
|
||||
}
|
||||
```
|
||||
|
||||
Для принципу найменших привілеїв обмежте `InvokeModel` конкретною моделлю:
|
||||
Для мінімально необхідних привілеїв обмежте `InvokeModel` конкретною моделлю:
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
@ -200,44 +202,45 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
---
|
||||
|
||||
## Конфігурація локальних embeddings
|
||||
## Конфігурація локальних ембедингів
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| --------------------- | -------- | ---------------------- | -------------------------------- |
|
||||
| `local.modelPath` | `string` | auto-downloaded | Шлях до файла моделі GGUF |
|
||||
| `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| --------------------- | ------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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 GB, auto-downloaded).
|
||||
Потребує нативного build: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`.
|
||||
Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 ГБ, автоматично завантажується).
|
||||
Потрібна нативна збірка: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
## Конфігурація hybrid search
|
||||
## Конфігурація гібридного пошуку
|
||||
|
||||
Усе розміщується в `memorySearch.query.hybrid`:
|
||||
Усе в `memorySearch.query.hybrid`:
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| --------------------- | --------- | --------------- | ------------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Увімкнути hybrid BM25 + vector search |
|
||||
| `enabled` | `boolean` | `true` | Увімкнути гібридний пошук BM25 + vector |
|
||||
| `vectorWeight` | `number` | `0.7` | Вага для vector-оцінок (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Вага для BM25-оцінок (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів |
|
||||
|
||||
### MMR (різноманіття)
|
||||
### MMR (різноманітність)
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------ | --------- | --------------- | ------------------------------------------ |
|
||||
| `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 = максимальна релевантність |
|
||||
|
||||
### Temporal decay (давність)
|
||||
### Часовий спад (свіжість)
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------------- | --------- | --------------- | ------------------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Увімкнути підсилення за давністю |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------------- | --------- | --------------- | --------------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Увімкнути підсилення свіжості |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів |
|
||||
|
||||
Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ніколи не піддаються згасанню.
|
||||
Для evergreen-файлів (`MEMORY.md`, файли без дат у `memory/`) часовий спад ніколи не застосовується.
|
||||
|
||||
### Повний приклад
|
||||
|
||||
@ -262,11 +265,11 @@ Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ні
|
||||
|
||||
---
|
||||
|
||||
## Додаткові шляхи memory
|
||||
## Додаткові шляхи пам’яті
|
||||
|
||||
| Ключ | Тип | Опис |
|
||||
| ----------- | ---------- | ----------------------------------------- |
|
||||
| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексації |
|
||||
| `extraPaths` | `string[]` | Додаткові каталоги або файли для індексування |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -280,153 +283,152 @@ Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ні
|
||||
}
|
||||
```
|
||||
|
||||
Шляхи можуть бути абсолютними або відносними до workspace. Каталоги скануються
|
||||
рекурсивно на наявність файлів `.md`. Обробка symlink залежить від активного backend:
|
||||
вбудований engine ігнорує symlink, тоді як QMD дотримується поведінки
|
||||
базового scanner QMD.
|
||||
Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги
|
||||
скануються рекурсивно на наявність файлів `.md`. Обробка симлінків залежить від активного бекенда:
|
||||
вбудований рушій ігнорує симлінки, тоді як QMD наслідує поведінку базового
|
||||
сканера QMD.
|
||||
|
||||
Для agent-scoped пошуку транскриптів між агентами використовуйте
|
||||
Для пошуку транскриптів між агентами в межах агента використовуйте
|
||||
`agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`.
|
||||
Ці додаткові collections дотримуються тієї самої форми `{ path, name, pattern? }`, але
|
||||
зливаються для кожного агента окремо й можуть зберігати явні спільні назви, коли шлях
|
||||
вказує поза поточний workspace.
|
||||
Якщо той самий розв’язаний шлях з’являється і в `memory.qmd.paths`, і в
|
||||
`memorySearch.qmd.extraCollections`, QMD залишає перший запис і пропускає
|
||||
Ці додаткові колекції мають ту саму форму `{ path, name, pattern? }`, але
|
||||
об’єднуються для кожного агента і можуть зберігати явно задані спільні назви, коли шлях
|
||||
вказує за межі поточного робочого простору.
|
||||
Якщо той самий визначений шлях з’являється і в `memory.qmd.paths`, і в
|
||||
`memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає
|
||||
дублікат.
|
||||
|
||||
---
|
||||
|
||||
## Multimodal memory (Gemini)
|
||||
## Мультимодальна пам’ять (Gemini)
|
||||
|
||||
Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2:
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------------- | ---------- | --------------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Увімкнути multimodal indexing |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Увімкнути мультимодальне індексування |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файла для індексації |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файлу для індексування |
|
||||
|
||||
Застосовується лише до файлів у `extraPaths`. Типові корені memory і далі підтримують лише Markdown.
|
||||
Потребує `gemini-embedding-2-preview`. `fallback` має бути `"none"`.
|
||||
Застосовується лише до файлів у `extraPaths`. Типові корені пам’яті залишаються лише для Markdown.
|
||||
Потрібен `gemini-embedding-2-preview`. `fallback` має бути `"none"`.
|
||||
|
||||
Підтримувані формати: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
(зображення); `.mp3`, `.wav`, `.ogg`, `.opus`, `.m4a`, `.aac`, `.flac` (аудіо).
|
||||
|
||||
---
|
||||
|
||||
## Кеш embeddings
|
||||
## Кеш ембедингів
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------ | --------- | --------------- | ---------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Кешувати embeddings чанків у SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Максимум кешованих embeddings |
|
||||
| `cache.enabled` | `boolean` | `false` | Кешувати ембединги чанків у SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Максимум кешованих ембедингів |
|
||||
|
||||
Запобігає повторному embedding незміненого тексту під час reindex або оновлень транскриптів.
|
||||
Запобігає повторному створенню ембедингів для незміненого тексту під час переіндексації або оновлень транскриптів.
|
||||
|
||||
---
|
||||
|
||||
## Пакетна індексація
|
||||
## Пакетне індексування
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ----------------------------- | --------- | --------------- | ---------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Увімкнути пакетний API embedding |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ----------------------------- | --------- | --------------- | ------------------------------ |
|
||||
| `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 зазвичай
|
||||
найшвидший і найдешевший для великих зворотних індексацій.
|
||||
найшвидший і найдешевший для великих зворотних заповнень.
|
||||
|
||||
---
|
||||
|
||||
## Memory search сесій (експериментально)
|
||||
## Пошук у пам’яті сесій (експериментально)
|
||||
|
||||
Індексуйте транскрипти сесій і відображайте їх через `memory_search`:
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------------- | ---------- | --------------- | ------------------------------------------ |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексацію сесій |
|
||||
| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для reindex |
|
||||
| `sync.sessions.deltaMessages`| `number` | `50` | Поріг повідомлень для reindex |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ----------------------------- | ---------- | --------------- | ------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексування сесій |
|
||||
| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для переіндексації |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для переіндексації |
|
||||
|
||||
Індексація сесій є opt-in і виконується асинхронно. Результати можуть бути трохи
|
||||
застарілими. Логи сесій живуть на диску, тому вважайте доступ до файлової системи
|
||||
Індексування сесій виконується за явною згодою і працює асинхронно. Результати можуть бути
|
||||
дещо застарілими. Журнали сесій зберігаються на диску, тож вважайте доступ до файлової системи
|
||||
межею довіри.
|
||||
|
||||
---
|
||||
|
||||
## Прискорення векторів SQLite (sqlite-vec)
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------------- | --------- | --------------- | ------------------------------------ |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для vector queries |
|
||||
| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------------------------- | --------- | --------------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів |
|
||||
| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec |
|
||||
|
||||
Коли sqlite-vec недоступний, OpenClaw автоматично повертається до cosine
|
||||
similarity у процесі.
|
||||
Коли sqlite-vec недоступний, OpenClaw автоматично повертається до косинусної
|
||||
схожості в межах процесу.
|
||||
|
||||
---
|
||||
|
||||
## Зберігання індексу
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------- | -------- | -------------------------------------- | ------------------------------------------------ |
|
||||
| `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.backend = "qmd"`. Усі налаштування QMD розміщені в
|
||||
`memory.qmd`:
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------------ | --------- | --------------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Шлях до виконуваного файла QMD |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------------ | --------- | --------------- | ------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | Шлях до виконуваного файлу QMD |
|
||||
| `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` | -- | Каталог експорту |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сесій |
|
||||
| `sessions.retentionDays` | `number` | -- | Термін зберігання транскриптів |
|
||||
| `sessions.exportDir` | `string` | -- | Каталог експорту |
|
||||
|
||||
OpenClaw надає перевагу поточним формам collection і MCP query у QMD, але
|
||||
зберігає працездатність старіших випусків QMD, повертаючись до застарілих прапорців collection `--mask`
|
||||
та старіших назв MCP tools за потреби.
|
||||
OpenClaw віддає перевагу поточним формам колекцій QMD і запитів MCP, але
|
||||
підтримує старіші випуски QMD, за потреби повертаючись до застарілих прапорців колекцій `--mask`
|
||||
і старіших назв інструментів MCP.
|
||||
|
||||
Перевизначення моделей QMD залишаються на стороні QMD, а не в конфігурації OpenClaw. Якщо вам потрібно
|
||||
Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно
|
||||
глобально перевизначити моделі QMD, задайте змінні середовища, такі як
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у
|
||||
runtime-середовищі gateway.
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у середовищі виконання Gateway.
|
||||
|
||||
### Розклад оновлення
|
||||
### Розклад оновлень
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------------- | --------- | --------------- | ------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | Інтервал оновлення |
|
||||
| `update.debounceMs` | `number` | `15000` | Debounce змін файлів |
|
||||
| `update.debounceMs` | `number` | `15000` | Debounce для змін файлів |
|
||||
| `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення |
|
||||
| `update.embedInterval` | `string` | -- | Окремий ритм embed |
|
||||
| `update.embedInterval` | `string` | -- | Окрема частота ембедингів |
|
||||
| `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD |
|
||||
| `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій embed QMD |
|
||||
| `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій ембедингів QMD |
|
||||
|
||||
### Обмеження
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ------------------------- | -------- | --------------- | ------------------------------ |
|
||||
| `limits.maxResults` | `number` | `6` | Максимум результатів пошуку |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Обмежити довжину снипета |
|
||||
| `limits.maxSnippetChars` | `number` | -- | Обмежити довжину сніпета |
|
||||
| `limits.maxInjectedChars` | `number` | -- | Обмежити загальну кількість вставлених символів |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку |
|
||||
|
||||
### Scope
|
||||
### Область дії
|
||||
|
||||
Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й
|
||||
Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й для
|
||||
[`session.sendPolicy`](/uk/gateway/configuration-reference#session):
|
||||
|
||||
```json5
|
||||
@ -442,21 +444,21 @@ runtime-середовищі gateway.
|
||||
}
|
||||
```
|
||||
|
||||
Постачуване типове значення дозволяє direct і channel sessions, водночас і далі забороняючи
|
||||
groups.
|
||||
Типова конфігурація в постачанні дозволяє прямі сесії та сесії каналів, водночас забороняючи
|
||||
групи.
|
||||
|
||||
Типове значення — лише DM. `match.keyPrefix` зіставляється з нормалізованим ключем сесії;
|
||||
`match.rawKeyPrefix` зіставляється з сирим ключем, включно з `agent:<id>:`.
|
||||
|
||||
### Citations
|
||||
### Цитування
|
||||
|
||||
`memory.citations` застосовується до всіх backend:
|
||||
`memory.citations` застосовується до всіх бекендів:
|
||||
|
||||
| Значення | Поведінка |
|
||||
| ---------------- | --------------------------------------------------- |
|
||||
| `auto` (типово) | Включати footer `Source: <path#line>` у снипети |
|
||||
| `on` | Завжди включати footer |
|
||||
| `off` | Не включати footer (шлях усе одно передається агенту внутрішньо) |
|
||||
| `auto` (типово) | Додає нижній колонтитул `Source: <path#line>` у сніпети |
|
||||
| `on` | Завжди додає нижній колонтитул |
|
||||
| `off` | Не додає нижній колонтитул (шлях усе одно передається агенту внутрішньо) |
|
||||
|
||||
### Повний приклад QMD
|
||||
|
||||
@ -486,17 +488,17 @@ groups.
|
||||
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).
|
||||
|
||||
### Налаштування користувача
|
||||
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ----------- | --------- | --------------- | ----------------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Повністю ввімкнути або вимкнути Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Необов’язковий Cron-ритм для повного проходу Dreaming |
|
||||
| Ключ | Тип | Типове значення | Опис |
|
||||
| ---------- | --------- | --------------- | ------------------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | Увімкнути або повністю вимкнути Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Необов’язкова Cron-частота для повного проходу Dreaming |
|
||||
|
||||
### Приклад
|
||||
|
||||
@ -519,6 +521,6 @@ Dreaming виконується як один запланований прох
|
||||
|
||||
Примітки:
|
||||
|
||||
- Dreaming записує стан машини в `memory/.dreams/`.
|
||||
- Dreaming записує людиночитний наративний вивід у `DREAMS.md` (або наявний `dreams.md`).
|
||||
- Політика та пороги фаз light/deep/REM є внутрішньою поведінкою, а не користувацькою конфігурацією.
|
||||
- Dreaming записує машинний стан у `memory/.dreams/`.
|
||||
- Dreaming записує зрозумілий людині наративний вивід у `DREAMS.md` (або наявний `dreams.md`).
|
||||
- Політика фаз light/deep/REM і порогові значення є внутрішньою поведінкою, а не користувацькою конфігурацією.
|
||||
|
||||
@ -4,48 +4,48 @@ read_when:
|
||||
summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage
|
||||
title: Тести
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:11:07Z"
|
||||
generated_at: "2026-04-23T21:58:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f6b9c765c8a6a3ad668626e0787a9a94bcb250d2627594ef960ab024f229e8ca
|
||||
source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54
|
||||
source_path: reference/test.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
- Повний набір для тестування (сьюти, live, Docker): [Тестування](/uk/help/testing)
|
||||
|
||||
- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували з уже запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив порт 18789 зайнятим.
|
||||
- `pnpm test:coverage`: запускає unit-сьют з покриттям V8 (через `vitest.unit.config.ts`). Це поріг покриття завантажених unit-файлів, а не покриття всіх файлів у всьому репозиторії. Пороги: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, поріг вимірює файли, завантажені unit-сьютом покриття, замість того щоб вважати всі файли split-lane source непокритими.
|
||||
- `pnpm test:coverage:changed`: запускає unit coverage лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lanes, коли diff торкається лише routable source/test-файлів. Зміни config/setup, як і раніше, використовують запасний варіант — native root projects run — щоб зміни wiring, де потрібно, повторно запускалися ширше.
|
||||
- `pnpm changed:lanes`: показує архітектурні lanes, які запускає diff відносно `origin/main`.
|
||||
- `pnpm check:changed`: запускає smart changed gate для diff відносно `origin/main`. Він запускає core-роботу з core test lanes, extension-роботу з extension test lanes, роботу лише з тестами — лише з test typecheck/tests, розширює зміни в public Plugin SDK або plugin-contract до перевірки extension і залишає зміни лише в release metadata та version bump на цільових перевірках version/config/root-dependency.
|
||||
- `pnpm test`: маршрутизує явні цілі file/directory через scoped Vitest lanes. Запуски без конкретної цілі використовують фіксовані shard groups і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard-конфігурацій для кожного extension окремо, а не до одного гігантського root-project процесу.
|
||||
- Повні та shard-запуски extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; подальші запуски використовують ці таймінги, щоб балансувати повільні та швидкі shards. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
|
||||
- Вибрані test-файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lanes, які залишають лише `test/setup.ts`, тоді як важкі runtime-кейси залишаються на своїх наявних lanes.
|
||||
- Вибрані source helper-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними sibling-тестами в цих легких lanes, тож малі зміни helper не змушують повторно запускати важкі runtime-backed сьюти.
|
||||
- `auto-reply` тепер також розділено на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper.
|
||||
- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний runner без ізоляції увімкнено по всіх конфігураціях репозиторію.
|
||||
- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує порт керування за замовчуванням, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789.
|
||||
- `pnpm test:coverage`: запускає набір unit-тестів з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття unit-тестів для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення: 70% для рядків/функцій/інструкцій і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit-тестів з покриттям, замість того щоб вважати всі файли вихідного коду з розбитих lane непокритими.
|
||||
- `pnpm test:coverage:changed`: запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:changed`: розгортає змінені шляхи git у scoped lane Vitest, коли diff торкається лише routable файлів джерела/тестів. Зміни конфігурації/налаштування, як і раніше, повертаються до нативного запуску root projects, щоб за потреби правки wiring запускали ширший прогін.
|
||||
- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`.
|
||||
- `pnpm check:changed`: запускає розумну перевірку changed gate для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lane, роботу над розширеннями — з extension test lane, роботу лише над тестами — лише з typecheck/tests для тестів, розгортає зміни публічного Plugin SDK або plugin-contract до перевірки розширень і залишає version bump лише в release metadata на цільових перевірках version/config/root-dependency.
|
||||
- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілі використовують фіксовані shard-групи та розгортаються в leaf configs для локального паралельного виконання; група розширень завжди розгортається в shard-конфіги для кожного extension/plugin, а не в один великий процес root-project.
|
||||
- Повні запуски та запуски shard розширень оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів.
|
||||
- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane, які залишають тільки `test/setup.ts`, а ресурсомісткі runtime-кейси лишаються на своїх наявних lane.
|
||||
- Вибрані файли вихідного коду helper у `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane, щоб невеликі правки helper не перезапускали важкі сьюти, що залежать від runtime.
|
||||
- `auto-reply` тепер також поділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper.
|
||||
- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний non-isolated runner увімкнено в усіх конфігураціях репозиторію.
|
||||
- `pnpm test:channels` запускає `vitest.channels.config.ts`.
|
||||
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shards extension/plugin. Важкі channel extensions і OpenAI працюють як окремі shards; інші групи extension залишаються об’єднаними. Використовуйте `pnpm test extensions/<id>` для одного lane вбудованого Plugin.
|
||||
- `pnpm test:perf:imports`: вмикає звітування Vitest про тривалість імпорту та import-breakdown, при цьому зберігаючи scoped lane routing для явних цілей file/directory.
|
||||
- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` порівнює routed changed-mode path з native root-project run для того самого committed git diff.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` порівнює поточний набір змін у worktree без попереднього commit.
|
||||
- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugin, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin лишаються згрупованими. Використовуйте `pnpm test extensions/<id>` для одного lane bundled plugin.
|
||||
- `pnpm test:perf:imports`: вмикає звітність Vitest щодо тривалості імпорту та деталізації імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів.
|
||||
- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` виконує benchmark маршрутизованого changed-режиму проти нативного запуску root-project для того самого закоміченого git diff.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту.
|
||||
- `pnpm test:perf:profile:main`: записує CPU-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`).
|
||||
- `pnpm test:perf:profile:runner`: записує CPU + heap-профілі для unit runner (`.artifacts/vitest-runner-profile`).
|
||||
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest для повного набору і записує згруповані дані тривалості плюс JSON/log-артефакти для кожної конфігурації. Агент продуктивності тестів використовує це як базову лінію перед спробами виправлення повільних тестів.
|
||||
- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`).
|
||||
- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest повного набору та записує дані про тривалість за групами, а також JSON/лог-артефакти для кожної конфігурації. Агент Test Performance використовує це як базову лінію перед спробою виправити повільні тести.
|
||||
- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність.
|
||||
- Інтеграція Gateway: opt-in через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: запускає end-to-end smoke-тести gateway (multi-instance WS/HTTP/node pairing). Типово використовує `threads` + `isolate: false` з адаптивними worker у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=<n>` і встановіть `OPENCLAW_E2E_VERBOSE=1` для докладних журналів.
|
||||
- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потребує API keys і `LIVE=1` (або специфічних для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск.
|
||||
- `pnpm test:docker:all`: один раз збирає спільний образ live-test і образ Docker E2E, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`, типово з паралелізмом 4. Налаштовуйте через `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. Runner припиняє планувати нові pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lanes, чутливі до старту або провайдера, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests/<run-id>/`.
|
||||
- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного live model key (наприклад OpenAI у `~/.profile`), витягує зовнішній образ Open WebUI і не очікується, що буде настільки ж стабільним для CI, як звичайні unit/e2e сьюти.
|
||||
- `pnpm test:docker:mcp-channels`: запускає seeded Gateway container і другий client container, який стартує `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, outbound send routing і сповіщення у стилі Claude про channel + permission через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, тож smoke відображає те, що bridge фактично передає.
|
||||
- Інтеграція Gateway: увімкнення за бажанням через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (multi-instance WS/HTTP/node pairing). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю worker у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=<n>`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`.
|
||||
- `pnpm test:live`: запускає live-тести provider (minimax/zai). Потрібні API-ключі та `LIVE=1` (або provider-специфічний `*_LIVE_TEST=1`) для зняття `skip`.
|
||||
- `pnpm test:docker:all`: один раз збирає спільний образ для live-тестів і Docker E2E image, а потім запускає Docker smoke lane з `OPENCLAW_SKIP_DOCKER_BUILD=1` і типовим паралелізмом 4. Налаштовується через `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а для кожного lane діє тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до старту або provider, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests/<run-id>/`.
|
||||
- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксований чат через `/api/chat/completions`. Потрібен робочий live model key (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і цей сценарій не очікується стабільним у CI так, як звичайні unit/e2e сьюти.
|
||||
- `pnpm test:docker:mcp-channels`: запускає seeded-контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-фрейми напряму, щоб smoke-тест відображав те, що міст фактично надсилає.
|
||||
|
||||
## Локальний PR gate
|
||||
## Локальна PR-перевірка
|
||||
|
||||
Для локальних перевірок land/gate PR запускайте:
|
||||
Для локальних перевірок перед злиттям PR запускайте:
|
||||
|
||||
- `pnpm check:changed`
|
||||
- `pnpm check`
|
||||
@ -54,12 +54,12 @@ x-i18n:
|
||||
- `pnpm test`
|
||||
- `pnpm check:docs`
|
||||
|
||||
Якщо `pnpm test` дає flaky-збої на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
|
||||
Якщо `pnpm test` нестабільно працює на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте проблему через `pnpm test <path/to/test>`. Для хостів з обмеженою пам’яттю використовуйте:
|
||||
|
||||
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
|
||||
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
|
||||
|
||||
## Бенч затримки моделі (локальні ключі)
|
||||
## Benchmark затримки моделі (локальні ключі)
|
||||
|
||||
Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts)
|
||||
|
||||
@ -67,14 +67,14 @@ x-i18n:
|
||||
|
||||
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
|
||||
- Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
|
||||
- Типовий prompt: “Reply with a single word: ok. No punctuation or extra text.”
|
||||
- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.”
|
||||
|
||||
Останній запуск (2025-12-31, 20 запусків):
|
||||
Останній запуск (2025-12-31, 20 прогонів):
|
||||
|
||||
- minimax median 1279ms (min 1114, max 2431)
|
||||
- opus median 2454ms (min 1224, max 3170)
|
||||
|
||||
## Бенч запуску CLI
|
||||
## Benchmark запуску CLI
|
||||
|
||||
Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
|
||||
|
||||
@ -95,41 +95,41 @@ x-i18n:
|
||||
- `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu`
|
||||
- `pnpm tsx scripts/bench-cli-startup.ts --json`
|
||||
|
||||
Набори пресетів:
|
||||
Preset:
|
||||
|
||||
- `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status`
|
||||
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
|
||||
- `all`: обидва пресети
|
||||
- `all`: обидва preset
|
||||
|
||||
Вивід включає `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, тож захоплення таймінгів і профілів використовує той самий harness.
|
||||
Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного прогону, тож вимірювання часу та захоплення профілю використовують той самий harness.
|
||||
|
||||
Домовленості щодо збереженого виводу:
|
||||
Умовні позначення для збереженого виводу:
|
||||
|
||||
- `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json`
|
||||
- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1`
|
||||
- `pnpm test:startup:bench:update` оновлює закомічений baseline-fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1`
|
||||
- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1`
|
||||
|
||||
Закомічений fixture:
|
||||
|
||||
- `test/fixtures/cli-startup-bench.json`
|
||||
- Оновити: `pnpm test:startup:bench:update`
|
||||
- Порівняти поточні результати з fixture: `pnpm test:startup:bench:check`
|
||||
- Оновлення: `pnpm test:startup:bench:update`
|
||||
- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check`
|
||||
|
||||
## Onboarding E2E (Docker)
|
||||
|
||||
Docker необов’язковий; це потрібно лише для containerized onboarding smoke-тестів.
|
||||
Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів.
|
||||
|
||||
Повний cold-start flow у чистому Linux container:
|
||||
Повний cold-start сценарій у чистому Linux-контейнері:
|
||||
|
||||
```bash
|
||||
scripts/e2e/onboard-docker.sh
|
||||
```
|
||||
|
||||
Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`.
|
||||
Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`.
|
||||
|
||||
## QR import smoke (Docker)
|
||||
## Smoke-тест імпорту QR (Docker)
|
||||
|
||||
Переконується, що підтримуваний helper QR runtime завантажується в підтримуваних Docker Node runtime (типово Node 24, сумісність із Node 22):
|
||||
Переконується, що підтримуваний QR runtime helper завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22):
|
||||
|
||||
```bash
|
||||
pnpm test:docker:qr
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Генерація зображень через агента
|
||||
- Налаштування providers і моделей для генерації зображень
|
||||
- Розуміння параметрів інструмента image_generate
|
||||
summary: Генерувати та редагувати зображення за допомогою налаштованих providers (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)
|
||||
- Генерування зображень через агента
|
||||
- Налаштування provider і моделей для генерації зображень
|
||||
- Розуміння параметрів інструмента `image_generate`
|
||||
summary: Генеруйте та редагуйте зображення за допомогою налаштованих provider (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)
|
||||
title: Генерація зображень
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:15:30Z"
|
||||
generated_at: "2026-04-23T21:59:24Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2ca23553fa80fbc286046baa2bdb639aab76a24f2d55dc1764085f57b24be29e
|
||||
source_hash: 77b104fb5e7d1a512d77493218276b9000c03a05b7579719ac9d182603d6b03e
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Інструмент `image_generate` дає агенту змогу створювати й редагувати зображення за допомогою ваших налаштованих providers. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
|
||||
Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою налаштованих provider. Згенеровані зображення автоматично додаються як медіавкладення у відповідь агента.
|
||||
|
||||
<Note>
|
||||
Інструмент з’являється лише тоді, коли доступний принаймні один provider генерації зображень. Якщо ви не бачите `image_generate` серед інструментів агента, налаштуйте `agents.defaults.imageGenerationModel` або задайте API-ключ provider.
|
||||
Інструмент з’являється лише тоді, коли доступний принаймні один provider для генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ provider або увійдіть через OpenAI Codex OAuth.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
1. Задайте API-ключ принаймні для одного provider (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`).
|
||||
1. Задайте API-ключ принаймні для одного provider (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth.
|
||||
2. За бажанням задайте бажану модель:
|
||||
|
||||
```json5
|
||||
@ -37,24 +37,25 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
3. Попросіть агента: _"Generate an image of a friendly lobster mascot."_
|
||||
Codex OAuth використовує той самий ref моделі `openai/gpt-image-2`. Коли налаштовано профіль OAuth `openai-codex`, OpenClaw маршрутизує запити на зображення через цей самий профіль OAuth замість того, щоб спочатку пробувати `OPENAI_API_KEY`. Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API-ключ або custom/Azure base URL, знову вмикає прямий маршрут через OpenAI Images API.
|
||||
|
||||
Агент автоматично викличе `image_generate`. Додавання в allow-list інструментів не потрібне — він типово ввімкнений, коли доступний provider.
|
||||
3. Попросіть агента: _«Згенеруй зображення дружнього робота-маскота.»_
|
||||
|
||||
## Підтримувані providers
|
||||
Агент автоматично викликає `image_generate`. Додавати інструмент до allow-list не потрібно — він увімкнений за замовчуванням, коли provider доступний.
|
||||
|
||||
| Provider | Типова модель | Підтримка редагування | API-ключ |
|
||||
| ------------ | ------------------------------- | -------------------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` |
|
||||
| OpenAI Codex | `gpt-image-2` | Так (до 4 зображень) | OpenAI Codex OAuth |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Так (посилання на subject) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, залежить від workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
## Підтримувані provider
|
||||
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні providers і моделі під час виконання:
|
||||
| Provider | Модель за замовчуванням | Підтримка редагування | Автентифікація |
|
||||
| -------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------ |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Так (референс суб’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, задається workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні provider і моделі під час виконання:
|
||||
|
||||
```
|
||||
/tool image_generate action=list
|
||||
@ -62,22 +63,22 @@ x-i18n:
|
||||
|
||||
## Параметри інструмента
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| ------------- | --------- | ------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Prompt для генерації зображення (обов’язковий для `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (типово) або `"list"` для перегляду providers |
|
||||
| `model` | string | Перевизначення provider/model, наприклад `openai/gpt-image-2` |
|
||||
| `image` | string | Шлях або URL одного опорного зображення для режиму редагування |
|
||||
| `images` | string[] | Кілька опорних зображень для режиму редагування (до 5) |
|
||||
| `size` | string | Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` |
|
||||
| `aspectRatio` | string | Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | Підказка роздільної здатності: `1K`, `2K` або `4K` |
|
||||
| `count` | number | Кількість зображень для генерації (1–4) |
|
||||
| `filename` | string | Підказка для імені вихідного файла |
|
||||
| Параметр | Тип | Опис |
|
||||
| ------------ | -------- | ------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Prompt для генерації зображення (обов’язковий для `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (за замовчуванням) або `"list"` для перегляду provider |
|
||||
| `model` | string | Перевизначення provider/моделі, наприклад `openai/gpt-image-2` |
|
||||
| `image` | string | Шлях або URL одного референсного зображення для режиму редагування |
|
||||
| `images` | string[] | Кілька референсних зображень для режиму редагування (до 5) |
|
||||
| `size` | string | Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` |
|
||||
| `aspectRatio`| string | Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | Підказка роздільної здатності: `1K`, `2K` або `4K` |
|
||||
| `count` | number | Кількість зображень для генерації (1–4) |
|
||||
| `filename` | string | Підказка для імені вихідного файлу |
|
||||
|
||||
Не всі providers підтримують усі параметри. Коли fallback-provider підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує на найближчий підтримуваний `size`, `aspectRatio` або `resolution`. Справді непідтримувані перевизначення все одно повідомляються в результаті інструмента.
|
||||
Не всі provider підтримують усі параметри. Коли fallback provider підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням зіставляє запит із найближчим підтримуваним розміром, співвідношенням сторін або роздільною здатністю. Справді непідтримувані перевизначення все одно зазначаються в результаті інструмента.
|
||||
|
||||
Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час fallback provider, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
|
||||
Результати інструмента показують застосовані налаштування. Коли OpenClaw змінює геометрію під час fallback provider, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -98,114 +99,102 @@ x-i18n:
|
||||
|
||||
### Порядок вибору provider
|
||||
|
||||
Під час генерації зображення OpenClaw пробує providers у такому порядку:
|
||||
Під час генерації зображення OpenClaw пробує provider у такому порядку:
|
||||
|
||||
1. **Параметр `model`** з виклику інструмента (якщо агент його вказує)
|
||||
2. **`imageGenerationModel.primary`** з config
|
||||
3. **`imageGenerationModel.fallbacks`** у вказаному порядку
|
||||
4. **Автовизначення** — використовує лише типові значення providers, підкріплені auth:
|
||||
- спочатку поточний типовий provider
|
||||
- далі решта зареєстрованих providers генерації зображень у порядку provider-id
|
||||
1. **Параметр `model`** із виклику інструмента (якщо агент його задає)
|
||||
2. **`imageGenerationModel.primary`** із конфігурації
|
||||
3. **`imageGenerationModel.fallbacks`** у заданому порядку
|
||||
4. **Автовизначення** — використовує лише типові значення provider, підкріплені автентифікацією:
|
||||
- спочатку поточний provider за замовчуванням
|
||||
- далі решта зареєстрованих provider генерації зображень у порядку provider-id
|
||||
|
||||
Якщо provider не спрацьовує (помилка auth, rate limit тощо), автоматично пробується наступний кандидат. Якщо не спрацювали всі, помилка містить подробиці кожної спроби.
|
||||
Якщо provider завершується помилкою (помилка автентифікації, rate limit тощо), автоматично пробується наступний кандидат. Якщо не спрацьовують усі, помилка містить подробиці про кожну спробу.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Автовизначення враховує auth. Типове значення provider потрапляє до списку кандидатів
|
||||
лише тоді, коли OpenClaw справді може автентифікувати цей provider.
|
||||
- Автовизначення типово ввімкнено. Установіть
|
||||
`agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`.
|
||||
- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих providers,
|
||||
їхні типові моделі та підказки щодо auth env-var.
|
||||
- Автовизначення враховує автентифікацію. Типовий provider потрапляє до списку кандидатів лише тоді, коли OpenClaw справді може автентифікувати цей provider.
|
||||
- Автовизначення ввімкнене за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`.
|
||||
- Використовуйте `action: "list"`, щоб переглянути поточні зареєстровані provider, їхні моделі за замовчуванням і підказки щодо env var для автентифікації.
|
||||
|
||||
### Редагування зображень
|
||||
|
||||
OpenAI, Google, fal, MiniMax, ComfyUI та xAI підтримують редагування опорних зображень. Передайте шлях або URL опорного зображення:
|
||||
OpenAI, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування референсних зображень. Передайте шлях або URL референсного зображення:
|
||||
|
||||
```
|
||||
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
|
||||
"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
OpenAI, Google та xAI підтримують до 5 опорних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
OpenAI, Google і xAI підтримують до 5 референсних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
Генерація зображень OpenAI типово використовує `openai/gpt-image-2`. Старішу
|
||||
модель `openai/gpt-image-1` усе ще можна вибрати явно, але для нових запитів на генерацію зображень і редагування зображень через OpenAI слід використовувати `gpt-image-2`.
|
||||
Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано профіль OAuth `openai-codex`, OpenClaw повторно використовує той самий профіль OAuth, що й для моделей чату за підпискою Codex, і надсилає запит на зображення через бекенд Codex Responses; він не виконує непомітний fallback на `OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут через OpenAI Images API, явно налаштуйте `models.providers.openai` за допомогою API-ключа, custom base URL або Azure endpoint. Старішу модель `openai/gpt-image-1` усе ще можна явно вибрати, але нові запити OpenAI на генерацію та редагування зображень мають використовувати `gpt-image-2`.
|
||||
|
||||
`gpt-image-2` підтримує як генерацію text-to-image, так і редагування опорних зображень через той самий інструмент `image_generate`. OpenClaw передає в OpenAI `prompt`,
|
||||
`count`, `size` і опорні зображення. OpenAI не отримує
|
||||
`aspectRatio` або `resolution` напряму; коли можливо, OpenClaw відображає їх у
|
||||
підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення.
|
||||
`gpt-image-2` підтримує як генерацію зображень за текстом, так і редагування за референсним зображенням через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size` і референсні зображення. OpenAI не отримує `aspectRatio` або `resolution` напряму; коли можливо, OpenClaw зіставляє їх із підтримуваним `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення.
|
||||
|
||||
Згенерувати одне landscape-зображення 4K:
|
||||
Згенерувати одне панорамне 4K-зображення:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Згенерувати два квадратні зображення:
|
||||
Згенерувати два квадратних зображення:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
|
||||
```
|
||||
|
||||
Відредагувати одне локальне опорне зображення:
|
||||
Відредагувати одне локальне референсне зображення:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Редагування з кількома опорними зображеннями:
|
||||
Редагування з кількома референсами:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
```
|
||||
|
||||
Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість
|
||||
`api.openai.com`, див. [Azure OpenAI endpoints](/uk/providers/openai#azure-openai-endpoints)
|
||||
у документації провайдера OpenAI.
|
||||
Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. [Azure OpenAI endpoints](/uk/providers/openai#azure-openai-endpoints) у документації provider OpenAI.
|
||||
|
||||
Генерація зображень MiniMax доступна через обидва вбудовані шляхи auth MiniMax:
|
||||
Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax:
|
||||
|
||||
- `minimax/image-01` для налаштувань через API-ключ
|
||||
- `minimax-portal/image-01` для налаштувань через OAuth
|
||||
- `minimax/image-01` для налаштувань з API-ключем
|
||||
- `minimax-portal/image-01` для налаштувань з OAuth
|
||||
|
||||
## Можливості providers
|
||||
## Можливості provider
|
||||
|
||||
| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ------------------------------------ | ------- | -------------------- |
|
||||
| Generate | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначені workflow outputs) | Так (1) | Так (до 4) |
|
||||
| Edit/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, subject ref) | Так (1 зображення, залежить від workflow) | Ні | Так (до 5 зображень) |
|
||||
| Керування size | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні |
|
||||
| Aspect ratio | Ні | Так | Так (лише generate) | Так | Ні | Ні | Так |
|
||||
| Resolution (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
|
||||
| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
|
||||
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначається виходами workflow) | Так (1) | Так (до 4) |
|
||||
| Редагування/референс | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, референс суб’єкта) | Так (1 зображення, задається workflow) | Ні | Так (до 5 зображень) |
|
||||
| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні |
|
||||
| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так |
|
||||
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
|
||||
|
||||
### xAI `grok-imagine-image`
|
||||
|
||||
Вбудований provider xAI використовує `/v1/images/generations` для запитів лише з prompt
|
||||
і `/v1/images/edits`, коли присутній `image` або `images`.
|
||||
Вбудований provider xAI використовує `/v1/images/generations` для запитів лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`.
|
||||
|
||||
- Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
|
||||
- Count: до 4
|
||||
- Опорні зображення: один `image` або до п’яти `images`
|
||||
- Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Resolutions: `1K`, `2K`
|
||||
- Outputs: повертаються як керовані OpenClaw вкладення зображень
|
||||
- Кількість: до 4
|
||||
- Референси: один `image` або до п’яти `images`
|
||||
- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Роздільна здатність: `1K`, `2K`
|
||||
- Результати: повертаються як керовані OpenClaw вкладення зображень
|
||||
|
||||
OpenClaw навмисно не надає xAI-нативні `quality`, `mask`, `user` або
|
||||
додаткові native-only aspect ratios, доки ці елементи керування не з’являться в спільному
|
||||
крос-провайдерному контракті `image_generate`.
|
||||
OpenClaw навмисно не відкриває для xAI рідні параметри `quality`, `mask`, `user` або додаткові співвідношення сторін, доступні лише нативно, доки ці елементи керування не з’являться в спільному міжprovider-ному контракті `image_generate`.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд Tools](/uk/tools) — усі доступні інструменти агента
|
||||
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
|
||||
- [fal](/uk/providers/fal) — налаштування provider зображень і відео fal
|
||||
- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та Comfy Cloud workflow
|
||||
- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та workflow Comfy Cloud
|
||||
- [Google (Gemini)](/uk/providers/google) — налаштування provider зображень Gemini
|
||||
- [MiniMax](/uk/providers/minimax) — налаштування provider зображень MiniMax
|
||||
- [OpenAI](/uk/providers/openai) — налаштування provider OpenAI Images
|
||||
- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та speech у Vydra
|
||||
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, search, виконання коду та TTS
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — config `imageGenerationModel`
|
||||
- [Models](/uk/concepts/models) — конфігурація моделей і failover
|
||||
- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra
|
||||
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS
|
||||
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `imageGenerationModel`
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і failover
|
||||
|
||||
Loading…
Reference in New Issue
Block a user