diff --git a/docs/uk/ci.md b/docs/uk/ci.md index c0f4023fa..a36b973ad 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -2,100 +2,109 @@ read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, обмеження області дії та локальні еквіваленти команд +summary: Граф завдань CI, гейти за областю змін і локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-23T15:01:12Z" + generated_at: "2026-04-23T17:53:34Z" model: gpt-5.4 provider: openai - source_hash: e9a03440ae28a15167fc08d9c66bb1fd719ddfa1517aaecb119c80f2ad826c0d + source_hash: 1de796d57e79eda0328f20172f9029af485a57a3996bc8615e3a7bce281b7d85 source_path: ci.md workflow: 15 --- # Конвеєр CI -CI запускається для кожного push у `main` і для кожного pull request. Він використовує розумне обмеження області дії, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. +CI запускається під час кожного push у `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки. -QA Lab має окремі смуги CI поза основним робочим процесом із розумним обмеженням області. Робочий процес `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватне середовище виконання QA та порівнює агентні пакети mock GPT-5.4 і Opus 4.6. Робочий процес `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а смуга Telegram використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі смуги QA Lab перед погодженням релізу. +QA Lab має окремі гілки CI поза основним workflow з розумним визначенням області змін. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний запуск; він збирає приватний runtime QA і порівнює агентні пакети mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний запуск; він розгалужує mock parity gate, live lane Matrix і live lane Telegram як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а lane Telegram використовує оренди Convex. `OpenClaw Release Checks` також запускає ті самі lane QA Lab перед погодженням релізу. + +Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно вказані PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано і що кожен дублікат має або спільну згадану issue, або перекривні змінені hunks. + +```bash +gh workflow run duplicate-after-merge.yml \ + -f landed_pr=70532 \ + -f duplicate_prs='70530,70592' \ + -f apply=true +``` ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Визначення змін лише в документації, змінених областей, змінених розширень і побудова маніфесту 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, перевірки built-artifact і багаторазово використовуваних downstream-артефактів | Зміни, релевантні Node | -| `checks-fast-core` | Швидкі Linux-смуги коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні Node | -| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, релевантні Node | -| `checks-node-core-test` | Шарди тестів core Node, без смуг каналів, bundled, contract і extension | Зміни, релевантні Node | -| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request зі змінами в extension | -| `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-тести built-CLI і smoke перевірка пам’яті під час запуску | Зміни, релевантні Node | -| `checks` | Верифікатор для channel-тестів built-artifact плюс сумісність Node 22 лише для push | Зміни, релевантні Node | -| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Документацію змінено | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills | -| `checks-windows` | Windows-специфічні тестові смуги | Зміни, релевантні Windows | -| `macos-node` | Смуга тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні macOS | -| `macos-swift` | Lint, збірка та тести Swift для застосунку macOS | Зміни, релевантні macOS | -| `android` | Юніт-тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні Android | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | +| `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, перевірки built-artifact і перевикористовувані downstream-артефакти | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux lane коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шарди тестів bundled plugin у всьому наборі extensions | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди core Node тестів, окрім lane каналів, bundled, контрактів і extensions | Зміни, релевантні для Node | +| `extension-fast` | Сфокусовані тести лише для змінених bundled plugin | Pull request зі змінами в extensions | +| `check` | Шардований еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Архітектурні, boundary, guards поверхні extensions, package-boundary і shard gateway-watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка пам’яті під час старту | Зміни, релевантні для Node | +| `checks` | Верифікатор для built-artifact тестів каналів плюс lane сумісності Node 22 лише для push | Зміни, релевантні для Node | +| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Змінено docs | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows lane тестів | Зміни, релевантні для Windows | +| `macos-node` | Lane TypeScript тестів на macOS з використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Android unit-тести для обох flavor плюс одна debug APK збірка | Зміни, релевантні для Android | ## Порядок fail-fast -Завдання впорядковано так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запустяться дорогі: +Завдання впорядковано так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі: -1. `preflight` вирішує, які смуги взагалі існують. Логіка `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`, PR-only `extension-fast`, `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` падають швидко, не чекаючи важчих artifact- і platform-matrix-завдань. +3. `build-artifacts` виконується паралельно зі швидкими Linux lane, щоб downstream-споживачі могли почати роботу, щойно спільна збірка буде готова. +4. Після цього розгалужуються важчі platform і runtime lane: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покрита юніт-тестами в `src/scripts/ci-changed-scope.test.ts`. -Зміни в workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують виконувати нативні збірки Windows, Android або macOS; ці платформні смуги залишаються прив’язаними до змін у вихідному коді відповідних платформ. -Перевірки Windows Node обмежені специфічними для Windows обгортками процесів/шляхів, допоміжними засобами запуску npm/pnpm/UI runner, конфігурацією менеджера пакунків і поверхнями workflow CI, які виконують цю смугу; не пов’язані зміни у вихідному коді, plugin, install-smoke і зміни лише в тестах залишаються в Linux Node lanes, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже виконується звичайними тестовими шардами. -Окремий workflow `install-smoke` повторно використовує той самий скрипт області дії через власне завдання `preflight`. Він обчислює `run_install_smoke` на основі вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, релевантних встановленню, пакуванню, контейнерам, production changes у bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke jobs. Зміни лише в тестах і лише в документації не резервують Docker workers. Його smoke для QR package примушує Docker-шар `pnpm install` виконатися повторно, зберігаючи кеш BuildKit pnpm store, тому інсталяція все одно перевіряється без повторного завантаження залежностей під час кожного запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах цього завдання, тому додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локальна команда `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім паралельно запускає live/E2E smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте типову паралельність 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор типово припиняє планувати нові pooled lanes після першої помилки, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до запуску або провайдера, виконуються ексклюзивно після паралельного пулу. Багаторазово використовуваний workflow live/E2E відтворює шаблон shared-image: спочатку збирає і публікує один Docker E2E image із тегом SHA у GHCR перед матрицею Docker, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір для release-path. Тести QR та installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Окреме завдання `docker-e2e-fast` запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд: repair залежностей setup-entry плюс ізоляція синтетичної помилки bundled-loader. Повна матриця bundled update/channel залишається ручною/для повного набору, оскільки вона виконує повторні реальні проходи npm update і doctor repair. +Логіка області змін живе в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Редагування CI workflow перевіряє Node CI graph разом із lint перевіркою workflow, але саме по собі не примушує запускати нативні збірки Windows, Android або macOS; ці platform lane залишаються прив’язаними до змін у platform source. +Перевірки Windows Node прив’язані до специфічних для Windows обгорток process/path, helper-ів npm/pnpm/UI runner, конфігурації package manager і поверхонь CI workflow, які запускають цей lane; непов’язані зміни в source, plugin, install-smoke і лише тестові зміни залишаються в Linux Node lane, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже забезпечують звичайні шарди тестів. +Окремий workflow `install-smoke` повторно використовує той самий скрипт області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` з вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з install, packaging, контейнерами, production changes у bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Лише тестові та лише docs-редагування не резервують Docker workers. Його QR package smoke примушує шар Docker `pnpm install` виконатися повторно, зберігаючи cache сховища BuildKit pnpm, тому інсталяція все одно перевіряється без повторного завантаження залежностей під час кожного запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах цього завдання, тож додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локально `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lane паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартний рівень паралелізму 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled lane після першої помилки, а кожен lane має таймаут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до startup або provider, запускаються ексклюзивно після паралельного пулу. Повторно використовуваний workflow live/E2E віддзеркалює шаблон shared-image: він збирає і пушить один Docker E2E image у GHCR з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний релізний Docker suite. Docker-тести QR та installer зберігають власні install-орієнтовані Dockerfile. Окреме завдання `docker-e2e-fast` запускає обмежений Docker profile для bundled plugin з таймаутом команди 120 секунд: repair залежностей setup-entry плюс синтетична ізоляція збоїв bundled-loader. Повна matrix оновлення bundled і каналів залишається manual/full-suite, тому що вона виконує повторні реальні проходи npm update і doctor repair. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо архітектурних меж, ніж широка платформа області дії CI: зміни production у core запускають перевірку типів core prod плюс тести core, зміни лише в тестах core запускають лише перевірку типів/тести core test, зміни production у extension запускають перевірку типів extension prod плюс тести extension, а зміни лише в тестах extension запускають лише перевірку типів/тести extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку до extension, оскільки extension залежать від цих контрактів core. Зміни лише в метаданих релізу з оновленням версій запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно призводять до запуску всіх смуг. +Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіший щодо архітектурних boundary, ніж широка CI-область платформ: зміни в core production запускають core prod typecheck плюс core тести, лише зміни в core tests запускають лише core test typecheck/tests, зміни в extension production запускають extension prod typecheck плюс extension тести, а лише зміни в extension tests запускають лише extension test typecheck/tests. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extensions, тому що extensions залежать від цих core-контрактів. Зміни лише в release metadata для version bump запускають точкові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно призводять до запуску всіх lane. -Для push матриця `checks` додає смугу `compat-node22`, яка запускається лише для push. Для pull request ця смуга пропускається, і матриця зосереджується на звичайних test/channel lanes. +Для push matrix `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, а matrix залишається зосередженою на звичайних test/channel lane. -Найповільніші сімейства тестів Node розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів запускаються як три зважені шарди, тести bundled plugin балансуються між шістьма workers extension, малі core unit lanes об’єднані в пари, auto-reply виконується на трьох збалансованих workers замість шести малих workers, а agentic gateway/plugin configs розподілено між наявними agentic Node jobs лише для вихідного коду, замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої спеціалізовані конфігурації Vitest замість спільного універсального набору plugin. Широка смуга agents використовує спільний планувальник file-parallel Vitest, оскільки в ній домінують імпорти/планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не утримував хвіст виконання. `check-additional` тримає compile/canary роботу package-boundary разом і відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard виконує свої малі незалежні guards паралельно в межах одного завдання. Gateway watch, channel tests і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи їхні старі назви перевірок як легкі завдання-верифікатори та уникаючи двох додаткових Blacksmith workers і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Варіант third-party не має окремого source set або manifest; його смуга юніт-тестів усе одно компілює цей flavor із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK для кожного push, релевантного Android. -`extension-fast` є лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок щодо змінених plugin для рев’ю, не резервуючи додатковий Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. +Найповільніші сімейства Node тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів запускаються у трьох зважених shard, тести bundled plugin збалансовані між шістьма workers для extensions, невеликі core unit lane об’єднано попарно, auto-reply запускається в трьох збалансованих workers замість шести дрібних, а agentic gateway/plugin configs розподілено між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin тести використовують свої окремі конфігурації Vitest замість спільного універсального plugin-набору. Широкий lane agents використовує спільний file-parallel scheduler Vitest, тому що в ньому домінують імпорт і планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не залишався найдовшим. `check-additional` тримає разом роботу package-boundary compile/canary і відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно всередині одного завдання. Gateway watch, тести каналів і shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи їхні попередні назви перевірок як легкі завдання-верифікатори, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-тестів усе одно компілює цей flavor з прапорами SMS/call-log у BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK під час кожного Android-релевантного push. +`extension-fast` запускається лише для PR, тому що push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок щодо змінених plugin для review, не резервуючи додатковий Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати застарілі завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, щоб і далі повідомляти про звичайні помилки shard, але не ставали в чергу після того, як увесь workflow уже було витіснено новішим запуском. -Ключ конкурентності CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. +GitHub може позначати замінені новішими запусками завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо тільки найновіший запуск для того самого ref теж не падає. Агреговані shard checks використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні помилки shard, але не стають у чергу після того, як увесь workflow уже було замінено новішим. +Ключ concurrency у CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main. -## Runners +## Виконавці -| Runner | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегатори (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегатори `check-additional`, агрегатори-верифікатори тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує Ubuntu на GitHub-hosted, щоб матриця 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 використовується резервний варіант `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для fork використовується резервний варіант `macos-latest` | +| Виконавець | Завдання | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, shard `check`, окрім lint, shard `check-additional` і агрегати, aggregate verifier-и Node тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; `preflight` для install-smoke також використовує GitHub-hosted Ubuntu, щоб matrix Blacksmith могла стати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard Node тестів на Linux, 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 # розумний локальний gate: changed typecheck/lint/tests за boundary lane -pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні fast guards +pnpm check:changed # розумний локальний gate: typecheck/lint/tests для змін за boundary lane +pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # той самий gate із таймінгами для кожного етапу +pnpm check:timed # той самий gate з таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування документації + lint + зламані посилання -pnpm build # збирає dist, коли важливі смуги CI artifact/build-smoke -node scripts/ci-run-timings.mjs # підсумувати wall time, час у черзі та найповільніші завдання -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI +pnpm check:docs # форматування docs + lint + биті посилання +pnpm build # зібрати dist, коли важливі CI lane artifact/build-smoke +node scripts/ci-run-timings.mjs # підсумувати загальний час, час очікування в черзі та найповільніші завдання +node scripts/ci-run-timings.mjs --recent 10 # порівняти останні успішні запуски main CI ``` diff --git a/docs/uk/tools/exec-approvals.md b/docs/uk/tools/exec-approvals.md index 597fc3dbb..f80a80a75 100644 --- a/docs/uk/tools/exec-approvals.md +++ b/docs/uk/tools/exec-approvals.md @@ -1,65 +1,66 @@ --- read_when: - - Налаштування схвалень виконання або списків дозволеного - - Реалізація UX для схвалення виконання в застосунку macOS - - Перегляд підказок щодо виходу з пісочниці та їхніх наслідків -summary: Підказки щодо схвалення виконання, списків дозволеного та виходу з пісочниці -title: Схвалення виконання + - Налаштування підтверджень виконання або списків дозволених елементів + - Реалізація UX підтвердження виконання в застосунку для macOS + - Перегляд запитів на вихід із пісочниці та їхніх наслідків +summary: Підтвердження виконання, списки дозволених елементів і запити на вихід із пісочниці +title: Підтвердження виконання x-i18n: - generated_at: "2026-04-23T17:31:37Z" + generated_at: "2026-04-23T17:53:33Z" model: gpt-5.4 provider: openai - source_hash: edfc53f7f343969411f9cda848933e7a1ab80076257e4a0802910a910b3a47ea + source_hash: 942d09665ff9d567361b0c5ee195a5a6b8c893ea1c9412caa33a02acd8e5e5be source_path: tools/exec-approvals.md workflow: 15 --- -# Схвалення виконання +# Підтвердження виконання -Схвалення виконання — це **захисний механізм companion app / вузлового хоста** для того, щоб дозволити агенту в пісочниці запускати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли політика + список дозволеного + (необов’язкове) схвалення користувача збігаються. Схвалення виконання накладаються **поверх** політики інструментів і режиму підвищених прав (крім випадку, коли elevated встановлено в `full`, що пропускає схвалення). +Підтвердження виконання — це **захисний механізм застосунку-компаньйона / хоста node** для надання агенту в пісочниці можливості запускати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли збігаються політика + список дозволених елементів + (необов’язково) підтвердження користувача. Підтвердження виконання накладаються **поверх** політики інструментів і підвищеного доступу (окрім випадку, коли elevated встановлено в `full`, що пропускає підтвердження). -Ефективна політика — **суворіша** з `tools.exec.*` і типових налаштувань схвалень; якщо поле схвалень пропущене, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан схвалень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжуватиме запитувати підтвердження, навіть якщо типові значення сесії або конфігурації вказують `ask: "on-miss"`. +Ефективна політика є **суворішою** з `tools.exec.*` і типових значень підтверджень; якщо якесь поле підтверджень пропущене, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан підтверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжить показувати запити, навіть якщо сеанс або типові значення конфігурації вимагають `ask: "on-miss"`. ## Перегляд ефективної політики -- `openclaw approvals get`, `... --gateway`, `... --node ` — показати запитану політику, джерела політики хоста та ефективний результат. -- `openclaw exec-policy show` — об’єднане подання для локальної машини. -- `openclaw exec-policy set|preset` — синхронізувати локальну запитану політику з локальним файлом схвалень хоста в один крок. +- `openclaw approvals get`, `... --gateway`, `... --node ` — показують запитану політику, джерела політики хоста та ефективний результат. +- `openclaw exec-policy show` — об’єднане представлення для локальної машини. +- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом підтверджень хоста в один крок. -Коли локальна область запитує `host=node`, `exec-policy show` повідомляє про цю область як керовану вузлом під час виконання, замість того щоб удавати, що локальний файл схвалень є джерелом істини. +Коли локальна область видимості запитує `host=node`, `exec-policy show` повідомляє, що ця область керується node під час виконання, замість того щоб удавати, ніби локальний файл підтверджень є джерелом істини. -Якщо UI companion app **недоступний**, будь-який запит, який зазвичай мав би викликати запит на підтвердження, вирішується через **резервну поведінку ask** (типово: deny). +Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, який зазвичай вимагав би підтвердження, обробляється через **резервний режим ask** (типово: deny). -Нативні клієнти схвалення в чаті можуть наповнювати повідомлення про очікуване схвалення специфічними для каналу елементами керування. Наприклад, Matrix додає ярлики реакцій (`✅` дозволити один раз, `❌` заборонити, `♾️` дозволити завжди), при цьому залишаючи команди `/approve ...` у повідомленні як резервний варіант. +Нативні клієнти підтвердження в чаті можуть додавати специфічні для каналу елементи керування до повідомлення про очікуване підтвердження. Наприклад, Matrix додає швидкі реакції (`✅` +дозволити один раз, `❌` відхилити, `♾️` завжди дозволяти), водночас залишаючи команди `/approve ...` у повідомленні як запасний варіант. ## Де це застосовується -Схвалення виконання примусово застосовуються локально на хості виконання: +Підтвердження виконання застосовуються локально на хості виконання: -- **gateway host** → процес `openclaw` на машині Gateway -- **node host** → виконавець вузла (companion app для macOS або headless-вузловий хост) +- **хост gateway** → процес `openclaw` на машині gateway +- **хост node** → раннер node (застосунок-компаньйон для macOS або безголовий хост node) Примітка щодо моделі довіри: -- Виклики, автентифіковані через Gateway, вважаються довіреними операторами для цього Gateway. -- Спарені вузли розширюють цю можливість довіреного оператора на вузловий хост. -- Схвалення виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні окремого користувача. -- Схвалені запуски на вузловому хості прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, коли це застосовно. -- Для shell-скриптів і прямих викликів інтерпретатора/середовища виконання для файлів OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після схвалення, але до виконання, запуск забороняється замість виконання зміненого вмісту. -- Ця прив’язка файлів навмисно є best-effort, а не повною семантичною моделлю для кожного шляху завантаження інтерпретатора/середовища виконання. Якщо режим схвалення не може визначити рівно один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підкріплений схваленням, замість того щоб удавати повне покриття. +- Викликаючі сторони, автентифіковані через Gateway, є довіреними операторами для цього Gateway. +- Прив’язані nodes поширюють цю можливість довіреного оператора на хост node. +- Підтвердження виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні користувача. +- Схвалені запуски на хості node прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, де це застосовно. +- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту. +- Ця прив’язка файлу навмисно реалізована за принципом максимально можливого наближення, а не як повна семантична модель для кожного шляху завантаження інтерпретатора/середовища виконання. Якщо режим підтвердження не може точно визначити один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підкріплений підтвердженням, замість того щоб удавати повне покриття. -Поділ для macOS: +Поділ у macOS: -- **сервіс вузлового хоста** пересилає `system.run` до **застосунку macOS** через локальний IPC. -- **застосунок macOS** примусово застосовує схвалення + виконує команду в контексті UI. +- **служба хоста node** пересилає `system.run` до **застосунку macOS** через локальний IPC. +- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI. -## Налаштування та зберігання +## Налаштування і зберігання -Схвалення зберігаються в локальному JSON-файлі на хості виконання: +Підтвердження зберігаються в локальному JSON-файлі на хості виконання: `~/.openclaw/exec-approvals.json` @@ -98,30 +99,30 @@ x-i18n: } ``` -## Режим "YOLO" без схвалень +## Режим "YOLO" без підтверджень -Якщо ви хочете, щоб виконання на хості працювало без запитів на схвалення, потрібно відкрити **обидва** шари політики: +Якщо ви хочете, щоб виконання на хості працювало без запитів на підтвердження, потрібно відкрити **обидва** шари політики: - запитану політику виконання в конфігурації OpenClaw (`tools.exec.*`) -- локальну для хоста політику схвалень у `~/.openclaw/exec-approvals.json` +- локальну політику підтверджень хоста в `~/.openclaw/exec-approvals.json` Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою: - `tools.exec.security`: `full` на `gateway`/`node` - `tools.exec.ask`: `off` -- host `askFallback`: `full` +- `host askFallback`: `full` Важлива відмінність: -- `tools.exec.host=auto` вибирає, де виконуватиметься exec: у пісочниці, якщо вона доступна, інакше на gateway. -- YOLO визначає, як схвалюється виконання на хості: `security=full` плюс `ask=off`. -- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр схвалення для обфускації команд або шар відхилення попередньої перевірки скриптів поверх налаштованої політики виконання на хості. -- `auto` не робить маршрутизацію через gateway безкоштовним обходом із сесії в пісочниці. Запит `host=node` для окремого виклику дозволено з `auto`, а `host=gateway` дозволено з `auto` лише коли активне середовище пісочниці відсутнє. Якщо вам потрібне стабільне типове значення не `auto`, установіть `tools.exec.host` або явно використовуйте `/exec host=...`. +- `tools.exec.host=auto` вибирає, де запускається виконання: у пісочниці, якщо вона доступна, інакше на gateway. +- YOLO вибирає, як схвалюється виконання на хості: `security=full` плюс `ask=off`. +- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд або додатковий шар відхилення скриптів перед запуском поверх налаштованої політики виконання на хості. +- `auto` не робить маршрутизацію через gateway вільним обхідним шляхом із сеансу в пісочниці. Запит `host=node` для окремого виклику дозволений із `auto`, а `host=gateway` дозволяється з `auto` лише тоді, коли активного середовища пісочниці немає. Якщо вам потрібне стабільне типове значення не `auto`, встановіть `tools.exec.host` або використовуйте `/exec host=...` явно. -Якщо вам потрібне більш консервативне налаштування, знову зробіть будь-який із шарів суворішим до `allowlist` / `on-miss` +Якщо вам потрібне більш консервативне налаштування, зробіть будь-який із шарів суворішим, повернувши `allowlist` / `on-miss` або `deny`. -Постійне налаштування gateway-host "ніколи не запитувати": +Постійне налаштування "ніколи не запитувати" для хоста gateway: ```bash openclaw config set tools.exec.host gateway @@ -130,7 +131,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -Потім налаштуйте файл схвалень хоста відповідно: +Потім налаштуйте файл підтверджень хоста відповідним чином: ```bash openclaw approvals set --stdin <<'EOF' @@ -145,22 +146,22 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Локальний скорочений спосіб для тієї ж політики gateway-host на поточній машині: +Локальний скорочений варіант для тієї ж політики хоста gateway на поточній машині: ```bash openclaw exec-policy preset yolo ``` -Цей локальний скорочений спосіб оновлює обидва: +Цей локальний скорочений варіант оновлює обидва значення: - локальні `tools.exec.host/security/ask` -- локальні типові значення `~/.openclaw/exec-approvals.json` +- локальні типові значення в `~/.openclaw/exec-approvals.json` -Він навмисно працює лише локально. Якщо вам потрібно змінити схвалення gateway-host або node-host +Він навмисно працює лише локально. Якщо вам потрібно змінити підтвердження хоста gateway або хоста node віддалено, і надалі використовуйте `openclaw approvals set --gateway` або `openclaw approvals set --node `. -Для вузлового хоста застосуйте той самий файл схвалень на цьому вузлі: +Для хоста node застосуйте той самий файл підтверджень на цьому node: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -175,45 +176,45 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -Важливе обмеження лише для локальної машини: +Важливе обмеження лише для локального використання: -- `openclaw exec-policy` не синхронізує схвалення вузла +- `openclaw exec-policy` не синхронізує підтвердження node - `openclaw exec-policy set --host node` відхиляється -- схвалення виконання вузла отримуються з вузла під час виконання, тому оновлення, спрямовані на вузол, мають використовувати `openclaw approvals --node ...` +- підтвердження виконання для node отримуються з node під час виконання, тому оновлення, націлені на node, потрібно виконувати через `openclaw approvals --node ...` -Скорочений спосіб лише для сесії: +Скорочений варіант лише для сеансу: -- `/exec security=full ask=off` змінює лише поточну сесію. -- `/elevated full` — це аварійний shortcut, який також пропускає схвалення виконання для цієї сесії. +- `/exec security=full ask=off` змінює лише поточний сеанс. +- `/elevated full` — це аварійний скорочений варіант, який також пропускає підтвердження виконання для цього сеансу. -Якщо файл схвалень хоста залишається суворішим за конфігурацію, усе одно перемагає суворіша політика хоста. +Якщо файл підтверджень хоста залишається суворішим за конфігурацію, все одно перемагає суворіша політика хоста. -## Параметри політики +## Перемикачі політики -### Безпека (`exec.security`) +### Security (`exec.security`) - **deny**: блокувати всі запити на виконання на хості. -- **allowlist**: дозволяти лише команди зі списку дозволеного. +- **allowlist**: дозволяти лише команди зі списку дозволених елементів. - **full**: дозволяти все (еквівалентно elevated). ### Ask (`exec.ask`) - **off**: ніколи не запитувати. -- **on-miss**: запитувати лише тоді, коли список дозволеного не збігається. +- **on-miss**: запитувати лише тоді, коли список дозволених елементів не збігається. - **always**: запитувати для кожної команди. -- довірений режим `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always` +- довготривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask має значення `always` -### Резервна поведінка ask (`askFallback`) +### Ask fallback (`askFallback`) -Якщо потрібен запит на підтвердження, але жоден UI недоступний, резервна поведінка визначає: +Якщо потрібне підтвердження, але жоден UI недосяжний, резервний режим визначає результат: - **deny**: блокувати. -- **allowlist**: дозволяти лише якщо є збіг зі списком дозволеного. +- **allowlist**: дозволяти лише за збігу зі списком дозволених елементів. - **full**: дозволяти. -### Посилення для вбудованого eval інтерпретатора (`tools.exec.strictInlineEval`) +### Посилений режим для inline eval в інтерпретаторах (`tools.exec.strictInlineEval`) -Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми вбудованого виконання коду через eval як такі, що потребують явного схвалення, навіть якщо сам двійковий файл інтерпретатора є в списку дозволеного. +Коли `tools.exec.strictInlineEval=true`, OpenClaw трактує форми inline code-eval як такі, що потребують лише явного підтвердження, навіть якщо сам бінарний файл інтерпретатора додано до списку дозволених елементів. Приклади: @@ -225,15 +226,15 @@ EOF - `lua -e` - `osascript -e` -Це захист у глибину для механізмів завантаження інтерпретатора, які не можна чисто зіставити з одним стабільним файловим операндом. У строгому режимі: +Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються однозначно з одним стабільним файловим операндом. У строгому режимі: -- ці команди все одно потребують явного схвалення; -- `allow-always` не зберігає для них нові записи списку дозволеного автоматично. +- ці команди все одно потребують явного підтвердження; +- `allow-always` не зберігає автоматично нові записи списку дозволених елементів для них. -## Список дозволеного (для кожного агента) +## Список дозволених елементів (для кожного агента) -Списки дозволеного є **окремими для кожного агента**. Якщо існує кілька агентів, перемикайте агента, який ви редагуєте, у застосунку macOS. Патерни — це **глоб-збіги без урахування регістру**. Патерни мають указувати на **шляхи до двійкових файлів** (записи лише з basename ігноруються). Застарілі записи `agents.default` мігрують до `agents.main` під час завантаження. -Shell-ланцюжки, такі як `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволеного. +Списки дозволених елементів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, який редагується, у застосунку для macOS. Шаблони — це **глоб-збіги без урахування регістру**. Шаблони мають вказувати на **шляхи до бінарних файлів** (записи лише з базовою назвою ігноруються). Застарілі записи `agents.default` мігрують у `agents.main` під час завантаження. +Shell-ланцюжки на кшталт `echo ok && pwd` однаково вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволених елементів. Приклади: @@ -241,34 +242,41 @@ Shell-ланцюжки, такі як `echo ok && pwd`, усе одно вима - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Кожен запис списку дозволеного відстежує: +Кожен запис списку дозволених елементів відстежує: -- **id** — стабільний UUID, що використовується для ідентифікації в UI (необов’язково) -- **час останнього використання** +- **id** — стабільний UUID для ідентичності в UI (необов’язково) +- **останнє використання** — часову позначку - **остання використана команда** -- **останній розпізнаний шлях** +- **останній визначений шлях** ## Автодозвіл для CLI зі Skills Коли ввімкнено **Автодозвіл для CLI зі Skills**, виконувані файли, на які посилаються відомі Skills, -вважаються такими, що входять до списку дозволеного на вузлах (вузол macOS або headless-вузловий хост). Для цього використовується -`skills.bins` через Gateway RPC, щоб отримати список bin-файлів Skills. Вимкніть це, якщо хочете суворі ручні списки дозволеного. +вважаються такими, що входять до списку дозволених елементів на nodes (macOS node або безголовий хост node). Для цього використовується +`skills.bins` через Gateway RPC, щоб отримати список бінарних файлів Skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволених елементів. Важливі примітки щодо довіри: -- Це **неявний список дозволеного для зручності**, окремий від ручних записів списку дозволеного за шляхами. -- Він призначений для середовищ із довіреними операторами, де Gateway і вузол перебувають в одній межі довіри. -- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволеного за шляхами. +- Це **неявний зручний список дозволених елементів**, окремий від ручних записів списку шляхів. +- Він призначений для середовищ довірених операторів, де Gateway і node перебувають в одній межі довіри. +- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволених шляхів. -## Безпечні bin-файли (лише stdin) +## Safe bins (лише stdin) -`tools.exec.safeBins` визначає невеликий список **bin-файлів лише для stdin** (наприклад `cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволеного. Безпечні bin-файли відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри. +`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, +`cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволених елементів. Safe bins відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тож +вони можуть працювати лише з вхідним потоком. Сприймайте це як вузький швидкий шлях для +потокових фільтрів, а не як загальний список довіри. -**Не** додавайте двійкові файли інтерпретаторів або середовищ виконання (наприклад `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код, виконувати підкоманди або читати файли, надавайте перевагу явним записам списку дозволеного й залишайте запити на схвалення ввімкненими. Користувацькі безпечні bin-файли мають визначати явний профіль у `tools.exec.safeBinProfiles.`. +**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад `python3`, `node`, +`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда може обчислювати код, +виконувати підкоманди або читати файли за своєю природою, надавайте перевагу явним записам у списку дозволених елементів +і залишайте запити на підтвердження ввімкненими. Користувацькі safe bins мають визначати явний +профіль у `tools.exec.safeBinProfiles.`. -Типові безпечні bin-файли: +Типові safe bins: [//]: # "SAFE_BIN_DEFAULTS:START" @@ -276,163 +284,162 @@ Shell-ланцюжки, такі як `echo ok && pwd`, усе одно вима [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` і `sort` не входять до типового списку. Якщо ви вирішите їх увімкнути, зберігайте явні записи списку дозволеного для їхніх сценаріїв, що не обмежуються stdin. Для `grep` у режимі safe-bin +`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні +записи списку дозволених елементів для їхніх робочих сценаріїв, відмінних від stdin. Для `grep` у режимі safe-bin вказуйте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється, -щоб файлові операнди не можна було замаскувати як неоднозначні позиційні аргументи. +щоб файлові операнди не можна було приховано передати як неоднозначні позиційні аргументи. Перевірка є детермінованою лише за формою argv (без перевірок існування - файлової системи хоста), що запобігає поведінці файлового оракула через - відмінності між дозволом і забороною. Файлоорієнтовані опції заборонені для - типових безпечних bin-файлів; довгі опції перевіряються за принципом fail-closed - (невідомі прапорці та неоднозначні скорочення відхиляються). + файлів у файловій системі хоста), що запобігає поведінці оракула існування файлів через відмінності між + дозволом і відмовою. Для типових safe bins файлово-орієнтовані параметри заборонені; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці й неоднозначні скорочення відхиляються). Заборонені прапорці за профілем safe-bin: [//]: # "SAFE_BIN_DENIED_FLAGS:START" - - `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` - - `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` - - `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` - - `wc`: `--files0-from` +- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` +- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` +- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` +- `wc`: `--files0-from` [//]: # "SAFE_BIN_DENIED_FLAGS:END" - Безпечні bin-файли також примусово трактують токени argv як **буквальний текст** - під час виконання (без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, - тож шаблони на кшталт `*` або `$HOME/...` не можуть використовуватися для прихованого читання - файлів. + Safe bins також примусово трактують токени argv як **буквальний текст** під + час виконання (без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, + тому шаблони на кшталт `*` або `$HOME/...` не можна використати для прихованого читання + файлів. - + - - Безпечні bin-файли мають визначатися з довірених каталогів двійкових файлів (системні типові - значення плюс необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не - стають довіреними автоматично. Типові довірені каталоги навмисно мінімальні: - `/bin`, `/usr/bin`. Якщо виконуваний файл вашого safe-bin розташований у - шляхах менеджера пакетів/користувача (наприклад `/opt/homebrew/bin`, - `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до - `tools.exec.safeBinTrustedDirs`. - + + Safe bins мають визначатися з довірених каталогів бінарних файлів (системні типові + значення плюс необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не + вважаються довіреними автоматично. Типові довірені каталоги навмисно мінімальні: + `/bin`, `/usr/bin`. Якщо ваш виконуваний файл safe-bin розташований у + шляхах менеджера пакетів/користувача (наприклад `/opt/homebrew/bin`, + `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до + `tools.exec.safeBinTrustedDirs`. + - - Ланцюжки shell-команд (`&&`, `||`, `;`) дозволені, коли кожен сегмент верхнього рівня - відповідає списку дозволеного (включно з безпечними bin-файлами або автодозволом для Skills). - Переспрямування залишаються непідтримуваними в режимі allowlist. Підстановка команд - (`$()` / зворотні лапки) відхиляється під час розбору allowlist, зокрема всередині - подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. + + Shell-ланцюжки (`&&`, `||`, `;`) дозволені, якщо кожен сегмент верхнього рівня + відповідає списку дозволених елементів + (включно з safe bins або автодозволом для Skills). + Перенаправлення в режимі allowlist, як і раніше, не підтримуються. Підстановка команд + (`$()` / зворотні лапки) відхиляється під час аналізу allowlist, зокрема всередині + подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. - У схваленнях companion app для macOS необроблений shell-текст, що містить керувальний - або розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, - `)`), вважається пропуском allowlist, якщо сам двійковий файл shell не - входить до списку дозволеного. + У підтвердженнях застосунку-компаньйона для macOS необроблений shell-текст, що містить shell-керування + або синтаксис розгортання (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, + `)`), вважається промахом allowlist, якщо сам shell-бінарний файл не входить до + списку дозволених елементів. - Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту - зводяться до невеликого явного allowlist (`TERM`, `LANG`, - `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). + Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту + зводяться до невеликого явного списку дозволених елементів (`TERM`, `LANG`, + `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). - Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери - (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях до внутрішнього виконуваного файла - замість шляху до самої обгортки. Shell-мультиплексори (`busybox`, `toybox`) так само - розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо - обгортку або мультиплексор не можна безпечно розгорнути, запис allowlist не зберігається автоматично. + Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери + (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях внутрішнього виконуваного файла + замість шляху обгортки. Shell-мультиплексори (`busybox`, `toybox`) + так само розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо + обгортку або мультиплексор неможливо безпечно розгорнути, запис allowlist не зберігається автоматично. - Якщо ви додаєте інтерпретатори на кшталт `python3` або `node` до allowlist, краще - використовувати `tools.exec.strictInlineEval=true`, щоб вбудований eval усе одно вимагав - явного схвалення. У строгому режимі `allow-always` усе ще може зберігати - нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval не зберігаються - автоматично. + Якщо ви додаєте до allowlist інтерпретатори на кшталт `python3` або `node`, краще + встановити `tools.exec.strictInlineEval=true`, щоб inline eval і далі вимагав + явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі + виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. -### Безпечні bin-файли проти allowlist +### Safe bins порівняно зі списком allowlist | Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | Мета | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів | -| Тип збігу | Назва виконуваного файла + політика argv safe-bin | Глоб-патерн для шляху до визначеного виконуваного файла | -| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише збіг за шляхом; за аргументи в іншому відповідаєте ви | +| Тип збігу | Ім’я виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла | +| Обсяг аргументів | Обмежений профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи в іншому відповідаєте ви | | Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI | -| Найкраще застосування | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | +| Найкраще використання | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | Розташування конфігурації: -- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для окремого агента). -- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для окремого агента). -- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для окремого агента). Ключі профілів окремого агента перевизначають глобальні ключі. +- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для агента). +- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для агента). +- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для агента). Ключі профілю для агента перевизначають глобальні ключі. - записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). -- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли двійкові файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. -- `openclaw doctor --fix` може згенерувати відсутні користувацькі записи `safeBinProfiles.` як `{}` (після цього перегляньте й посильте їх). Двійкові файли інтерпретатора/середовища виконання не генеруються автоматично. +- `openclaw security audit` попереджає за допомогою `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. +- `openclaw doctor --fix` може створити відсутні користувацькі записи `safeBinProfiles.` у вигляді `{}` (після цього перегляньте й посильте їх). Бінарні файли інтерпретатора/середовища виконання автоматично не створюються. Приклад користувацького профілю: __OC_I18N_900005__ Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє вбудовану команду `env` у режимі safe-bin, щоб `jq -n env` не міг вивантажити середовище процесу хоста без явного шляху allowlist -або запиту на схвалення. +або запиту на підтвердження. ## Редагування в Control UI -Використовуйте картку **Control UI → Nodes → Exec approvals** для редагування типових значень, перевизначень -для окремих агентів і allowlist. Виберіть область (Defaults або агент), змініть політику, -додайте/видаліть патерни allowlist, а потім натисніть **Save**. UI показує метадані **last used** -для кожного патерна, щоб вам було простіше підтримувати список у впорядкованому стані. +Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення +для окремих агентів і списки allowlist. Виберіть область видимості (типові значення або агент), змініть політику, +додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **останнього використання** +для кожного шаблону, щоб список було зручно підтримувати в порядку. -Селектор цілі вибирає **Gateway** (локальні схвалення) або **Node**. Вузли -мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-вузловий хост). -Якщо вузол ще не оголошує exec approvals, редагуйте його локальний +Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Nodes +мають оголошувати `system.execApprovals.get/set` (застосунок для macOS або безголовий хост node). +Якщо node ще не оголошує підтримку підтверджень виконання, редагуйте його локальний `~/.openclaw/exec-approvals.json` безпосередньо. -CLI: `openclaw approvals` підтримує редагування gateway або node (див. [Approvals CLI](/cli/approvals)). +CLI: `openclaw approvals` підтримує редагування для gateway або node (див. [CLI підтверджень](/cli/approvals)). -## Потік схвалення +## Потік підтвердження -Коли потрібен запит на схвалення, gateway транслює `exec.approval.requested` клієнтам-операторам. -Control UI і застосунок macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає -схвалений запит на вузловий хост. +Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам-операторам. +Control UI і застосунок для macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає +схвалений запит до хоста node. -Для `host=node` запити на схвалення містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує -цей план як авторитетний контекст команди/cwd/сесії під час пересилання схвалених запитів `system.run`. +Для `host=node` запити на підтвердження включають канонічне корисне навантаження `systemRunPlan`. Gateway використовує +цей план як авторитетний контекст команди/cwd/сеансу під час пересилання схвалених запитів `system.run`. -Це важливо для затримки асинхронного схвалення: +Це важливо для затримки асинхронного підтвердження: -- шлях виконання node готує один канонічний план заздалегідь -- запис схвалення зберігає цей план і його метадані прив’язки -- після схвалення фінальний пересланий виклик `system.run` повторно використовує збережений план - замість довіри до пізніших змін виклику -- якщо виклик змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` після створення запиту на схвалення, gateway відхиляє - пересланий запуск як невідповідність схваленню +- шлях виконання node заздалегідь готує один канонічний план +- запис підтвердження зберігає цей план і його метадані прив’язки +- після схвалення остаточний пересланий виклик `system.run` повторно використовує збережений план, + замість того щоб довіряти пізнішим змінам викликача +- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або + `sessionKey` після створення запиту на підтвердження, gateway відхиляє + пересланий запуск як невідповідність підтвердженню ## Команди інтерпретатора/середовища виконання -Запуски інтерпретатора/середовища виконання, підкріплені схваленням, навмисно є консервативними: +Запуски інтерпретатора/середовища виконання, підкріплені підтвердженням, навмисно зроблено консервативними: - Точний контекст argv/cwd/env завжди прив’язується. -- Прямі форми shell-скриптів і прямі форми runtime-файлів best-effort прив’язуються до одного конкретного локального - знімка файлу. -- Поширені форми обгорток менеджерів пакетів, які все ще визначаються в один прямий локальний файл (наприклад +- Форми прямого shell-скрипта і прямого файла середовища виконання прив’язуються за принципом максимально можливого наближення до одного конкретного + знімка локального файла. +- Поширені форми обгорток менеджерів пакетів, які все ще визначаються до одного прямого локального файла (наприклад `pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою. - Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання - (наприклад package scripts, форми eval, ланцюжки завантажувачів, специфічні для runtime, або неоднозначні багатофайлові - форми), виконання, підкріплене схваленням, відхиляється замість того, щоб заявляти семантичне покриття, якого воно не - має. -- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний - довірений робочий процес allowlist/full, де оператор приймає ширшу семантику runtime. + (наприклад, для пакетних скриптів, форм eval, специфічних для середовища виконання ланцюжків завантаження або неоднозначних багатофайлових + форм), виконання, підкріплене підтвердженням, відхиляється замість того, щоб заявляти семантичне покриття, якого + насправді немає. +- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний довірений + процес allowlist/full, де оператор приймає ширшу семантику середовища виконання. -Коли потрібні схвалення, інструмент exec негайно повертає ідентифікатор схвалення. Використовуйте цей ідентифікатор, щоб -зіставляти пізніші системні події (`Exec finished` / `Exec denied`). Якщо до завершення часу очікування -рішення не надходить, запит розглядається як тайм-аут схвалення й відображається як причина відмови. +Коли потрібні підтвердження, інструмент exec відразу повертає id підтвердження. Використовуйте цей id, щоб +зіставляти пізніші системні події (`Exec finished` / `Exec denied`). Якщо до завершення +тайм-ауту не надходить рішення, запит вважається тайм-аутом підтвердження і відображається як причина відмови. -### Поведінка доставки наступного повідомлення +### Поведінка доставки подальших повідомлень -Після завершення схваленого асинхронного exec OpenClaw надсилає наступний хід `agent` у ту саму сесію. +Після завершення схваленого асинхронного виконання OpenClaw надсилає подальший хід `agent` до того самого сеансу. -- Якщо існує коректна зовнішня ціль доставки (канал доставки плюс цільовий `to`), доставка наступного повідомлення використовує цей канал. -- У потоках лише webchat або внутрішніх сесій без зовнішньої цілі доставка наступного повідомлення залишається лише в межах сесії (`deliver: false`). -- Якщо виклик явно запитує сувору зовнішню доставку без жодного визначуваного зовнішнього каналу, запит завершується помилкою `INVALID_REQUEST`. -- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не може бути визначений, доставка знижується до лише-сесійної замість помилки. +- Якщо існує дійсна зовнішня ціль доставки (канал, який підтримує доставку, плюс ціль `to`), доставка подальших повідомлень використовує цей канал. +- У потоках лише webchat або внутрішнього сеансу без зовнішньої цілі доставка подальших повідомлень залишається лише в межах сеансу (`deliver: false`). +- Якщо викликач явно запитує сувору зовнішню доставку без зовнішнього каналу, який можна визначити, запит завершується помилкою `INVALID_REQUEST`. +- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не вдається визначити, доставка знижується до лише-сеансової замість помилки. Діалог підтвердження містить: @@ -440,116 +447,116 @@ Control UI і застосунок macOS обробляють це через `e - cwd - id агента - визначений шлях до виконуваного файла -- метадані хоста + політики +- хост + метадані політики Дії: -- **Allow once** → виконати зараз -- **Always allow** → додати до allowlist + виконати +- **Allow once** → запустити зараз +- **Always allow** → додати до allowlist + запустити - **Deny** → заблокувати -## Пересилання схвалень до чат-каналів +## Пересилання підтверджень до чат-каналів -Ви можете пересилати запити на схвалення exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати -їх за допомогою `/approve`. Для цього використовується звичайний конвеєр вихідної доставки. +Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати +їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки. Конфігурація: __OC_I18N_900006__ Відповідь у чаті: __OC_I18N_900007__ -Команда `/approve` обробляє як exec approvals, так і схвалення Plugin. Якщо ID не відповідає жодному очікуваному схваленню exec, вона автоматично перевіряє натомість схвалення Plugin. +Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin. Якщо ID не збігається з очікуваним підтвердженням exec, вона автоматично перевіряє підтвердження Plugin. -### Пересилання схвалень Plugin +### Пересилання підтверджень Plugin -Пересилання схвалень Plugin використовує той самий конвеєр доставки, що й exec approvals, але має власну +Пересилання підтверджень Plugin використовує той самий конвеєр доставки, що й підтвердження exec, але має власну незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше. __OC_I18N_900008__ Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`, -`sessionFilter` і `targets` працюють однаково. +`sessionFilter` і `targets` працюють так само. -Канали, які підтримують спільні інтерактивні відповіді, відображають ті самі кнопки схвалення як для exec, так і для -схвалень Plugin. Канали без спільного інтерактивного UI використовують звичайний текст із -інструкціями `/approve`. +Канали, що підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для +підтверджень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями +`/approve`. -### Схвалення в тому самому чаті на будь-якому каналі +### Підтвердження в тому самому чаті на будь-якому каналі -Коли запит на схвалення exec або Plugin походить із чат-поверхні, придатної для доставки, цей самий чат -тепер може схвалити його через `/approve` типово. Це застосовується до таких каналів, як Slack, Matrix і -Microsoft Teams, на додачу до вже наявних потоків Web UI та terminal UI. +Коли запит на підтвердження exec або Plugin походить із чат-поверхні, що підтримує доставку, цей самий чат +тепер типово може схвалити його через `/approve`. Це застосовується до таких каналів, як Slack, Matrix і +Microsoft Teams, на додачу до вже наявних потоків у Web UI та terminal UI. -Цей спільний шлях текстових команд використовує звичайну модель автентифікації каналу для цієї розмови. Якщо -чат-джерело вже може надсилати команди й отримувати відповіді, запитам на схвалення більше не потрібен -окремий нативний адаптер доставки лише для того, щоб залишатися очікуваними. +Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо +початковий чат уже може надсилати команди й отримувати відповіді, для запитів на підтвердження більше не потрібен +окремий нативний адаптер доставки лише для того, щоб вони залишалися очікуваними. -Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все одно використовують свій -визначений список затверджувачів для авторизації, навіть коли нативну доставку схвалень вимкнено. +Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все ще використовують свій +визначений список затверджувачів для авторизації, навіть коли нативну доставку підтверджень вимкнено. -Для Telegram та інших нативних клієнтів схвалення, які викликають Gateway напряму, -цей резервний механізм навмисно обмежено збоями типу "схвалення не знайдено". Реальна -відмова/помилка схвалення exec не повторюється мовчки як схвалення Plugin. +Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway безпосередньо, +цей запасний механізм навмисно обмежено помилками типу «підтвердження не знайдено». Справжня +відмова/помилка підтвердження exec не повторюється мовчки як підтвердження Plugin. -### Нативна доставка схвалень +### Нативна доставка підтверджень -Деякі канали також можуть діяти як нативні клієнти схвалення. Нативні клієнти додають DM для затверджувачів, fanout у початковий чат -і специфічний для каналу інтерактивний UX схвалення поверх спільного потоку `/approve` +Деякі канали також можуть діяти як нативні клієнти підтвердження. Нативні клієнти додають DM для затверджувачів, fanout до початкового чату +та специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` у тому самому чаті. -Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним -шляхом для агента. Агент також не повинен дублювати звичайну чат-команду -`/approve`, якщо тільки результат інструмента не вказує, що чат-схвалення недоступні або -ручне схвалення — єдиний шлях, що залишився. +Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним +шляхом, видимим агенту. Агент також не повинен дублювати звичайну чат-команду +`/approve`, якщо результат інструмента не вказує, що чат-підтвердження недоступні або +ручне підтвердження є єдиним шляхом, що залишився. Загальна модель: -- політика виконання на хості все одно визначає, чи потрібне схвалення exec -- `approvals.exec` керує пересиланням запитів на схвалення до інших чат-цілей -- `channels..execApprovals` керує тим, чи діє цей канал як нативний клієнт схвалення +- політика виконання на хості все одно визначає, чи потрібне підтвердження exec +- `approvals.exec` керує пересиланням запитів на підтвердження до інших чат-цілей +- `channels..execApprovals` керує тим, чи діє цей канал як нативний клієнт підтвердження -Нативні клієнти схвалення автоматично вмикають доставку спочатку в DM, коли виконуються всі ці умови: +Нативні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі наведені умови істинні: -- канал підтримує нативну доставку схвалень -- затверджувачів можна визначити з явних `execApprovals.approvers` або з - документованих резервних джерел цього каналу -- `channels..execApprovals.enabled` не встановлено або дорівнює `"auto"` +- канал підтримує нативну доставку підтверджень +- затверджувачів можна визначити з явних `execApprovals.approvers` або з документованих резервних джерел цього + каналу +- `channels..execApprovals.enabled` не встановлено або має значення `"auto"` -Установіть `enabled: false`, щоб явно вимкнути нативний клієнт схвалення. Установіть `enabled: true`, щоб примусово -увімкнути його, коли затверджувачів визначено. Публічна доставка в початковий чат залишається явною через +Установіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Установіть `enabled: true`, щоб примусово +увімкнути його, коли затверджувачі визначаються. Публічна доставка до початкового чату й надалі явно керується через `channels..execApprovals.target`. -FAQ: [Чому для чат-схвалень існують дві конфігурації схвалення exec?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +FAQ: [Чому для підтверджень exec у чаті є дві конфігурації?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord: `channels.discord.execApprovals.*` - Slack: `channels.slack.execApprovals.*` - Telegram: `channels.telegram.execApprovals.*` -Ці нативні клієнти схвалення додають маршрутизацію в DM та необов’язковий fanout у канал поверх спільного -потоку `/approve` у тому самому чаті та спільних кнопок схвалення. +Ці нативні клієнти підтвердження додають маршрутизацію в DM і необов’язковий fanout до каналу поверх спільного +потоку `/approve` у тому самому чаті та спільних кнопок підтвердження. Спільна поведінка: -- Slack, Matrix, Microsoft Teams та подібні чати з можливістю доставки використовують звичайну модель автентифікації каналу +- Slack, Matrix, Microsoft Teams та подібні чати з підтримкою доставки використовують звичайну модель автентифікації каналу для `/approve` у тому самому чаті -- коли нативний клієнт схвалення вмикається автоматично, типовою нативною ціллю доставки є DM затверджувачів -- для Discord і Telegram лише визначені затверджувачі можуть схвалювати або забороняти -- затверджувачі Discord можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- затверджувачі Telegram можуть бути явними (`execApprovals.approvers`) або виведеними з наявної конфігурації власника (`allowFrom`, плюс `defaultTo` для прямих повідомлень, де це підтримується) -- затверджувачі Slack можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- нативні кнопки Slack зберігають тип id схвалення, тож ідентифікатори `plugin:` можуть визначати схвалення Plugin +- коли нативний клієнт підтвердження вмикається автоматично, типовою нативною ціллю доставки є DM затверджувачів +- для Discord і Telegram лише визначені затверджувачі можуть схвалювати або відхиляти +- затверджувачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- затверджувачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації власника (`allowFrom`, плюс `defaultTo` для direct-message, де це підтримується) +- затверджувачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- нативні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть визначати підтвердження Plugin без другого локального для Slack резервного шару -- нативна маршрутизація Matrix для DM/каналу та ярлики реакцій обробляють і exec, і схвалення Plugin; - авторизація Plugin все одно надходить із `channels.matrix.dm.allowFrom` +- нативна маршрутизація Matrix у DM/канал і швидкі реакції обробляють як підтвердження exec, так і Plugin; + авторизація Plugin і далі надходить із `channels.matrix.dm.allowFrom` - запитувач не обов’язково має бути затверджувачем -- початковий чат може схвалювати напряму через `/approve`, коли цей чат уже підтримує команди й відповіді -- нативні кнопки схвалення Discord маршрутизуються за типом id схвалення: ідентифікатори `plugin:` переходять - безпосередньо до схвалень Plugin, усе інше переходить до схвалень exec -- нативні кнопки схвалення Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve` -- коли нативний `target` вмикає доставку в початковий чат, запити на схвалення містять текст команди -- очікувані схвалення exec типово спливають через 30 хвилин -- якщо жоден UI оператора або налаштований клієнт схвалення не може прийняти запит, запит переходить до `askFallback` +- початковий чат може підтвердити запит безпосередньо через `/approve`, коли цей чат уже підтримує команди та відповіді +- нативні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять + безпосередньо до підтверджень Plugin, усе інше — до підтверджень exec +- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve` +- коли нативний `target` вмикає доставку до початкового чату, запити на підтвердження включають текст команди +- очікувані підтвердження exec типово спливають через 30 хвилин +- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, підтвердження переходить до `askFallback` -Telegram типово використовує DM затверджувачів (`target: "dm"`). Ви можете перемкнути на `channel` або `both`, якщо -хочете, щоб запити на схвалення також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram -OpenClaw зберігає тему для запиту на схвалення та наступного повідомлення після схвалення. +Для Telegram типовим є DM затверджувачів (`target: "dm"`). Ви можете переключитися на `channel` або `both`, якщо +хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram +OpenClaw зберігає тему для запиту на підтвердження і подальшого повідомлення після підтвердження. Дивіться: @@ -560,9 +567,9 @@ OpenClaw зберігає тему для запиту на схвалення __OC_I18N_900009__ Примітки щодо безпеки: -- Режим Unix-сокета `0600`, токен зберігається в `exec-approvals.json`. -- Перевірка peer з тим самим UID. -- Challenge/response (nonce + HMAC token + хеш запиту) + короткий TTL. +- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`. +- Перевірка однотипного UID. +- Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL. ## Системні події @@ -572,34 +579,34 @@ __OC_I18N_900009__ - `Exec finished` - `Exec denied` -Вони публікуються в сесію агента після того, як вузол повідомляє про подію. -Схвалення exec на gateway-host надсилають ті самі події життєвого циклу, коли команда завершується (і необов’язково коли виконується довше за поріг). -Exec із контролем через схвалення повторно використовують id схвалення як `runId` у цих повідомленнях для зручного зіставлення. +Вони публікуються в сеансі агента після того, як node повідомляє про подію. +Підтвердження exec на хості gateway генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, під час виконання довше за поріг). +Exec, які проходять через підтвердження, повторно використовують id підтвердження як `runId` у цих повідомленнях для зручного зіставлення. -## Поведінка при відхиленому схваленні +## Поведінка при відхиленні підтвердження -Коли асинхронне схвалення exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати -вивід із будь-якого попереднього запуску тієї самої команди в сесії. Причина відмови -передається з явною вказівкою, що вивід команди недоступний, що зупиняє -агента від тверджень про наявність нового виводу або повторення відхиленої команди зі +Коли асинхронне підтвердження exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати +вивід будь-якого попереднього запуску тієї самої команди в межах сеансу. Причина відмови +передається з явною вказівкою, що жодного виводу команди немає, що зупиняє +агента від заяв про новий вивід або повторення відхиленої команди зі застарілими результатами попереднього успішного запуску. ## Наслідки -- **full** — потужний режим; за можливості надавайте перевагу allowlist. -- **ask** залишає вас у циклі, водночас даючи змогу швидко схвалювати. -- Списки дозволеного для окремих агентів не дають схваленням одного агента проникати до інших. -- Схвалення застосовуються лише до запитів на виконання на хості від **авторизованих відправників**. Неавторизовані відправники не можуть викликати `/exec`. -- `/exec security=full` — це зручний параметр рівня сесії для авторизованих операторів, і він навмисно пропускає схвалення. Щоб жорстко заблокувати виконання на хості, установіть для безпеки схвалень `deny` або забороніть інструмент `exec` через політику інструментів. +- **full** має широкі повноваження; де можливо, віддавайте перевагу allowlist. +- **ask** тримає вас у контурі, водночас дозволяючи швидкі підтвердження. +- Списки allowlist для окремих агентів не дають підтвердженням одного агента просочуватися до інших. +- Підтвердження застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть викликати `/exec`. +- `/exec security=full` — це зручний варіант на рівні сеансу для авторизованих операторів, який навмисно пропускає підтвердження. Щоб жорстко заблокувати host exec, установіть для security підтверджень значення `deny` або забороніть інструмент `exec` через політику інструментів. ## Пов’язане - + Інструмент виконання shell-команд. - Аварійний шлях, який також пропускає схвалення. + Аварійний шлях, який також пропускає підтвердження. Режими пісочниці та доступ до робочого простору. @@ -607,8 +614,8 @@ Exec із контролем через схвалення повторно ви Модель безпеки та посилення захисту. - - Коли варто використовувати кожен із цих механізмів. + + Коли слід використовувати кожен із цих механізмів керування. Поведінка автодозволу на основі Skills.