diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 9a18674af..436fd33d9 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,49 +1,112 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI було або не було запущене - - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, обмежувальні перевірки за областю змін і локальні еквіваленти команд -title: конвеєр CI + - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Ви налагоджуєте перевірки GitHub Actions, які не пройшли +summary: Граф завдань CI, шлюзи областей і локальні еквіваленти команд +title: пайплайн CI x-i18n: - generated_at: "2026-04-27T23:13:06Z" + generated_at: "2026-04-28T00:03:40Z" model: gpt-5.4 provider: openai - source_hash: 0f9181fe819550b195068ded66076722323e055e5a9f1e46bff61ba205ae5f8c + source_hash: 4d9fabbc0980661076f4b0187dda4ac682b2361943266c7ec85a8cf38796299a source_path: ci.md workflow: 15 --- -CI запускається для кожного push до `main` і для кожного pull request. Він використовує розумне обмеження за областю змін, щоб пропускати дорогі завдання, коли змінювалися лише не пов’язані ділянки. Ручні запуски через `workflow_dispatch` навмисно обходять це розумне обмеження й розгортають повний звичайний граф CI для кандидатів на реліз або широкої валідації. +Пайплайн CI запускається при кожному пуші в `main` і для кожного pull request. Він використовує розумне визначення області, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне визначення області й розгортають повний звичайний граф CI для кандидатів на реліз або широкої валідації. -`Full Release Validation` — це ручний umbrella workflow для сценарію «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю та запускає `OpenClaw Release Checks` для інсталяційного smoke-тесту, приймання пакета, Docker-наборів для шляху релізу, live/E2E, OpenWebUI, паритету QA Lab, Matrix і Telegram-ланок. Він також може запускати post-publish workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. Umbrella workflow записує ідентифікатори запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні підсумкові стани дочірніх запусків. Якщо дочірній workflow було перезапущено і він став зеленим, перезапустіть лише батьківське завдання перевірки, щоб оновити результат umbrella workflow. +`Full Release Validation` — це ручний umbrella workflow для сценарію «запустити все +перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний +workflow `CI` з цією ціллю, а також запускає `OpenClaw Release Checks` +для smoke-перевірки встановлення, приймання пакетів, наборів Docker на шляху релізу, live/E2E, +OpenWebUI, паритету QA Lab, Matrix і Telegram lane. Він також може запускати +workflow `NPM Telegram Beta E2E` після публікації, якщо надано специфікацію +опублікованого пакета. Umbrella workflow записує ідентифікатори запущених дочірніх run, а фінальне +завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх run. Якщо +дочірній workflow перезапущено і він став зеленим, перезапустіть лише батьківське завдання верифікації, щоб +оновити результат umbrella workflow. -Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для кандидата на реліз, `ci` лише для звичайного повного дочірнього CI, `release-checks` для кожного дочірнього релізного завдання або вужчу релізну групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` в umbrella workflow. Це дозволяє обмежити повторний запуск невдалого релізного блоку після точкового виправлення. +Для відновлення `Full Release Validation` і `OpenClaw Release Checks` обидва +приймають `rerun_group`. Використовуйте `all` для кандидата на реліз, `ci` лише для +звичайного повного дочірнього CI, `release-checks` для всіх дочірніх перевірок релізу +або вужчу групу релізу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, +`qa-parity`, `qa-live` або `npm-telegram` в umbrella workflow. Це допомагає +обмежити повторний запуск невдалого релізного бокса після точкового виправлення. -Дочірня live/E2E-перевірка релізу зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди (`native-live-src-agents`, `native-live-src-gateway-core`, `native-live-src-gateway-backends`, `native-live-test`, `native-live-extensions-a-k`, `native-live-extensions-l-n`, `native-live-extensions-openai`, `native-live-extensions-o-z` і `native-live-extensions-media`) через `scripts/test-live-shard.mjs`, а не як одне послідовне завдання. Це зберігає те саме файлове покриття, одночасно спрощуючи повторний запуск і діагностику повільних збоїв live-провайдерів. +Дочірній live/E2E workflow релізу зберігає широке native-покриття `pnpm test:live`, але +виконує його як іменовані shard (`native-live-src-agents`, +`native-live-src-gateway-core`, відфільтровані за provider +завдання `native-live-src-gateway-profiles`, +`native-live-src-gateway-backends`, `native-live-test`, +`native-live-extensions-a-k`, `native-live-extensions-l-n`, +`native-live-extensions-openai`, `native-live-extensions-o-z-other`, +`native-live-extensions-xai` і розділені media shard для audio/music/video) через +`scripts/test-live-shard.mjs` замість одного послідовного завдання. Це зберігає те саме +покриття файлів і водночас полегшує повторний запуск і діагностику повільних live-збоїв provider. Агреговані назви shard +`native-live-extensions-o-z` і +`native-live-extensions-media` залишаються валідними для ручних одноразових повторних запусків. -`Package Acceptance` — це окремий workflow для валідації артефакту пакета без блокування workflow релізу. Він визначає одного кандидата з опублікованої npm-специфікації, довіреного `package_ref`, зібраного за допомогою вибраного harness із `workflow_ref`, HTTPS tarball URL із SHA-256 або tarball-артефакту з іншого запуску GitHub Actions, завантажує його як артефакт `package-under-test`, а потім повторно використовує Docker-планувальник релізу/E2E з цим tarball замість перепакування checkout workflow. Профілі охоплюють smoke, package, product, full і custom вибір Docker-ланок. Профіль `package` використовує офлайн-покриття Plugin, тож валідація опублікованого пакета не залежить від доступності live ClawHub. Необов’язкова Telegram-ланка повторно використовує артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, при цьому шлях опублікованої npm-специфікації зберігається для окремих ручних запусків. +`Package Acceptance` — це побічний workflow для перевірки артефакта пакета +без блокування workflow релізу. Він визначає одного кандидата з +опублікованої npm-специфікації, довіреного `package_ref`, зібраного з вибраним +harness `workflow_ref`, HTTPS tarball URL із SHA-256 або артефакта tarball +з іншого run GitHub Actions, завантажує його як артефакт `package-under-test`, а потім повторно використовує +планувальник Docker release/E2E з цим tarball замість повторного пакування checkout +workflow. Профілі охоплюють smoke, package, product, full і власний вибір Docker lane. Профіль +`package` використовує offline-покриття Plugin, тож перевірка опублікованого пакета +не блокується доступністю live ClawHub. Необов’язковий lane Telegram повторно використовує +артефакт `package-under-test` у workflow `NPM Telegram Beta E2E`, а шлях +опублікованої npm-специфікації зберігається для окремих dispatch. ## Приймання пакета -Використовуйте `Package Acceptance`, коли питання звучить як «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, а package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі проходять після встановлення або оновлення. +Використовуйте `Package Acceptance`, коли питання звучить як «чи працює цей +встановлюваний пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI +перевіряє дерево вихідного коду, тоді як приймання пакета перевіряє один tarball через +той самий Docker E2E harness, який користувачі проходять після встановлення або оновлення. Workflow має чотири завдання: -1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і виводить джерело, workflow ref, package ref, версію, SHA-256 і профіль у GitHub step summary. -2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє вміст tarball, за потреби готує Docker-образи з digest пакета і запускає вибрані Docker-ланки проти цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow один раз готує пакет і спільні образи, а потім розгортає ці ланки як паралельні цільові Docker-завдання з унікальними артефактами. -3. `package_telegram` за потреби викликає `NPM Telegram Beta E2E`. Воно запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance його визначив; окремий запуск Telegram, як і раніше, може встановлювати опубліковану npm-специфікацію. -4. `summary` завершує workflow з помилкою, якщо не вдалося визначити пакет, не пройшла Docker acceptance або необов’язкова Telegram-ланка завершилася помилкою. +1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, + записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує + `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як + артефакт `package-under-test` і виводить джерело, workflow ref, package + ref, версію, SHA-256 і профіль у GitHub step summary. +2. `docker_acceptance` викликає + `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і + `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує + цей артефакт, перевіряє інвентар tarball, за потреби готує package-digest + Docker image і запускає вибрані Docker lane для цього пакета замість пакування + checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow + готує пакет і спільні image один раз, а потім розгортає ці lane як + паралельні цільові Docker-завдання з унікальними артефактами. +3. `package_telegram` за потреби викликає `NPM Telegram Beta E2E`. Воно запускається, коли + `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, + якщо Package Acceptance його визначив; окремий dispatch Telegram + усе ще може встановлювати опубліковану npm-специфікацію. +4. `summary` завершує workflow помилкою, якщо не вдалося визначити пакет, не пройшло Docker-приймання або + необов’язковий lane Telegram завершився помилкою. -Джерела кандидатів: +Джерела кандидата: -- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable. -- `source=ref`: пакує довірену гілку, тег або повний SHA коміту з `package_ref`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або з релізного тега, встановлює залежності в detached worktree і пакує їх за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=npm`: приймає лише `openclaw@beta`, `openclaw@latest` або точну + версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для + перевірки опублікованих beta/stable. +- `source=ref`: пакує довірену гілку, тег або повний SHA коміту `package_ref`. + Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт + досяжний з історії гілок репозиторію або тега релізу, встановлює залежності у + detached worktree і пакує їх за допомогою `scripts/package-openclaw-for-docker.mjs`. - `source=url`: завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим. -- `source=artifact`: завантажує один `.tgz` із `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його слід указувати для зовнішньо поширюваних артефактів. +- `source=artifact`: завантажує один `.tgz` з `artifact_run_id` і + `artifact_name`; `package_sha256` необов’язковий, але його слід указувати для + артефактів, якими діляться зовні. -Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/harness, який запускає тест. `package_ref` — це коміт джерела, який пакується, коли `source=ref`. Це дозволяє поточному test harness перевіряти старіші довірені коміти джерела без запуску старої логіки workflow. +Розділяйте `workflow_ref` і `package_ref`. `workflow_ref` — це довірений код +workflow/harness, який запускає тест. `package_ref` — це коміт вихідного коду, +який пакується, коли `source=ref`. Це дозволяє поточному test harness перевіряти +старі довірені коміти вихідного коду без запуску старої логіки workflow. -Профілі відповідають покриттю Docker: +Профілі відповідають Docker-покриттю: - `smoke`: `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package`: `npm-onboard-channel-agent`, `doctor-switch`, @@ -51,22 +114,40 @@ Workflow має чотири завдання: `plugin-update` - `product`: `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full`: повні Docker-чанки шляху релізу з OpenWebUI +- `full`: повні Docker-chunk шляху релізу з OpenWebUI - `custom`: точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Release checks викликає Package Acceptance з `source=ref`, +Перевірки релізу викликають Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і -`telegram_mode=mock-openai`. Docker-чанки шляху релізу покривають ланки package/update/plugin, що перетинаються, тоді як Package Acceptance забезпечує нативну для артефакту перевірку bundled-channel compat, offline Plugin і Telegram на основі того самого визначеного tarball пакета. -Кросплатформені release checks, як і раніше, покривають специфічну для ОС поведінку onboarding, інсталятора та платформи; валідацію продукту для package/update слід починати з Package Acceptance. Ланки Windows packaged та installer fresh також перевіряють, що встановлений пакет може імпортувати перевизначення browser-control із сирого абсолютного шляху Windows. +`telegram_mode=mock-openai`. Docker-chunk +шляху релізу покривають lane пакета/оновлення/Plugin, що перетинаються, тоді як Package +Acceptance зберігає нативну для артефакта перевірку bundled-channel compat, offline Plugin і +доказ Telegram на основі того самого визначеного tarball пакета. +Cross-OS перевірки релізу й надалі покривають специфічну для ОС поведінку onboarding, інсталятора й платформи; +валідацію продукту пакета/оновлення слід починати з Package +Acceptance. Windows lane із пакетом та інсталятором для чистого встановлення також перевіряють, що +встановлений пакет може імпортувати override browser-control із сирого абсолютного шляху Windows. -Package Acceptance має обмежене вікно зворотної сумісності для вже опублікованих пакетів до `2026.4.25`, включно з `2026.4.25-beta.*`. Ці послаблення задокументовані тут, щоб не перетворитися на постійні мовчазні пропуски: відомі приватні записи QA у `dist/postinstall-inventory.json` можуть спричиняти попередження, якщо tarball не містив цих файлів; `doctor-switch` може пропускати підвипадок із збереженням `gateway install --wrapper`, якщо пакет не надає цього прапорця; `update-channel-switch` може обрізати відсутні `pnpm.patchedDependencies` із підробленого git-fixture, похідного від tarball, і може журналювати відсутній збережений `update.channel`; plugin smoke-тести можуть читати застарілі розташування записів про встановлення або приймати відсутність збереження запису встановлення маркетплейсу; а `plugin-update` може дозволяти міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб запис встановлення і поведінка без повторного встановлення залишалися незмінними. Пакети після `2026.4.25` повинні відповідати сучасним контрактам; за тих самих умов буде помилка, а не попередження чи пропуск. +Package Acceptance має обмежене вікно legacy-сумісності для вже +опублікованих пакетів до `2026.4.25`, включно з `2026.4.25-beta.*`. Ці +допуски задокументовано тут, щоб вони не перетворилися на постійні тихі пропуски: +відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть давати +попередження, якщо в tarball не було цих файлів; `doctor-switch` може пропустити +підвипадок збереження `gateway install --wrapper`, якщо пакет не надає +цей прапорець; `update-channel-switch` може відсікати відсутні +`pnpm.patchedDependencies` із tarball-похідного фальшивого git fixture і може логувати відсутній збережений +`update.channel`; smoke-перевірки Plugin можуть читати legacy-розташування install-record або +приймати відсутність збереження install-record marketplace; а `plugin-update` може +дозволяти міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб install record і +поведінка без перевстановлення залишалися незмінними. Пакети після `2026.4.25` мають відповідати +сучасним контрактам; ті самі умови призводять до помилки, а не до попередження чи пропуску. Приклади: ```bash -# Validate the current beta package with product-level coverage. +# Перевірити поточний beta-пакет із покриттям рівня product. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -75,7 +156,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=product \ -f telegram_mode=mock-openai -# Pack and validate a release branch with the current harness. +# Запакувати й перевірити гілку релізу з поточним harness. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -84,7 +165,7 @@ gh workflow run package-acceptance.yml \ -f suite_profile=package \ -f telegram_mode=mock-openai -# Validate a tarball URL. SHA-256 is mandatory for source=url. +# Перевірити tarball URL. Для source=url SHA-256 є обов’язковим. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -93,7 +174,7 @@ gh workflow run package-acceptance.yml \ -f package_sha256=<64-char-sha256> \ -f suite_profile=smoke -# Reuse a tarball uploaded by another Actions run. +# Повторно використати tarball, завантажений іншим run Actions. gh workflow run package-acceptance.yml \ --ref main \ -f workflow_ref=main \ @@ -104,22 +185,67 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску package acceptance почніть із summary у `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: -`.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали ланок, час виконання фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker-ланок замість повторного запуску повної release validation. +Під час налагодження невдалого run package acceptance починайте з +summary `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте +дочірній run `docker_acceptance` і його Docker-артефакти: +`.artifacts/docker-tests/**/summary.json`, `failures.json`, логи lane, phase +timings і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або +точних Docker lane замість повторного запуску повної валідації релізу. -QA Lab має окремі ланки CI поза основним workflow з розумним обмеженням за областю змін. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне середовище виконання QA і порівнює agentic packs для mock GPT-5.5 та Opus 4.6. -Workflow `QA-Lab - All Lanes` запускається щонічно на `main` і через ручний запуск; він розгортає mock parity gate, live Matrix-ланку та live Telegram- і Discord-ланки як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують оренди Convex. Matrix використовує `--profile fast` для запланованих і релізних перевірок, додаючи `--fail-fast` лише тоді, коли CLI з checked-out підтримує його. Значення CLI за замовчуванням і ручний вхід workflow залишаються `all`; ручний запуск із `matrix_profile=all` -завжди шардує повне покриття Matrix на завдання `transport`, `media`, +QA Lab має виділені CI lane поза основним workflow із розумним визначенням області. Workflow +`Parity gate` запускається для відповідних змін у PR і при ручному dispatch; він +збирає приватний runtime QA і порівнює agentic pack mock GPT-5.5 та Opus 4.6. +Workflow `QA-Lab - All Lanes` запускається щоночі для `main` і при +ручному dispatch; він розгортає mock parity gate, live lane Matrix і live +lane Telegram та Discord як паралельні завдання. Live-завдання використовують +середовище `qa-live-shared`, а Telegram/Discord використовують lease Convex. Matrix +використовує `--profile fast` для scheduled і release gate, додаючи `--fail-fast` лише +коли checked-out CLI це підтримує. Значення CLI за замовчуванням і ручний ввід workflow +залишаються `all`; ручний dispatch `matrix_profile=all` +завжди розбиває повне покриття Matrix на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` також -запускає критичні для релізу ланки QA Lab перед погодженням релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва артефакти в невелике report-завдання для фінального порівняння паритету. +запускає критично важливі для релізу lane QA Lab перед затвердженням релізу; його QA parity +gate запускає lane кандидатного й базового pack як паралельні завдання, а потім завантажує +обидва артефакти в невелике завдання звіту для фінального порівняння паритету. -Workflow `Duplicate PRs After Merge` — це ручний workflow супровідника для очищення дублікатів після злиття. За замовчуванням він працює в dry-run режимі й закриває лише явно перелічені PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільне пов’язане issue, або перетин змінених hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для +очищення дублікатів після приземлення. За замовчуванням він працює в режимі dry-run і +закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, він +перевіряє, що приземлений PR уже злитий і що кожен дублікат має або спільне посилання на issue, +або перетин змінених hunks. -Workflow `CodeQL` навмисно є вузьким першим етапом сканування, а не повним обходом усього репозиторію. Щоденні й ручні запуски сканують код workflow Actions і найризикованіші поверхні JavaScript/TypeScript, пов’язані з auth, secrets, sandbox, Cron і Gateway. Критична security-ланка використовує високоточні security-запити, а окрема critical quality-ланка запускає лише несек’юрні запити рівня помилки для тієї самої вузької поверхні JavaScript/TypeScript. Розширення CodeQL на Swift, Android, Python, UI та вбудовані Plugin слід додавати назад лише як окрему scoped або sharded подальшу роботу після того, як вузький профіль матиме стабільний runtime і signal. +Workflow `CodeQL` навмисно є вузьким сканером першого проходу, а не +повним охопленням репозиторію. Щоденні та ручні запуски сканують код workflow Actions і +поверхні JavaScript/TypeScript з найвищим ризиком, пов’язані з auth, секретами, sandbox, +Cron і Gateway. Критично важливий безпековий lane використовує високоточні security query, а +окремий critical quality lane запускає лише non-security query з рівнем error +для тієї самої вузької поверхні JavaScript/TypeScript. Розширення CodeQL на +Swift, Android, Python, UI та bundled Plugin слід повертати лише як +обмежену за областю або шардовану подальшу роботу після того, як вузький профіль матиме стабільний час виконання й корисний сигнал. -Workflow `Docs Agent` — це керована подіями lane технічного обслуговування Codex для підтримання наявної документації у відповідності до нещодавно злитих змін. Вона не має окремого розкладу: її може запустити успішний неботовий CI-запуск push у `main`, а також її можна запустити напряму вручну. Виклики через workflow run пропускаються, якщо `main` уже пішов далі або якщо за останню годину вже було створено інший непропущений запуск Docs Agent. Коли вона запускається, вона переглядає діапазон комітів від попереднього SHA джерела останнього непропущеного Docs Agent до поточного `main`, тому один щогодинний запуск може охопити всі зміни в main, що накопичилися з моменту останнього проходу по документації. +Workflow `Docs Agent` — це event-driven lane обслуговування Codex для підтримання +наявної документації у відповідності до нещодавно приземлених змін. Він не має окремого запуску за розкладом: +його може запустити успішний run CI після пушу в `main`, якщо він не від бота, +а також його можна запустити напряму через ручний dispatch. Виклики через workflow-run пропускаються, +якщо `main` уже пішов далі або якщо інший непропущений run Docs Agent було створено +за останню годину. Коли він запускається, він переглядає діапазон комітів від попереднього +непропущеного вихідного SHA Docs Agent до поточного `main`, тож один щогодинний run +може охопити всі зміни в main, накопичені з моменту останнього проходу документації. -Workflow `Test Performance Agent` — це керована подіями lane технічного обслуговування Codex для повільних тестів. Вона не має окремого розкладу: її може запустити успішний неботовий CI-запуск push у `main`, але вона пропускається, якщо інший виклик через workflow run уже виконувався або виконується в цю добу UTC. Ручний запуск обходить це денне обмеження активності. Lane будує звіт про продуктивність Vitest для повного набору тестів із групуванням, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів без втрати покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору й відхиляє зміни, які зменшують базову кількість успішних тестів. Якщо в базовому стані є тести з помилками, Codex може виправляти лише очевидні збої, а підсумковий звіт повного набору після роботи агента має проходити повністю, перш ніж щось буде закомічено. Коли `main` просувається далі до того, як push бота буде злитий, lane перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; застарілі патчі з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й docs agent. +Workflow `Test Performance Agent` — це event-driven lane обслуговування Codex +для повільних тестів. Він не має окремого запуску за розкладом: його може запустити +успішний run CI після пушу в `main`, якщо він не від бота, але він пропускається, +якщо інший виклик через workflow-run уже виконався або виконується в ту саму добу UTC. +Ручний dispatch обходить цей денний шлюз активності. Lane будує +згрупований звіт про продуктивність повного набору Vitest, дозволяє Codex +вносити лише невеликі виправлення продуктивності тестів без втрати покриття замість широких рефакторингів, +потім повторно запускає звіт повного набору і відхиляє зміни, які зменшують +базову кількість тестів, що проходять. Якщо в базовому стані є тести, що не проходять, Codex +може виправляти лише очевидні збої, а звіт повного набору після роботи агента +має пройти до того, як щось буде закомічено. Коли `main` просувається далі до того, як пуш бота буде приземлено, +lane ребейзить перевірений патч, повторно запускає `pnpm check:changed` і +повторює спробу пушу; конфліктні застарілі патчі пропускаються. Він використовує GitHub-hosted Ubuntu, +щоб дія Codex могла зберігати ту саму безпечну поставу drop-sudo, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -130,31 +256,38 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Job | Призначення | Коли запускається | +| Завдання | Призначення | Коли запускається | | -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Виявлення змін лише в docs, змінених областей, змінених extensions і побудова маніфесту CI | Завжди для non-draft push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для non-draft push і PR | -| `security-fast` | Обов’язковий агрегатор для швидких security-завдань | Завжди для non-draft push і PR | -| `build-artifacts` | Збирання `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-ланки коректності, такі як перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шардовані тести bundled-plugin по всьому набору extension | Зміни, релевантні для Node | -| `checks-node-core-test` | Шардовані core Node тести, за винятком ланок channel, bundled, contract та extension | Зміни, релевантні для Node | -| `check` | Шардований еквівалент основного локального gate: production types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди architecture, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke-тест пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Verifier для channel-тестів built-artifact | Зміни, релевантні для Node | -| `checks-node-compat-node22` | Ланка сумісності Node 22 для збирання та smoke | Ручний запуск CI для релізів | -| `check-docs` | Форматування docs, lint і перевірки битих посилань | Docs змінено | -| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Windows-специфічні тести процесів/шляхів плюс регресії shared runtime import specifier | Зміни, релевантні для Windows | -| `macos-node` | Ланка тестів TypeScript на macOS із використанням shared built artifacts | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, збирання та тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одне debug APK-збирання | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів через Codex після довіреної активності | Успіх CI в main або ручний запуск | +| `preflight` | Виявлення змін лише в документації, змінених областей, змінених extensions і побудова маніфесту CI | Завжди для push і PR не в draft | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR не в draft | +| `security-dependency-audit` | Аудит production lockfile без залежностей за advisory npm | Завжди для push і PR не в draft | +| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для push і PR не в draft | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, пов’язані з Node | +| `checks-fast-core` | Швидкі lane коректності Linux, такі як перевірки bundled/plugin-contract/protocol | Зміни, пов’язані з Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, пов’язані з Node | +| `checks-node-extensions` | Повні шарди тестів bundled Plugin для всього набору extension | Зміни, пов’язані з Node | +| `checks-node-core-test` | Шарди тестів core Node, крім lane каналів, bundled, контрактів і extension | Зміни, пов’язані з Node | +| `check` | Шардований локальний еквівалент головного шлюзу: prod types, lint, guards, test types і strict smoke | Зміни, пов’язані з Node | +| `check-additional` | Шарди архітектури, меж, guard для поверхні extension, меж пакетів і gateway-watch | Зміни, пов’язані з Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke startup-memory | Зміни, пов’язані з Node | +| `checks` | Verifier для тестів каналів на зібраних артефактах | Зміни, пов’язані з Node | +| `checks-node-compat-node22` | Lane сумісності Node 22 для збірки і smoke | Ручний dispatch CI для релізів | +| `check-docs` | Перевірки форматування документації, lint і битих посилань | Документацію змінено | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills | +| `checks-windows` | Специфічні для Windows тести процесів/шляхів плюс спільні регресії import specifier runtime | Зміни, релевантні Windows | +| `macos-node` | Lane тестів TypeScript на macOS із використанням спільних зібраних артефактів | Зміни, релевантні macOS | +| `macos-swift` | Lint, збірка і тести Swift для застосунку macOS | Зміни, релевантні macOS | +| `android` | Юніт-тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний main CI або ручний dispatch | -Ручні запуски CI запускають той самий граф завдань, що й звичайний CI, але примусово вмикають кожну lane, обмежену за областю змін: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python Skills, Windows, macOS, Android і i18n для Control UI. Ручні запуски використовують унікальну concurrency group, щоб повний набір для кандидата на реліз не скасовувався іншим push- або PR-запуском на тому самому ref. Необов’язковий вхід `target_ref` дозволяє довіреному виклику запускати цей граф для гілки, тегу або повного SHA коміту, використовуючи файл workflow з вибраного ref для dispatch. +Ручні dispatch CI запускають той самий граф завдань, що й звичайний CI, але +примусово вмикають кожен lane з визначенням області: шарди Linux Node, шарди bundled Plugin, контракти каналів, +сумісність Node 22, `check`, `check-additional`, build smoke, перевірки документації, +Python Skills, Windows, macOS, Android і i18n Control UI. Ручні запуски використовують +унікальну concurrency group, щоб повний набір для кандидата на реліз не було скасовано +іншим run push або PR на тому самому ref. Необов’язковий вхід `target_ref` дозволяє +довіреному виклику запускати цей граф для гілки, тега або повного SHA коміту, +використовуючи файл workflow з вибраного ref dispatch. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -164,52 +297,53 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Порядок 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` швидко завершуються з помилкою, не очікуючи важчих матричних завдань для артефактів і платформ. -3. `build-artifacts` виконується паралельно зі швидкими Linux-ланками, щоб downstream-споживачі могли стартувати, щойно буде готове спільне збирання. -4. Після цього розгортаються важчі платформені й runtime-ланки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які lane взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються помилкою без очікування важчих матричних завдань артефактів і платформ. +3. `build-artifacts` виконується паралельно зі швидкими lane Linux, щоб downstream-споживачі могли стартувати, щойно буде готова спільна збірка. +4. Після цього розгортаються важчі platform і runtime lane: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка обмеження за областю змін міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Ручний dispatch пропускає визначення changed-scope і змушує маніфест preflight поводитися так, ніби змінилися всі області з обмеженням за scope. -Зміни workflow CI перевіряють граф Node CI плюс linting workflow, але самі по собі не примушують запускати нативні збирання Windows, Android або macOS; ці платформені ланки й надалі обмежуються змінами у вихідному коді відповідних платформ. -Зміни лише в маршрутизації CI, окремі дешеві редагування fixture для core-тестів і вузькі редагування helper/test-routing для plugin contract використовують швидкий шлях маніфесту лише для Node: preflight, security і єдине завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності Node 22, channel contracts, повних core shards, bundled-plugin shards і додаткових guard-матриць, коли змінені файли обмежені поверхнями маршрутизації або helper, які швидке завдання перевіряє безпосередньо. -Перевірки Windows Node обмежуються Windows-специфічними wrappers для процесів/шляхів, helper для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, що запускають цю ланку; не пов’язані зміни у вихідному коді, Plugin, install-smoke і лише тестові зміни залишаються на Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий scope-скрипт через власне завдання `preflight`. Він ділить smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request-и запускають швидкий шлях для поверхонь Docker/package, змін package/manifest у bundled Plugin, а також поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише у вихідному коді bundled Plugin, лише тестові зміни і зміни лише в docs не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає smoke CLI `agents delete shared-workspace`, запускає container gateway-network e2e, перевіряє аргумент збирання bundled extension і запускає обмежений Docker-профіль bundled-plugin із сукупним timeout команди 240 секунд, при цьому `docker run` для кожного сценарію обмежується окремо. Повний шлях зберігає покриття встановлення QR package і installer Docker/update для щонічних запланованих запусків, ручних dispatch, release checks через workflow-call і pull request-ів, які справді торкаються поверхонь installer/package/Docker. Push у `main`, включно з merge commit, не примушують повний шлях; коли логіка changed-scope запитує повне покриття під час push, workflow зберігає швидкий Docker smoke і залишає повний install smoke на нічні або релізні перевірки. Повільний smoke для Bun global install image-provider окремо керується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні dispatch `install-smoke` можуть явно його ввімкнути, але pull request-и і push у `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, орієнтовані на інсталяцію. Локальний `test:docker:all` попередньо збирає один спільний образ live-test, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: базовий runner Node/Git для ланок installer/update/plugin-dependency і функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних ланок. Визначення Docker-ланок містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної ланки через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає ланки з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартну кількість слотів main-pool, що дорівнює 10, через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів provider-sensitive tail-pool, що також дорівнює 10, через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких ланок за замовчуванням — `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб ланки npm install і multi-service не перевантажували Docker, поки легші ланки все ще заповнюють доступні слоти. Одна ланка, важча за ефективні обмеження, все одно може стартувати з порожнього пулу, а потім виконується сама, доки не звільнить ємність. Запуски ланок за замовчуванням розносяться на 2 секунди, щоб уникнути локальних бур створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегований запуск попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних ланок, зберігає таймінги ланок для впорядкування від найдовших і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для інспекції планувальника. За замовчуванням він припиняє планування нових pooled lanes після першого збою, а кожна ланка має резервний timeout 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes використовують жорсткіші обмеження для окремих ланок. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні scheduler lanes, включно з ланками лише для релізу, такими як `install-e2e`, і розділеними bundled update lanes, такими як `bundled-channel-update-acpx`, пропускаючи cleanup smoke, щоб агенти могли відтворити одну невдалу ланку. Повторно використовуваний workflow live/E2E запитує в `scripts/test-docker-all.mjs --plan-json`, який package, kind образу, live image, lane і покриття облікових даних потрібні, а потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує package artifact поточного запуску, або завантажує package artifact з `package_artifact_run_id`; перевіряє вміст tarball; збирає і пушить package-digest-tagged bare/functional GHCR Docker E2E images через Docker layer cache від Blacksmith, коли план потребує package-installed lanes; і повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи package-digest замість повторного збирання. Workflow `Package Acceptance` — це високорівневий gate для пакета: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакту попереднього workflow, а потім передає єдиний артефакт `package-under-test` у повторно використовуваний Docker E2E workflow. Він тримає `workflow_ref` окремо від `package_ref`, щоб поточна логіка acceptance могла перевіряти старіші довірені коміти без checkout старого коду workflow. Release checks запускають власну дельту Package Acceptance для цільового ref: bundled-channel compat, offline fixture для Plugin і Telegram package QA проти визначеного tarball. Docker-набір шляху релізу запускає менші chunked jobs із `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk отримував лише той kind образу, який йому потрібен, і виконував кілька ланок через той самий weighted scheduler (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`). OpenWebUI включається в `plugins-runtime-core`, коли повне покриття шляху релізу цього потребує, і зберігає окремий chunk `openwebui` лише для dispatch, спрямованих виключно на OpenWebUI. Застарілі агреговані назви chunk — `package-update`, `plugins-runtime` і `plugins-integrations` — усе ще працюють для ручних повторних запусків, але workflow релізу використовує розділені chunks, щоб installer E2E і повні проходи встановлення/видалення bundled Plugin не домінували на критичному шляху. Псевдонім ланки `install-e2e` залишається агрегованим псевдонімом ручного повторного запуску для обох ланок installer provider. Chunk `bundled-channels` запускає розділені ланки `bundled-channel-*` і `bundled-channel-update-*` замість послідовної all-in-one ланки `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` із журналами ланок, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних ланок і командами повторного запуску для кожної ланки. Вхід workflow `docker_lanes` запускає вибрані ланки проти підготовлених образів замість chunk jobs, що утримує налагодження невдалої ланки в межах одного цільового Docker-завдання та готує, завантажує або повторно використовує package artifact для цього запуску; якщо вибрана ланка є live Docker lane, цільове завдання локально збирає образ live-test для цього повторного запуску. Згенеровані команди повторного запуску GitHub для кожної ланки містять `package_artifact_run_id`, `package_artifact_name` і входи підготовлених образів, коли ці значення існують, щоб невдала ланка могла повторно використати точний package і образи з невдалого запуску. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти з GitHub run і вивести комбіновані/поканальні цільові команди повторного запуску; використовуйте `pnpm test:docker:timings ` для зведень по повільних ланках і критичному шляху фаз. Запланований workflow live/E2E щодня запускає повний Docker-набір шляху релізу. Матриця bundled update розділена за ціллю оновлення, щоб повторні проходи npm update і doctor repair могли шардуватися разом з іншими bundled-перевірками. +Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покривається юніт-тестами в `src/scripts/ci-changed-scope.test.ts`. +Ручний dispatch пропускає визначення changed-scope і змушує маніфест preflight +працювати так, ніби змінилася кожна область зі scope. +Редагування workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують Windows, Android або macOS до нативних збірок; ці platform lane й далі обмежуються змінами у вихідному коді відповідної платформи. +Редагування лише маршрутизації CI, вибрані дешеві редагування fixture core-test і вузькі редагування helper/test-routing для контрактів Plugin використовують швидкий шлях маніфесту лише для Node: preflight, security і одне завдання `checks-fast-core`. Цей шлях уникає build artifacts, сумісності Node 22, контрактів каналів, повних shard core, shard bundled Plugin і додаткових guard-матриць, коли змінені файли обмежені поверхнями маршрутизації або helper, які швидке завдання безпосередньо перевіряє. +Перевірки Windows Node обмежені специфічними для Windows wrapper процесів/шляхів, helper для запуску npm/pnpm/UI, конфігурацією менеджера пакетів і поверхнями workflow CI, які виконують цей lane; нерелевантні зміни у вихідному коді, Plugin, install-smoke та лише тестах залишаються в lane Linux Node, щоб не резервувати 16-vCPU worker Windows для покриття, яке вже забезпечують звичайні test shard. +Окремий workflow `install-smoke` повторно використовує той самий скрипт scope через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled Plugin і поверхонь core plugin/channel/Gateway/Plugin SDK, які використовують Docker smoke-завдання. Зміни лише у вихідному коді bundled Plugin, лише в тестах і лише в документації не резервують Docker workers. Швидкий шлях один раз збирає root Dockerfile image, перевіряє CLI, запускає CLI smoke `agents delete shared-workspace`, запускає container `gateway-network` e2e, перевіряє build arg для bundled extension і запускає обмежений Docker-профіль bundled Plugin під загальним тайм-аутом команди 240 секунд, де `docker run` для кожного сценарію окремо також обмежений. Повний шлях зберігає покриття QR package install і installer Docker/update для нічних запусків за розкладом, ручних dispatch, release checks через workflow-call і pull request, які справді зачіпають поверхні installer/package/Docker. Push у `main`, включно з merge-комітами, не примушують повний шлях; коли логіка changed-scope запитує повне покриття для push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації. Повільний smoke image-provider для глобального встановлення Bun керується окремо через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні dispatch `install-smoke` можуть його увімкнути, але pull request і push у `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Локальний `test:docker:all` попередньо збирає один спільний image live-test, один раз пакує OpenClaw як npm tarball і збирає два спільні image `scripts/e2e/Dockerfile`: базовий runner Node/Git для lane installer/update/plugin-dependency і функціональний image, який встановлює той самий tarball у `/app` для звичайних функціональних lane. Визначення Docker lane містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає image для кожного lane через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lane з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартну кількість слотів основного пулу 10 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів tail-пулу, чутливого до provider, також 10 — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких lane за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб lane з npm install і кількома сервісами не перевантажували Docker, поки легші lane все ще заповнюють доступні слоти. Один lane, важчий за ефективні обмеження, усе одно може стартувати з порожнього пулу, а потім виконується самостійно, доки не звільнить ресурси. Запуски lane за замовчуванням розносяться на 2 секунди, щоб уникати локальних штормів створення в Docker daemon; це можна змінити через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегатний запуск попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, показує статус активних lane, зберігає таймінги lane для сортування від найдовших до найкоротших і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для інспекції планувальника. За замовчуванням він припиняє планування нових lane в пулах після першої помилки, і кожен lane має запасний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lane мають жорсткіші обмеження для окремого lane. `OPENCLAW_DOCKER_ALL_LANES=` запускає точні lane планувальника, включно з lane лише для релізу, як-от `install-e2e`, і розділеними lane bundled update, як-от `bundled-channel-update-acpx`, при цьому пропускаючи cleanup smoke, щоб агенти могли відтворити один невдалий lane. Повторно використовуваний workflow live/E2E запитує в `scripts/test-docker-all.mjs --plan-json`, який package, kind image, live image, lane і покриття credential потрібні, після чого `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summary. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакета з поточного run, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає і публікує Docker E2E image bare/functional з тегами package-digest у GHCR через кеш шарів Docker від Blacksmith, коли плану потрібні lane зі встановленим пакетом; а також повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні image package-digest замість повторної збірки. Workflow `Package Acceptance` — це високорівневий шлюз пакета: він визначає кандидата з npm, довіреного `package_ref`, HTTPS tarball плюс SHA-256 або артефакта попереднього workflow, а потім передає цей єдиний артефакт `package-under-test` у повторно використовуваний workflow Docker E2E. Він зберігає `workflow_ref` окремо від `package_ref`, щоб поточна логіка приймання могла перевіряти старі довірені коміти без checkout старого коду workflow. Release checks запускають власну delta-перевірку Package Acceptance для цільового ref: bundled-channel compat, offline fixture Plugin і Telegram package QA для визначеного tarball. Набір Docker для шляху релізу запускає менші chunk-завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому kind image і виконував кілька lane через той самий ваговий планувальник (`OPENCLAW_DOCKER_ALL_PROFILE=release-path`, `OPENCLAW_DOCKER_ALL_CHUNK=core|package-update-openai|package-update-anthropic|package-update-core|plugins-runtime-core|plugins-runtime-install-a|plugins-runtime-install-b|bundled-channels`). OpenWebUI включено в `plugins-runtime-core`, коли повне покриття release-path цього вимагає, і окремий chunk `openwebui` зберігається лише для dispatch, призначених тільки для OpenWebUI. Legacy-агреговані назви chunk `package-update`, `plugins-runtime` і `plugins-integrations` і далі працюють для ручних повторних запусків, але workflow релізу використовує розділені chunk, щоб installer E2E і повні проходи встановлення/видалення bundled Plugin не домінували у критичному шляху. Псевдонім lane `install-e2e` лишається агрегованим псевдонімом ручного повторного запуску для обох lane installer provider. Chunk `bundled-channels` запускає розділені lane `bundled-channel-*` і `bundled-channel-update-*` замість послідовного all-in-one lane `bundled-channel-deps`. Кожен chunk завантажує `.artifacts/docker-tests/` з логами lane, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних lane і командами повторного запуску для кожного lane. Вхід workflow `docker_lanes` запускає вибрані lane на підготовлених image замість chunk-завдань, що обмежує налагодження невдалого lane одним цільовим Docker-завданням і готує, завантажує або повторно використовує артефакт пакета для цього run; якщо вибраний lane є live Docker lane, цільове завдання локально збирає image live-test для цього повторного запуску. Згенеровані GitHub-команди повторного запуску для кожного lane включають `package_artifact_run_id`, `package_artifact_name` і підготовлені входи image, коли ці значення існують, щоб невдалий lane міг повторно використати точний пакет і image з невдалого run. Використовуйте `pnpm test:docker:rerun `, щоб завантажити Docker-артефакти з GitHub run і вивести комбіновані/по-окремих lane цільові команди повторного запуску; використовуйте `pnpm test:docker:timings ` для зведень про повільні lane і критичний шлях фаз. Запланований workflow live/E2E щодня запускає повний Docker-набір release-path. Матриця bundled update розділена за ціллю оновлення, щоб повторні проходи `npm update` і `doctor repair` могли шардитися разом з іншими bundled-перевірками. -Поточні релізні Docker-chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-core`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований chunk `bundled-channels` залишається доступним для ручних одноразових повторних запусків, але workflow релізу використовує розділені chunks, щоб channel smoke, цілі оновлення і setup/runtime contracts могли виконуватися паралельно. Цільові dispatch через `docker_lanes` також розбивають кілька вибраних ланок на паралельні завдання після одного спільного кроку підготовки package/image, а bundled-channel update lanes повторюються один раз у разі тимчасових npm network failures. +Поточні Docker-chunk релізу: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-core`, `plugins-runtime-install-a`, `plugins-runtime-install-b`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований chunk `bundled-channels` лишається доступним для ручних одноразових повторних запусків, але workflow релізу використовує розділені chunk, щоб smoke каналів, цілі оновлення і контракти setup/runtime могли виконуватися паралельно. Цільові dispatch `docker_lanes` також розбивають кілька вибраних lane на паралельні завдання після одного спільного кроку підготовки package/image, а lane оновлення bundled-channel один раз повторюють спробу у разі тимчасових збоїв мережі npm. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо меж архітектури, ніж широка платформена область CI: зміни в core production запускають core prod і core test typecheck плюс core lint/guards, зміни лише в core tests запускають лише core test typecheck плюс core lint, зміни в extension production запускають extension prod і extension test typecheck плюс extension lint, а зміни лише в extension tests запускають extension test typecheck плюс extension lint. Публічні зміни Plugin SDK або plugin-contract розширюються до extension typecheck, тому що extensions залежать від цих core contract, але повні проходи Vitest для extension — це окрема явна тестова робота. Зміни лише в release metadata version bumps запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно розширюються до всіх check lanes. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний шлюз перевірок суворіший щодо архітектурних меж, ніж широка платформа scope у CI: зміни у production core запускають typecheck core prod і core test плюс core lint/guards, зміни лише в core test запускають лише typecheck core test плюс core lint, зміни у production extension запускають typecheck extension prod і extension test плюс extension lint, а зміни лише в extension test запускають typecheck extension test плюс extension lint. Публічні зміни Plugin SDK або plugin-contract розширюють typecheck на extension, оскільки extension залежать від цих контрактів core, але повні проходи Vitest для extension — це явна тестова робота. Version bump лише для metadata релізу запускають цільові перевірки version/config/root-dependency. Невідомі зміни root/config безпечно переводять виконання на всі lane перевірок. -Ручні dispatch CI запускають `checks-node-compat-node22` як покриття сумісності для кандидата на реліз. Звичайні pull request-и і push у `main` пропускають цю ланку й залишають матрицю зосередженою на ланках тестів/channel для Node 24. +Ручні dispatch CI запускають `checks-node-compat-node22` як покриття сумісності для кандидата на реліз. Звичайні pull request і push у `main` пропускають цей lane і зберігають матрицю зосередженою на lane тестів/каналів Node 24. -Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені шарди, bundled Plugin-тести балансуються між шістьма worker-ами extension, малі core unit-ланки об’єднані в пари, auto-reply виконується на чотирьох збалансованих worker-ах із розділенням піддерева reply на шарди agent-runner, dispatch і commands/state-routing, а agentic-конфігурації gateway/Plugin розподіляються між наявними Node-завданнями agentic лише для source замість очікування built artifacts. Широкі browser-, QA-, media- і miscellaneous Plugin-тести використовують свої окремі конфігурації Vitest замість спільного catch-all для Plugin. Завдання shard для extension запускають до двох груп конфігурацій Plugin одночасно з одним worker-ом Vitest на групу і більшим heap Node, щоб пакетні набори Plugin з великою кількістю імпортів не створювали зайвих CI-завдань. Широка agents-ланка використовує спільний file-parallel scheduler Vitest, оскільки в ній домінують імпорти/планування, а не один конкретний повільний тестовий файл. `runtime-config` запускається разом із шардом infra core-runtime, щоб спільний runtime-shard не тягнув хвіст. Include-pattern shards записують записи таймінгів із використанням назви CI-shard, тому `.artifacts/vitest-shard-timings.json` може розрізняти цілу конфігурацію і відфільтрований shard. `check-additional` тримає compile/canary-роботу package-boundary разом і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard запускає свої малі незалежні guards паралельно всередині одного завдання. Gateway watch, channel-тести і shard support-boundary для core запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви перевірок як легкі verifier-завдання та уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. +Найповільніші сімейства тестів Node розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner: контракти каналів запускаються як три зважені shard, тести bundled Plugin балансуються між шістьма worker extension, малі lane юніт-тестів core об’єднуються в пари, auto-reply виконується як чотири збалансовані worker із розбиттям піддерева reply на shard agent-runner, dispatch і commands/state-routing, а agentic-конфігурації Gateway/Plugin розподіляються по наявних Node-завданнях agentic лише для source замість очікування зібраних артефактів. Широкі тести browser, QA, media та різних Plugin використовують свої окремі конфігурації Vitest замість спільного catch-all для Plugin. Завдання shard для extension запускають до двох груп конфігурацій Plugin одночасно з одним worker Vitest на групу й більшим heap Node, щоб пакети Plugin з важкими import не створювали додаткові завдання CI. Широкий lane agents використовує спільний планувальник паралелізму файлів Vitest, оскільки в ньому домінують import/планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard `infra core-runtime`, щоб спільний shard runtime не залишався хвостом. Shard за include-pattern записують записи таймінгів із використанням назви shard CI, тому `.artifacts/vitest-shard-timings.json` може відрізняти цілу конфігурацію від відфільтрованого shard. `check-additional` тримає разом роботу compile/canary для меж пакетів і відділяє архітектуру топології runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guard паралельно в межах одного завдання. Gateway watch, тести каналів і shard support-boundary core виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи їхні старі назви перевірок як легкі завдання-верифікатори й водночас уникаючи двох додаткових worker Blacksmith і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає debug APK для Play. У flavor third-party немає окремого source set або manifest; його ланка unit-тестів усе одно компілює цей flavor з прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого пакування debug APK на кожному push, релевантному для Android. -GitHub може позначати замінені новішими завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується помилкою. Агреговані перевірки shard використовують `!cancelled() && always()`, щоб вони все одно повідомляли про звичайні збої shard, але не ставали в чергу після того, як увесь workflow уже було замінено новішим. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає debug APK для Play. Сторонній flavor не має окремого source set або manifest; його lane юніт-тестів усе одно компілює цей flavor із прапорцями BuildConfig для SMS/журналу дзвінків, уникаючи при цьому дублювання завдання пакування debug APK при кожному push, релевантному для Android. +GitHub може позначати застарілі завдання як `cancelled`, коли новіший push потрапляє в той самий ref PR або `main`. Вважайте це шумом CI, якщо тільки найновіший run для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні збої shard, але не стають у чергу після того, як увесь workflow уже було замінено новішим. -Автоматичний ключ concurrency для CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main. Ручні запуски повного набору використовують `CI-manual-v1-*` і не скасовують уже запущені виконання. +Ключ автоматичної concurrency CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безстроково блокувати новіші run для main. Ручні запуски повного набору використовують `CI-manual-v1-*` і не скасовують run, що вже виконуються. -## Runner-и +## Runner -| Runner | Jobs | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі security-завдання та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, шарди `check`, окрім lint, шарди й агрегати `check-additional`, aggregate verifier-и Node-тестів, docs checks, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла стати в чергу раніше | -| `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` | +| Runner | Завдання | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, shard `check`, крім lint, shard і агрегати `check-additional`, агрегатні verifier для тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard тестів Linux Node, shard тестів 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 використовується `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумний локальний check gate: changed typecheck/lint/guards за boundary lane -pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні швидкі guards +pnpm check:changed # розумний локальний шлюз перевірок: changed typecheck/lint/guards за 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 @@ -217,13 +351,13 @@ pnpm test # тести vitest pnpm test:changed # дешеві розумні changed-цілі Vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування docs + lint + перевірка битих посилань -pnpm build # зібрати dist, коли важливі CI artifact/build-smoke lanes -pnpm ci:timings # підсумувати останній запуск push CI для origin/main -pnpm ci:timings:recent # порівняти нещодавні успішні запуски main CI -node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші jobs -node scripts/ci-run-timings.mjs --latest-main # ігнорувати шум від issue/comment і вибрати push CI для origin/main -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI +pnpm check:docs # форматування документації + lint + перевірка битих посилань +pnpm build # зібрати dist, коли важливі lane CI artifact/build-smoke +pnpm ci:timings # підсумувати останній run CI push у origin/main +pnpm ci:timings:recent # порівняти нещодавні успішні run CI для main +node scripts/ci-run-timings.mjs # підсумувати wall time, queue time і найповільніші завдання +node scripts/ci-run-timings.mjs --latest-main # ігнорувати шум issue/comment і вибрати push CI для origin/main +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні run CI для main 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 ``` @@ -231,4 +365,4 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## Пов’язане - [Огляд встановлення](/uk/install) -- [Канали релізів](/uk/install/development-channels) +- [Канали релізу](/uk/install/development-channels) diff --git a/docs/uk/concepts/memory.md b/docs/uk/concepts/memory.md index 96aeebeb0..99c55a9f5 100644 --- a/docs/uk/concepts/memory.md +++ b/docs/uk/concepts/memory.md @@ -1,38 +1,39 @@ --- read_when: - Ви хочете зрозуміти, як працює пам’ять - - Ви хочете знати, які файли пам’яті потрібно записувати + - Ви хочете знати, які файли пам’яті слід записувати summary: Як OpenClaw запам’ятовує речі між сеансами title: Огляд пам’яті x-i18n: - generated_at: "2026-04-27T06:24:32Z" + generated_at: "2026-04-28T00:03:40Z" model: gpt-5.4 provider: openai - source_hash: 8855ca049761b339438b6f6434ae94a6f2c9babeb007bd84929e490ede897ca4 + source_hash: 31e5e76dfb53fa66fcfab1450cb56b5d9f8ed350391d6aecaf3a7e982567f0a2 source_path: concepts/memory.md workflow: 15 --- -OpenClaw запам’ятовує речі, записуючи **звичайні Markdown-файли** в робочому -просторі вашого агента. Модель "запам’ятовує" лише те, що збережено на диск — +OpenClaw запам’ятовує речі, записуючи **звичайні файли Markdown** у робочому +просторі вашого агента. Модель лише «пам’ятає» те, що було збережено на диск — жодного прихованого стану немає. ## Як це працює -Ваш агент має три файли, пов’язані з пам’яттю: +Ваш агент має три пов’язані з пам’яттю файли: - **`MEMORY.md`** — довготривала пам’ять. Стійкі факти, уподобання та рішення. Завантажується на початку кожного сеансу DM. - **`memory/YYYY-MM-DD.md`** — щоденні нотатки. Поточний контекст і спостереження. - Нотатки за сьогодні й учора завантажуються автоматично. -- **`DREAMS.md`** (необов’язково) — Dream Diary і підсумки проходів - Dreaming для перегляду людиною, включно з обґрунтованими записами історичного дозаповнення. + Нотатки за сьогодні та вчора завантажуються автоматично. +- **`DREAMS.md`** (необов’язково) — щоденник Dreaming і + підсумки проходів Dreaming для перегляду людиною, включно з обґрунтованими записами + історичного доопрацювання. -Ці файли зберігаються в робочому просторі агента (типово `~/.openclaw/workspace`). +Ці файли розміщуються в робочому просторі агента (типово `~/.openclaw/workspace`). -Якщо ви хочете, щоб ваш агент щось запам’ятав, просто попросіть його: "Запам’ятай, що я -надаю перевагу TypeScript." Він запише це у відповідний файл. +Якщо ви хочете, щоб ваш агент щось запам’ятав, просто попросіть його: «Запам’ятай, що я +віддаю перевагу TypeScript». Він запише це у відповідний файл. ## Інструменти пам’яті @@ -43,113 +44,117 @@ OpenClaw запам’ятовує речі, записуючи **звичайн формулювання відрізняється від оригінального. - **`memory_get`** — читає конкретний файл пам’яті або діапазон рядків. -Обидва інструменти надаються активним plugin пам’яті (типово: `memory-core`). +Обидва інструменти надаються активним Plugin пам’яті (типово: `memory-core`). -## Додатковий Plugin Memory Wiki +## Супровідний Plugin Memory Wiki -Якщо ви хочете, щоб довготривала пам’ять поводилася більше як підтримувана база знань, а не -просто як сирі нотатки, використовуйте вбудований plugin `memory-wiki`. +Якщо ви хочете, щоб стійка пам’ять працювала більше як підтримувана база знань, а не +просто сирі нотатки, використовуйте вбудований Plugin `memory-wiki`. -`memory-wiki` компілює довготривалі знання у wiki vault з: +`memory-wiki` компілює стійкі знання у wiki-сховище з: - детермінованою структурою сторінок -- структурованими твердженнями й доказами +- структурованими твердженнями та доказами - відстеженням суперечностей і актуальності - згенерованими панелями -- скомпільованими дайджестами для агентів/споживачів середовища виконання +- скомпільованими дайджестами для споживачів агента/середовища виконання - wiki-native інструментами, такими як `wiki_search`, `wiki_get`, `wiki_apply` і `wiki_lint` -Він не замінює активний plugin пам’яті. Активний plugin пам’яті, як і раніше, -відповідає за пригадування, просування й Dreaming. `memory-wiki` додає поруч -із ним шар знань, багатий на походження. +Він не замінює активний Plugin пам’яті. Активний Plugin пам’яті, як і раніше, +відповідає за згадування, підвищення важливості та Dreaming. `memory-wiki` додає +поруч із ним шар знань, насичений походженням даних. Див. [Memory Wiki](/uk/plugins/memory-wiki). ## Пошук у пам’яті -Коли налаштовано провайдера ембедингів, `memory_search` використовує **гібридний -пошук** — поєднуючи векторну схожість (семантичний зміст) із пошуком за ключовими словами +Коли налаштовано постачальника embedding, `memory_search` використовує **гібридний +пошук** — поєднуючи векторну схожість (семантичне значення) з пошуком за ключовими словами (точні терміни, як-от ID та символи коду). Це працює одразу після того, як у вас є -API-ключ будь-якого підтримуваного провайдера. +API-ключ для будь-якого підтримуваного постачальника. -OpenClaw автоматично визначає вашого провайдера ембедингів за доступними API-ключами. Якщо у -вас налаштовано ключ OpenAI, Gemini, Voyage або Mistral, пошук у пам’яті +OpenClaw автоматично визначає вашого постачальника embedding за доступними API-ключами. Якщо у вас +налаштовано ключ OpenAI, Gemini, Voyage або Mistral, пошук у пам’яті вмикається автоматично. -Докладніше про те, як працює пошук, параметри налаштування та налаштування провайдерів див. -у [Пошук у пам’яті](/uk/concepts/memory-search). +Докладніше про те, як працює пошук, параметри налаштування та налаштування постачальників див. у +[Memory Search](/uk/concepts/memory-search). ## Бекенди пам’яті -На базі SQLite. Працює одразу з пошуком за ключовими словами, векторною схожістю та +На основі SQLite. Працює одразу з пошуком за ключовими словами, векторною схожістю та гібридним пошуком. Жодних додаткових залежностей. -Локальний sidecar з пріоритетом локальної роботи, із reranking, query expansion і можливістю індексувати -каталоги поза робочим простором. +Local-first sidecar із повторним ранжуванням, розширенням запитів і можливістю індексувати +каталоги поза межами робочого простору. AI-native міжсеансова пам’ять із моделюванням користувача, семантичним пошуком і -обізнаністю про кількох агентів. Установлюється як plugin. +обізнаністю про кількох агентів. Встановлення Plugin. + + +Вбудована пам’ять на базі LanceDB з embedding, сумісними з OpenAI, автоматичним згадуванням, +автоматичним захопленням і підтримкою локальних embedding Ollama. -## Шар wiki знань +## Рівень wiki знань -Компілює довготривалу пам’ять у wiki vault, багатий на походження, із твердженнями, +Компілює стійку пам’ять у wiki-сховище, насичене походженням даних, із твердженнями, панелями, bridge mode і workflow, дружніми до Obsidian. ## Автоматичне скидання пам’яті -Перед тим як [Compaction](/uk/concepts/compaction) підсумовує вашу розмову, OpenClaw +Перш ніж [Compaction](/uk/concepts/compaction) підсумує вашу розмову, OpenClaw виконує тихий хід, який нагадує агенту зберегти важливий контекст у файли пам’яті. -Це ввімкнено типово — вам нічого не потрібно налаштовувати. +Це ввімкнено типово — вам не потрібно нічого налаштовувати. Скидання пам’яті запобігає втраті контексту під час Compaction. Якщо у розмові вашого агента є -важливі факти, які ще не записані у файл, їх буде автоматично збережено -перед створенням підсумку. +важливі факти, які ще не записано у файл, вони будуть автоматично збережені +до того, як відбудеться підсумовування. ## Dreaming -Dreaming — це необов’язковий фоновий прохід консолідації пам’яті. Він збирає -короткострокові сигнали, оцінює кандидатів і просуває до довготривалої пам’яті (`MEMORY.md`) -лише кваліфіковані елементи. +Dreaming — це необов’язковий фоновий прохід консолідації для пам’яті. Він збирає +короткострокові сигнали, оцінює кандидатів і просуває до довготривалої пам’яті +(`MEMORY.md`) лише ті елементи, що відповідають вимогам. -Його створено для того, щоб довготривала пам’ять залишалася високосигнальною: +Його створено, щоб підтримувати високу інформаційну цінність довготривалої пам’яті: -- **Добровільне ввімкнення**: типово вимкнено. +- **За бажанням**: типово вимкнено. - **За розкладом**: коли ввімкнено, `memory-core` автоматично керує одним повторюваним завданням Cron для повного проходу Dreaming. -- **З порогами**: просування має пройти пороги оцінки, частоти пригадування та +- **З порогами**: просування має пройти пороги оцінки, частоти згадування та різноманітності запитів. -- **Доступно для перегляду**: підсумки фаз і записи щоденника записуються до `DREAMS.md` +- **З можливістю перегляду**: підсумки фаз і записи щоденника записуються до `DREAMS.md` для перегляду людиною. -Докладніше про поведінку фаз, сигнали оцінки та деталі Dream Diary див. у +Щоб дізнатися про поведінку фаз, сигнали оцінювання та подробиці щоденника Dreaming, див. [Dreaming](/uk/concepts/dreaming). -## Обґрунтоване дозаповнення й live-просування +## Обґрунтоване доопрацювання та живе просування -Система Dreaming тепер має два тісно пов’язані канали перегляду: +Система Dreaming тепер має дві тісно пов’язані лінії перегляду: -- **Live dreaming** працює з короткостроковим сховищем Dreaming у - `memory/.dreams/` і саме його нормальна глибока фаза використовує, вирішуючи, що - може бути перенесено до `MEMORY.md`. -- **Grounded backfill** читає історичні нотатки `memory/YYYY-MM-DD.md` як - автономні денні файли й записує структурований результат перегляду до `DREAMS.md`. +- **Живе Dreaming** працює з короткострокового сховища Dreaming у + `memory/.dreams/` і саме його використовує звичайна глибока фаза, коли вирішує, що + може перейти до `MEMORY.md`. +- **Обґрунтоване доопрацювання** читає історичні нотатки `memory/YYYY-MM-DD.md` як + окремі файли дня та записує структурований результат перегляду до `DREAMS.md`. -Grounded backfill корисний, коли ви хочете програти старі нотатки й перевірити, що -система вважає довготривалим, не редагуючи вручну `MEMORY.md`. +Обґрунтоване доопрацювання корисне, коли ви хочете повторно програти старі нотатки та перевірити, що +система вважає довговічним, без ручного редагування `MEMORY.md`. Коли ви використовуєте: @@ -157,16 +162,16 @@ Grounded backfill корисний, коли ви хочете програти openclaw memory rem-backfill --path ./memory --stage-short-term ``` -обґрунтовані довготривалі кандидати не просуваються безпосередньо. Вони розміщуються -в тому самому короткостроковому сховищі Dreaming, яке вже використовує нормальна глибока фаза. Це -означає: +обґрунтовані стійкі кандидати не просуваються напряму. Вони поміщаються до +того самого короткострокового сховища Dreaming, яке вже використовує звичайна глибока фаза. Це +означає, що: -- `DREAMS.md` залишається поверхнею перегляду для людини. +- `DREAMS.md` залишається поверхнею для перегляду людиною. - короткострокове сховище залишається поверхнею ранжування для машини. -- `MEMORY.md` усе ще записується лише під час глибокого просування. +- `MEMORY.md`, як і раніше, записується лише глибоким просуванням. -Якщо ви вирішите, що відтворення було не корисним, ви можете видалити підготовлені артефакти, -не торкаючись звичайних записів щоденника або нормального стану пригадування: +Якщо ви вирішите, що повторне програвання було некорисним, ви можете видалити підготовлені артефакти, +не торкаючись звичайних записів щоденника або нормального стану згадування: ```bash openclaw memory rem-backfill --rollback @@ -176,25 +181,27 @@ openclaw memory rem-backfill --rollback-short-term ## CLI ```bash -openclaw memory status # Перевірити стан індексу й провайдера +openclaw memory status # Перевірити стан індексу та постачальника openclaw memory search "query" # Пошук із командного рядка openclaw memory index --force # Перебудувати індекс ``` ## Додаткові матеріали -- [Вбудований рушій пам’яті](/uk/concepts/memory-builtin): типовий бекенд SQLite. -- [Рушій пам’яті QMD](/uk/concepts/memory-qmd): просунутий локальний sidecar. -- [Пам’ять Honcho](/uk/concepts/memory-honcho): AI-native міжсеансова пам’ять. -- [Memory Wiki](/uk/plugins/memory-wiki): скомпільоване сховище знань і wiki-native інструменти. -- [Пошук у пам’яті](/uk/concepts/memory-search): конвеєр пошуку, провайдери й налаштування. -- [Dreaming](/uk/concepts/dreaming): фонове просування з короткострокового пригадування до довготривалої пам’яті. -- [Довідка з конфігурації пам’яті](/uk/reference/memory-config): усі параметри конфігурації. +- [Builtin memory engine](/uk/concepts/memory-builtin): типовий бекенд SQLite. +- [QMD memory engine](/uk/concepts/memory-qmd): розширений local-first sidecar. +- [Honcho memory](/uk/concepts/memory-honcho): AI-native міжсеансова пам’ять. +- [Memory LanceDB](/uk/plugins/memory-lancedb): Plugin на базі LanceDB з embedding, сумісними з OpenAI. +- [Memory Wiki](/uk/plugins/memory-wiki): скомпільоване сховище знань та wiki-native інструменти. +- [Memory search](/uk/concepts/memory-search): конвеєр пошуку, постачальники та налаштування. +- [Dreaming](/uk/concepts/dreaming): фонове просування з короткострокового згадування до довготривалої пам’яті. +- [Memory configuration reference](/uk/reference/memory-config): усі параметри конфігурації. - [Compaction](/uk/concepts/compaction): як Compaction взаємодіє з пам’яттю. ## Пов’язане - [Active Memory](/uk/concepts/active-memory) -- [Пошук у пам’яті](/uk/concepts/memory-search) -- [Вбудований рушій пам’яті](/uk/concepts/memory-builtin) -- [Пам’ять Honcho](/uk/concepts/memory-honcho) +- [Memory search](/uk/concepts/memory-search) +- [Builtin memory engine](/uk/concepts/memory-builtin) +- [Honcho memory](/uk/concepts/memory-honcho) +- [Memory LanceDB](/uk/plugins/memory-lancedb) diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index fe1ba8143..5a932012a 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,53 +1,55 @@ --- read_when: - - Ви хочете використовувати комплектний каркас app-server Codex - - Вам потрібні приклади конфігурації каркаса Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до PI -summary: Запускайте ходи вбудованого агента OpenClaw через комплектний каркас app-server Codex -title: каркас Codex + - Ви хочете використовувати вбудований app-server harness Codex + - Вам потрібні приклади конфігурації harness Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу на Pi +summary: Запускайте ходи вбудованого агента OpenClaw через вбудований app-server harness Codex +title: harness Codex x-i18n: - generated_at: "2026-04-27T23:45:00Z" + generated_at: "2026-04-28T00:03:45Z" model: gpt-5.4 provider: openai - source_hash: ef9654bdc6a2cb44726a53002f2735d823119d2e0379adc68907d8a0980ba4c2 + source_hash: c048ff928fb0b601b6a75631f9e33bbf23d08d1c21ad762b22ac3fb182d862ff source_path: plugins/codex-harness.md workflow: 15 --- -Комплектний Plugin `codex` дає OpenClaw змогу запускати ходи вбудованого агента через app-server Codex замість вбудованого каркаса PI. +Вбудований Plugin `codex` дає OpenClaw змогу запускати ходи вбудованого агента через app-server Codex замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction та виконанням через app-server. +OpenClaw і далі керує чат-каналами, файлами сесій, вибором моделей, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Якщо ви намагаєтеся зорієнтуватися, почніть із -[Середовища виконання агента](/uk/concepts/agent-runtimes). Коротка версія така: -`openai/gpt-5.5` — це посилання моделі, `codex` — це середовище виконання, а Telegram, +Якщо ви лише починаєте орієнтуватися, почніть із +[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко: +`openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, Discord, Slack або інший канал лишається поверхнею комунікації. ## Що змінює цей Plugin -Комплектний Plugin `codex` додає кілька окремих можливостей: +Вбудований Plugin `codex` додає кілька окремих можливостей: -| Можливість | Як її використовувати | Що вона робить | -| -------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- | -| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає ходи вбудованого агента OpenClaw через app-server Codex. | -| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками app-server Codex із розмови в месенджері. | -| Провайдер/каталог app-server Codex | внутрішні механізми `codex`, показані через каркас | Дає середовищу виконання змогу виявляти та перевіряти моделі app-server. | -| Шлях розуміння медіа Codex | шляхи сумісності з моделями зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | -| Нативна ретрансляція хуків | Хуки Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/фіналізації Codex. | +| Можливість | Як її використовувати | Що вона робить | +| -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | +| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає ходи вбудованого агента OpenClaw через app-server Codex. | +| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками app-server Codex із розмови в месенджері. | +| Провайдер/каталог app-server Codex | внутрішні частини `codex`, доступні через harness | Дозволяє середовищу виконання виявляти та перевіряти моделі app-server. | +| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | +| Нативна ретрансляція хуків | Хуки Plugin навколо нативних подій Codex | Дозволяє OpenClaw спостерігати/блокувати підтримувані нативні події інструментів/завершення Codex. | Увімкнення Plugin робить ці можливості доступними. Воно **не**: - не починає використовувати Codex для кожної моделі OpenAI -- не перетворює посилання моделей `openai-codex/*` на нативне середовище виконання -- не робить ACP/acpx типовим шляхом Codex -- не перемикає на льоту наявні сесії, у яких уже зафіксовано середовище виконання PI -- не замінює доставку каналів OpenClaw, файли сесій, зберігання профілів автентифікації або маршрутизацію повідомлень +- не перетворює посилання на моделі `openai-codex/*` на нативне середовище виконання +- не робить ACP/acpx типовим шляхом для Codex +- не перемикає на ходу наявні сесії, у яких уже зафіксовано середовище виконання PI +- не замінює доставку каналів OpenClaw, файли сесій, сховище auth-profile або + маршрутизацію повідомлень -Той самий Plugin також керує нативною поверхнею команд керування чатом `/codex`. Якщо +Цей самий Plugin також володіє нативною поверхнею команд керування чатом `/codex`. Якщо Plugin увімкнено і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити -потоки Codex із чату, агенти мають віддавати перевагу `/codex ...` замість ACP. ACP лишається -явним запасним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP -Codex. +потоки Codex із чату, агенти мають надавати перевагу `/codex ...` замість ACP. ACP лишається +явним резервним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP Codex. Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: @@ -60,134 +62,129 @@ Codex. - `before_agent_finalize` через ретрансляцію Codex `Stop` - `agent_end` -Plugins також можуть реєструвати нейтральне до середовища виконання проміжне програмне забезпечення для результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після виконання інструмента OpenClaw і до повернення результату в Codex. Це окремо від публічного хука Plugin -`tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, якими керує OpenClaw. +Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернено до Codex. Це окремо від публічного хука Plugin +`tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, якими володіє OpenClaw. -Щодо семантики самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks) -і [Поведінка захисту Plugin](/uk/tools/plugin). +Про семантику самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks) +та [Поведінка guard у Plugin](/uk/tools/plugin). -Каркас вимкнено типово. Нові конфігурації мають зберігати посилання моделей OpenAI -канонічними як `openai/gpt-*` і явно примусово задавати +Harness вимкнений типово. У нових конфігураціях слід зберігати канонічні +посилання на моделі OpenAI як `openai/gpt-*` і явно примусово вказувати `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне нативне виконання app-server. Застарілі посилання моделей `codex/*` і далі автоматично вибирають -каркас для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, -не показуються як звичайні варіанти моделі/провайдера. +потрібне нативне виконання через app-server. Устарілі посилання на моделі `codex/*` усе ще автоматично вибирають +harness для сумісності, але усталені префікси провайдерів, підкріплені середовищем виконання, не показуються як звичайні варіанти моделей/провайдерів. Якщо Plugin `codex` увімкнено, але основна модель усе ще -`openai-codex/*`, `openclaw doctor` виводить попередження замість зміни маршруту. Це +`openai-codex/*`, `openclaw doctor` показує попередження замість зміни маршруту. Це навмисно: `openai-codex/*` лишається шляхом OAuth/підписки PI Codex, а -нативне виконання app-server лишається явним вибором середовища виконання. +нативне виконання через app-server лишається явним вибором середовища виконання. ## Карта маршрутів Скористайтеся цією таблицею перед зміною конфігурації: -| Бажана поведінка | Посилання моделі | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка статусу | -| ------------------------------------------- | --------------------------- | -------------------------------------- | -------------------------- | ------------------------------- | -| API OpenAI через звичайний виконавець OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | -| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Змішані провайдери з консервативним автоматичним режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові середовища виконання Plugin | Залежить від вибраного середовища виконання | -| Явна сесія адаптера Codex ACP | залежить від запиту/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Статус задачі/сесії ACP | +| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка стану | +| ------------------------------------------ | -------------------------- | -------------------------------------- | -------------------------- | ----------------------------- | +| API OpenAI через звичайний раннер OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | +| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Змішані провайдери з консервативним авто-режимом | посилання провайдера | `agentRuntime.id: "auto"` | Необов’язкові Plugin runtime | Залежить від вибраного runtime | +| Явна сесія адаптера ACP Codex | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Статус задачі/сесії ACP | -Важливий поділ — між провайдером і середовищем виконання: +Ключове розділення — це провайдер проти середовища виконання: -- `openai-codex/*` відповідає на запитання «який маршрут провайдера/автентифікації має використовувати PI?» -- `agentRuntime.id: "codex"` відповідає на запитання «який цикл має виконувати цей +- `openai-codex/*` відповідає на питання «який маршрут провайдера/автентифікації має використовувати PI?» +- `agentRuntime.id: "codex"` відповідає на питання «який цикл має виконувати цей вбудований хід?» -- `/codex ...` відповідає на запитання «до якої нативної розмови Codex має бути прив’язаний - або якою слід керувати в цьому чаті?» -- ACP відповідає на запитання «який зовнішній процес каркаса має запустити acpx?» +- `/codex ...` відповідає на питання «до якої нативної розмови Codex слід прив’язати + цей чат або якою слід керувати?» +- ACP відповідає на питання «який зовнішній процес harness має запускати acpx?» ## Виберіть правильний префікс моделі Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете OAuth Codex через PI; використовуйте `openai/*`, коли хочете прямий доступ до API OpenAI або -коли примусово вмикаєте нативний каркас app-server Codex: +коли примусово використовуєте нативний harness app-server Codex: -| Посилання моделі | Шлях середовища виконання | Використовуйте, коли | -| --------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через механізми OpenClaw/PI | Вам потрібен актуальний прямий доступ до API OpenAI Platform через `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex зі стандартним виконавцем PI. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | Каркас app-server Codex | Вам потрібне нативне виконання app-server Codex для ходу вбудованого агента. | +| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | +| -------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підпискою ChatGPT/Codex із типовим раннером PI. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для ходу вбудованого агента. | GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для OAuth PI або `openai/gpt-5.5` із каркасом -app-server Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` буде підтримуватися, -щойно OpenAI увімкне GPT-5.5 у публічному API. +`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримується, +щойно OpenAI ввімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor -під час міграції сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання моделей і окремо записує політику середовища виконання, тоді як застарілі посилання лише для запасного варіанта лишаються без змін, бо середовище виконання налаштовується для всього контейнера агента. -Нові конфігурації OAuth PI Codex мають використовувати `openai-codex/gpt-*`; нові конфігурації -каркаса нативного app-server мають використовувати `openai/gpt-*` плюс +Устарілі посилання `codex/gpt-*` і далі приймаються як сумісні псевдоніми. Doctor +міграція сумісності переписує усталені основні посилання на runtime до канонічних посилань на моделі та окремо зберігає політику середовища виконання, тоді як усталені посилання лише для резервного варіанта лишаються без змін, бо runtime налаштовується для всього контейнера агента. +Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові +конфігурації harness app-server мають використовувати `openai/gpt-*` разом із `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` дотримується того самого поділу префіксів. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має працювати +`agents.defaults.imageModel` дотримується такого ж розділення за префіксами. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI +Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися через обмежений хід app-server Codex. Модель app-server Codex має -заявляти підтримку введення зображень; текстові моделі Codex завершуються помилкою до початку -медіа-ходу. +оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до початку медіа-ходу. -Використовуйте `/status`, щоб підтвердити фактичний каркас для поточної сесії. Якщо -вибір видається несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness` -і перевірте структурований запис шлюзу `agent harness selected`. Він -містить id вибраного каркаса, причину вибору, політику середовища виконання/запасного варіанта та, +Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір виявився неочікуваним, увімкніть налагоджувальне журналювання для підсистеми `agents/harness` +і перевірте структурований запис gateway `agent harness selected`. Він +містить id вибраного harness, причину вибору, політику runtime/резервного варіанта і, у режимі `auto`, результат підтримки для кожного кандидата Plugin. ### Що означають попередження doctor -`openclaw doctor` виводить попередження, коли виконуються всі ці умови: +`openclaw doctor` показує попередження, коли всі ці умови істинні: -- комплектний Plugin `codex` увімкнено або дозволено +- вбудований Plugin `codex` увімкнено або дозволено - основна модель агента — `openai-codex/*` -- фактичне середовище виконання цього агента — не `codex` +- фактичне runtime цього агента — не `codex` Це попередження існує, тому що користувачі часто очікують, що «Plugin Codex увімкнено» означає -«нативне середовище виконання app-server Codex». OpenClaw не робить такого переходу автоматично. Попередження означає: +«нативне runtime app-server Codex». OpenClaw не робить такого кроку. Попередження означає: -- **Нічого змінювати не потрібно**, якщо вам був потрібен OAuth ChatGPT/Codex через PI. +- **Жодних змін не потрібно**, якщо ви мали на увазі OAuth ChatGPT/Codex через PI. - Змініть модель на `openai/` і встановіть - `agentRuntime.id: "codex"`, якщо вам було потрібне нативне виконання - app-server. -- Наявним сесіям усе одно потрібні `/new` або `/reset` після зміни середовища виконання, - тому що прив’язки середовища виконання сесії є фіксованими. + `agentRuntime.id: "codex"`, якщо ви мали на увазі нативне виконання + через app-server. +- Наявні сесії все одно потребують `/new` або `/reset` після зміни runtime, + тому що прив’язки runtime сесії є сталими. -Вибір каркаса — це не механізм керування живою сесією. Коли виконується вбудований хід, -OpenClaw записує id вибраного каркаса в цю сесію й надалі використовує його для -пізніших ходів у межах того самого id сесії. Змінюйте конфігурацію `agentRuntime` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший каркас; +Вибір harness — це не механізм керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує id вибраного harness у цій сесії й продовжує використовувати його для +наступних ходів із тим самим id сесії. Змінюйте конфігурацію `agentRuntime` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI і Codex. Це запобігає повторному програванню одного транскрипту через +розмови між PI та Codex. Це запобігає повторному програванню одного транскрипту через дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи прив’язок каркаса, вважаються прив’язаними до PI, щойно -в них з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести -цю розмову на Codex після зміни конфігурації. +Устарілі сесії, створені до появи прив’язок harness, вважаються прив’язаними до PI, щойно +вони мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на +Codex після зміни конфігурації. -`/status` показує фактичне середовище виконання моделі. Стандартний каркас PI відображається як -`Runtime: OpenClaw Pi Default`, а каркас app-server Codex — як +`/status` показує фактичне runtime моделі. Типовий harness PI відображається як +`Runtime: OpenClaw Pi Default`, а harness app-server Codex — як `Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним комплектним Plugin `codex`. -- Codex app-server `0.125.0` або новіший. Комплектний Plugin типово керує сумісним - бінарним файлом app-server Codex, тому локальні команди `codex` у `PATH` - не впливають на звичайний запуск каркаса. -- Автентифікація Codex, доступна для процесу app-server. +- OpenClaw із доступним вбудованим Plugin `codex`. +- Codex app-server `0.125.0` або новіший. Вбудований Plugin типово керує сумісним + двійковим файлом app-server Codex, тому локальні команди `codex` у `PATH` не + впливають на звичайний запуск harness. +- Автентифікація Codex, доступна для процесу app-server або для bridge автентифікації Codex в OpenClaw. -Plugin блокує старіші або неверсіоновані рукостискання app-server. Це дозволяє -OpenClaw лишатися в межах поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshake app-server. Це утримує +OpenClaw у межах поверхні протоколу, з якою його тестували. -Для live- і Docker-smoke-тестів автентифікація зазвичай походить із `OPENAI_API_KEY`, а також -з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте той самий автентифікаційний матеріал, що й ваш локальний -app-server Codex. +Для live- і Docker smoke-тестів автентифікація зазвичай походить від облікового запису Codex CLI +або auth-profile `openai-codex` в OpenClaw. Локальні запуски app-server через stdio також +можуть використовувати `CODEX_API_KEY` / `OPENAI_API_KEY`, коли облікового запису немає. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте каркас `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово вкажіть harness `codex`: ```json5 { @@ -209,7 +206,7 @@ app-server Codex. } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -224,26 +221,28 @@ app-server Codex. } ``` -Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як -`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають -віддавати перевагу `openai/` плюс явний запис `agentRuntime`, наведений вище. +Устарілі конфігурації, які задають `agents.defaults.model` або модель агента як +`codex/`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають +надавати перевагу `openai/` разом із явним записом `agentRuntime`, наведеним вище. ## Додайте Codex поруч з іншими моделями Не задавайте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися -між Codex і моделями інших провайдерів. Примусове середовище виконання застосовується до кожного -вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, коли це середовище виконання примусово задано, OpenClaw все одно спробує каркас Codex і завершиться помилкою без тихого перенаправлення цього ходу через PI. +між моделями провайдера Codex і не-Codex. Примусове runtime застосовується до кожного +вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки +це runtime примусово задане, OpenClaw усе одно спробує використати harness Codex і завершиться помилкою +без неявного маршрутування цього ходу через PI. -Замість цього використовуйте одну з таких форм: +Використовуйте натомість одну з цих схем: -- Розмістіть Codex на окремому агенті з `agentRuntime.id: "codex"`. -- Залиште типовий агент на `agentRuntime.id: "auto"` і запасному варіанті PI для звичайного змішаного +- Виділіть Codex в окремого агента з `agentRuntime.id: "codex"`. +- Залиште типовому агенту `agentRuntime.id: "auto"` і резервний перехід на PI для звичайного змішаного використання провайдерів. - Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу - `openai/*` плюс явна політика середовища виконання Codex. + `openai/*` разом із явною політикою runtime Codex. -Наприклад, це залишає типовий агент на звичайному автоматичному виборі та -додає окремий агент Codex: +Наприклад, така конфігурація залишає типовий агент на звичайному автоматичному виборі та +додає окремого агента Codex: ```json5 { @@ -280,36 +279,36 @@ app-server Codex. } ``` -У такій формі: +За такої схеми: -- Типовий агент `main` використовує звичайний шлях провайдера та запасний варіант сумісності PI. -- Агент `codex` використовує каркас app-server Codex. -- Якщо Codex відсутній або не підтримується для агента `codex`, хід завершується - помилкою замість тихого використання PI. +- Типовий агент `main` використовує звичайний шлях провайдера та резервну сумісність із PI. +- Агент `codex` використовує harness app-server Codex. +- Якщо Codex відсутній або не підтримується для агента `codex`, хід + завершується помилкою замість тихого переходу на PI. ## Маршрутизація команд агента Агенти мають маршрутизувати запити користувача за наміром, а не лише за словом "Codex": -| Користувач просить... | Агент має використовувати... | -| ------------------------------------------------------ | ----------------------------------------------- | -| "Прив’яжи цей чат до Codex" | `/codex bind` | -| "Віднови тут потік Codex ``" | `/codex resume ` | -| "Покажи потоки Codex" | `/codex threads` | -| "Використовуй Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | -| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання моделей `openai-codex/*` | -| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, а не `/codex` і не нативні субагенти | +| Користувач просить... | Агент має використовувати... | +| ----------------------------------------------------- | ----------------------------------------------- | +| "Прив’яжи цей чат до Codex" | `/codex bind` | +| "Віднови тут потік Codex ``" | `/codex resume ` | +| "Покажи потоки Codex" | `/codex threads` | +| "Використовуй Codex як runtime для цього агента" | зміну конфігурації `agentRuntime.id` | +| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | +| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, не `/codex` і не нативні субагенти | -OpenClaw показує агентам рекомендації щодо запуску ACP лише тоді, коли ACP увімкнено, -можна диспетчеризувати і він підкріплений завантаженим бекендом середовища виконання. Якщо ACP недоступний, -системний запит і Skills Plugin не повинні навчати агента маршрутизації +OpenClaw показує агентам вказівки щодо запуску через ACP лише тоді, коли ACP увімкнено, +його можна диспетчеризувати, і він підтримується завантаженим backend runtime. Якщо ACP недоступний, +системний prompt і Skills Plugin не мають навчати агента маршрутизації через ACP. ## Розгортання лише з Codex -Примусово використовуйте каркас Codex, коли потрібно підтвердити, що кожен хід вбудованого агента -використовує Codex. Явні середовища виконання Plugin типово не мають запасного варіанта PI, тому +Примусово використовуйте harness Codex, коли потрібно довести, що кожен хід вбудованого агента +використовує Codex. Явні runtime Plugin типово працюють без резервного переходу на PI, тому `fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 @@ -326,20 +325,20 @@ OpenClaw показує агентам рекомендації щодо зап } ``` -Перевизначення через середовище: +Перевизначення через змінну середовища: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Якщо Codex примусово ввімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, -app-server занадто старий або app-server не може запуститися. Встановлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв -відсутній вибір каркаса. +Якщо Codex примусово увімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, app-server +застарілий або app-server не може запуститися. Встановлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви свідомо хочете, щоб PI обробляв +відсутній вибір harness. ## Codex для окремого агента -Ви можете зробити один агент таким, що використовує тільки Codex, тоді як типовий агент зберігатиме звичайний +Ви можете зробити одного агента лише з Codex, тоді як типовий агент зберігатиме нормальний автовибір: ```json5 @@ -371,15 +370,15 @@ app-server занадто старий або app-server не може запу } ``` -Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а каркас Codex створює або відновлює свій побічний потік app-server +Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову +сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server за потреби. `/reset` очищує прив’язку сесії OpenClaw для цього потоку -і дає наступному ходу змогу знову визначити каркас із поточної конфігурації. +і дає змогу наступному ходу знову визначити harness із поточної конфігурації. ## Виявлення моделей Типово Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або перевищує час очікування, він використовує комплектний запасний каталог для: +виявлення завершується помилкою або перевищує час очікування, він використовує вбудований резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -405,8 +404,8 @@ app-server занадто старий або app-server не може запу } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався -запасний каталог: +Вимкніть виявлення, якщо хочете, щоб запуск не намагався опитувати Codex і дотримувався +резервного каталогу: ```json5 { @@ -425,27 +424,27 @@ app-server занадто старий або app-server не може запу } ``` -## Підключення app-server і політика +## Підключення до app-server і політика -Типово Plugin запускає локально бінарний файл Codex, яким керує OpenClaw, за допомогою: +Типово Plugin локально запускає керований OpenClaw двійковий файл Codex такою командою: ```bash codex app-server --listen stdio:// ``` -Керований бінарний файл оголошується як комплектна залежність середовища виконання Plugin і розміщується -разом з рештою залежностей Plugin `codex`. Це зберігає версію app-server прив’язаною -до комплектного Plugin, а не до будь-якого окремого Codex CLI, +Керований двійковий файл оголошено як вбудовану залежність runtime Plugin і підготовлено +разом з іншими залежностями Plugin `codex`. Це прив’язує версію app-server +до вбудованого Plugin, а не до будь-якого окремого Codex CLI, який випадково встановлено локально. Встановлюйте `appServer.command` лише тоді, коли свідомо хочете запускати інший виконуваний файл. -Типово OpenClaw запускає локальні сесії каркаса Codex у режимі YOLO: +Типово OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена локальна робоча модель оператора, яка використовується -для автономних Heartbeat: Codex може використовувати інструменти оболонки та мережі без -зупинки на нативних запитах підтвердження, на які нікому відповісти. +`sandbox: "danger-full-access"`. Це довірена локальна операторська модель, що використовується +для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без +зупинки на нативних prompt підтвердження, на які нікому відповісти. -Щоб увімкнути підтвердження Codex із переглядом guardian, задайте `appServer.mode: +Щоб увімкнути підтвердження з нативною перевіркою guardian у Codex, встановіть `appServer.mode: "guardian"`: ```json5 @@ -466,16 +465,18 @@ codex app-server --listen stdio:// } ``` -Режим guardian використовує нативний шлях автоматичного перегляду підтверджень Codex. Коли Codex просить -вийти з пісочниці, записати поза робочим простором або додати дозволи, як-от доступ до мережі, -Codex спрямовує цей запит на підтвердження нативному рецензенту, а не людині через запит. Рецензент застосовує модель ризиків Codex і підтверджує або відхиляє конкретний запит. Використовуйте Guardian, коли потрібні додаткові запобіжники порівняно з режимом YOLO, -але водночас потрібно, щоб агенти без нагляду могли рухатися далі. +Режим Guardian використовує нативний шлях автоматичної перевірки підтверджень Codex. Коли Codex просить +вийти з sandbox, записати за межами робочого простору або додати дозволи на кшталт доступу до мережі, +Codex надсилає такий запит на підтвердження нативному рецензенту замість +людського prompt. Рецензент застосовує модель оцінки ризику Codex і схвалює або відхиляє +конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші обмеження, ніж у режимі YOLO, +але при цьому потрібно, щоб агенти без нагляду могли просуватися далі. -Налаштування `guardian` розгортається в `approvalPolicy: "on-request"`, +Попереднє налаштування `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. -Окремі поля політики все одно перевизначають `mode`, тому розширені розгортання можуть поєднувати -цей шаблон з явними виборами. Старе значення рецензента `guardian_subagent` -і далі приймається як псевдонім сумісності, але нові конфігурації мають використовувати +Окремі поля політики все одно мають пріоритет над `mode`, тож розширені розгортання можуть поєднувати +цей preset із явними налаштуваннями. Старе значення рецензента `guardian_subagent` +і далі приймається як псевдонім для сумісності, але нові конфігурації мають використовувати `auto_review`. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -500,24 +501,65 @@ Codex спрямовує цей запит на підтвердження на } ``` +Запуски app-server через stdio типово успадковують середовище процесу OpenClaw, +але OpenClaw керує bridge облікового запису app-server Codex. Автентифікація вибирається в такому +порядку: + +1. Явний auth-profile Codex OpenClaw для агента. +2. Наявний обліковий запис app-server, наприклад локальний вхід ChatGPT у Codex CLI. +3. Лише для локальних запусків app-server через stdio: `CODEX_API_KEY`, потім + `OPENAI_API_KEY`, якщо облікового запису app-server немає, а автентифікація OpenAI + усе ще потрібна. + +Коли OpenClaw бачить auth-profile Codex у стилі підписки ChatGPT, він видаляє +`CODEX_API_KEY` і `OPENAI_API_KEY` із породженого дочірнього процесу Codex. Це +дозволяє API key на рівні Gateway лишатися доступними для embeddings або прямих моделей OpenAI, +не спричиняючи випадкового білінгу нативних ходів app-server Codex через API. +Явні профілі Codex з API key і локальний резервний варіант env-key для stdio використовують вхід app-server, а не успадковане середовище дочірнього процесу. Підключення до app-server через WebSocket +не отримують резервний варіант API key із середовища Gateway; використовуйте явний auth-profile або +власний обліковий запис віддаленого app-server. + +Якщо розгортанню потрібна додаткова ізоляція змінних середовища, додайте ці змінні до +`appServer.clearEnv`: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + clearEnv: ["CODEX_API_KEY", "OPENAI_API_KEY"], + }, + }, + }, + }, + }, +} +``` + +`appServer.clearEnv` впливає лише на породжений дочірній процес app-server Codex через stdio. + Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL WebSocket app-server. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | -| `mode` | `"yolo"` | Попередньо встановлений режим для виконання YOLO або guardian-reviewed. | -| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається на старт/відновлення потоку/хід. | -| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається на старт/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити підтвердження. `guardian_subagent` лишається застарілим псевдонімом. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| Поле | Типове значення | Значення | +| ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | керований двійковий файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований двійковий файл; задавайте лише для явного перевизначення. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не встановлено | URL app-server WebSocket. | +| `authToken` | не встановлено | Bearer token для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються з породженого процесу stdio app-server після того, як OpenClaw сформує успадковане середовище. | +| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | +| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з перевіркою guardian. | +| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається під час запуску/відновлення потоку/ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні prompt підтвердження. `guardian_subagent` лишається застарілим псевдонімом. | +| `serviceTier` | не встановлено | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Перевизначення через середовище й далі доступні для локального тестування: +Перевизначення через змінні середовища і далі доступні для локального тестування: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -525,21 +567,21 @@ Codex спрямовує цей запит на підтвердження на - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований бінарний файл, коли +`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований двійковий файл, коли `appServer.command` не задано. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Натомість використовуйте `plugins.entries.codex.config.appServer.mode: "guardian"` або `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація -є бажаною для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у тому самому -перевіреному файлі, що й решта налаштування каркаса Codex. +є кращим варіантом для відтворюваних розгортань, оскільки зберігає поведінку Plugin в тому самому +перевіреному файлі, що й решта налаштувань harness Codex. ## Використання комп’ютера -Computer Use описано в окремому посібнику з налаштування: +Використання комп’ютера описано в окремому посібнику з налаштування: [Codex Computer Use](/uk/plugins/codex-computer-use). -Коротка версія: OpenClaw не постачає застосунок для керування робочим столом і не виконує +Коротко: OpenClaw не постачає застосунок для керування робочим столом і не виконує дії на робочому столі самостійно. Він готує app-server Codex, перевіряє, що MCP-сервер `computer-use` доступний, а потім дозволяє Codex обробляти нативні виклики інструментів MCP під час ходів у режимі Codex. @@ -579,18 +621,18 @@ MCP-сервер `computer-use` доступний, а потім дозволя - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use специфічний для macOS і може вимагати локальних дозволів ОС, перш ніж -MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true і MCP- -сервер недоступний, ходи в режимі Codex завершуються помилкою до запуску потоку замість -тихого виконання без нативних інструментів Computer Use. Див. -[Codex Computer Use](/uk/plugins/codex-computer-use) щодо вибору marketplace, -обмежень віддаленого каталогу, причин стану та усунення несправностей. +Computer Use призначений для macOS і може потребувати локальних дозволів ОС, перш ніж +MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true, а MCP- +сервер недоступний, ходи в режимі Codex завершуються помилкою ще до запуску потоку, замість +тихої роботи без нативних інструментів Computer Use. Див. +[Codex Computer Use](/uk/plugins/codex-computer-use) для відомостей про варіанти marketplace, +обмеження віддаленого каталогу, причини станів і усунення несправностей. Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати стандартний -комплектний marketplace Codex Desktop з +вбудований marketplace Codex Desktop із `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, якщо Codex ще не виявив локальний marketplace. Використовуйте `/new` або `/reset` після -зміни конфігурації середовища виконання або Computer Use, щоб наявні сесії не зберігали стару +зміни конфігурації runtime або Computer Use, щоб наявні сесії не зберігали стару прив’язку потоку PI або Codex. ## Поширені рецепти @@ -609,7 +651,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перевірка каркаса лише з Codex: +Перевірка harness лише з Codex: ```json5 { @@ -631,7 +673,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Підтвердження Codex із переглядом guardian: +Підтвердження Codex із перевіркою guardian: ```json5 { @@ -653,7 +695,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -676,69 +718,69 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано +Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано до наявного потоку Codex, наступний хід знову надсилає до -app-server поточно вибрані модель OpenAI, провайдера, політику підтверджень, пісочницю та рівень сервісу. +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` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, обмеження швидкості, MCP-сервери та Skills. - `/codex models` перелічує живі моделі app-server Codex. - `/codex threads [filter]` перелічує нещодавні потоки Codex. - `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. - `/codex compact` просить app-server Codex виконати Compaction приєднаного потоку. - `/codex review` запускає нативну перевірку Codex для приєднаного потоку. - `/codex computer-use status` перевіряє налаштований Plugin Computer Use і MCP-сервер. -- `/codex computer-use install` установлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. -- `/codex account` показує стан облікового запису та лімітів швидкості. +- `/codex computer-use install` встановлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. +- `/codex account` показує стан облікового запису та обмежень швидкості. - `/codex mcp` перелічує стан MCP-сервера app-server Codex. - `/codex skills` перелічує Skills app-server Codex. -`/codex resume` записує той самий побічний файл прив’язки, який каркас використовує для -звичайних ходів. На наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw до app-server і зберігає увімкнену +`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає ввімкнену розширену історію. -Поверхня команд вимагає Codex app-server `0.125.0` або новішої версії. Окремі +Поверхня команд потребує Codex app-server `0.125.0` або новішої версії. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або нестандартний app-server не надає цей метод JSON-RPC. +майбутній або спеціальний app-server не надає цей метод JSON-RPC. ## Межі хуків -Каркас Codex має три шари хуків: +Harness Codex має три шари хуків: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | -------------------------------------------------------------------- | -| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між каркасами PI і Codex. | -| Проміжне ПЗ розширень app-server Codex | Комплектні Plugins OpenClaw | Поведінка адаптера на рівні ходу навколо динамічних інструментів OpenClaw. | +| Шар | Власник | Призначення | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI та Codex. | +| Middleware розширення app-server Codex | Вбудовані Plugins OpenClaw | Поведінка адаптера на рівні ходу навколо динамічних інструментів OpenClaw. | | Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує файли `hooks.json` проєкту або глобальні файли Codex для маршрутизації -поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів +OpenClaw не використовує файли проєктного або глобального Codex `hooks.json` для маршрутизації +поведінки Plugin OpenClaw. Для підтримуваного bridge нативних інструментів і дозволів OpenClaw впроваджує конфігурацію Codex для кожного потоку для `PreToolUse`, `PostToolUse`, -`PermissionRequest` і `Stop`. Інші хуки Codex, як-от `SessionStart` і -`UserPromptSubmit`, залишаються елементами керування на рівні Codex; вони не -експонуються як хуки Plugin OpenClaw у контракті v1. +`PermissionRequest` і `Stop`. Інші хуки Codex, такі як `SessionStart` і +`UserPromptSubmit`, залишаються елементами керування на рівні Codex; вони не відкриваються як +хуки Plugin OpenClaw у контракті v1. Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тож OpenClaw запускає поведінку Plugin і проміжного ПЗ, якою він володіє в -адаптері каркаса. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. -OpenClaw може віддзеркалювати вибрані події, але не може переписувати нативний потік Codex, -якщо Codex не відкриє цю операцію через app-server або зворотні виклики +виклик, тому OpenClaw запускає належну йому поведінку Plugin і middleware в +адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. +OpenClaw може дзеркалити вибрані події, але не може переписати нативний потік Codex, +якщо Codex не відкриває цю операцію через app-server або зворотні виклики нативних хуків. -Проєкції Compaction і життєвого циклу LLM походять із сповіщень app-server Codex -і стану адаптера OpenClaw, а не з команд нативних хуків Codex. +Проєкції Compaction і життєвого циклу LLM надходять із +сповіщень app-server Codex і стану адаптера OpenClaw, а не з команд нативних хуків Codex. Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` — це спостереження на рівні адаптера, а не побайтні захоплення -внутрішнього запиту Codex або даних Compaction. +`llm_output` — це спостереження на рівні адаптера, а не побайтові захоплення +внутрішнього запиту Codex або payload Compaction. Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. @@ -746,126 +788,124 @@ OpenClaw може віддзеркалювати вибрані події, ал ## Контракт підтримки V1 -Режим Codex — це не PI з іншим викликом моделі під ним. Codex володіє більшою частиною -нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесії +Режим Codex — це не PI з іншим викликом моделі під ним. Codex керує більшою частиною +нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій навколо цієї межі. -Підтримується в середовищі виконання Codex v1: +Підтримується в runtime Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл моделі OpenAI через Codex | Підтримується | App-server Codex володіє ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | -| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза середовищем виконання моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається на шляху виконання. | -| Plugins запиту та контексту | Підтримується | OpenClaw будує накладки запиту та проєктує контекст у хід Codex перед запуском або відновленням потоку. | -| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або супровід після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | -| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і проміжне ПЗ для результатів інструментів виконуються навколо динамічних інструментів OpenClaw. | -| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` запускаються з чесними даними режиму Codex. | -| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативного хука | Codex `Stop` ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | -| Блокування або спостереження нативної оболонки, patch і MCP | Підтримується через ретрансляцію нативного хука | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, включно з корисними навантаженнями MCP в Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | -| Політика нативних дозволів | Підтримується через ретрансляцію нативного хука | Codex `PermissionRequest` можна маршрутизувати через політику OpenClaw там, де це надає середовище виконання. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях підтвердження guardian або користувача. | -| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які він отримує. | +| Поверхня | Підтримка | Чому | +| --------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Цикл моделі OpenAI через Codex | Підтримується | App-server Codex керує ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконувати ці інструменти, тому OpenClaw залишається в шляху виконання. | +| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням потоку. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або обслуговування після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | +| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload для режиму Codex. | +| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних хуків | `Stop` Codex ретранслюється до `before_agent_finalize`; `revise` просить Codex зробити ще один прохід моделі перед завершенням. | +| Блокування або спостереження за нативними shell, patch і MCP | Підтримується через ретрансляцію нативних хуків | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Нативна політика дозволів | Підтримується через ретрансляцію нативних хуків | `PermissionRequest` Codex можна маршрутизувати через політику OpenClaw там, де runtime це підтримує. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях підтвердження guardian або користувача. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які отримує. | -Не підтримується в середовищі виконання Codex v1: +Не підтримується в runtime Codex v1: -| Поверхня | Межа V1 | Майбутній шлях | -| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка hook/schema Codex для заміни вхідних даних інструмента. | -| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібна хірургія нативного потоку. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей хук перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна було б віддзеркалювати перетворені записи, але канонічне переписування потребує підтримки Codex. | -| Багаті метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільний список збереженого/відкинутого, дельту токенів або дані зведення. | Потрібні багатші події Compaction Codex. | -| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post хуки Compaction Codex, якщо Plugins мають скасовувати або переписувати нативну Compaction. | -| Побайтне захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex внутрішньо будує фінальний запит до API OpenAI. | Потрібна подія трасування запиту моделі Codex або API налагодження. | +| Поверхня | Межа V1 | Подальший шлях | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки Codex hooks/schema для заміни вхідних даних інструмента. | +| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібне втручання в нативний потік. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей hook перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Може дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. | +| Багаті метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/відкинутого, дельти токенів або payload підсумку. | Потрібні багатші події Compaction у Codex. | +| Втручання в Compaction | Поточні hooks Compaction в OpenClaw працюють у режимі Codex на рівні сповіщень. | Додати hooks Codex до/після Compaction, якщо Plugins мають блокувати або переписувати нативну Compaction. | +| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити та сповіщення app-server, але ядро Codex формує фінальний запит до OpenAI API внутрішньо. | Потрібна подія трасування запиту моделі Codex або debug API. | ## Інструменти, медіа та Compaction -Каркас Codex змінює лише низькорівневий виконавець вбудованого агента. +Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw, як і раніше, формує список інструментів і отримує результати динамічних інструментів від -каркаса. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів обміну повідомленнями -і далі проходять звичайним шляхом доставки OpenClaw. +OpenClaw і далі будує список інструментів і отримує результати динамічних інструментів від +harness. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів повідомлень +і далі проходять через звичайний шлях доставки OpenClaw. -Ретрансляція нативних хуків навмисно є загальною, але контракт підтримки v1 -обмежений шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У -середовищі виконання Codex це включає корисні навантаження `PreToolUse`, -`PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня -подія хука Codex є поверхнею Plugin OpenClaw, доки її не буде названо в контракті -середовища виконання. +Ретрансляція нативних hooks навмисно є загальною, але контракт підтримки v1 +обмежено шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У +runtime Codex це включає payload `PreToolUse`, +`PostToolUse` і `PermissionRequest` для shell, patch та MCP. Не припускайте, що кожна майбутня +подія hook Codex є поверхнею Plugin OpenClaw, доки контракт runtime +не назве її явно. Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny -лише тоді, коли політика ухвалює рішення. Результат без рішення — це не allow. Codex -розглядає його як відсутність рішення хука і переходить до власного шляху підтвердження guardian або користувача. +лише коли це визначає політика. Результат без рішення — це не allow. Codex трактує його як +відсутність рішення hook і переходить до власного шляху підтвердження guardian або користувача. -Запити на підтвердження інструментів MCP Codex маршрутизуються через потік -підтвердження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до -початкового чату, а наступне поставлене в чергу follow-up-повідомлення відповідає на цей нативний -запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити на elicitation MCP -і далі завершуються помилкою без небезпечного продовження. +Запити на підтвердження інструментів MCP Codex маршрутизуються через +потік підтвердження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Prompt `request_user_input` Codex надсилаються назад до +початкового чату, а наступне повідомлення в черзі відповідає на цей запит нативного +сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити MCP на отримання даних +і далі завершуються помилкою безпечним способом. -Коли вибрана модель використовує каркас Codex, нативна Compaction потоку делегується -app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або каркаса. Дзеркало -включає запит користувача, фінальний текст асистента та легковагові записи -міркування або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише -записує сигнали початку та завершення нативної Compaction. Він поки не показує -людинозрозуміле зведення Compaction або придатний для аудиту список того, які записи Codex +Коли вибрана модель використовує harness Codex, нативна Compaction потоку +делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало +містить prompt користувача, фінальний текст асистента та полегшені записи міркування або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише записує сигнали початку та завершення нативної Compaction. Він іще не показує +людинозрозумілий підсумок Compaction або аудитований список того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі -не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, -коли OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. +Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не +переписує записи результатів нативних інструментів Codex. Він застосовується лише коли +OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, як-от +Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і розуміння медіа +і далі використовують відповідні налаштування провайдера/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не з’являється як звичайний провайдер `/model`:** це очікувана поведінка для +**Codex не з’являється як звичайний провайдер `/model`:** це очікувано для нових конфігурацій. Виберіть модель `openai/gpt-*` з `agentRuntime.id: "codex"` (або застаріле посилання `codex/*`), увімкніть `plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає `codex`. **OpenClaw використовує PI замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати PI як -бекенд сумісності, коли жоден каркас Codex не бере на себе цей запуск. Установіть +backend сумісності, коли жоден harness Codex не бере виконання на себе. Встановіть `agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Примусове -середовище виконання Codex тепер завершується помилкою замість переходу до PI, якщо ви -явно не встановите `agentRuntime.fallback: "pi"`. Щойно app-server Codex -вибрано, його помилки відображаються напряму без додаткової конфігурації запасного варіанта. +runtime Codex тепер завершується помилкою замість переходу на PI, якщо ви +явно не встановили `agentRuntime.fallback: "pi"`. Щойно app-server Codex +вибрано, його збої проявляються безпосередньо без додаткової конфігурації резервного варіанта. -**App-server відхиляється:** оновіть Codex, щоб рукостискання app-server -повідомляло версію `0.125.0` або новішу. Попередні випуски тієї ж версії або версії з суфіксом збірки, -такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, тому що саме стабільний -мінімум протоколу `0.125.0` тестує OpenClaw. +**app-server відхиляється:** оновіть Codex так, щоб handshake app-server +повідомляв версію `0.125.0` або новішу. Попередні випуски тієї самої версії або версії +із суфіксом збірки, як-от `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки +стабільна нижня межа протоколу `0.125.0` — це те, що тестує OpenClaw. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Модель не Codex використовує PI:** це очікувана поведінка, якщо ви не примусово встановили +**Модель не Codex використовує PI:** це очікувано, якщо ви не примусово встановили `agentRuntime.id: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму нормальному -шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований -хід для цього агента має бути моделлю OpenAI, підтримуваною Codex. +посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму +звичайному шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований +хід для цього агента має використовувати підтримувану Codex модель OpenAI. -**Computer Use установлено, але інструменти не запускаються:** перевірте -`/codex computer-use status` з нової сесії. Якщо інструмент повідомляє -`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не зникає, перезапустіть -gateway, щоб очистити застарілі реєстрації нативних хуків. Якщо `computer-use.list_apps` +**Computer Use встановлено, але інструменти не працюють:** перевірте +`/codex computer-use status` із нової сесії. Якщо інструмент повідомляє +`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не допомагає, перезапустіть +gateway, щоб очистити застарілі реєстрації нативних hooks. Якщо `computer-use.list_apps` перевищує час очікування, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. -## Пов’язані матеріали +## Пов’язане -- [Plugins каркаса агента](/uk/plugins/sdk-agent-harness) -- [Середовища виконання агента](/uk/concepts/agent-runtimes) +- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Середовища виконання агентів](/uk/concepts/agent-runtimes) - [Провайдери моделей](/uk/concepts/model-providers) - [Провайдер OpenAI](/uk/providers/openai) - [Стан](/uk/cli/status) - [Хуки Plugin](/uk/plugins/hooks) -- [Довідник з конфігурації](/uk/gateway/configuration-reference) +- [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/memory-lancedb.md b/docs/uk/plugins/memory-lancedb.md new file mode 100644 index 000000000..e141f7d7b --- /dev/null +++ b/docs/uk/plugins/memory-lancedb.md @@ -0,0 +1,274 @@ +--- +read_when: + - Ви налаштовуєте вбудований плагін memory-lancedb + - Вам потрібна довготривала пам’ять на базі LanceDB з автоматичним пригадуванням або автоматичним збереженням + - Ви використовуєте локальні ембединги, сумісні з OpenAI, наприклад Ollama +sidebarTitle: Memory LanceDB +summary: Налаштуйте вбудований плагін пам’яті LanceDB, включно з локальними ембедингами, сумісними з Ollama +title: Пам’ять LanceDB +x-i18n: + generated_at: "2026-04-28T00:03:39Z" + model: gpt-5.4 + provider: openai + source_hash: e3d0e1a286dfae36967a04863c047f40b629656efa62364c65e67283d3c7a945 + source_path: plugins/memory-lancedb.md + workflow: 15 +--- + +`memory-lancedb` — це вбудований плагін пам’яті, який зберігає довготривалу пам’ять у +LanceDB і використовує ембединги для пригадування. Він може автоматично +пригадувати релевантні спогади перед ходом моделі та фіксувати важливі факти +після відповіді. + +Використовуйте його, якщо вам потрібна локальна векторна база даних для пам’яті, +потрібна точка доступу до ембедингів, сумісна з OpenAI, або якщо ви хочете +зберігати базу даних пам’яті поза типовим вбудованим сховищем пам’яті. + + +`memory-lancedb` — це активний плагін пам’яті. Увімкніть його, вибравши слот +пам’яті через `plugins.slots.memory = "memory-lancedb"`. Супутні плагіни, такі як +`memory-wiki`, можуть працювати поруч із ним, але лише один плагін володіє +слотом Active Memory. + + +## Швидкий старт + +```json5 +{ + plugins: { + slots: { + memory: "memory-lancedb", + }, + entries: { + "memory-lancedb": { + enabled: true, + config: { + embedding: { + apiKey: "${OPENAI_API_KEY}", + model: "text-embedding-3-small", + }, + autoRecall: true, + autoCapture: false, + }, + }, + }, + }, +} +``` + +Перезапустіть Gateway після зміни конфігурації плагіна: + +```bash +openclaw gateway restart +``` + +Потім перевірте, що плагін завантажено: + +```bash +openclaw plugins list +``` + +## Ембединги Ollama + +`memory-lancedb` викликає ембединги через API ембедингів, сумісний з OpenAI. +Для ембедингів Ollama використовуйте тут endpoint сумісності Ollama `/v1`. Це +стосується лише ембедингів; провайдер чату/моделей Ollama використовує нативний +URL API Ollama, описаний у [Ollama](/uk/providers/ollama). + +```json5 +{ + plugins: { + slots: { + memory: "memory-lancedb", + }, + entries: { + "memory-lancedb": { + enabled: true, + config: { + embedding: { + apiKey: "ollama", + baseUrl: "http://127.0.0.1:11434/v1", + model: "mxbai-embed-large", + dimensions: 1024, + }, + recallMaxChars: 400, + autoRecall: true, + autoCapture: false, + }, + }, + }, + }, +} +``` + +Установіть `dimensions` для нестандартних моделей ембедингів. OpenClaw знає +розмірність для `text-embedding-3-small` і `text-embedding-3-large`; для +користувацьких моделей потрібно вказати це значення в конфігурації, щоб LanceDB +міг створити векторний стовпець. + +Для невеликих локальних моделей ембедингів зменште `recallMaxChars`, якщо +бачите помилки довжини контексту від локального сервера. + +## Обмеження пригадування та збереження + +`memory-lancedb` має два окремі текстові обмеження: + +| Налаштування | Типово | Діапазон | Застосовується до | +| ---------------- | ------- | --------- | --------------------------------------------- | +| `recallMaxChars` | `1000` | 100-10000 | тексту, надісланого до API ембедингів для пригадування | +| `captureMaxChars` | `500` | 100-10000 | довжини повідомлення асистента, придатної для збереження | + +`recallMaxChars` керує автоматичним пригадуванням, інструментом `memory_recall`, +шляхом запиту `memory_forget` і `openclaw ltm search`. Автоматичне пригадування +надає перевагу останньому повідомленню користувача в ході та повертається до +повного prompt лише тоді, коли повідомлення користувача недоступне. Це дозволяє +не включати метадані каналу й великі блоки prompt у запит на ембединг. + +`captureMaxChars` визначає, чи є відповідь достатньо короткою, щоб її можна було +розглядати для автоматичного збереження. Це не обмежує ембединги запитів для +пригадування. + +## Команди + +Коли `memory-lancedb` є активним плагіном пам’яті, він реєструє простір імен CLI +`ltm`: + +```bash +openclaw ltm list +openclaw ltm search "project preferences" +openclaw ltm stats +``` + +Агенти також отримують інструменти пам’яті LanceDB від активного плагіна пам’яті: + +- `memory_recall` для пригадування на базі LanceDB +- `memory_store` для збереження важливих фактів, уподобань, рішень і сутностей +- `memory_forget` для видалення відповідних спогадів + +## Сховище + +Типово дані LanceDB розміщуються в `~/.openclaw/memory/lancedb`. Щоб змінити +шлях, використайте `dbPath`: + +```json5 +{ + plugins: { + entries: { + "memory-lancedb": { + enabled: true, + config: { + dbPath: "~/.openclaw/memory/lancedb", + embedding: { + apiKey: "${OPENAI_API_KEY}", + model: "text-embedding-3-small", + }, + }, + }, + }, + }, +} +``` + +`storageOptions` приймає рядкові пари ключ/значення для бекендів сховища LanceDB +і підтримує розгортання `${ENV_VAR}`: + +```json5 +{ + plugins: { + entries: { + "memory-lancedb": { + enabled: true, + config: { + dbPath: "s3://memory-bucket/openclaw", + storageOptions: { + access_key: "${AWS_ACCESS_KEY_ID}", + secret_key: "${AWS_SECRET_ACCESS_KEY}", + endpoint: "${AWS_ENDPOINT_URL}", + }, + embedding: { + apiKey: "${OPENAI_API_KEY}", + model: "text-embedding-3-small", + }, + }, + }, + }, + }, +} +``` + +## Залежності середовища виконання + +`memory-lancedb` залежить від нативного пакета `@lancedb/lancedb`. Паковані +встановлення OpenClaw спочатку намагаються використати вбудовану залежність +середовища виконання та можуть відновити залежність середовища виконання плагіна +в стані OpenClaw, якщо вбудований імпорт недоступний. + +Якщо в старішому встановленні під час завантаження плагіна в журналі з’являється +помилка про відсутній `dist/package.json` або відсутній `@lancedb/lancedb`, +оновіть OpenClaw і перезапустіть Gateway. + +Якщо плагін журналює, що LanceDB недоступний на `darwin-x64`, використовуйте на +цій машині типовий бекенд пам’яті, перенесіть Gateway на підтримувану платформу +або вимкніть `memory-lancedb`. + +## Усунення проблем + +### Довжина вхідних даних перевищує довжину контексту + +Зазвичай це означає, що модель ембедингів відхилила запит на пригадування: + +```text +memory-lancedb: recall failed: Error: 400 the input length exceeds the context length +``` + +Установіть менше значення `recallMaxChars`, а потім перезапустіть Gateway: + +```json5 +{ + plugins: { + entries: { + "memory-lancedb": { + config: { + recallMaxChars: 400, + }, + }, + }, + }, +} +``` + +Для Ollama також перевірте, що сервер ембедингів доступний з хоста Gateway: + +```bash +curl http://127.0.0.1:11434/v1/embeddings \ + -H "Content-Type: application/json" \ + -d '{"model":"mxbai-embed-large","input":"hello"}' +``` + +### Непідтримувана модель ембедингів + +Без `dimensions` відомі лише вбудовані розмірності ембедингів OpenAI. Для +локальних або користувацьких моделей ембедингів установіть `embedding.dimensions` +у розмір вектора, який повідомляє ця модель. + +### Плагін завантажується, але спогади не з’являються + +Перевірте, що `plugins.slots.memory` вказує на `memory-lancedb`, а потім +виконайте: + +```bash +openclaw ltm stats +openclaw ltm search "recent preference" +``` + +Якщо `autoCapture` вимкнено, плагін пригадуватиме наявні спогади, але не +зберігатиме автоматично нові. Використовуйте інструмент `memory_store` або +увімкніть `autoCapture`, якщо хочете автоматичне збереження. + +## Пов’язані матеріали + +- [Огляд пам’яті](/uk/concepts/memory) +- [Active Memory](/uk/concepts/active-memory) +- [Пошук у пам’яті](/uk/concepts/memory-search) +- [Memory Wiki](/uk/plugins/memory-wiki) +- [Ollama](/uk/providers/ollama) diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 95ce6f5ca..0692b8826 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,311 +1,317 @@ --- read_when: - - Вибір правильного підшляху plugin-sdk для імпорту plugin - - Аудит підшляхів bundled-plugin і допоміжних поверхонь + - Вибір правильного підшляху plugin-sdk для імпорту Plugin + - Аудит підшляхів bundled-plugin і поверхонь допоміжних функцій summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-27T23:28:31Z" + generated_at: "2026-04-28T00:03:44Z" model: gpt-5.4 provider: openai - source_hash: 36691aa4951e8207e5d87b532e6a653cf50f9a1a74aaeaed289ef2f6778555bd + source_hash: 5a51833cc4d8136f4e432822f3fc27e38373784519cfcb7ce209dbe01fa0a325 source_path: plugins/sdk-subpaths.md workflow: 15 --- - Plugin SDK представлено як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - Ця сторінка каталогізує найуживаніші підшляхи, згруповані за призначенням. Згенерований - повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також з’являються там, але є - деталлю реалізації, якщо лише сторінка документації явно не просуває їх. + Plugin SDK представлений як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці наведено каталог поширених підшляхів, згрупованих за призначенням. Згенерований + повний список із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`; + зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями + реалізації, якщо лише певна сторінка документації явно не рекомендує їх. - Для посібника з розробки plugin див. [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Посібник з розробки Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). - ## Точка входу plugin + ## Точка входу Plugin - | Підшлях | Основні експорти | - | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | Публічні тестові фікстури plugin, допоміжні засоби реєстрації/каталогу провайдерів, хуки контрактів майстра та допоміжні засоби підтримки контрактів bundled-plugin | - | `plugin-sdk/plugin-test-api` | Мінімальний конструктор моків `OpenClawPluginApi` для прямих unit-тестів реєстрації plugin | - | `plugin-sdk/migration` | Допоміжні засоби елементів провайдера міграції, як-от `createMigrationItem`, константи причин, маркери стану елементів, засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби runtime для міграції, як-от `copyMigrationFileItem` і `writeMigrationReport` | + | Підшлях | Основні експорти | + | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/testing` | Публічні тестові фікстури Plugin, допоміжні функції реєстрації/каталогу провайдерів, хуки контрактів майстра та допоміжні функції підтримки контрактів bundled-plugin | + | `plugin-sdk/plugin-test-api` | Мінімальний конструктор мока `OpenClawPluginApi` для прямих модульних тестів реєстрації Plugin | + | `plugin-sdk/channel-test-helpers` | Допоміжні функції для тестування життєвого циклу облікового запису каналу, директорії, конфігурації надсилання, мока середовища виконання та хуків | + | `plugin-sdk/plugin-test-contracts` | Допоміжні функції контрактів для реєстрації Plugin, маніфесту пакета, публічного артефакту, API середовища виконання, побічного ефекту імпорту та прямого імпорту | + | `plugin-sdk/provider-test-contracts` | Допоміжні функції контрактів для середовища виконання провайдера, автентифікації, виявлення, онбордингу, каталогу, web-search/fetch і майстра | + | `plugin-sdk/migration` | Допоміжні функції елементів провайдера міграції, як-от `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні функції редагування та `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні функції міграції для середовища виконання, як-от `copyMigrationFileItem` і `writeMigrationReport` | - + | Підшлях | Основні експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, підказки списку дозволених, конструктори стану налаштування | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування, підказки allowlist, конструктори статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби конфігурації/контролю дій для багатьох облікових записів, допоміжні засоби резервного використання типового облікового запису | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного використання типового | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні функції конфігурації/шлюзу дій для кількох облікових записів, допоміжні функції резервного переходу до облікового запису за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації ідентифікатора облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису та резервного переходу до типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та універсальний конструктор | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та узагальнений конструктор | | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзування авторизації команд | + | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із резервною підтримкою bundled-contract | + | `plugin-sdk/command-gating` | Вузькі допоміжні функції шлюзу авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернетки | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних даних + побудови конверта | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей | - | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних даних для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби runtime для вихідної доставки, ідентичності, делегата надсилання, сесії, форматування та планування корисного навантаження | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор корисного навантаження медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби runtime для прив’язки розмов/потоків, pairing і налаштованих прив’язок | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби runtime для визначення групових політик | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні функції життєвого циклу/фіналізації чернеткового потоку | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршрутів вхідних повідомлень і конструктора envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису та диспетчеризації вхідних відповідей | + | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Легковаговий пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні функції доставки вихідних повідомлень, ідентичності, делегата надсилання, сесії, форматування та планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні функції нормалізації poll | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції життєвого циклу thread-binding і адаптера | + | `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа агента | + | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки conversation/thread, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція знімка конфігурації середовища виконання | + | `plugin-sdk/runtime-group-policy` | Допоміжні функції визначення group-policy для середовища виконання | + | `plugin-sdk/channel-status` | Спільні допоміжні функції знімка/зведення статусу каналу | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти plugin каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації списку дозволених | - | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби runtime для семантичного подання повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Подання повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Барель сумісності для debounce вхідних даних, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів конверта | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних даних | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні runtime вхідних даних | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування конверта вхідних даних | - | `plugin-sdk/channel-location` | Допоміжні засоби контексту розташування каналу та форматування | - | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналів для відкидання вхідних даних і збоїв typing/ack | + | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні допоміжні функції автентифікації/захисту direct-DM | + | `plugin-sdk/interactive-runtime` | Допоміжні функції семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Барель сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних функцій mention-policy та envelope | + | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні функції debounce вхідних повідомлень | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні функції mention-policy, маркерів згадок і тексту згадок без ширшої поверхні середовища виконання вхідних повідомлень | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні функції форматування вхідних envelope | + | `plugin-sdk/channel-location` | Допоміжні функції контексту та форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні функції логування каналу для відкидання вхідних повідомлень і збоїв typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби нативних схем, збережені для сумісності plugin | - | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контрактів каналів | - | `plugin-sdk/channel-feedback` | Підключення зворотного зв’язку/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-контрактів, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret-цілей | + | `plugin-sdk/channel-actions` | Допоміжні функції дій з повідомленнями каналу, а також застарілі допоміжні функції native schema, збережені для сумісності Plugin | + | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/channel-contract` | Типи контрактів каналу | + | `plugin-sdk/channel-feedback` | Зв’язування feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret | - + | Підшлях | Основні експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей runtime | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для типових локальних серверів, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення бекенда CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime для визначення API-ключів для plugin провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілів API-ключів, як-от `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний конструктор результатів OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugin провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища auth провайдера | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделі в середовищі виконання | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для типових параметрів локального сервера, виявлення моделей, заголовків запитів і допоміжних функцій для завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локального/self-hosted провайдера | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдера, сумісного з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції визначення API-key у середовищі виконання для Plugin провайдера | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу/запису профілю API-key, як-от `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату автентифікації OAuth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для Plugin провайдера | + | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку auth env var провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик replay, допоміжні засоби endpoint провайдерів та допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Хуки runtime каталогу провайдерів і шви реєстру plugin-провайдерів для тестів контрактів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні функції endpoint провайдера та допоміжні функції нормалізації model-id, як-от `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання каталогу провайдера та шви реєстру plugin-provider для контрактних тестів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/endpoint-можливостей провайдерів, помилки HTTP провайдерів і допоміжні засоби multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контрактів конфігурації/вибору web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення ввімкнення plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-засоби встановлення/отримання облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime провайдера web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей endpoint провайдера, помилки HTTP провайдера та допоміжні функції multipart form для аудіотранскрипції | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні функції контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешу провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні функції config/credential для web-search для провайдерів, яким не потрібне вбудовування enable Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні функції контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешу/середовища виконання провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні функції сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби runtime транспорту нативного провайдера, як-от guarded fetch, трансформації транспортних повідомлень і потоки записуваних транспортних подій | - | `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні функції wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні функції транспорту нативного провайдера, як-от guarded fetch, перетворення transport message і writable потоки transport event | + | `plugin-sdk/provider-onboard` | Допоміжні функції patch конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні функції singleton/map/cache, локальних для процесу | + | `plugin-sdk/group-activation` | Вузькі допоміжні функції режиму активації групи та розбору команд | - + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні функції авторизації відправника | | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Native адаптери можливостей/доставки approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway для approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native адаптера approval для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для обробника approval; віддавайте перевагу вужчим швам adapter/gateway, якщо їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native цілей approval + прив’язки облікових записів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби корисного навантаження відповіді для exec/plugin approval | - | `plugin-sdk/approval-runtime` | Допоміжні засоби корисного навантаження exec/plugin approval, native допоміжні засоби маршрутизації/runtime approval і структуровані допоміжні засоби відображення approval, як-от `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого тестового бареля | - | `plugin-sdk/command-auth-native` | Native auth команд, форматування меню динамічних аргументів і native допоміжні засоби session-target | - | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команд і поверхні команд | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції визначення затверджувача та автентифікації дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра затвердження native exec | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval | + | `plugin-sdk/approval-gateway-runtime` | Спільна допоміжна функція визначення Gateway approval | + | `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні функції завантаження адаптера native approval для гарячих точок входу каналу | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні функції середовища виконання approval handler; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілі native approval + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді для затвердження exec/Plugin | + | `plugin-sdk/approval-runtime` | Допоміжні функції payload затвердження exec/Plugin, допоміжні функції маршрутизації/середовища виконання native approval і допоміжні функції структурованого відображення approval, як-от `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні функції скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні функції тестування контрактів каналу без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні функції native session-target | + | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | + | `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналу | + | `plugin-sdk/command-surface` | Допоміжні функції нормалізації command-body і command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-контрактів для secret-поверхонь каналів/plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби типізації `coerceSecretRef` і SecretRef для парсингу secret-контрактів/конфігурації | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | - | `plugin-sdk/ssrf-dispatcher` | Вузькі pinned-dispatcher допоміжні засоби без широкої інфраструктурної runtime-поверхні | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, SSRF-захищеного fetch, помилок SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби парсингу secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції збирання secret-contract для поверхонь secret каналу/Plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні функції `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні функції trust, DM gating, external-content, редагування чутливого тексту, порівняння secret за сталий час і збирання secret | + | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватної мережі | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні функції pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF, помилки SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні функції розбору secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі Webhook і приведення raw websocket/body | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру body/timeout запиту | - + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, парсингу URL CDP і допоміжних засобів auth керування браузером | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | + | `plugin-sdk/runtime` | Широкі допоміжні функції середовища виконання/логування/резервного копіювання/встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env середовища виконання, logger, timeout, retry і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних функцій автентифікації browser-control | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні функції реєстрації та пошуку runtime-context каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy імпорту/runtime-прив’язки, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версії, виклику аргументів і lazy груп команд | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway, Gateway CLI RPC, помилок протоколу Gateway і patch стану каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації plugin, як-от `OpenClawConfig` і типів конфігурації каналів/провайдерів | - | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації plugin у runtime, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і сетери тестових знімків | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого бареля text-runtime | - | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, конструктори можливостей approval, допоміжні засоби auth/профілів, native допоміжні засоби маршрутизації/runtime і форматування шляху структурованого відображення approval | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних даних/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей і ярликів розмов | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби історії відповідей короткого вікна та маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції команд/хуків/http/interactive Plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні функції конвеєра Webhook/внутрішніх хуків | + | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy import/binding середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні функції exec процесу | + | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, wait, version, invocation аргументів і lazy command-group | + | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway, CLI RPC Gateway, помилок протоколу Gateway та patch статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig` і типів конфігурації каналу/провайдера | + | `plugin-sdk/plugin-config-runtime` | Допоміжні функції пошуку plugin-config у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні функції транзакційної мутації конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні функції знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setters знімків для тестів | + | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації назв/описів команд Telegram і перевірок дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Допоміжні функції затвердження exec/Plugin, конструктори approval-capability, допоміжні функції auth/profile, допоміжні функції native routing/runtime і форматування структурованого шляху відображення approval | + | `plugin-sdk/reply-runtime` | Спільні допоміжні функції середовища виконання для вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize відповідей і conversation-label | + | `plugin-sdk/reply-history` | Спільні допоміжні функції та маркери історії відповідей для короткого вікна, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, `updated-at` і мутації сховища | - | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумків стану каналів/облікових записів, типові значення runtime-state і допоміжні засоби метаданих issue | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних входів | - | `plugin-sdk/run-command` | Виконувач команд із таймінгом і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool | - | `plugin-sdk/tool-send` | Витягування канонічних полів цілей надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби логера підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації talk-провайдера | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON-стану | - | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного блокування файлів | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового кешу дедуплікації | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесії ACP і dispatch відповідей | - | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації native команд | - | `plugin-sdk/agent-harness` | Експериментальна trusted-plugin поверхня для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики runtime-plan tool, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | - | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів runtime-стану | - | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | - | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності async-задач | - | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | - | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб спорожнення черги очікуваної вихідної доставки | - | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів локальних файлів і джерел медіа | - | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | - | `plugin-sdk/number-runtime` | Допоміжний засіб числового приведення | - | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | - | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | - | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте вищенаведені сфокусовані runtime-підшляхи | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби прапорів діагностики, подій і trace-context | - | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні функції шляху сховища сесій, session-key, updated-at і мутації сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні функції шляху/load/save сховища Cron | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів директорій state/OAuth | + | `plugin-sdk/routing` | Допоміжні функції маршруту/ключа сесії/прив’язки облікового запису, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні функції зведення статусу каналу/облікового запису, типові значення runtime-state і допоміжні функції метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції target resolver | + | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витягування рядкових URL із вхідних даних типу fetch/request | + | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні функції logger підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму та конвертації таблиць Markdown | + | `plugin-sdk/model-session-runtime` | Допоміжні функції перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні функції визначення конфігурації провайдера talk | + | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні функції реентерабельного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні функції кешу дедуплікації на диску | + | `plugin-sdk/acp-runtime` | Допоміжні функції середовища виконання/сесії ACP і dispatch відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації середовища виконання агента | + | `plugin-sdk/boolean-param` | Читач вільного boolean параметра | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні функції початкової ініціалізації пристрою та pairing token | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних функцій passive-channel, статусу й ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні функції відповідей команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні функції списку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні функції steer/abort активного запуску, допоміжні функції мосту інструментів OpenClaw, допоміжні функції політики tool для runtime-plan, класифікація результатів terminal, допоміжні функції форматування/деталізації прогресу tool і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.A.I | + | `plugin-sdk/async-lock-runtime` | Допоміжна функція локального для процесу async lock для невеликих файлів runtime state | + | `plugin-sdk/channel-activity-runtime` | Допоміжна функція telemetry активності каналу | + | `plugin-sdk/concurrency-runtime` | Допоміжна функція обмеженої конкурентності async задач | + | `plugin-sdk/dedupe-runtime` | Допоміжні функції кешу дедуплікації в пам’яті | + | `plugin-sdk/delivery-queue-runtime` | Допоміжна функція drain черги очікуваної вихідної доставки | + | `plugin-sdk/file-access-runtime` | Допоміжні функції безпечних шляхів до локальних файлів і джерел медіа | + | `plugin-sdk/heartbeat-runtime` | Допоміжні функції подій і видимості Heartbeat | + | `plugin-sdk/number-runtime` | Допоміжна функція приведення чисел | + | `plugin-sdk/secure-random-runtime` | Допоміжні функції безпечних token/UUID | + | `plugin-sdk/system-event-runtime` | Допоміжні функції черги системних подій | + | `plugin-sdk/transport-ready-runtime` | Допоміжна функція очікування готовності транспорту | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи середовища виконання | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні функції прапорців, подій і trace-context діагностики | + | `plugin-sdk/error-runtime` | Допоміжні функції графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch, proxy і pinned lookup | | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Допоміжний засіб читання тіла відповіді з обмеженням без широкої media runtime-поверхні | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування конфігурації | - | `plugin-sdk/context-visibility-runtime` | Допоміжні засоби визначення видимості контексту та фільтрації додаткового контексту без широких імпортів конфігурації/безпеки | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконувача retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/response-limit-runtime` | Читач обмеженого response body без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації configured binding або pairing stores | + | `plugin-sdk/session-store-runtime` | Допоміжні функції session-store без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні функції приведення й нормалізації primitive record/string без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і хоста SCP | + | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні функції директорії/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/dedup директорії на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори корисного навантаження медіа | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, як-от `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, як-от видалення тексту, видимого асистенту, допоміжні засоби рендерингу/chunking/таблиць markdown, засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів експорти директив, реєстру, валідації та допоміжних засобів мовлення | - | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, реєстр, директиви, нормалізація та експорти допоміжних засобів мовлення | - | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера та парсинг model-ref | - | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера та парсинг model-ref | - | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа, а також конструктори payload медіа | + | `plugin-sdk/media-store` | Вузькі допоміжні функції media store, як-от `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також експорти допоміжних функцій для зображень/аудіо, орієнтованих на провайдера | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції text/markdown/logging, як-от видалення видимого для асистента тексту, допоміжні функції render/chunking/table для Markdown, допоміжні функції редагування, допоміжні функції тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдера speech, а також експорти допоміжних функцій директив, реєстру, валідації та speech, орієнтованих на провайдера | + | `plugin-sdk/speech-core` | Спільні типи провайдера speech, а також експорти допоміжних функцій реєстру, директив, нормалізації та speech | + | `plugin-sdk/realtime-transcription` | Типи провайдера realtime transcription, допоміжні функції реєстру та спільна допоміжна функція сесії WebSocket | + | `plugin-sdk/realtime-voice` | Типи провайдера realtime voice і допоміжні функції реєстру | + | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні функції failover, auth і реєстру | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/webhook-targets` | Допоміжні функції реєстру цілей Webhook і встановлення маршруту | + | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Публічні допоміжні засоби тестування extension, включно з моками реєстру/runtime plugin, захопленням реєстрації провайдерів, допоміжними засобами майстра налаштування, фікстурами fetch/env/temp/time, допоміжними засобами schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні засоби extension `*.test-support.ts` мають лишатися тут або у сфокусованих підшляхах SDK, а не у внутрішніх модулях core | - | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для прямих unit-тестів реєстрації plugin без імпорту мостів repo test helper | + | `plugin-sdk/testing` | Публічні допоміжні функції тестування extension, включно з моками реєстру/runtime Plugin, захопленням реєстрації провайдера, допоміжними функціями майстра налаштування, фікстурами fetch/env/temp/time, допоміжними функціями schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні функції extension `*.test-support.ts` мають залишатися тут або на сфокусованих підшляхах SDK, а не в core internals | + | `plugin-sdk/plugin-test-api` | Мінімальна допоміжна функція `createTestPluginApi` для прямих модульних тестів реєстрації Plugin без імпорту містків допоміжних функцій тестування репозиторію | + | `plugin-sdk/channel-test-helpers` | Орієнтовані на канал допоміжні функції тестування для життєвого циклу запуску облікового запису, перевірок директорії, threading конфігурації надсилання, моків runtime, проблем статусу, вихідної доставки та реєстрації хуків | + | `plugin-sdk/plugin-test-contracts` | Допоміжні функції контрактів для пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, API runtime та побічного ефекту імпорту | + | `plugin-sdk/provider-test-contracts` | Допоміжні функції контрактів для runtime провайдера, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream | - + | Підшлях | Основні експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/допоміжних засобів CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embeddings хоста пам’яті, доступ до реєстру, локальний провайдер і загальні допоміжні засоби batch/remote | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | - | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | + | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для менеджера/конфігурації/файлів/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання індексу/пошуку Memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний провайдер і загальні допоміжні функції batch/remote | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста Memory | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції query хоста Memory | + | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста Memory | + | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста Memory | + | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста Memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції CLI runtime хоста Memory | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста Memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста Memory | + | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для допоміжних функцій core runtime хоста Memory | + | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для допоміжних функцій журналу подій хоста Memory | + | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для допоміжних функцій файлів/runtime хоста Memory | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції managed-markdown для plugin, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад середовища виконання Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для допоміжних функцій статусу хоста Memory | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb | - | Сімейство | Поточні підшляхи | Призначене використання | + | Family | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` лишається барелем сумісності. | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних засобів bundled channel. Нові plugin мають імпортувати універсальні підшляхи SDK або локальні барелі plugin. | - | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних функцій/runtime bundled Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime bundled LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій bundled IRC | + | Допоміжні функції для конкретних каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних функцій bundled channel. Нові plugins мають імпортувати загальні підшляхи SDK або локальні barrel модуля plugin. | + | Допоміжні функції auth/plugin для конкретних сценаріїв | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних функцій bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | @@ -313,4 +319,4 @@ x-i18n: - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugin](/uk/plugins/building-plugins) +- [Створення plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/sdk-testing.md b/docs/uk/plugins/sdk-testing.md index c2e954d9c..e79d5191b 100644 --- a/docs/uk/plugins/sdk-testing.md +++ b/docs/uk/plugins/sdk-testing.md @@ -1,37 +1,43 @@ --- read_when: - - Ви пишете тести для плагіна - - Вам потрібні утиліти тестування з SDK плагіна - - Ви хочете зрозуміти контрактні тести для вбудованих плагінів + - Ви пишете тести для Plugin + - Вам потрібні утиліти тестування з SDK Plugin + - Ви хочете зрозуміти контрактні тести для вбудованих Plugin sidebarTitle: Testing -summary: Утиліти та шаблони тестування для плагінів OpenClaw -title: Тестування плагінів +summary: Утиліти та шаблони тестування для Plugin OpenClaw +title: Тестування Plugin x-i18n: - generated_at: "2026-04-27T23:28:28Z" + generated_at: "2026-04-28T00:03:38Z" model: gpt-5.4 provider: openai - source_hash: e68bd201689490e9b42c8511fc205e5a14383c56e534270692cf3b21d0758e40 + source_hash: 2c2aa1506f6f115168c980d76785db6b8531c6565219ac07b35f43319b0a5bbd source_path: plugins/sdk-testing.md workflow: 15 --- -Довідник з утиліт тестування, шаблонів і примусового застосування lint-правил для плагінів OpenClaw. +Довідник з утиліт тестування, шаблонів і примусового застосування lint для Plugin OpenClaw. **Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів: - [Тести плагінів каналів](/uk/plugins/sdk-channel-plugins#step-6-test) і - [Тести плагінів провайдерів](/uk/plugins/sdk-provider-plugins#step-6-test). + [Тести Plugin каналу](/uk/plugins/sdk-channel-plugins#step-6-test) і + [Тести Plugin провайдера](/uk/plugins/sdk-provider-plugins#step-6-test). ## Утиліти тестування **Загальний імпорт:** `openclaw/plugin-sdk/testing` -**Імпорт моків Plugin API:** `openclaw/plugin-sdk/plugin-test-api` +**Імпорт мока API Plugin:** `openclaw/plugin-sdk/plugin-test-api` -**Імпорт контрактів каналів:** `openclaw/plugin-sdk/channel-contract-testing` +**Імпорт контракту каналу:** `openclaw/plugin-sdk/channel-contract-testing` -Підшлях testing експортує вузький набір допоміжних засобів для авторів плагінів: +**Імпорт допоміжного засобу тестування каналу:** `openclaw/plugin-sdk/channel-test-helpers` + +**Імпорт контракту Plugin:** `openclaw/plugin-sdk/plugin-test-contracts` + +**Імпорт контракту провайдера:** `openclaw/plugin-sdk/provider-test-contracts` + +Підшлях testing експортує вузький набір допоміжних засобів для авторів Plugin: ```typescript import { @@ -41,48 +47,59 @@ import { } from "openclaw/plugin-sdk/testing"; import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api"; import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing"; +import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers"; +import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts"; +import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts"; ``` ### Доступні експорти -| Export | Призначення | +| Export | Purpose | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `createTestPluginApi` | Створює мінімальний мок plugin API для прямих unit-тестів реєстрації. Імпортується з `plugin-sdk/plugin-test-api` | -| `expectChannelInboundContextContract` | Перевіряє форму вхідного контексту каналу. Імпортується з `plugin-sdk/channel-contract-testing` | -| `installChannelOutboundPayloadContractSuite` | Додає набір контрактних перевірок для вихідного payload каналу. Імпортується з `plugin-sdk/channel-contract-testing` | +| `createTestPluginApi` | Побудувати мінімальний мок API Plugin для прямих модульних тестів реєстрації. Імпортуйте з `plugin-sdk/plugin-test-api` | +| `expectChannelInboundContextContract` | Перевірити форму вхідного контексту каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `installChannelOutboundPayloadContractSuite` | Встановити набір контрактних випадків для вихідного payload каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `createStartAccountContext` | Побудувати контексти життєвого циклу облікового запису каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `describePluginRegistrationContract` | Встановити перевірки контракту реєстрації Plugin. Імпортуйте з `plugin-sdk/plugin-test-contracts` | +| `describeOpenAIProviderRuntimeContract` | Встановити перевірки контракту середовища виконання для сімейства провайдерів. Імпортуйте з `plugin-sdk/provider-test-contracts` | | `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок під час визначення цілі | -| `shouldAckReaction` | Перевіряє, чи має канал додавати реакцію підтвердження | -| `removeAckReactionAfterReply` | Видаляє реакцію підтвердження після доставки відповіді | -| `createTestRegistry` | Створює тестову фікстуру реєстру плагінів каналів | -| `createEmptyPluginRegistry` | Створює порожню тестову фікстуру реєстру плагінів | -| `setActivePluginRegistry` | Встановлює фікстуру реєстру для runtime-тестів плагінів | -| `createRequestCaptureJsonFetch` | Перехоплює JSON-запити fetch у тестах медіадопоміжних засобів | -| `withFetchPreconnect` | Запускає тести fetch із встановленими хуками preconnect | -| `withEnv` / `withEnvAsync` | Тимчасово змінює змінні середовища | -| `createTempHomeEnv` / `withTempDir` | Створює ізольовані файлові тестові фікстури | -| `createMockServerResponse` | Створює мінімальний мок HTTP-відповіді сервера | -| `registerSingleProviderPlugin` | Реєструє один плагін провайдера в smoke-тестах завантажувача | -| `registerProviderPlugin` | Збирає всі типи провайдерів з одного плагіна | -| `registerProviderPlugins` | Збирає реєстрації провайдерів з кількох плагінів | -| `requireRegisteredProvider` | Перевіряє, що колекція провайдерів містить id | -| `runProviderCatalog` | Виконує хук каталогу провайдера з тестовими залежностями | -| `resolveProviderWizardOptions` | Визначає варіанти майстра налаштування провайдера в контрактних тестах | -| `resolveProviderModelPickerEntries` | Визначає елементи вибору моделей провайдера в контрактних тестах | -| `buildProviderPluginMethodChoice` | Створює id варіантів майстра провайдера для перевірок | -| `setProviderWizardProvidersResolverForTest` | Впроваджує провайдери майстра для ізольованих тестів | -| `createProviderUsageFetch` | Створює фікстури fetch для використання провайдера | -| `useFrozenTime` / `useRealTime` | Заморожує та відновлює таймери для чутливих до часу тестів | -| `createRuntimeEnv` | Створює змокане CLI/runtime-середовище плагіна | -| `createTestWizardPrompter` | Створює змоканий prompter майстра налаштування | -| `createPluginSetupWizardStatus` | Створює допоміжні засоби стану налаштування для плагінів каналів | -| `createRuntimeTaskFlow` | Створює ізольований стан runtime TaskFlow | -| `typedCases` | Зберігає літеральні типи для табличних тестів | +| `shouldAckReaction` | Перевірити, чи має канал додавати реакцію підтвердження | +| `removeAckReactionAfterReply` | Видалити реакцію підтвердження після доставки відповіді | +| `createTestRegistry` | Побудувати фікстуру реєстру Plugin каналу | +| `createEmptyPluginRegistry` | Побудувати порожню фікстуру реєстру Plugin | +| `setActivePluginRegistry` | Встановити фікстуру реєстру для тестів середовища виконання Plugin | +| `createRequestCaptureJsonFetch` | Перехоплювати JSON-запити fetch у тестах допоміжних засобів для медіа | +| `withFetchPreconnect` | Запускати тести fetch з установленими хуками preconnect | +| `withEnv` / `withEnvAsync` | Тимчасово підміняти змінні середовища | +| `createTempHomeEnv` / `withTempDir` | Створювати ізольовані файлові фікстури для тестів | +| `createMockServerResponse` | Створювати мінімальний мок відповіді HTTP-сервера | +| `registerSingleProviderPlugin` | Реєструвати один Plugin провайдера в smoke-тестах завантажувача | +| `registerProviderPlugin` | Захоплювати всі типи провайдерів з одного Plugin | +| `registerProviderPlugins` | Захоплювати реєстрації провайдерів у кількох Plugin | +| `requireRegisteredProvider` | Перевіряти, що колекція провайдерів містить ідентифікатор | +| `runProviderCatalog` | Виконувати хук каталогу провайдера з тестовими залежностями | +| `resolveProviderWizardOptions` | Визначати варіанти майстра налаштування провайдера в контрактних тестах | +| `resolveProviderModelPickerEntries` | Визначати елементи засобу вибору моделей провайдера в контрактних тестах | +| `buildProviderPluginMethodChoice` | Будувати ідентифікатори варіантів майстра провайдера для перевірок | +| `setProviderWizardProvidersResolverForTest` | Впроваджувати провайдерів майстра провайдера для ізольованих тестів | +| `createProviderUsageFetch` | Побудувати фікстури fetch для використання провайдера | +| `useFrozenTime` / `useRealTime` | Заморожувати й відновлювати таймери для тестів, чутливих до часу | +| `createRuntimeEnv` | Побудувати змокане середовище виконання CLI/Plugin | +| `createTestWizardPrompter` | Побудувати змоканий prompter майстра налаштування | +| `createPluginSetupWizardStatus` | Побудувати допоміжні засоби стану налаштування для Plugin каналу | +| `createRuntimeTaskFlow` | Створювати ізольований стан виконання TaskFlow | +| `typedCases` | Зберігати literal-типи для таблично-керованих тестів | -Контрактні набори тестів для вбудованих плагінів також використовують підшляхи SDK testing для тестових допоміжних засобів реєстру, маніфесту, публічних артефактів і runtime-фікстур. Нові тести розширень мають використовувати `openclaw/plugin-sdk/testing` або вужчий задокументований підшлях SDK, як-от `plugin-sdk/plugin-test-api` чи `plugin-sdk/channel-contract-testing`, замість прямого імпорту файлів `src/**` із репозиторію. +Набори контрактних тестів для вбудованих Plugin також використовують підшляхи SDK testing для допоміжних засобів фікстур реєстру, маніфесту, публічного артефакту та середовища виконання, призначених лише для тестів. Набори лише для core, які залежать від інвентаря вбудованого OpenClaw, залишаються в `src/plugins/contracts`. +Нові тести розширень слід тримати на `openclaw/plugin-sdk/testing` або в більш вузькому +задокументованому підшляху SDK, як-от `plugin-sdk/plugin-test-api` або +`plugin-sdk/channel-contract-testing`, `plugin-sdk/channel-test-helpers`, +`plugin-sdk/plugin-test-contracts` чи `plugin-sdk/provider-test-contracts`, +а не імпортувати безпосередньо файли репозиторію `src/**` або мости репозиторію `test/helpers/plugins/*`. ### Типи -Підшлях testing також повторно експортує типи, корисні у тестових файлах: +Підшлях testing також повторно експортує типи, корисні у файлах тестів: ```typescript import type { @@ -97,7 +114,8 @@ import type { ## Тестування визначення цілі -Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для визначення цілі каналу: +Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для +визначення цілі каналу: ```typescript import { describe } from "vitest"; @@ -123,17 +141,24 @@ describe("my-channel target resolution", () => { ### Тестування контрактів реєстрації -Unit-тести, які передають вручну написаний мок `api` до `register(api)`, не перевіряють умови прийняття завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі завантажувача для кожної поверхні реєстрації, від якої залежить ваш плагін, особливо для хуків та ексклюзивних можливостей, таких як пам’ять. +Модульні тести, які передають власноруч написаний мок `api` у `register(api)`, не перевіряють +шлюзи приймання завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі завантажувача +для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для хуків і +ексклюзивних можливостей, таких як пам’ять. -Справжній завантажувач завершує реєстрацію плагіна з помилкою, якщо бракує обов’язкових метаданих або якщо плагін викликає API можливості, якою не володіє. Наприклад, -`api.registerHook(...)` потребує назви хука, а -`api.registerMemoryCapability(...)` вимагає, щоб маніфест плагіна або експортована точка входу оголошували `kind: "memory"`. +Справжній завантажувач не допускає реєстрацію Plugin, якщо бракує обов’язкових метаданих або якщо +Plugin викликає API можливості, якою він не володіє. Наприклад, +`api.registerHook(...)` вимагає ім’я хука, а +`api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортована точка входу оголошували `kind: "memory"`. -### Тестування доступу до runtime-конфігурації +### Тестування доступу до конфігурації середовища виконання -Під час тестування вбудованих плагінів віддавайте перевагу спільному моку runtime плагіна з допоміжних засобів тестування репозиторію. Його застарілі моки `runtime.config.loadConfig()` і `runtime.config.writeConfigFile(...)` за замовчуванням викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці моки лише тоді, коли тест явно покриває застарілу поведінку сумісності. +Для тестування вбудованих Plugin каналів надавайте перевагу спільному моку середовища виконання Plugin з `openclaw/plugin-sdk/channel-test-helpers`. Його застарілі моки `runtime.config.loadConfig()` і +`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилки, щоб тести виявляли нове +використання API сумісності. Перевизначайте ці моки лише тоді, коли тест +явно покриває застарілу поведінку сумісності. -### Unit-тестування плагіна каналу +### Модульне тестування Plugin каналу ```typescript import { describe, it, expect, vi } from "vitest"; @@ -169,7 +194,7 @@ describe("my-channel plugin", () => { }); ``` -### Unit-тестування плагіна провайдера +### Модульне тестування Plugin провайдера ```typescript import { describe, it, expect } from "vitest"; @@ -197,9 +222,9 @@ describe("my-provider plugin", () => { }); ``` -### Мокання runtime плагіна +### Мокання середовища виконання Plugin -Для коду, який використовує `createPluginRuntimeStore`, замокуйте runtime у тестах: +Для коду, який використовує `createPluginRuntimeStore`, змокуйте середовище виконання в тестах: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -230,9 +255,9 @@ store.setRuntime(mockRuntime); store.clearRuntime(); ``` -### Тестування з окремими стабами для екземплярів +### Тестування з підмінами для окремих екземплярів -Віддавайте перевагу окремим стабам для екземплярів замість мутації прототипу: +Надавайте перевагу підмінам для окремих екземплярів замість мутації прототипу: ```typescript // Preferred: per-instance stub @@ -243,9 +268,9 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // MyChannelClient.prototype.sendMessage = vi.fn(); ``` -## Контрактні тести (плагіни в репозиторії) +## Контрактні тести (Plugin у репозиторії) -Вбудовані плагіни мають контрактні тести, які перевіряють належність реєстрації: +Вбудовані Plugin мають контрактні тести, які перевіряють належність реєстрації: ```bash pnpm test -- src/plugins/contracts/ @@ -253,14 +278,14 @@ pnpm test -- src/plugins/contracts/ Ці тести перевіряють: -- Які плагіни реєструють які провайдери -- Які плагіни реєструють які мовленнєві провайдери +- Які Plugin реєструють які провайдери +- Які Plugin реєструють які мовленнєві провайдери - Коректність форми реєстрації -- Відповідність runtime-контракту +- Відповідність контракту середовища виконання -### Запуск тестів для окремої області +### Запуск тестів з обмеженою областю -Для конкретного плагіна: +Для конкретного Plugin: ```bash pnpm test -- /my-channel/ @@ -274,20 +299,20 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Примусове застосування lint-правил (плагіни в репозиторії) +## Примусове застосування lint (Plugin у репозиторії) -Три правила застосовуються через `pnpm check` для плагінів у репозиторії: +`pnpm check` примусово застосовує три правила для Plugin у репозиторії: -1. **Жодних монолітних кореневих імпортів** -- кореневий barrel `openclaw/plugin-sdk` заборонений -2. **Жодних прямих імпортів із `src/`** -- плагіни не можуть напряму імпортувати `../../src/` -3. **Жодних self-imports** -- плагіни не можуть імпортувати власний підшлях `plugin-sdk/` +1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` заборонено +2. **Без прямих імпортів із `src/`** -- Plugin не можуть імпортувати `../../src/` напряму +3. **Без самоімпортів** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` -Зовнішні плагіни не підпадають під ці lint-правила, але дотримуватися тих самих +Зовнішні Plugin не підпадають під дію цих правил lint, але дотримуватися тих самих шаблонів рекомендується. ## Конфігурація тестування -OpenClaw використовує Vitest із порогами покриття V8. Для тестів плагінів: +OpenClaw використовує Vitest із порогами покриття V8. Для тестів Plugin: ```bash # Run all tests @@ -303,7 +328,7 @@ pnpm test -- /my-channel/ -t "resolves account" pnpm test:coverage ``` -Якщо локальні запуски спричиняють нестачу пам’яті: +Якщо локальні запуски спричиняють навантаження на пам’ять: ```bash OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test @@ -311,7 +336,7 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ## Пов’язане -- [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту -- [Плагіни каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс плагіна каналу -- [Плагіни провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- хуки плагіна провайдера -- [Створення плагінів](/uk/plugins/building-plugins) -- посібник для початку роботи +- [Огляд SDK](/uk/plugins/sdk-overview) -- угоди щодо імпорту +- [Plugin каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс Plugin каналу +- [Plugin провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- хуки Plugin провайдера +- [Створення Plugin](/uk/plugins/building-plugins) -- посібник для початку роботи diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 696d0471c..c5cd2bf40 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,46 +1,46 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете використовувати автентифікацію через підписку Codex замість ключів API - - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використовуйте OpenAI через ключі API або підписку Codex в OpenClaw + - Ви хочете автентифікацію через підписку Codex замість API-ключів + - Вам потрібні суворіші правила виконання агента GPT-5 +summary: Використовуйте OpenAI через API-ключі або підписку Codex у OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-27T14:20:48Z" + generated_at: "2026-04-28T00:03:38Z" model: gpt-5.4 provider: openai - source_hash: f6a33485bb8372dca81d91d35a4fddca315613336adf601efa7ef9a418bf8480 + source_hash: b9cce8535a4ed5991fc931783daa8908fd2ba1e6e183ea5bcbbcffcfad9f76bd source_path: providers/openai.md workflow: 15 --- OpenAI надає API для розробників для моделей GPT, а Codex також доступний як -агент для програмування в плані ChatGPT через клієнти Codex від OpenAI. OpenClaw зберігає ці +агент для програмування в планах ChatGPT через клієнти Codex від OpenAI. OpenClaw зберігає ці поверхні окремими, щоб конфігурація залишалася передбачуваною. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає -маршрут provider/auth; окремий параметр runtime визначає, хто виконує +маршрут провайдера/автентифікації; окреме налаштування середовища виконання визначає, хто виконує вбудований цикл агента: -- **Ключ API** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) -- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`) -- **Codex app-server harness** — нативне виконання Codex app-server (моделі `openai/*` плюс `agents.defaults.agentRuntime.id: "codex"`) +- **API-ключ** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` models) +- **Підписка Codex через PI** — вхід через ChatGPT/Codex з доступом за підпискою (`openai-codex/*` models) +- **Обв’язка app-server Codex** — нативне виконання через app-server Codex (`openai/*` models плюс `agents.defaults.agentRuntime.id: "codex"`) -OpenAI явно підтримує використання subscription OAuth у зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах, як-от OpenClaw. -Provider, модель, runtime і канал — це окремі рівні. Якщо ці назви -плутаються між собою, прочитайте [Agent runtimes](/uk/concepts/agent-runtimes) перед -зміною конфігурації. +Провайдер, модель, середовище виконання та канал — це окремі рівні. Якщо ці позначення +почали змішуватися, прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes), перш ніж +змінювати конфігурацію. ## Швидкий вибір -| Ціль | Використовуйте | Примітки | -| --------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- | -| Прямий білінг за ключем API | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або виконайте онбординг OpenAI з ключем API. | -| GPT-5.5 з автентифікацією за підпискою ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій із підпискою. | -| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово використовує Codex app-server harness для цього посилання на модель. | -| Генерація або редагування зображень | `openai/gpt-image-2` | Працює або з `OPENAI_API_KEY`, або з OpenAI Codex OAuth. | -| Зображення з прозорим тлом | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | +| Мета | Використовуйте | Примітки | +| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | +| Пряма тарифікація за API-ключем | `openai/gpt-5.5` | Установіть `OPENAI_API_KEY` або запустіть налаштування OpenAI API key. | +| GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій з підпискою. | +| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `agentRuntime.id: "codex"` | Примусово використовує обв’язку app-server Codex для цього посилання на модель. | +| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. | +| Зображення з прозорим фоном | `openai/gpt-image-1.5` | Використовуйте `outputFormat=png` або `webp` і `openai.background=transparent`. | ## Карта назв @@ -48,55 +48,55 @@ Provider, модель, runtime і канал — це окремі рівні. | Назва, яку ви бачите | Рівень | Значення | | --------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------- | -| `openai` | Префікс provider | Прямий маршрут API OpenAI Platform. | -| `openai-codex` | Префікс provider | Маршрут OpenAI Codex OAuth/підписки через звичайний runner PI OpenClaw. | -| `codex` plugin | Plugin | Вбудований Plugin OpenClaw, який надає нативний runtime Codex app-server і елементи керування чатом `/codex`. | -| `agentRuntime.id: codex` | Agent runtime | Примусово використовувати нативний Codex app-server harness для вбудованих ходів. | -| `/codex ...` | Набір команд чату | Прив’язка/керування потоками Codex app-server із розмови. | -| `runtime: "acp", agentId: "codex"` | Маршрут сеансу ACP | Явний резервний маршрут, який запускає Codex через ACP/acpx. | +| `openai` | Префікс провайдера | Прямий маршрут API OpenAI Platform. | +| `openai-codex` | Префікс провайдера | Маршрут OpenAI Codex OAuth/підписки через звичайний runner PI OpenClaw. | +| `codex` plugin | Plugin | Вбудований Plugin OpenClaw, який надає нативне середовище виконання app-server Codex і елементи керування чатом `/codex`. | +| `agentRuntime.id: codex` | Середовище виконання агента | Примусово використовує нативну обв’язку app-server Codex для вбудованих ходів. | +| `/codex ...` | Набір команд чату | Прив’язує/керує потоками app-server Codex із розмови. | +| `runtime: "acp", agentId: "codex"` | Маршрут сесії ACP | Явний резервний шлях, який запускає Codex через ACP/acpx. | Це означає, що конфігурація може навмисно містити і `openai-codex/*`, і -plugin `codex`. Це правильно, якщо ви хочете Codex OAuth через PI і також хочете, -щоб були доступні нативні елементи керування чатом `/codex`. `openclaw doctor` попереджає про таку +`codex` plugin. Це коректно, якщо ви хочете Codex OAuth через PI і водночас +хочете, щоб були доступні нативні елементи керування чатом `/codex`. `openclaw doctor` попереджає про таку комбінацію, щоб ви могли підтвердити, що вона навмисна; він її не переписує. -GPT-5.5 доступна як через прямий доступ за ключем API OpenAI Platform, так і -через маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку -через `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для Codex OAuth через PI, або -`openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативного -Codex app-server harness. +GPT-5.5 доступна як через прямий доступ до OpenAI Platform API за API-ключем, так і через +маршрути підписки/OAuth. Використовуйте `openai/gpt-5.5` для прямого трафіку +через `OPENAI_API_KEY`, `openai-codex/gpt-5.5` для Codex OAuth через PI або +`openai/gpt-5.5` з `agentRuntime.id: "codex"` для нативної +обв’язки app-server Codex. Увімкнення plugin OpenAI або вибір моделі `openai-codex/*` не -вмикає вбудований plugin Codex app-server. OpenClaw вмикає цей plugin лише -коли ви явно вибираєте нативний Codex harness через +вмикає вбудований plugin app-server Codex. OpenClaw вмикає цей plugin лише +коли ви явно вибираєте нативну обв’язку Codex за допомогою `agentRuntime.id: "codex"` або використовуєте застаріле посилання на модель `codex/*`. -Якщо вбудований plugin `codex` увімкнено, але `openai-codex/*` усе ще визначається -через PI, `openclaw doctor` виводить попередження і не змінює маршрут. +Якщо вбудований plugin `codex` увімкнено, але `openai-codex/*` все ще визначається +через PI, `openclaw doctor` попереджає та залишає маршрут без змін. ## Покриття можливостей OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Стан | -| ------------------------ | -------------------------------------------------------- | ------------------------------------------------------ | -| Chat / Responses | provider моделей `openai/` | Так | -| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Codex app-server harness | `openai/` з `agentRuntime.id: 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` / розуміння медіа | Так | -| Streaming speech-to-text | Voice Call `streaming.provider: "openai"` | Так | -| Realtime voice | Voice Call `realtime.provider: "openai"` / розмова в Control UI | Так | -| Embeddings | provider embedding для memory | Так | +| Можливість OpenAI | Поверхня OpenClaw | Стан | +| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | +| Чат / Responses | Провайдер моделей `openai/` | Так | +| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | +| Обв’язка app-server Codex | `openai/` з `agentRuntime.id: 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"` / Control UI Talk | Так | +| Ембеддинги | провайдер ембеддингів пам’яті | Так | -## Memory embeddings +## Ембеддинги пам’яті -OpenClaw може використовувати OpenAI або OpenAI-сумісний endpoint embedding для -індексації `memory_search` і embedding запитів: +OpenClaw може використовувати OpenAI або OpenAI-сумісну кінцеву точку ембеддингів для +індексування `memory_search` і ембеддингів запитів: ```json5 { @@ -111,36 +111,36 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс } ``` -Для OpenAI-сумісних endpoint, які вимагають асиметричних міток embedding, установіть -`queryInputType` і `documentInputType` у `memorySearch`. OpenClaw пересилає -їх як специфічні для provider поля запиту `input_type`: embedding запитів використовують -`queryInputType`; проіндексовані фрагменти memory і пакетна індексація використовують -`documentInputType`. Див. [довідник конфігурації Memory](/uk/reference/memory-config#provider-specific-config) для повного прикладу. +Для OpenAI-сумісних кінцевих точок, які вимагають асиметричних міток ембеддингів, установіть +`queryInputType` і `documentInputType` у `memorySearch`. OpenClaw передає +їх як поля запиту `input_type`, специфічні для провайдера: ембеддинги запитів використовують +`queryInputType`; проіндексовані фрагменти пам’яті та пакетне індексування використовують +`documentInputType`. Повний приклад див. у [Довіднику з конфігурації пам’яті](/uk/reference/memory-config#provider-specific-config). ## Початок роботи Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - - **Найкраще для:** прямого доступу до API та білінгу за використанням. + + **Найкраще для:** прямого доступу до API та тарифікації за використання. - - Створіть або скопіюйте ключ API з [панелі OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API-ключ на [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` - Або передайте ключ напряму: + Або передайте ключ безпосередньо: ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -149,17 +149,17 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ### Підсумок маршрутів - | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | - | ---------------------- | ---------------------------- | --------------------------- | --------------- | - | `openai/gpt-5.5` | пропущено / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.4-mini` | пропущено / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server | + | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | + | ---------------------- | --------------------------------- | -------------------------- | ---------------- | + | `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка app-server Codex | app-server Codex | - `openai/*` — це прямий маршрут за ключем API OpenAI, якщо ви явно не примушуєте - використання Codex app-server harness. Використовуйте `openai-codex/*` для Codex OAuth через - типовий runner PI або `openai/gpt-5.5` з - `agentRuntime.id: "codex"` для нативного виконання через Codex app-server. + `openai/*` — це прямий маршрут OpenAI API-key, якщо ви явно не примусите + використання обв’язки app-server Codex. Використовуйте `openai-codex/*` для Codex OAuth через + типовий runner PI або використовуйте `openai/gpt-5.5` з + `agentRuntime.id: "codex"` для нативного виконання через app-server Codex. ### Приклад конфігурації @@ -178,7 +178,7 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого ключа API. Codex cloud вимагає входу через ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Хмарний Codex вимагає входу в ChatGPT. @@ -186,13 +186,13 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс openclaw onboard --auth-choice openai-codex ``` - Або запустіть OAuth напряму: + Або запустіть OAuth безпосередньо: ```bash openclaw models auth login --provider openai-codex ``` - Для headless-конфігурацій або конфігурацій із проблемами callback додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback локального браузера: + Для headless або несумісних із callback конфігурацій додайте `--device-code`, щоб увійти за допомогою потоку коду пристрою ChatGPT замість callback браузера через localhost: ```bash openclaw models auth login --provider openai-codex --device-code @@ -203,7 +203,7 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -212,16 +212,16 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ### Підсумок маршрутів - | Посилання на модель | Конфігурація runtime | Маршрут | Автентифікація | + | Посилання на модель | Конфігурація середовища виконання | Маршрут | Автентифікація | |-----------|----------------|-------|------| - | `openai-codex/gpt-5.5` | пропущено / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | вхід Codex | - | `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо тільки якийсь plugin явно не заявляє `openai-codex` | вхід Codex | - | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | автентифікація Codex app-server | + | `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | ChatGPT/Codex OAuth через PI | вхід Codex | + | `openai-codex/gpt-5.5` | `runtime: "auto"` | Усе ще PI, якщо лише якийсь plugin явно не заявить `openai-codex` | вхід Codex | + | `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Обв’язка app-server Codex | автентифікація app-server Codex | - Продовжуйте використовувати ідентифікатор provider `openai-codex` для команд - auth/profile. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth. - Він не вибирає і не автовмикає вбудований Codex app-server harness. + Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд + автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth. + Він не вибирає і не вмикає автоматично вбудовану обв’язку app-server Codex. ### Приклад конфігурації @@ -233,80 +233,100 @@ OpenClaw може використовувати OpenAI або OpenAI-суміс ``` - Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через browser OAuth (типово) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента. + Налаштування більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (типово) або через наведений вище потік коду пристрою — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. ### Індикатор стану - Чат-команда `/status` показує, який runtime моделі активний для поточного сеансу. - Типовий harness PI відображається як `Runtime: OpenClaw Pi Default`. Коли - вибрано вбудований Codex app-server harness, `/status` показує - `Runtime: OpenAI Codex`. Наявні сеанси зберігають записаний для них ID harness, тому використайте + Чат `/status` показує, яке середовище виконання моделі активне для поточної сесії. + Типова обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли + вибрано вбудовану обв’язку app-server Codex, `/status` показує + `Runtime: OpenAI Codex`. Наявні сесії зберігають свій записаний ідентифікатор обв’язки, тому використовуйте `/new` або `/reset` після зміни `agentRuntime`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. - ### Попередження Doctor + ### Попередження doctor - Якщо вбудований plugin `codex` увімкнено, тоді як у цій вкладці + Якщо вбудований plugin `codex` увімкнено, поки в цій вкладці вибрано маршрут `openai-codex/*`, `openclaw doctor` попереджає, що модель усе ще визначається через PI. Залишайте конфігурацію без змін, якщо це і є -потрібний маршрут автентифікації за підпискою. Перемикайтеся на `openai/` плюс -`agentRuntime.id: "codex"` лише тоді, коли хочете нативне виконання через Codex -app-server. +бажаний маршрут автентифікації через підписку. Перемикайтеся на `openai/` плюс +`agentRuntime.id: "codex"` лише тоді, коли вам потрібне нативне виконання через +app-server Codex. -### Обмеження вікна контексту + ### Обмеження вікна контексту -OpenClaw розглядає метадані моделі та ліміт контексту runtime як окремі значення. + OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення. -Для `openai-codex/gpt-5.5` через Codex OAuth: + Для `openai-codex/gpt-5.5` через Codex OAuth: -- Нативне `contextWindow`: `1000000` -- Типовий ліміт runtime `contextTokens`: `272000` + - Нативний `contextWindow`: `1000000` + - Типове обмеження `contextTokens` у середовищі виконання: `272000` -Менший типовий ліміт на практиці має кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: + Менше типове обмеження на практиці має кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: -```json5 -{ - models: { - providers: { - "openai-codex": { - models: [{ id: "gpt-5.5", contextTokens: 160000 }], + ```json5 + { + models: { + providers: { + "openai-codex": { + models: [{ id: "gpt-5.5", contextTokens: 160000 }], + }, + }, }, - }, - }, -} -``` + } + ``` - -Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime. - + + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання. + -### Відновлення каталогу + ### Відновлення каталогу -OpenClaw використовує метадані каталогу Codex з джерела для `gpt-5.5`, коли вони -наявні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, хоча -обліковий запис автентифікований, OpenClaw синтезує цей рядок OAuth-моделі, щоб -запуски Cron, sub-agent і налаштованої моделі за замовчуванням не завершувалися помилкою -`Unknown model`. + OpenClaw використовує метадані каталогу Codex з upstream для `gpt-5.5`, коли вони + наявні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, поки + обліковий запис автентифіковано, OpenClaw синтезує цей рядок моделі OAuth, щоб + запуски Cron, субагентів і налаштованої моделі за замовчуванням не завершувалися помилкою + `Unknown model`. +## Нативна автентифікація app-server Codex + +Нативна обв’язка app-server Codex використовує посилання на моделі `openai/*` плюс +`agentRuntime.id: "codex"`, але її автентифікація все ще базується на обліковому записі. OpenClaw +вибирає автентифікацію в такому порядку: + +1. Явний профіль автентифікації OpenClaw `openai-codex`, прив’язаний до агента. +2. Наявний обліковий запис app-server, наприклад локальний вхід у Codex CLI через ChatGPT. +3. Лише для локальних запусків app-server через stdio — спочатку `CODEX_API_KEY`, потім + `OPENAI_API_KEY`, коли app-server повідомляє, що облікового запису немає, і все ще вимагає + автентифікацію OpenAI. + +Це означає, що локальний вхід через підписку ChatGPT/Codex не замінюється лише +через те, що процес gateway також має `OPENAI_API_KEY` для прямих моделей OpenAI +або ембеддингів. Резервне використання API-ключа через env працює лише для локального шляху stdio без облікового запису; воно +не надсилається до підключень app-server через WebSocket. Коли вибрано профіль Codex +у стилі підписки, OpenClaw також не передає `CODEX_API_KEY` і `OPENAI_API_KEY` +у дочірній процес stdio app-server, який запускається, і надсилає вибрані облікові дані +через RPC входу app-server. + ## Генерація зображень Вбудований plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує як генерацію зображень OpenAI за ключем API, так і генерацію зображень -через Codex OAuth через те саме посилання на модель `openai/gpt-image-2`. +Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію зображень через Codex OAuth +через те саме посилання на модель `openai/gpt-image-2`. -| Можливість | Ключ API OpenAI | Codex OAuth | -| ------------------------ | ---------------------------------- | ------------------------------------- | -| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | Вхід через OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | backend Codex Responses | -| Макс. зображень на запит | 4 | 4 | -| Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | -| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | -| Співвідношення сторін / роздільна здатність | Не пересилаються в OpenAI Images API | Зіставляються з підтримуваним розміром, коли це безпечно | +| Можливість | API-ключ OpenAI | Codex OAuth | +| ------------------------- | ---------------------------------- | ------------------------------------ | +| Посилання на модель | `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 { @@ -319,24 +339,24 @@ OpenClaw використовує метадані каталогу Codex з д ``` -Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору provider і поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. -`gpt-image-2` є типовим для текстової генерації зображень OpenAI та редагування -зображень. `gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються доступними як +`gpt-image-2` — це модель за замовчуванням як для генерації зображень з тексту OpenAI, так і для +редагування зображень. `gpt-image-1.5`, `gpt-image-1` і `gpt-image-1-mini` залишаються доступними як явні перевизначення моделі. Використовуйте `openai/gpt-image-1.5` для виводу PNG/WebP -із прозорим тлом; поточний API `gpt-image-2` відхиляє +із прозорим фоном; поточний API `gpt-image-2` відхиляє `background: "transparent"`. -Для запиту з прозорим тлом агенти мають викликати `image_generate` з +Для запиту на прозорий фон агенти мають викликати `image_generate` з `model: "openai/gpt-image-1.5"`, `outputFormat: "png"` або `"webp"` і -`background: "transparent"`; старіший параметр provider `openai.background` -усе ще приймається. OpenClaw також захищає публічні маршрути OpenAI і +`background: "transparent"`; старіший параметр провайдера `openai.background` +усе ще підтримується. OpenClaw також захищає публічні маршрути OpenAI та OpenAI Codex OAuth, переписуючи типові прозорі запити `openai/gpt-image-2` -на `gpt-image-1.5`; Azure і власні OpenAI-сумісні endpoint зберігають -свої налаштовані назви розгортання/моделі. +на `gpt-image-1.5`; Azure і користувацькі OpenAI-сумісні кінцеві точки зберігають +свої налаштовані назви deployment/model. -Те саме налаштування доступне і для headless-запусків CLI: +Те саме налаштування доступне для headless-запусків CLI: ```bash openclaw infer image generate \ @@ -348,34 +368,33 @@ openclaw infer image generate \ ``` Використовуйте ті самі прапорці `--output-format` і `--background` з -`openclaw infer image edit`, коли починаєте з вхідного файла. -`--openai-background` лишається доступним як OpenAI-специфічний псевдонім. +`openclaw infer image edit`, коли починаєте з вхідного файлу. +`--openai-background` залишається доступним як OpenAI-специфічний псевдонім. -Для встановлень із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw визначає цей збережений токен доступу OAuth -і надсилає запити на зображення через backend Codex Responses. Він -не намагається спочатку використати `OPENAI_API_KEY` і не переходить непомітно на ключ API для цього -запиту. Явно налаштуйте `models.providers.openai` з ключем API, -власним base URL або endpoint Azure, якщо хочете використовувати прямий маршрут +Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли +налаштовано профіль OAuth `openai-codex`, OpenClaw визначає цей збережений OAuth-токен доступу +й надсилає запити на зображення через бекенд Codex Responses. Він +не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихого резервного переходу на API-ключ для цього +запиту. Явно налаштуйте `models.providers.openai` з API-ключем, +користувацькою базовою URL-адресою або кінцевою точкою Azure, коли хочете використовувати прямий маршрут OpenAI Images API. -Якщо цей власний endpoint зображень розміщено в довіреній LAN/приватній адресі, також установіть -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw тримає -приватні/внутрішні OpenAI-сумісні endpoint зображень заблокованими, якщо цей явний дозвіл -не задано. +Якщо ця користувацька кінцева точка зображень знаходиться в довіреній LAN/приватній адресі, також установіть +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і надалі +блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо цього opt-in немає. -Генерація: +Згенерувати: ``` /tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 ``` -Генерація прозорого PNG: +Згенерувати прозорий PNG: ``` /tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent ``` -Редагування: +Редагувати: ``` /tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 @@ -385,12 +404,12 @@ OpenAI Images API. Вбудований plugin `openai` реєструє генерацію відео через інструмент `video_generate`. -| Можливість | Значення | -| --------------- | --------------------------------------------------------------------------------- | -| Типова модель | `openai/sora-2` | -| Режими | Текст у відео, зображення у відео, редагування одного відео | -| Еталонні входи | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Можливість | Значення | +| ---------------- | --------------------------------------------------------------------------------- | +| Модель за замовчуванням | `openai/sora-2` | +| Режими | Текст у відео, зображення у відео, редагування одного відео | +| Еталонні вхідні дані | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -404,22 +423,22 @@ OpenAI Images API. ``` -Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору provider і поведінки failover. +Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. -## Внесок у prompt GPT-5 +## Внесок у підказку GPT-5 -OpenClaw додає спільний внесок у prompt GPT-5 для запусків сімейства GPT-5 у різних provider. Він застосовується за ID моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однаковий оверлей. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у підказку GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий накладений шар. Старіші моделі GPT-4.x його не отримують. -Вбудований нативний Codex harness використовує ту саму поведінку GPT-5 і оверлей Heartbeat через інструкції розробника Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ту саму послідовність виконання та проактивні підказки Heartbeat, навіть якщо рештою prompt harness керує Codex. +Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладення Heartbeat через інструкції розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `agentRuntime.id: "codex"`, зберігають ті самі вказівки щодо доведення справ до кінця та проактивного Heartbeat, навіть попри те, що Codex керує рештою підказки обв’язки. -Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни tools, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається в спільному системному prompt OpenClaw і політиці вихідної доставки. Настанови GPT-5 завжди увімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається у спільній системній підказці OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| ---------------------- | ----------------------------------------- | -| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише шар дружнього стилю | +| Значення | Ефект | +| --------------------- | ------------------------------------------ | +| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише шар дружнього стилю | @@ -443,11 +462,11 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап -Під час виконання значення нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю. +Під час виконання значення не чутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю. -Застарілий параметр `plugins.entries.openai.config.personality` усе ще читається як резервний механізм сумісності, коли спільний параметр `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застарілий `plugins.entries.openai.config.personality` усе ще зчитується як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення @@ -456,15 +475,15 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап Вбудований plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Параметр | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | За замовчуванням | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `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` | + | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових повідомлень, `mp3` для файлів | + | API-ключ | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Базова URL-адреса | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -481,21 +500,21 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS, не впливаючи на endpoint chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS, не впливаючи на кінцеву точку chat API. - - Вбудований plugin `openai` реєструє пакетне speech-to-text через - поверхню транскрибування media-understanding OpenClaw. + + Вбудований plugin `openai` реєструє пакетне перетворення мовлення на текст через + поверхню транскрибування для розуміння медіа в OpenClaw. - - Типова модель: `gpt-4o-transcribe` - - Endpoint: REST OpenAI `/v1/audio/transcriptions` - - Вхідний шлях: multipart-завантаження аудіофайла - - Підтримується в OpenClaw скрізь, де вхідне транскрибування аудіо використовує - `tools.media.audio`, зокрема для сегментів голосових каналів Discord і - аудіовкладень каналів + - Модель за замовчуванням: `gpt-4o-transcribe` + - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` + - Шлях вхідних даних: multipart-завантаження аудіофайлу + - Підтримується в OpenClaw всюди, де транскрибування вхідного аудіо використовує + `tools.media.audio`, зокрема сегменти голосових каналів Discord і + аудіовкладення каналів Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: @@ -517,25 +536,25 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап } ``` - Підказки мови і prompt пересилаються до OpenAI, коли вони задані спільною - конфігурацією audio media або запитом на транскрибування для конкретного виклику. + Підказки щодо мови та prompt передаються до OpenAI, коли вони надані + спільною конфігурацією аудіомедіа або запитом транскрибування для конкретного виклику. Вбудований plugin `openai` реєструє транскрибування в реальному часі для plugin Voice Call. - | Параметр | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | За замовчуванням | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | | Prompt | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | Ключ API | `...openai.apiKey` | Якщо не задано, використовується `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Використовується з’єднання WebSocket до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей streaming provider призначено для шляху транскрибування в реальному часі plugin Voice Call; голос у Discord наразі записує короткі сегменти й використовує пакетний шлях транскрибування `tools.media.audio`. + Використовує підключення WebSocket до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі у Voice Call; голос Discord зараз натомість записує короткі сегменти й використовує пакетний шлях транскрибування `tools.media.audio`. @@ -543,57 +562,58 @@ OpenClaw додає спільний внесок у prompt GPT-5 для зап Вбудований plugin `openai` реєструє голос у реальному часі для plugin Voice Call. - | Параметр | Шлях конфігурації | Типово | + | Налаштування | Шлях конфігурації | За замовчуванням | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | - | Температура | `...openai.temperature` | `0.8` | + | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | Ключ API | `...openai.apiKey` | Якщо не задано, використовується `OPENAI_API_KEY` | + | API-ключ | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для backend-мостів реального часу. Підтримує двонапрямлений виклик tools. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment` для бекендових realtime-містків. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law. - Розмова в Control UI використовує браузерні сеанси OpenAI у реальному часі з - тимчасовим секретом клієнта, випущеним Gateway, і прямим браузерним обміном WebRTC SDP з - OpenAI Realtime API. Жива перевірка для супроводжувачів доступна через + Control UI Talk використовує браузерні сесії OpenAI у реальному часі з + ефемерним клієнтським секретом, виданим Gateway, і прямим браузерним обміном WebRTC SDP з + OpenAI Realtime API. Для супровідної live-перевірки доступно `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`; - гілка OpenAI випускає секрет клієнта в Node, генерує браузерну пропозицію SDP - з фальшивим медіапотоком мікрофона, надсилає її до OpenAI і застосовує відповідь SDP + гілка OpenAI створює клієнтський секрет у Node, генерує браузерну SDP-пропозицію + з підробленим медіапотоком мікрофона, надсилає її до OpenAI та застосовує SDP-відповідь без логування секретів. -## Endpoint Azure OpenAI +## Кінцеві точки Azure OpenAI -Вбудований provider `openai` може бути спрямований на ресурс Azure OpenAI для -генерації зображень через перевизначення base URL. На шляху генерації зображень OpenClaw -визначає імена хостів Azure в `models.providers.openai.baseUrl` і автоматично -перемикається на формат запитів Azure. +Вбудований провайдер `openai` може використовувати ресурс Azure OpenAI для генерації +зображень через перевизначення базової URL-адреси. У шляху генерації зображень OpenClaw +визначає хости Azure за `models.providers.openai.baseUrl` і автоматично перемикається +на формат запиту Azure. Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос -у реальному часі** в розділі [Голос і мовлення](#voice-and-speech) для параметрів Azure. +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному +часі** в розділі [Голос і мовлення](#voice-and-speech), щоб побачити його параметри +Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка Azure OpenAI, квота або корпоративна угода -- Вам потрібна регіональна локалізація даних або механізми відповідності, які надає Azure -- Ви хочете залишити трафік у межах наявного середовища Azure +- у вас уже є підписка Azure OpenAI, квота або корпоративна угода +- вам потрібні регіональна резидентність даних або засоби відповідності, які надає Azure +- ви хочете зберігати трафік у межах наявного tenancy Azure ### Конфігурація -Для генерації зображень через Azure за допомогою вбудованого provider `openai` вкажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure, а `apiKey` установіть у -значення ключа Azure OpenAI (а не ключа OpenAI Platform): +Для генерації зображень через Azure за допомогою вбудованого провайдера `openai` вкажіть +`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як +ключ Azure OpenAI (а не ключ OpenAI Platform): ```json5 { @@ -614,21 +634,21 @@ OpenClaw розпізнає такі суфікси хостів Azure для м - `*.services.ai.azure.com` - `*.cognitiveservices.azure.com` -Для запитів на генерацію зображень до розпізнаного хоста Azure OpenClaw: +Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи в межах розгортання (`/openai/deployments/{deployment}/...`) +- Використовує шляхи з прив’язкою до deployment (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -- Використовує типовий тайм-аут запиту 600 с для викликів генерації зображень Azure. - Значення `timeoutMs` для окремих викликів усе ще перевизначають цей типовый параметр. +- Використовує типове значення тайм-ауту запиту 600 с для викликів генерації зображень Azure. + Значення `timeoutMs` для конкретного виклику все одно перевизначають це значення за замовчуванням. -Інші base URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний +Для інших базових URL-адрес (публічний OpenAI, OpenAI-сумісні проксі) зберігається стандартний формат запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень provider `openai` вимагає -OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який власний -`openai.baseUrl` так само, як публічний endpoint OpenAI, і завершуються помилкою при роботі з розгортаннями +Маршрутизація Azure для шляху генерації зображень провайдера `openai` вимагає +OpenClaw 2026.4.22 або новішої версії. Попередні версії обробляють будь-який користувацький +`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із deployment зображень Azure. @@ -641,68 +661,68 @@ OpenClaw 2026.4.22 або новішої версії. Попередні вер export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типове значення — `2024-12-01-preview`, якщо змінну не встановлено. +Значення за замовчуванням — `2024-12-01-preview`, якщо змінна не задана. -### Назви моделей — це назви розгортань +### Назви моделей — це назви deployment -Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure, -маршрутизованих через вбудований provider `openai`, поле `model` в OpenClaw -має бути **назвою розгортання Azure**, яку ви налаштували в порталі Azure, а не -публічним ID моделі OpenAI. +Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure, +маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw +має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не +публічним ідентифікатором моделі OpenAI. -Якщо ви створили розгортання `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 ``` -Те саме правило назв розгортань застосовується до викликів генерації зображень, -маршрутизованих через вбудований provider `openai`. +Те саме правило щодо назв deployment застосовується до викликів генерації зображень, +маршрутизованих через вбудований провайдер `openai`. ### Регіональна доступність -Генерація зображень Azure наразі доступна лише в частині регіонів +Генерація зображень Azure зараз доступна лише в частині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, -`uaenorth`). Перед створенням розгортання перевірте актуальний список регіонів Microsoft -і підтвердьте, що потрібна модель доступна у вашому регіоні. +`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням +deployment і переконайтеся, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні -значення `background` у `gpt-image-2`) або надавати їх лише для певних версій -моделі. Ці відмінності походять від Azure та базової моделі, а не від -OpenClaw. Якщо запит Azure завершується помилкою перевірки, перевірте -набір параметрів, підтримуваний вашим конкретним розгортанням і версією API в +значення `background` для `gpt-image-2`), або надавати їх лише в конкретних версіях +моделі. Ці відмінності походять від Azure і базової моделі, а не від +OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте +набір параметрів, який підтримує ваш конкретний deployment і версія API в порталі Azure. -Azure OpenAI використовує нативну транспортну і compat-поведінку, але не отримує -приховані заголовки attribution від OpenClaw — див. акордеон **Нативні та OpenAI-сумісні +Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує +приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні маршрути** в розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses в Azure (поза генерацією зображень) використовуйте -потік онбордингу або окрему конфігурацію provider Azure — одного лише `openai.baseUrl` -недостатньо, щоб підхопити формат API/автентифікації Azure. Існує окремий -provider `azure-openai-responses/*`; див. -акордеон Server-side Compaction нижче. +Для чату або трафіку Responses на Azure (окрім генерації зображень) використовуйте +потік налаштування або окрему конфігурацію провайдера Azure — одного лише `openai.baseUrl` +недостатньо, щоб увімкнути формат API/автентифікації Azure. Існує окремий +провайдер `azure-openai-responses/*`; див. +акордеон Server-side compaction нижче. ## Розширена конфігурація - OpenClaw використовує стратегію WebSocket-first із fallback на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`. + OpenClaw використовує WebSocket у першу чергу з резервним переходом на SSE (`"auto"`) і для `openai/*`, і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - - Повторює один ранній збій WebSocket перед переходом на SSE - - Після збою позначає WebSocket як degraded приблизно на 60 секунд і використовує SSE під час охолодження - - Додає стабільні заголовки ідентичності сеансу та ходу для повторів і перепідключень - - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту + - Повторює одну ранню помилку WebSocket перед переходом на SSE + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE протягом періоду охолодження + - Додає стабільні заголовки ідентичності сесії та ходу для повторів і перепідключень + - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) у різних варіантах транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | Спочатку WebSocket, потім fallback на SSE | + | `"auto"` (типово) | Спочатку WebSocket, резервно SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -723,17 +743,17 @@ provider `azure-openai-responses/*`; див. } ``` - Пов’язана документація OpenAI: - - [Realtime API з WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - - [Потокові відповіді API (SSE)](https://platform.openai.com/docs/guides/streaming-responses) + Пов’язані документи OpenAI: + - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) + - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) - - OpenClaw типово вмикає прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. + + OpenClaw за замовчуванням вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. ```json5 - // Вимкнути прогрів + // Вимкнути прогрівання { agents: { defaults: { @@ -752,10 +772,10 @@ provider `azure-openai-responses/*`; див. OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - - **Chat/UI:** `/fast status|on|off` - - **Config:** `agents.defaults.models["/"].params.fastMode` + - **Чат/UI:** `/fast status|on|off` + - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли його ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. + Коли його ввімкнено, OpenClaw зіставляє швидкий режим з пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` чи `text.verbosity`. ```json5 { @@ -770,7 +790,7 @@ provider `azure-openai-responses/*`; див. ``` - Перевизначення сеансу мають вищий пріоритет, ніж конфігурація. Очищення перевизначення сеансу в UI сеансів повертає сеанс до налаштованого типового значення. + Перевизначення сесії мають вищий пріоритет за конфігурацію. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого значення за замовчуванням. @@ -793,23 +813,23 @@ provider `azure-openai-responses/*`; див. Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` пересилається лише до нативних endpoint OpenAI (`api.openai.com`) і нативних endpoint Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-який із provider через проксі, OpenClaw не змінює `service_tier`. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw не змінює `service_tier`. - - Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) stream-обгортка Pi harness plugin OpenAI автоматично вмикає Server-side Compaction: + + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) stream wrapper Pi-harness plugin OpenAI автоматично вмикає server-side Compaction: - - Примусово встановлює `store: true` (якщо тільки compat моделі не задає `supportsStore: false`) - - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо воно недоступне) + - Примусово встановлює `store: true` (якщо сумісність моделі не задає `supportsStore: false`) + - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне) - Це застосовується до вбудованого шляху Pi harness і до хуків provider OpenAI, що використовуються вбудованими запусками. Нативний Codex app-server harness керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.agentRuntime.id`. + Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, що використовуються вбудованими запусками. Нативна обв’язка app-server Codex керує власним контекстом через Codex і налаштовується окремо за допомогою `agents.defaults.agentRuntime.id`. - - Корисно для сумісних endpoint, таких як Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses: ```json5 { @@ -825,7 +845,7 @@ provider `azure-openai-responses/*`; див. } ``` - + ```json5 { agents: { @@ -861,13 +881,13 @@ provider `azure-openai-responses/*`; див. - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses все одно примусово встановлюють `store: true`, якщо compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses усе одно примусово використовують `store: true`, якщо compat не задає `supportsStore: false`. - Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання: + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший контракт вбудованого виконання: ```json5 { @@ -880,35 +900,35 @@ provider `azure-openai-responses/*`; див. ``` Із `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія tool - - Повторює хід із вказівкою діяти зараз + - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента + - Повторює хід із вказівкою діяти негайно - Автоматично вмикає `update_plan` для суттєвої роботи - - Показує явний заблокований стан, якщо модель продовжує планувати без дій + - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші provider і старіші сімейства моделей зберігають типову поведінку. + Поширюється лише на запуски сімейства GPT-5 від OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - OpenClaw по-різному обробляє прямі endpoint OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`: + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort - - Опускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово використовують суворий режим схем tools - - Додають приховані заголовки attribution лише на перевірених нативних хостах - - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, reasoning-compat, підказки кешу prompt) + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують зусилля OpenAI `none` + - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` + - За замовчуванням використовують суворий режим схем інструментів + - Додають приховані заголовки атрибуції лише на перевірених нативних хостах + - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу prompt) - **Маршрути проксі/сумісності:** - - Використовують м’якшу compat-поведінку - - Вилучають Completions `store` із ненативних payload `openai-completions` - - Приймають розширений наскрізний JSON `params.extra_body`/`params.extraBody` для OpenAI-сумісних проксі Completions + **Проксі/сумісні маршрути:** + - Використовують м’якшу поведінку compat + - Видаляють Completions `store` з ненативних payload `openai-completions` + - Приймають наскрізний JSON `params.extra_body`/`params.extraBody` для розширених параметрів OpenAI-сумісних проксі Completions - Приймають `params.chat_template_kwargs` для OpenAI-сумісних проксі Completions, таких як vLLM - - Не примушують суворі схеми tools або заголовки, призначені лише для нативних маршрутів + - Не примусово вмикають суворі схеми інструментів або лише нативні заголовки - Azure OpenAI використовує нативну транспортну і compat-поведінку, але не отримує приховані заголовки attribution. + Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує приховані заголовки атрибуції. @@ -917,15 +937,15 @@ provider `azure-openai-responses/*`; див. - Вибір provider, посилань на моделі та поведінки failover. + Вибір провайдерів, посилань на моделі та поведінки failover. - Спільні параметри інструмента зображень і вибір provider. + Спільні параметри інструмента зображень і вибір провайдера. - Спільні параметри інструмента відео і вибір provider. + Спільні параметри інструмента відео та вибір провайдера. - Подробиці автентифікації та правила повторного використання облікових даних. + Докладно про автентифікацію та правила повторного використання облікових даних. diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index c26e062df..1e1406a2b 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,41 +1,37 @@ --- read_when: - - Встановлення або налаштування Plugins - - Розуміння правил виявлення та завантаження Plugins - - Робота з пакетами Plugins, сумісними з Codex/Claude + - Встановлення або налаштування плагінів + - Розуміння правил виявлення та завантаження плагінів + - Робота з сумісними з Codex/Claude пакетами плагінів sidebarTitle: Install and Configure -summary: Встановлюйте, налаштовуйте та керуйте Plugins OpenClaw -title: Plugins +summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw +title: Плагіни x-i18n: - generated_at: "2026-04-27T23:14:25Z" + generated_at: "2026-04-28T00:03:38Z" model: gpt-5.4 provider: openai - source_hash: f3465cb1f7e304c0ffd59ae9a4c586237f99f1dc861e93821f9a9d1fea4e371d + source_hash: 7cd8b279b49611bb556e71210cf86eb54b4dc291021df2ae376ad718113ac0de source_path: tools/plugin.md workflow: 15 --- -Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, -середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному -часі, розуміння медіа, генерація зображень, генерація відео, отримання даних із вебу, вебпошук -тощо. Деякі Plugins є **основними** (постачаються з OpenClaw), інші — -**зовнішніми** (опубліковані в npm спільнотою). +Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, обв’язки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання даних із вебу, вебпошук тощо. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші — **external** (опубліковані спільнотою в npm). ## Швидкий старт - + ```bash openclaw plugins list ``` - + ```bash - # Із npm + # From npm openclaw plugins install @openclaw/voice-call - # Із локального каталогу або архіву + # From a local directory or archive openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` @@ -47,12 +43,12 @@ Plugins розширюють OpenClaw новими можливостями: к openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. + Потім налаштуйте в `plugins.entries.\.config` у вашому конфігураційному файлі. -Якщо ви віддаєте перевагу керуванню безпосередньо з чату, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви надаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub:@openclaw/voice-call @@ -60,69 +56,58 @@ Plugins розширюють OpenClaw новими можливостями: к /plugin enable voice-call ``` -Шлях встановлення використовує той самий механізм визначення, що й CLI: локальний шлях/архів, явний -`clawhub:`, явний `npm:` або специфікація пакета без префікса (спочатку ClawHub, потім -резервний варіант через npm). +Шлях установлення використовує той самий механізм розпізнавання, що й CLI: локальний шлях/архів, явний `clawhub:`, явний `npm:` або специфікація пакета без префікса (спочатку ClawHub, потім резервний варіант npm). -Якщо конфігурація недійсна, встановлення зазвичай завершується безпечною відмовою й пропонує -`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях -перевстановлення вбудованого Plugin для Plugins, які погоджуються на +Якщо конфігурація недійсна, установлення зазвичай безпечно завершується з відмовою та вказує вам на `openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого плагіна для плагінів, які використовують `openclaw.install.allowInvalidConfigRecovery`. -Під час запуску Gateway недійсна конфігурація одного Plugin ізолюється на рівні цього Plugin: -під час запуску журналюється проблема `plugins.entries..config`, цей Plugin пропускається під час -завантаження, а інші Plugins і канали залишаються онлайн. Виконайте `openclaw doctor --fix`, -щоб ізолювати некоректну конфігурацію Plugin, вимкнувши запис цього Plugin і видаливши -його недійсне корисне навантаження конфігурації; звичайна резервна копія конфігурації зберігає попередні значення. -Коли конфігурація каналу посилається на Plugin, який більше неможливо виявити, але той самий -застарілий ідентифікатор Plugin залишається в конфігурації Plugin або записах встановлення, під час запуску Gateway +Під час запуску Gateway недійсна конфігурація одного плагіна ізолюється лише до цього плагіна: +під час запуску в журналі фіксується проблема `plugins.entries..config`, цей плагін пропускається під час завантаження, а інші плагіни та канали залишаються онлайн. Запустіть `openclaw doctor --fix`, +щоб ізолювати неправильну конфігурацію плагіна, вимкнувши цей запис плагіна та видаливши його недійсний вміст конфігурації; звичайна резервна копія конфігурації збереже попередні значення. +Коли конфігурація каналу посилається на плагін, який більше неможливо виявити, але той самий застарілий ідентифікатор плагіна залишається в конфігурації плагіна або записах установлення, під час запуску Gateway журналюються попередження, і цей канал пропускається замість блокування всіх інших каналів. -Виконайте `openclaw doctor --fix`, щоб видалити застарілі записи каналу/Plugin; невідомі -ключі каналів без ознак застарілого Plugin усе ще не проходять перевірку, щоб опечатки лишалися помітними. -Якщо встановлено `plugins.enabled: false`, застарілі посилання на Plugins вважаються неактивними: -під час запуску Gateway пропускається виявлення/завантаження Plugins, а `openclaw doctor` зберігає -вимкнену конфігурацію Plugin замість автоматичного видалення. Знову ввімкніть Plugins перед -запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори Plugin. +Запустіть `openclaw doctor --fix`, щоб видалити застарілі записи каналу/плагіна; невідомі ключі каналу без ознак застарілого плагіна все одно не проходять валідацію, щоб помилки в написанні залишалися помітними. +Якщо встановлено `plugins.enabled: false`, застарілі посилання на плагіни вважаються неактивними: +під час запуску Gateway пропускаються роботи з виявлення/завантаження плагінів, а `openclaw doctor` зберігає вимкнену конфігурацію плагіна замість її автоматичного видалення. Знову ввімкніть плагіни перед +запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори плагінів. -Пакетні інсталяції OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання для кожного вбудованого Plugin. -Коли вбудований Plugin, що належить OpenClaw, активний через -конфігурацію Plugin, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням, під час запуску -відновлюються лише задекларовані залежності середовища виконання цього Plugin перед його імпортом. -Лише збережений стан автентифікації каналу сам по собі не активує вбудований канал для відновлення +Пакетні інсталяції OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання для кожного вбудованого плагіна. +Коли вбудований плагін, який належить OpenClaw, активний через конфігурацію +плагіна, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням, під час запуску +виправляються лише оголошені залежності середовища виконання цього плагіна перед його імпортом. +Лише збережений стан автентифікації каналу сам по собі не активує вбудований канал для виправлення залежностей середовища виконання під час запуску Gateway. Явне вимкнення все одно має пріоритет: `plugins.entries..enabled: false`, `plugins.deny`, `plugins.enabled: false` і `channels..enabled: false` -запобігають автоматичному відновленню вбудованих залежностей середовища виконання для цього Plugin/каналу. -Непорожній `plugins.allow` також обмежує відновлення залежностей середовища виконання для вбудованих Plugins, увімкнених за замовчуванням; -явне ввімкнення вбудованого каналу (`channels..enabled: true`) усе ще може -відновити залежності Plugin цього каналу. -Зовнішні Plugins і власні шляхи завантаження все одно потрібно встановлювати через +запобігають автоматичному виправленню вбудованих залежностей середовища виконання для цього плагіна/каналу. +Непорожній `plugins.allow` також обмежує виправлення вбудованих залежностей середовища виконання для вбудованих плагінів, увімкнених за замовчуванням; +явне ввімкнення вбудованого каналу (`channels..enabled: true`) усе ще може виправити залежності плагіна цього каналу. +External-плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через `openclaw plugins install`. -## Типи Plugins +## Типи плагінів -OpenClaw розпізнає два формати Plugins: +OpenClaw розпізнає два формати плагінів: -| Формат | Як це працює | Приклади | -| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ | -| **Нативний** | `openclaw.plugin.json` + модуль середовища виконання; виконується в процесі | Офіційні Plugins, npm-пакети спільноти | -| **Пакет** | Сумісний із Codex/Claude/Cursor макет; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| Формат | Як це працює | Приклади | +| ---------- | --------------------------------------------------------------- | ------------------------------------------------------ | +| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, npm-пакети спільноти | +| **Bundle** | Сумісний із Codex/Claude/Cursor макет; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. у [Пакети Plugin](/uk/plugins/bundles). +Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. у [Plugin Bundles](/uk/plugins/bundles). -Якщо ви пишете нативний Plugin, почніть із [Створення Plugins](/uk/plugins/building-plugins) -і [Огляд SDK Plugin](/uk/plugins/sdk-overview). +Якщо ви пишете Native-плагін, почніть із [Building Plugins](/uk/plugins/building-plugins) +та [Plugin SDK Overview](/uk/plugins/sdk-overview). ## Точки входу пакета -Нативні npm-пакети Plugins мають оголошувати `openclaw.extensions` у `package.json`. -Кожен запис має залишатися в межах каталогу пакета та вказувати на придатний для читання -файл середовища виконання або на вихідний файл TypeScript із виведеним з нього -зібраним JavaScript-файлом, наприклад `src/index.ts` до `dist/index.js`. +Npm-пакети Native-плагінів мають оголошувати `openclaw.extensions` у `package.json`. +Кожен запис має залишатися в межах каталогу пакета та вказувати на доступний для читання +файл середовища виконання або на вихідний файл TypeScript з виведеним +зібраним JavaScript-відповідником, наприклад `src/index.ts` до `dist/index.js`. -Використовуйте `openclaw.runtimeExtensions`, коли опубліковані файли середовища виконання не розміщені -за тими самими шляхами, що й вихідні записи. Якщо це поле задано, -`runtimeExtensions` має містити рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до збою встановлення та -виявлення Plugin, а не до мовчазного повернення до шляхів вихідного коду. +Використовуйте `openclaw.runtimeExtensions`, якщо опубліковані файли середовища виконання не розміщені за тими самими шляхами, що й записи вихідного коду. Якщо цей параметр присутній, `runtimeExtensions` має містити +рівно один запис для кожного запису `extensions`. Невідповідні списки призводять до помилки встановлення та +виявлення плагіна замість тихого резервного переходу до шляхів вихідного коду. ```json { @@ -134,11 +119,11 @@ OpenClaw розпізнає два формати Plugins: } ``` -## Офіційні Plugins +## Офіційні плагіни ### Доступні для встановлення (npm) -| Plugin | Пакет | Документація | +| Плагін | Пакет | Документація | | --------------- | ---------------------- | ------------------------------------ | | Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | | Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | @@ -147,10 +132,10 @@ OpenClaw розпізнає два формати Plugins: | Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | | Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | -### Основні (постачаються з OpenClaw) +### Core (постачаються разом з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -158,22 +143,26 @@ OpenClaw розпізнає два формати Plugins: `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - - - `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`) - - `memory-lancedb` — довготривала пам’ять із встановленням на вимогу з автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) + + - `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`) + - `memory-lancedb` — довготривала пам’ять з установленням на вимогу, автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) + + Див. [Memory LanceDB](/uk/plugins/memory-lancedb), щоб дізнатися про + налаштування ембедингів, сумісних з OpenAI, приклади Ollama, ліміти пригадування та усунення несправностей. + - + `elevenlabs`, `microsoft` - - `browser` — вбудований Plugin браузера для інструмента браузера, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання браузера та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною) - - `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням) + - `browser` — вбудований browser-плагін для browser-інструмента, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime і служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною) + - `copilot-proxy` — міст VS Code Copilot Proxy (за замовчуванням вимкнений) -Шукаєте сторонні Plugins? Див. [Plugins спільноти](/uk/plugins/community). +Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community). ## Конфігурація @@ -191,111 +180,111 @@ OpenClaw розпізнає два формати Plugins: } ``` -| Поле | Опис | -| ---------------- | --------------------------------------------------------- | -| `enabled` | Головний перемикач (типово: `true`) | -| `allow` | Список дозволених Plugins (необов’язково) | -| `deny` | Список заборонених Plugins (необов’язково; заборона має пріоритет) | -| `load.paths` | Додаткові файли/каталоги Plugins | -| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі та конфігурація для окремого Plugin | +| Поле | Опис | +| --------------- | --------------------------------------------------------- | +| `enabled` | Головний перемикач (типово: `true`) | +| `allow` | Список дозволених плагінів (необов’язково) | +| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) | +| `load.paths` | Додаткові файли/каталоги плагінів | +| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | +| `entries.\` | Перемикачі та конфігурація для окремого плагіна | -Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з -відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`), -цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації. -Підтримуваного шляху гарячого перезавантаження для нативного коду середовища виконання Plugin або хуків життєвого циклу немає; -перезапустіть процес Gateway, який обслуговує живий канал, перш ніж +Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущений з +відстеженням конфігурації та внутрішньопроцесним перезапуском (стандартний шлях `openclaw gateway`), +цей перезапуск зазвичай виконується автоматично невдовзі після запису змін конфігурації. +Підтримуваного шляху гарячого перезавантаження для коду середовища виконання Native-плагіна або хуків життєвого циклу немає; +перезапустіть процес Gateway, який обслуговує активний канал, перш ніж очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, служби або -хуки провайдера/середовища виконання почнуть працювати. +хуки постачальника/runtime почнуть виконуватися. -`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugins. Позначка -`enabled` для Plugin там означає, що збережений реєстр і поточна конфігурація дозволяють цьому -Plugin брати участь у роботі. Це не доводить, що вже запущений віддалений дочірній Gateway -перезапустився з тим самим кодом Plugin. У конфігураціях VPS/контейнерів з -обгортками процесів надсилайте перезапуски до фактичного процесу `openclaw gateway run`, +`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Позначка +`enabled` для плагіна там означає, що збережений реєстр і поточна конфігурація дозволяють +плагіну брати участь у роботі. Це не доводить, що вже запущений віддалений дочірній процес Gateway +було перезапущено з тим самим кодом плагіна. У середовищах VPS/контейнерів з +процесами-обгортками надсилайте перезапуски фактичному процесу `openclaw gateway run` або використовуйте `openclaw gateway restart` для запущеного Gateway. - - - **Вимкнений**: Plugin існує, але правила ввімкнення вимкнули його. Конфігурація зберігається. - - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який не знайдено під час виявлення. - - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. Під час запуску Gateway пропускається лише цей Plugin; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та видаливши його корисне навантаження конфігурації. + + - **Вимкнений**: плагін існує, але правила ввімкнення вимкнули його. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення. + - **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі. Під час запуску Gateway пропускається лише цей плагін; `openclaw doctor --fix` може ізолювати недійсний запис, вимкнувши його та видаливши його вміст конфігурації. -## Виявлення та пріоритет +## Виявлення та пріоритетність -OpenClaw сканує Plugins в такому порядку (перший збіг має пріоритет): +OpenClaw сканує плагіни в такому порядку (перше знайдене збіг має пріоритет): - `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, які - вказують назад на власні паковані каталоги вбудованих Plugins OpenClaw, ігноруються; - виконайте `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. + `plugins.load.paths` — явні шляхи до файлів або каталогів. Шляхи, які вказують + назад на власні каталогі пакетних вбудованих плагінів OpenClaw, ігноруються; + запустіть `openclaw doctor --fix`, щоб видалити ці застарілі псевдоніми. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). + + Постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). Інші потребують явного ввімкнення. -Пакетні інсталяції та Docker-образи зазвичай визначають вбудовані Plugins із -скомпільованого дерева `dist/extensions`. Якщо каталог вихідного коду вбудованого Plugin -примонтовано bind-монтуванням поверх відповідного пакованого шляху вихідного коду, наприклад -`/app/extensions/synology-chat`, OpenClaw трактує цей примонтований каталог вихідного коду -як накладання джерела вбудованого Plugin і виявляє його раніше за пакований -пакет `/app/dist/extensions/synology-chat`. Це дає змогу циклам роботи супровідників у контейнерах -працювати без повернення кожного вбудованого Plugin до вихідного коду TypeScript. -Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати -паковані пакети dist, навіть коли присутні монтування з накладанням вихідного коду. +Пакетні інсталяції та Docker-образи зазвичай визначають вбудовані плагіни з +зібраного дерева `dist/extensions`. Якщо каталог вихідного коду вбудованого плагіна +монтується bind-монтуванням поверх відповідного пакетного шляху вихідного коду, наприклад +`/app/extensions/synology-chat`, OpenClaw розглядає цей змонтований каталог вихідного коду +як накладання вихідного коду вбудованого плагіна та виявляє його раніше за пакетний +пакет `/app/dist/extensions/synology-chat`. Це дозволяє циклам роботи супровідників у контейнерах +працювати без перемикання кожного вбудованого плагіна назад на вихідний код TypeScript. +Установіть `OPENCLAW_DISABLE_BUNDLED_SOURCE_OVERLAYS=1`, щоб примусово використовувати пакетні dist-збірки, +навіть якщо присутні змонтовані накладання вихідного коду. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі Plugins і пропускає роботу з виявлення/завантаження Plugins +- `plugins.enabled: false` вимикає всі плагіни й пропускає роботу з виявлення/завантаження плагінів - `plugins.deny` завжди має пріоритет над allow -- `plugins.entries.\.enabled: false` вимикає цей Plugin -- Plugins із походженням із робочого простору **типово вимкнені** (їх потрібно явно ввімкнути) -- Вбудовані Plugins дотримуються вбудованого набору типово ввімкнених, якщо не задано перевизначення -- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота -- Деякі вбудовані Plugins з добровільним увімкненням автоматично вмикаються, коли конфігурація називає - поверхню, що належить Plugin, наприклад посилання на модель провайдера, конфігурацію каналу або - середовище виконання harness -- Застаріла конфігурація Plugin зберігається, поки активний `plugins.enabled: false`; - знову ввімкніть Plugins перед запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори -- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugins: - `openai-codex/*` належить Plugin OpenAI, тоді як вбудований Plugin - app-server Codex вибирається через `agentRuntime.id: "codex"` або застарілі +- `plugins.entries.\.enabled: false` вимикає цей плагін +- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) +- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено +- Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота +- Деякі вбудовані opt-in плагіни вмикаються автоматично, коли конфігурація називає + поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або + runtime обв’язки +- Застаріла конфігурація плагіна зберігається, поки активне `plugins.enabled: false`; + знову ввімкніть плагіни перед запуском очищення doctor, якщо хочете видалити застарілі ідентифікатори +- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів: + `openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін Codex + app-server вибирається через `agentRuntime.id: "codex"` або застарілі посилання на модель `codex/*` -## Усунення проблем із хуками середовища виконання +## Усунення проблем із runtime-хуками -Якщо Plugin з’являється в `plugins list`, але побічні ефекти або хуки `register(api)` -не виконуються в трафіку живого чату, спочатку перевірте таке: +Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки +не запускаються в трафіку живого чату, спочатку перевірте таке: -- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні +- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні URL Gateway, профіль, шлях до конфігурації та процес — саме ті, які ви редагуєте. -- Перезапустіть живий Gateway після змін встановлення/конфігурації/коду Plugin. У контейнерах +- Перезапустіть активний Gateway після змін установлення/конфігурації/коду плагіна. У контейнерах з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. - Використайте `openclaw plugins inspect --json`, щоб підтвердити реєстрацію хуків і - діагностику. Для не вбудованих хукiв розмови, таких як `llm_input`, + діагностику. Для невбудованих conversation-хуків, таких як `llm_input`, `llm_output`, `before_agent_finalize` і `agent_end`, потрібен `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується перед - визначенням моделі для кроків агента; `llm_output` виконується лише після того, як спроба моделі - створить вивід асистента. +- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він запускається до + розв’язання моделі для ходів агента; `llm_output` запускається лише після того, як спроба моделі + дає відповідь асистента. - Для підтвердження фактичної моделі сесії використовуйте `openclaw sessions` або - поверхні сесії/стану Gateway, а під час налагодження корисних навантажень провайдера запускайте + поверхні сесії/статусу Gateway, а під час налагодження payload постачальника запускайте Gateway з `--raw-stream --raw-stream-path `. -### Дубльоване володіння каналом або інструментом +### Дублювання володіння каналом або інструментом Симптоми: @@ -303,81 +292,81 @@ OpenClaw сканує Plugins в такому порядку (перший зб - `channel setup already registered: ()` - `plugin tool name conflict (): ` -Це означає, що більше ніж один увімкнений Plugin намагається володіти тим самим каналом, -потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, -встановлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу. +Це означає, що більш ніж один увімкнений плагін намагається володіти тим самим каналом, +потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній плагін каналу, +установлений поруч із вбудованим плагіном, який тепер надає той самий ідентифікатор каналу. Кроки налагодження: -- Виконайте `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin - та його походження. -- Виконайте `openclaw plugins inspect --json` для кожного підозрілого Plugin і - порівняйте `channels`, `channelConfigs`, `tools` та діагностику. -- Виконайте `openclaw plugins registry --refresh` після встановлення або видалення - пакетів Plugin, щоб збережені метадані відображали поточне встановлення. -- Перезапустіть Gateway після змін встановлення, реєстру або конфігурації. +- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений плагін + і його походження. +- Запустіть `openclaw plugins inspect --json` для кожного підозрюваного плагіна та + порівняйте `channels`, `channelConfigs`, `tools` і діагностику. +- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення + пакетів плагінів, щоб збережені метадані відображали поточний стан установлення. +- Перезапустіть Gateway після змін установлення, реєстру або конфігурації. Варіанти виправлення: -- Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу, - бажаний Plugin має оголосити `channelConfigs..preferOver` з - ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). +- Якщо один плагін навмисно замінює інший для того самого ідентифікатора каналу, + бажаний плагін має оголосити `channelConfigs..preferOver` із + ідентифікатором плагіна з нижчим пріоритетом. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). - Якщо дублювання випадкове, вимкніть одну зі сторін через - `plugins.entries..enabled: false` або видаліть застаріле встановлення Plugin. -- Якщо ви явно ввімкнули обидва Plugins, OpenClaw зберігає цей запит і - повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте - інструменти, що належать Plugin, щоб поверхня середовища виконання була однозначною. + `plugins.entries..enabled: false` або видаліть застаріле встановлення плагіна. +- Якщо ви явно ввімкнули обидва плагіни, OpenClaw зберігає цей запит і + повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, + що належать плагіну, щоб поверхня runtime була однозначною. -## Слоти Plugin (ексклюзивні категорії) +## Слоти плагінів (ексклюзивні категорії) -Деякі категорії є ексклюзивними (одночасно активним може бути лише один): +Деякі категорії є ексклюзивними (одночасно може бути активним лише один): ```json5 { plugins: { slots: { - memory: "memory-core", // або "none", щоб вимкнути - contextEngine: "legacy", // або ідентифікатор Plugin + memory: "memory-core", // or "none" to disable + contextEngine: "legacy", // or a plugin id }, }, } ``` -| Слот | Що він керує | За замовчуванням | -| --------------- | ----------------------- | --------------------- | -| `memory` | Active Memory Plugin | `memory-core` | +| Слот | Що він контролює | Типово | +| --------------- | ----------------------- | ------------------- | +| `memory` | Active Memory plugin | `memory-core` | | `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | -## Довідник CLI +## Довідка CLI ```bash -openclaw plugins list # компактний список -openclaw plugins list --enabled # лише ввімкнені Plugins -openclaw plugins list --verbose # детальні рядки для кожного Plugin -openclaw plugins list --json # машиночитний список -openclaw plugins inspect # докладні деталі -openclaw plugins inspect --json # машиночитний формат -openclaw plugins inspect --all # таблиця для всього набору -openclaw plugins info # псевдонім inspect -openclaw plugins doctor # діагностика -openclaw plugins registry # перегляд збереженого стану реєстру -openclaw plugins registry --refresh # перебудова збереженого реєстру -openclaw doctor --fix # відновлення стану реєстру Plugin +openclaw plugins list # compact inventory +openclaw plugins list --enabled # only enabled plugins +openclaw plugins list --verbose # per-plugin detail lines +openclaw plugins list --json # machine-readable inventory +openclaw plugins inspect # deep detail +openclaw plugins inspect --json # machine-readable +openclaw plugins inspect --all # fleet-wide table +openclaw plugins info # inspect alias +openclaw plugins doctor # diagnostics +openclaw plugins registry # inspect persisted registry state +openclaw plugins registry --refresh # rebuild persisted registry +openclaw doctor --fix # repair plugin registry state -openclaw plugins install # встановлення (спочатку ClawHub, потім npm) -openclaw plugins install clawhub: # встановлення лише з ClawHub -openclaw plugins install npm: # встановлення лише з npm -openclaw plugins install --force # перезаписати наявне встановлення -openclaw plugins install # встановлення з локального шляху -openclaw plugins install -l # зв’язування (без копіювання) для розробки +openclaw plugins install # install (ClawHub first, then npm) +openclaw plugins install clawhub: # install from ClawHub only +openclaw plugins install npm: # install from npm only +openclaw plugins install --force # overwrite existing install +openclaw plugins install # install from local path +openclaw plugins install -l # link (no copy) for dev openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # записати точну визначену npm-специфікацію +openclaw plugins install --pin # record exact resolved npm spec openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # оновити один Plugin +openclaw plugins update # update one plugin openclaw plugins update --dangerously-force-unsafe-install -openclaw plugins update --all # оновити все -openclaw plugins uninstall # видалити конфігурацію та записи індексу Plugin +openclaw plugins update --all # update all +openclaw plugins uninstall # remove config and plugin index records openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -386,72 +375,71 @@ openclaw plugins enable openclaw plugins disable ``` -Вбудовані Plugins постачаються разом із OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, -вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований Plugin -браузера). Інші вбудовані Plugins усе ще потребують `openclaw plugins enable `. +Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, +вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований +browser-плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений Plugin або набір хуків на місці. Використовуйте -`openclaw plugins update ` для звичайних оновлень відстежуваних npm -Plugins. Цей параметр не підтримується з `--link`, який повторно використовує шлях до джерела -замість копіювання в керовану ціль встановлення. +`--force` перезаписує наявний установлений плагін або hook pack на місці. Використовуйте +`openclaw plugins update ` для звичайних оновлень відстежуваних npm- +плагінів. Він не підтримується з `--link`, який повторно використовує шлях до джерела +замість копіювання в керовану ціль установлення. -Коли `plugins.allow` уже задано, `openclaw plugins install` додає -ідентифікатор встановленого Plugin до цього списку allow перед його ввімкненням. Якщо той самий ідентифікатор Plugin -присутній у `plugins.deny`, встановлення видаляє цей застарілий запис deny, щоб -явно встановлений Plugin можна було одразу завантажити після перезапуску. +Коли `plugins.allow` уже встановлено, `openclaw plugins install` додає +ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням. Якщо той самий ідентифікатор плагіна +присутній у `plugins.deny`, установлення видаляє цей застарілий запис deny, щоб +явно встановлений плагін можна було одразу завантажити після перезапуску. -OpenClaw зберігає локальний реєстр Plugin як холодну модель читання для -обліку Plugins, володіння внесками та планування запуску. Потоки встановлення, оновлення, -видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану Plugin. -Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у -верхньорівневому `installRecords` і метадані маніфесту, які можна перебудувати, у `plugins`. Якщо +OpenClaw зберігає локальний реєстр плагінів як постійну модель холодного читання для +інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення, +видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану +плагіна. Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення у +верхньорівневому `installRecords` та відновлювані метадані маніфесту в `plugins`. Якщо реєстр відсутній, застарілий або недійсний, `openclaw plugins registry ---refresh` перебудовує його представлення маніфесту з записів встановлення, політики конфігурації та -метаданих маніфесту/пакета без завантаження модулів середовища виконання Plugin. -`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -npm-специфікації пакета з dist-tag або точною версією знову зіставляє назву пакета -із записом відстежуваного Plugin і записує нову специфікацію для майбутніх оновлень. -Передавання назви пакета без версії повертає точно закріплене встановлення назад до -типової лінії випуску реєстру. Якщо встановлений npm Plugin уже відповідає -визначеній версії та записаній ідентичності артефакта, OpenClaw пропускає оновлення -без завантаження, перевстановлення або переписування конфігурації. +--refresh` перебудовує його представлення маніфесту із записів установлення, політики конфігурації та +метаданих маніфесту/пакета без завантаження runtime-модулів плагіна. +`openclaw plugins update ` застосовується до відстежуваних установлень. Передавання +специфікації npm-пакета з dist-tag або точною версією зводить назву пакета +назад до відстежуваного запису плагіна та записує нову специфікацію для майбутніх оновлень. +Передавання назви пакета без версії повертає точно зафіксоване встановлення назад до +типової лінії випуску реєстру. Якщо встановлений npm-плагін уже відповідає +розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення +без завантаження, перевстановлення або перезапису конфігурації. -`--pin` працює лише для npm. Він не підтримується з `--marketplace`, оскільки -встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації. +`--pin` є лише для npm. Він не підтримується з `--marketplace`, тому що +установлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації. `--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних -спрацювань вбудованого сканера небезпечного коду. Воно дозволяє продовжити встановлення -та оновлення Plugin попри вбудовані результати `critical`, але все одно -не обходить блокування політики Plugin `before_install` або блокування через збої сканування. -Сканування встановлення ігнорує типові тестові файли та каталоги, такі як `tests/`, -`__tests__/`, `*.test.*` і `*.spec.*`, щоб уникнути блокування пакетованих тестових моків; -задекларовані точки входу середовища виконання Plugin усе одно скануються, навіть якщо вони використовують одну -з цих назв. +спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановлення плагінів +та оновлення плагінів попри вбудовані знахідки рівня `critical`, але все одно +не обходить блокування політики плагіна `before_install` або блокування через помилки сканування. +Сканування встановлення ігнорують поширені тестові файли та каталоги, такі як `tests/`, +`__tests__/`, `*.test.*` і `*.spec.*`, щоб не блокувати пакетні тестові моки; +оголошені runtime-точки входу плагіна все одно скануються, навіть якщо вони використовують одну з +цих назв. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Встановлення залежностей Skills -через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим потоком завантаження/встановлення Skills із ClawHub. +Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Установлення залежностей Skills через Gateway +замість цього використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як +`openclaw skills install` залишається окремим потоком завантаження/установлення Skills із ClawHub. Сумісні пакети беруть участь у тому самому потоці list/inspect/enable/disable -для Plugins. Поточна підтримка середовища виконання включає Skills пакетів, command-skills Claude, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і -`lspServers`, оголошені в маніфесті, command-skills Cursor і сумісні каталоги -хуків Codex. +для плагінів. Поточна підтримка runtime охоплює Skills у пакетах, Claude command-skills, +значення за замовчуванням Claude `settings.json`, значення за замовчуванням Claude `.lsp.json` і оголошені в маніфесті +`lspServers`, Cursor command-skills та сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також повідомляє про виявлені можливості пакетів, а також -підтримувані або непідтримувані записи MCP- і LSP-серверів для Plugins на основі пакетів. +`openclaw plugins inspect ` також повідомляє про виявлені можливості пакета, а також +підтримувані або непідтримувані записи MCP і LSP-серверів для плагінів на основі пакетів. -Джерелами marketplace можуть бути назва відомого marketplace Claude з -`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до -`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або URL git. Для віддалених marketplace записи Plugin мають залишатися в межах +Джерела marketplace можуть бути відомою назвою marketplace Claude з +`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або шляхом до +`marketplace.json`, скороченим записом GitHub на кшталт `owner/repo`, URL репозиторію GitHub або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах клонованого репозиторію marketplace і використовувати лише відносні шляхи джерел. -Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins). +Див. повну інформацію в [довідці CLI `openclaw plugins`](/uk/cli/plugins). -## Огляд API Plugin +## Огляд API плагінів -Нативні Plugins експортують об’єкт точки входу, який надає `register(api)`. Старіші -Plugins усе ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові Plugins повинні +Native-плагіни експортують вхідний об’єкт, який надає `register(api)`. Старіші +плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні використовувати `register`. ```typescript @@ -472,74 +460,73 @@ export default definePluginEntry({ }); ``` -OpenClaw завантажує об’єкт точки входу та викликає `register(api)` під час -активації Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugins, -але вбудовані Plugins і нові зовнішні Plugins повинні вважати `register` публічним контрактом. +OpenClaw завантажує вхідний об’єкт і викликає `register(api)` під час +активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів, +але вбудовані плагіни та нові зовнішні плагіни мають розглядати `register` як +публічний контракт. -`api.registrationMode` повідомляє Plugin, чому завантажується його точка входу: +`api.registrationMode` повідомляє плагіну, чому завантажується його вхідний об’єкт: -| Режим | Значення | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші побічні ефекти живого середовища. | -| `discovery` | Виявлення можливостей лише для читання. Реєструйте провайдерів і метадані; код точки входу довіреного Plugin може завантажуватися, але живі побічні ефекти слід пропускати. | -| `setup-only` | Завантаження метаданих налаштування каналу через полегшену точку входу налаштування. | -| `setup-runtime`| Завантаження налаштування каналу, яке також потребує точки входу середовища виконання. | -| `cli-metadata` | Лише збирання метаданих команд CLI. | +| Режим | Значення | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `full` | Активація runtime. Реєструйте інструменти, хуки, служби, команди, маршрути та інші побічні ефекти активної роботи. | +| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; код вхідного об’єкта довіреного плагіна може завантажуватися, але пропускайте побічні ефекти активної роботи. | +| `setup-only` | Завантаження метаданих налаштування каналу через полегшений вхідний об’єкт налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, яке також потребує runtime-вхідного об’єкта. | +| `cli-metadata` | Лише збирання метаданих команди CLI. | -Точки входу Plugin, які відкривають сокети, бази даних, фонові працівники або довготривалі -клієнти, повинні захищати ці побічні ефекти умовою `api.registrationMode === "full"`. +Записи плагінів, які відкривають сокети, бази даних, фонові воркери або довгоживучі +клієнти, повинні захищати ці побічні ефекти за допомогою `api.registrationMode === "full"`. Завантаження для виявлення кешуються окремо від активаційних завантажень і не замінюють -реєстр запущеного Gateway. Виявлення не активує, але й не є вільним від імпорту: -OpenClaw може обчислювати модуль точки входу довіреного Plugin або модуль Plugin каналу, щоб зібрати -знімок. Тримайте верхній рівень модулів легким і без побічних ефектів та переносіть -мережеві клієнти, підпроцеси, слухачі, читання облікових даних і запуск служб -за шляхи повного середовища виконання. +реєстр запущеного Gateway. Виявлення не активує runtime, але й не є вільним від імпорту: +OpenClaw може обчислювати довірений вхідний об’єкт плагіна або модуль channel-плагіна, щоб побудувати +знімок. Робіть верхні рівні модуля легкими та без побічних ефектів, а мережевих клієнтів, +підпроцеси, слухачів, зчитування облікових даних і запуск служб переносіть у шляхи повного runtime. Поширені методи реєстрації: -| Метод | Що він реєструє | -| -------------------------------------- | --------------------------- | -| `registerProvider` | Провайдер моделі (LLM) | -| `registerChannel` | Канал чату | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Хуки життєвого циклу | -| `registerSpeechProvider` | Синтез мовлення / STT | -| `registerRealtimeTranscriptionProvider`| Потоковий STT | -| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер отримання/скрейпінгу вебу | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP-ендпойнт | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Рушій контексту | -| `registerService` | Фонова служба | +| Метод | Що він реєструє | +| --------------------------------------- | -------------------------- | +| `registerProvider` | Постачальник моделей (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | +| `registerSpeechProvider` | Text-to-speech / STT | +| `registerRealtimeTranscriptionProvider` | Потоковий STT | +| `registerRealtimeVoiceProvider` | Двосторонній голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Постачальник отримання/скрапінгу вебданих | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP-ендпойнт | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Рушій контексту | +| `registerService` | Фонова служба | -Поведінка захисту хуків для типізованих хуків життєвого циклу: +Поведінка guard-хуків для типізованих хуків життєвого циклу: - `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує раніше встановлене блокування. +- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує раніше встановлене блокування. - `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує раніше встановлене блокування. +- `before_install`: `{ block: false }` нічого не робить і не скасовує раніше встановлене блокування. - `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує раніше встановлене скасування. +- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує раніше встановлене скасування. -Нативні запуски app-server Codex повертають події нативних інструментів Codex назад у цю -поверхню хуків. Plugins можуть блокувати нативні інструменти Codex через `before_tool_call`, -спостерігати за результатами через `after_tool_call` і брати участь у схваленнях -`PermissionRequest` Codex. Міст поки що не переписує аргументи нативних інструментів Codex. -Точна межа підтримки середовища виконання Codex описана в -[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). +Native Codex app-server повертає через міст події інструментів Codex-native назад у цю +поверхню хуків. Плагіни можуть блокувати native-інструменти Codex через `before_tool_call`, +спостерігати результати через `after_tool_call` і брати участь у схваленнях +Codex `PermissionRequest`. Міст поки що не переписує аргументи native-інструментів Codex. Точна межа підтримки runtime Codex описана в +[Codex harness v1 support contract](/uk/plugins/codex-harness#v1-support-contract). -Повну поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Щоб дізнатися про повну поведінку типізованих хуків, див. [огляд SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Створення plugins](/uk/plugins/building-plugins) — створіть власний Plugin -- [Пакети Plugin](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor -- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту -- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додайте інструменти агента в Plugin -- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження -- [Plugins спільноти](/uk/plugins/community) — сторонні списки +- [Building plugins](/uk/plugins/building-plugins) — створення власного плагіна +- [Plugin bundles](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor +- [Plugin manifest](/uk/plugins/manifest) — схема маніфесту +- [Registering tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін +- [Plugin internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження +- [Community plugins](/uk/plugins/community) — сторонні списки