chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
21a072f0e1
commit
a837eca18e
File diff suppressed because it is too large
Load Diff
120
docs/uk/ci.md
120
docs/uk/ci.md
@ -2,24 +2,24 @@
|
||||
read_when:
|
||||
- Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося
|
||||
- Ви налагоджуєте збої перевірок GitHub Actions
|
||||
summary: Граф завдань CI, гейти за областю змін і локальні еквіваленти команд
|
||||
summary: Граф завдань CI, обмеження області, і локальні еквіваленти команд
|
||||
title: Конвеєр CI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T17:53:34Z"
|
||||
generated_at: "2026-04-23T18:24:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1de796d57e79eda0328f20172f9029af485a57a3996bc8615e3a7bce281b7d85
|
||||
source_hash: 089e7b4dc59bf11ad643ced552537b761da62314717a15b7971e2abc7053a38b
|
||||
source_path: ci.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Конвеєр CI
|
||||
|
||||
CI запускається під час кожного push у `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані ділянки.
|
||||
CI запускається при кожному push у `main` і для кожного pull request. Він використовує розумне обмеження області, щоб пропускати дорогі завдання, коли змінено лише непов’язані частини.
|
||||
|
||||
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 перед погодженням релізу.
|
||||
QA Lab має окремі смуги CI поза основним workflow з розумним обмеженням області. Workflow `Parity gate` запускається для відповідних змін у PR і через manual dispatch; він збирає приватне середовище виконання QA і порівнює агентні набори mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram lane використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі смуги QA Lab перед схваленням релізу.
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -30,81 +30,81 @@ gh workflow run duplicate-after-merge.yml \
|
||||
|
||||
## Огляд завдань
|
||||
|
||||
| Завдання | Призначення | Коли запускається |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- |
|
||||
| `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 |
|
||||
| Завдання | Призначення | Коли запускається |
|
||||
| -------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ |
|
||||
| `preflight` | Визначає зміни лише в docs, змінені області, змінені extensions і будує маніфест CI | Завжди для non-draft push і PR |
|
||||
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR |
|
||||
| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR |
|
||||
| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для non-draft push і PR |
|
||||
| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built artifacts і багаторазово використовувані downstream artifacts | Зміни, релевантні для Node |
|
||||
| `checks-fast-core` | Швидкі correctness-смуги Linux, такі як bundled/plugin-contract/protocol checks | Зміни, релевантні для Node |
|
||||
| `checks-fast-contracts-channels` | Шардовані перевірки контрактів channel зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node |
|
||||
| `checks-node-extensions` | Повні шарди тестів bundled plugin у всьому наборі extension | Зміни, релевантні для Node |
|
||||
| `checks-node-core-test` | Шарди тестів core Node, за винятком смуг channel, bundled, contract та extension | Зміни, релевантні для Node |
|
||||
| `extension-fast` | Сфокусовані тести лише для змінених bundled plugin | Pull request із змінами extension |
|
||||
| `check` | Шардований еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node |
|
||||
| `check-additional` | Architecture, boundary, guards поверхні extension, package-boundary та шарди gateway-watch | Зміни, релевантні для Node |
|
||||
| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка startup-memory | Зміни, релевантні для Node |
|
||||
| `checks` | Верифікатор для built-artifact тестів channel плюс compat-напрям Node 22 лише для push | Зміни, релевантні для Node |
|
||||
| `check-docs` | Форматування docs, lint і перевірки зламаних посилань | Змінено docs |
|
||||
| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills |
|
||||
| `checks-windows` | Специфічні для Windows тестові смуги | Зміни, релевантні для Windows |
|
||||
| `macos-node` | Смуга тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні для macOS |
|
||||
| `macos-swift` | Lint, build і тести Swift для застосунку macOS | Зміни, релевантні для macOS |
|
||||
| `android` | Юніт-тести Android для обох flavor плюс одна збірка debug APK | Зміни, релевантні для Android |
|
||||
|
||||
## Порядок fail-fast
|
||||
## Порядок 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` падають швидко, не чекаючи важчих 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`.
|
||||
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`, `extension-fast` лише для PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
|
||||
|
||||
Логіка області змін живе в `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.
|
||||
Логіка області знаходиться в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`.
|
||||
Зміни workflow CI перевіряють граф Node CI плюс lint workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформені смуги залишаються обмеженими змінами у вихідному коді відповідних платформ.
|
||||
Перевірки Windows Node обмежені специфічними для Windows обгортками process/path, допоміжними засобами для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, що виконують цю смугу; непов’язані зміни вихідного коду, plugin, install-smoke і лише тестів залишаються в Linux Node smугам, щоб не резервувати Windows worker на 16 vCPU для покриття, яке вже виконується звичайними test shards.
|
||||
Окремий workflow `install-smoke` повторно використовує той самий скрипт області через власне завдання `preflight`. Він обчислює `run_install_smoke` із вужчого сигналу changed-smoke, тож Docker/install smoke запускається для змін, пов’язаних з install, packaging, контейнерами, production-змін bundled extension, а також для поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише тестів і лише docs не резервують Docker workers. Його smoke QR package змушує шар Docker `pnpm install` виконатися повторно, зберігаючи кеш BuildKit pnpm store, тож він усе одно перевіряє встановлення без повторного завантаження залежностей при кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в цьому завданні, тож додає реальне покриття WebSocket контейнер-до-контейнера без додавання ще однієї Docker build. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-смуги паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартний паралелізм 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled-smуги після першої помилки, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до startup або provider, виконуються ексклюзивно після паралельного пулу. Багаторазово використовуваний live/E2E workflow повторює шаблон спільного image, збираючи й публікуючи один GHCR Docker E2E image з тегом SHA перед Docker matrix, а потім запускає matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний Docker suite шляху релізу. Docker-тести QR та installer зберігають власні install-орієнтовані Dockerfile. Окреме завдання `docker-e2e-fast` запускає обмежений профіль Docker для bundled plugin з тайм-аутом команди 120 секунд: відновлення залежностей setup-entry плюс ізоляція синтетичного збою bundled-loader. Повна матриця bundled update/channel залишається ручною/повним набором, оскільки виконує повторні реальні проходи npm update і doctor repair.
|
||||
|
||||
Локальна логіка 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.
|
||||
Локальна логіка 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 безпечно переводять до всіх смуг.
|
||||
|
||||
Для push matrix `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, а matrix залишається зосередженою на звичайних test/channel lane.
|
||||
Для push матриця `checks` додає смугу `compat-node22`, яка запускається лише для push. Для pull request ця смуга пропускається, і матриця залишається зосередженою на звичайних test/channel смугах.
|
||||
|
||||
Найповільніші сімейства 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`.
|
||||
Найповільніші сімейства тестів Node розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти channel запускаються в трьох зважених shards, тести bundled plugin балансуються між шістьма worker-ами extension, малі core unit-смуги поєднані в пари, auto-reply запускається на трьох збалансованих worker-ах замість шести дрібних worker-ів, а конфігурації agentic gateway/plugin розподілені по наявних source-only agentic Node jobs замість очікування built artifacts. Широкі browser-, QA-, media- і miscellaneous plugin-тести використовують власні конфігурації Vitest замість спільного plugin catch-all. Завдання shard extension можуть запускати дві групи конфігурацій plugin одночасно, але обмежують кожну конфігурацію Vitest одним worker-ом, щоб важкі за імпортом пакети plugin не перевантажували малі CI runner-и. Широка agents-смуга використовує спільний Vitest file-parallel scheduler, тому що в ній домінують імпорт і планування, а не один повільний тестовий файл. `runtime-config` запускається разом із shard infra core-runtime, щоб спільний runtime shard не залишався хвостом. `check-additional` тримає package-boundary compile/canary-роботи разом і відокремлює архітектуру topology runtime від покриття gateway watch; shard boundary guard запускає свої невеликі незалежні guards паралельно в межах одного завдання. Gateway watch, channel tests і core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи їхні старі назви перевірок як легкі verifier jobs, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів.
|
||||
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його смуга 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 checks використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні помилки shard, але не стають у чергу після того, як увесь workflow уже було замінено новішим.
|
||||
Ключ concurrency у CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main.
|
||||
GitHub може позначати заміщені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо лише найновіший запуск для того самого ref також не завершується з помилкою. Агреговані перевірки shards використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої shards, але не стають у чергу після того, як увесь workflow уже було заміщено.
|
||||
Ключ concurrency для CI має версію (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски `main`.
|
||||
|
||||
## Виконавці
|
||||
|
||||
| Виконавець | Завдання |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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` |
|
||||
| Виконавець | Завдання |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів channel, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори тестів Node, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує Ubuntu, розміщений на GitHub, щоб матриця 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` |
|
||||
|
||||
## Локальні еквіваленти
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD
|
||||
pnpm check:changed # розумний локальний gate: typecheck/lint/tests для змін за boundary lane
|
||||
pnpm changed:lanes # перевірити локальний класифікатор changed-lane для origin/main...HEAD
|
||||
pnpm check:changed # розумний локальний gate: changed 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 # форматування docs + lint + биті посилання
|
||||
pnpm build # зібрати dist, коли важливі CI lane artifact/build-smoke
|
||||
node scripts/ci-run-timings.mjs <run-id> # підсумувати загальний час, час очікування в черзі та найповільніші завдання
|
||||
node scripts/ci-run-timings.mjs --recent 10 # порівняти останні успішні запуски main CI
|
||||
pnpm check:docs # форматування docs + lint + зламані посилання
|
||||
pnpm build # зібрати dist, коли важливі смуги CI artifact/build-smoke
|
||||
node scripts/ci-run-timings.mjs <run-id> # підсумувати загальний час, час у черзі й найповільніші завдання
|
||||
node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски CI для main
|
||||
```
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
2092
docs/uk/help/faq.md
2092
docs/uk/help/faq.md
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw не працює, і вам потрібен найшвидший шлях до виправлення
|
||||
- Ви хочете пройти потік тріажу, перш ніж занурюватися в детальні інструкції щодо усунення проблем
|
||||
- Ви хочете пройти процес тріажу, перш ніж заглиблюватися в докладні інструкції з усунення проблем
|
||||
summary: Центр усунення несправностей OpenClaw за симптомами
|
||||
title: Загальне усунення несправностей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-20T06:31:12Z"
|
||||
generated_at: "2026-04-23T18:24:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88
|
||||
source_hash: c6931ea9a8f29de0aa42c0afdf554e223fd2a794e95dce4f4795db99301d2c44
|
||||
source_path: help/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Усунення несправностей
|
||||
|
||||
Якщо у вас є лише 2 хвилини, використайте цю сторінку як початкову точку тріажу.
|
||||
Якщо у вас є лише 2 хвилини, використовуйте цю сторінку як вхідну точку для тріажу.
|
||||
|
||||
## Перші 60 секунд
|
||||
|
||||
Виконайте цю точну послідовність команд по порядку:
|
||||
Виконайте цю точну послідовність команд у вказаному порядку:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -31,14 +31,14 @@ openclaw channels status --probe
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Ознаки коректного виводу в одному рядку:
|
||||
Хороший результат в один рядок:
|
||||
|
||||
- `openclaw status` → показує налаштовані канали й відсутність очевидних помилок автентифікації.
|
||||
- `openclaw status --all` → повний звіт присутній і ним можна поділитися.
|
||||
- `openclaw gateway probe` → очікуваний Gateway призначення доступний (`Reachable: yes`). `Capability: ...` показує, який рівень автентифікації змогла підтвердити перевірка, а `Read probe: limited - missing scope: operator.read` означає погіршену діагностику, а не збій з’єднання.
|
||||
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` і правдоподібний рядок `Capability: ...`. Використовуйте `--require-rpc`, якщо вам також потрібне підтвердження RPC з доступом на читання.
|
||||
- `openclaw doctor` → немає блокувальних помилок конфігурації/сервісу.
|
||||
- `openclaw channels status --probe` → доступний Gateway повертає поточний стан транспорту для кожного облікового запису разом із результатами перевірки/аудиту, наприклад `works` або `audit ok`; якщо Gateway недоступний, команда повертається до зведень лише за конфігурацією.
|
||||
- `openclaw status` → показує налаштовані канали та відсутність явних помилок автентифікації.
|
||||
- `openclaw status --all` → повний звіт наявний і ним можна поділитися.
|
||||
- `openclaw gateway probe` → очікувана ціль Gateway доступна (`Reachable: yes`). `Capability: ...` показує, який рівень автентифікації вдалося підтвердити перевіркою, а `Read probe: limited - missing scope: operator.read` означає погіршену діагностику, а не збій з’єднання.
|
||||
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` і правдоподібний рядок `Capability: ...`. Використовуйте `--require-rpc`, якщо вам також потрібне підтвердження RPC з областю читання.
|
||||
- `openclaw doctor` → відсутні блокувальні помилки конфігурації або сервісу.
|
||||
- `openclaw channels status --probe` → доступний Gateway повертає живий стан транспорту для кожного облікового запису разом із результатами probe/audit, такими як `works` або `audit ok`; якщо Gateway недоступний, команда повертається до зведень лише на основі конфігурації.
|
||||
- `openclaw logs --follow` → стабільна активність, без повторюваних фатальних помилок.
|
||||
|
||||
## 429 для довгого контексту Anthropic
|
||||
@ -49,23 +49,16 @@ openclaw logs --follow
|
||||
|
||||
## Локальний OpenAI-compatible бекенд працює напряму, але не працює в OpenClaw
|
||||
|
||||
Якщо ваш локальний або self-hosted бекенд `/v1` відповідає на малі прямі перевірки
|
||||
`/v1/chat/completions`, але завершується помилкою на `openclaw infer model run` або під час звичайних
|
||||
ходів агента:
|
||||
Якщо ваш локальний або самостійно розгорнутий `/v1` бекенд відповідає на невеликі прямі перевірки `/v1/chat/completions`, але не працює з `openclaw infer model run` або під час звичайних ходів агента:
|
||||
|
||||
1. Якщо в помилці згадується, що `messages[].content` очікує рядок, установіть
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
2. Якщо бекенд і далі дає збій лише під час ходів агента OpenClaw, установіть
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false` і повторіть спробу.
|
||||
3. Якщо крихітні прямі виклики все ще працюють, але більші запити OpenClaw аварійно завершують
|
||||
бекенд, вважайте решту проблеми обмеженням моделі/сервера на боці вищого рівня і
|
||||
продовжуйте в детальній інструкції:
|
||||
1. Якщо в помилці згадується, що `messages[].content` очікує рядок, встановіть `models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
2. Якщо бекенд і далі не працює лише під час ходів агента OpenClaw, встановіть `models.providers.<provider>.models[].compat.supportsTools: false` і повторіть спробу.
|
||||
3. Якщо крихітні прямі виклики все ще працюють, але більші підказки OpenClaw аварійно завершують роботу бекенда, розглядайте решту проблеми як обмеження моделі/сервера на боці upstream і переходьте до докладної інструкції:
|
||||
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/uk/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
|
||||
|
||||
## Не вдається встановити Plugin через відсутні openclaw extensions
|
||||
|
||||
Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет Plugin
|
||||
використовує стару структуру, яку OpenClaw більше не приймає.
|
||||
Якщо встановлення завершується помилкою `package.json missing openclaw.extensions`, пакет Plugin використовує старий формат, який OpenClaw більше не приймає.
|
||||
|
||||
Виправлення в пакеті Plugin:
|
||||
|
||||
@ -97,8 +90,8 @@ flowchart TD
|
||||
B --> E[Gateway не запускається або сервіс не працює]
|
||||
B --> F[Канал підключається, але повідомлення не проходять]
|
||||
B --> G[Cron або Heartbeat не спрацював чи не доставив повідомлення]
|
||||
B --> H[Node спарено, але не працює інструмент camera canvas screen exec]
|
||||
B --> I[Не працює інструмент browser]
|
||||
B --> H[Node спарено, але camera canvas screen exec не працює]
|
||||
B --> I[Не працює інструмент браузера]
|
||||
|
||||
C --> C1[/Розділ «Немає відповідей»/]
|
||||
D --> D1[/Розділ «Control UI»/]
|
||||
@ -106,7 +99,7 @@ flowchart TD
|
||||
F --> F1[/Розділ «Потік каналу»/]
|
||||
G --> G1[/Розділ «Автоматизація»/]
|
||||
H --> H1[/Розділ «Інструменти Node»/]
|
||||
I --> I1[/Розділ «Browser»/]
|
||||
I --> I1[/Розділ «Браузер»/]
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
@ -119,21 +112,21 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- `Runtime: running`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` або `admin-capable`
|
||||
- Ваш канал показує підключений транспорт і, де це підтримується, `works` або `audit ok` у `channels status --probe`
|
||||
- Відправника показано як схваленого (або політика DM відкрита/є в allowlist)
|
||||
- Відправника показано як схваленого (або політика DM відкрита/дозволений список)
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `drop guild message (mention required` → обробку повідомлення було заблоковано вимогою згадки в Discord.
|
||||
- `pairing request` → відправника не схвалено, він очікує на схвалення спарювання в DM.
|
||||
- `blocked` / `allowlist` у журналах каналу → відправника, кімнату або групу відфільтровано.
|
||||
- `drop guild message (mention required` → у Discord повідомлення було заблоковане вимогою згадки.
|
||||
- `pairing request` → відправник не схвалений і очікує підтвердження спарювання DM.
|
||||
- `blocked` / `allowlist` у журналах каналу → відправник, кімната або група фільтруються.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#no-replies](/uk/gateway/troubleshooting#no-replies)
|
||||
- [/channels/troubleshooting](/uk/channels/troubleshooting)
|
||||
@ -150,28 +143,28 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- `Dashboard: http://...` показано в `openclaw gateway status`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` або `admin-capable`
|
||||
- У журналах немає циклу автентифікації
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `device identity required` → HTTP/незахищений контекст не може завершити автентифікацію пристрою.
|
||||
- `origin not allowed` → `Origin` браузера не дозволений для Gateway призначення Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` із підказками повторної спроби (`canRetryWithDeviceToken=true`) → автоматично може відбутися одна повторна спроба з довіреним токеном пристрою.
|
||||
- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають запитаний ними набір scope.
|
||||
- На асинхронному шляху Tailscale Serve для Control UI невдалі спроби для одного й того ж `{scope, ip}` серіалізуються до того, як лімітер зафіксує збій, тому друга одночасна хибна повторна спроба вже може показувати `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` з браузерного localhost-origin → повторні невдалі спроби з того самого `Origin` тимчасово блокуються; інший localhost-origin використовує окремий bucket.
|
||||
- повторювані `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідність режиму автентифікації або застарілий спарений токен пристрою.
|
||||
- `gateway connect failed:` → UI націлено на неправильний URL/порт або Gateway недоступний.
|
||||
- `origin not allowed` → `Origin` браузера не дозволений для цілі Gateway у Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` із підказками для повтору (`canRetryWithDeviceToken=true`) → одна довірена повторна спроба з токеном пристрою може відбутися автоматично.
|
||||
- Ця повторна спроба з кешованим токеном повторно використовує кешований набір областей, збережений разом зі спареним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` замість цього зберігають власний запитаний набір областей.
|
||||
- В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зафіксує збій, тому друга одночасна хибна повторна спроба вже може показувати `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` з локального джерела браузера localhost → повторні невдалі спроби з цього самого `Origin` тимчасово блокуються; інше джерело localhost використовує окремий bucket.
|
||||
- повторюване `unauthorized` після цієї повторної спроби → неправильний токен/пароль, невідповідний режим автентифікації або застарілий спарений токен пристрою.
|
||||
- `gateway connect failed:` → UI націлений на неправильний URL/порт або Gateway недоступний.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/uk/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
- [/web/control-ui](/uk/web/control-ui)
|
||||
- [/gateway/authentication](/uk/gateway/authentication)
|
||||
|
||||
</Accordion>
|
||||
@ -185,20 +178,20 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- `Service: ... (loaded)`
|
||||
- `Runtime: running`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` або `admin-capable`
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим Gateway встановлено як remote, або у файлі конфігурації відсутня позначка local-mode і його слід виправити.
|
||||
- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації Gateway (token/password або trusted-proxy, де налаштовано).
|
||||
- `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнято.
|
||||
- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → режим Gateway віддалений, або у файлі конфігурації відсутня позначка локального режиму і його слід відновити.
|
||||
- `refusing to bind gateway ... without auth` → прив’язка не-loopback без дійсного шляху автентифікації Gateway (токен/пароль або trusted-proxy, якщо налаштовано).
|
||||
- `another gateway instance is already listening` або `EADDRINUSE` → порт уже зайнятий.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#gateway-service-not-running](/uk/gateway/troubleshooting#gateway-service-not-running)
|
||||
- [/gateway/background-process](/uk/gateway/background-process)
|
||||
@ -215,19 +208,19 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- Транспорт каналу підключений.
|
||||
- Перевірки pairing/allowlist проходять.
|
||||
- Згадки визначаються там, де вони обов’язкові.
|
||||
- Перевірки pairing/allowlist успішні.
|
||||
- Згадки виявляються там, де вони потрібні.
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `mention required` → обробку заблоковано вимогою згадки в групі.
|
||||
- `pairing` / `pending` → відправника DM ще не схвалено.
|
||||
- `pairing` / `pending` → відправника в DM ще не схвалено.
|
||||
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → проблема з токеном дозволів каналу.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/uk/gateway/troubleshooting#channel-connected-messages-not-flowing)
|
||||
- [/channels/troubleshooting](/uk/channels/troubleshooting)
|
||||
@ -244,147 +237,147 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- `cron.status` показує, що його ввімкнено, і вказує час наступного пробудження.
|
||||
- `cron runs` показує нещодавні записи `ok`.
|
||||
- Heartbeat увімкнено й він не поза межами активних годин.
|
||||
- `cron.status` показує, що все ввімкнено і є наступне пробудження.
|
||||
- `cron runs` показує недавні записи `ok`.
|
||||
- Heartbeat увімкнено і він не поза межами активних годин.
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено.
|
||||
- `heartbeat skipped` з `reason=quiet-hours` → поза налаштованими активними годинами.
|
||||
- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній/header-only каркас.
|
||||
- `heartbeat skipped` з `reason=no-tasks-due` → увімкнено режим завдань `HEARTBEAT.md`, але час для жодного з інтервалів завдань ще не настав.
|
||||
- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожній/лише-заголовки каркас.
|
||||
- `heartbeat skipped` з `reason=no-tasks-due` → у `HEARTBEAT.md` активний режим завдань, але ще не настав час для жодного з інтервалів завдань.
|
||||
- `heartbeat skipped` з `reason=alerts-disabled` → усю видимість Heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені).
|
||||
- `requests-in-flight` → основна смуга зайнята; пробудження Heartbeat було відкладено.
|
||||
- `unknown accountId` → цільовий account доставки Heartbeat не існує.
|
||||
- `requests-in-flight` → основна смуга зайнята; пробудження Heartbeat було відкладене.
|
||||
- `unknown accountId` → цільовий обліковий запис доставки Heartbeat не існує.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/uk/gateway/troubleshooting#cron-and-heartbeat-delivery)
|
||||
- [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting)
|
||||
- [/gateway/heartbeat](/uk/gateway/heartbeat)
|
||||
|
||||
</Accordion>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Node спарено, але інструмент не працює: camera canvas screen exec">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
openclaw logs --follow
|
||||
```
|
||||
<Accordion title="Node спарено, але інструмент не працює: camera canvas screen exec">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw nodes status
|
||||
openclaw nodes describe --node <idOrNameOrIp>
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- Node показано як підключений і спарений для ролі `node`.
|
||||
- Для команди, яку ви викликаєте, існує Capability.
|
||||
- Для інструмента надано стан дозволу.
|
||||
- Node указано як підключений і спарений для ролі `node`.
|
||||
- Для команди, яку ви викликаєте, існує Capability.
|
||||
- Стан дозволів для інструмента надано.
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок Node на передній план.
|
||||
- `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено/він відсутній.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist для exec.
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → переведіть застосунок node на передній план.
|
||||
- `*_PERMISSION_REQUIRED` → дозвіл ОС було відхилено/відсутній.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → команди немає в allowlist exec.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails)
|
||||
- [/nodes/troubleshooting](/uk/nodes/troubleshooting)
|
||||
- [/tools/exec-approvals](/uk/tools/exec-approvals)
|
||||
- [/gateway/troubleshooting#node-paired-tool-fails](/uk/gateway/troubleshooting#node-paired-tool-fails)
|
||||
- [/nodes/troubleshooting](/uk/nodes/troubleshooting)
|
||||
- [/tools/exec-approvals](/uk/tools/exec-approvals)
|
||||
|
||||
</Accordion>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec раптом почав просити схвалення">
|
||||
```bash
|
||||
openclaw config get tools.exec.host
|
||||
openclaw config get tools.exec.security
|
||||
openclaw config get tools.exec.ask
|
||||
openclaw gateway restart
|
||||
```
|
||||
<Accordion title="Exec раптово просить схвалення">
|
||||
```bash
|
||||
openclaw config get tools.exec.host
|
||||
openclaw config get tools.exec.security
|
||||
openclaw config get tools.exec.ask
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Що змінилося:
|
||||
Що змінилося:
|
||||
|
||||
- Якщо `tools.exec.host` не встановлено, значенням за замовчуванням є `auto`.
|
||||
- `host=auto` визначається як `sandbox`, коли активне sandbox runtime, і як `gateway` в іншому разі.
|
||||
- `host=auto` впливає лише на маршрутизацію; поведінка "YOLO" без запитів походить від `security=full` разом із `ask=off` на gateway/node.
|
||||
- Для `gateway` і `node`, якщо `tools.exec.security` не встановлено, значенням за замовчуванням є `full`.
|
||||
- Якщо `tools.exec.ask` не встановлено, значенням за замовчуванням є `off`.
|
||||
- Результат: якщо ви бачите запити на схвалення, значить якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням.
|
||||
- Якщо `tools.exec.host` не задано, значенням за замовчуванням є `auto`.
|
||||
- `host=auto` перетворюється на `sandbox`, коли активне runtime sandbox, і на `gateway` в іншому випадку.
|
||||
- `host=auto` відповідає лише за маршрутизацію; поведінка без запитів "YOLO" походить від `security=full` разом із `ask=off` на gateway/node.
|
||||
- Для `gateway` і `node`, якщо `tools.exec.security` не задано, за замовчуванням використовується `full`.
|
||||
- Якщо `tools.exec.ask` не задано, за замовчуванням використовується `off`.
|
||||
- Результат: якщо ви бачите запити на схвалення, це означає, що якась локальна для хоста або поточної сесії політика зробила exec суворішим порівняно з поточними значеннями за замовчуванням.
|
||||
|
||||
Відновіть поточну поведінку без схвалень за замовчуванням:
|
||||
Відновлення поточної стандартної поведінки без схвалення:
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
openclaw config set tools.exec.security full
|
||||
openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
openclaw config set tools.exec.security full
|
||||
openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Безпечніші альтернативи:
|
||||
Безпечніші альтернативи:
|
||||
|
||||
- Установіть лише `tools.exec.host=gateway`, якщо вам потрібна просто стабільна маршрутизація хоста.
|
||||
- Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо хочете exec на хості, але все одно хочете перевірку для промахів повз allowlist.
|
||||
- Увімкніть sandbox mode, якщо хочете, щоб `host=auto` знову визначався як `sandbox`.
|
||||
- Встановіть лише `tools.exec.host=gateway`, якщо вам просто потрібна стабільна маршрутизація хоста.
|
||||
- Використовуйте `security=allowlist` разом із `ask=on-miss`, якщо вам потрібен host exec, але ви все ще хочете перевірку в разі промахів по allowlist.
|
||||
- Увімкніть режим sandbox, якщо хочете, щоб `host=auto` знову перетворювався на `sandbox`.
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `Approval required.` → команда очікує на `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec на вузлі-хості.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → неявний/явний вибір sandbox, але sandbox mode вимкнено.
|
||||
- `Approval required.` → команда очікує на `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec для хоста node.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → неявно/явно вибрано sandbox, але режим sandbox вимкнено.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/tools/exec](/uk/tools/exec)
|
||||
- [/tools/exec-approvals](/uk/tools/exec-approvals)
|
||||
- [/gateway/security#what-the-audit-checks-high-level](/uk/gateway/security#what-the-audit-checks-high-level)
|
||||
- [/tools/exec](/uk/tools/exec)
|
||||
- [/tools/exec-approvals](/uk/tools/exec-approvals)
|
||||
- [/gateway/security#what-the-audit-checks-high-level](/uk/gateway/security#what-the-audit-checks-high-level)
|
||||
|
||||
</Accordion>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Не працює інструмент browser">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw browser status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
<Accordion title="Не працює інструмент браузера">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
openclaw browser status
|
||||
openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Коректний вивід виглядає так:
|
||||
Хороший результат виглядає так:
|
||||
|
||||
- Статус browser показує `running: true` і вибраний browser/profile.
|
||||
- `openclaw` запускається, або `user` може бачити локальні вкладки Chrome.
|
||||
- Стан браузера показує `running: true` і вибраний браузер/профіль.
|
||||
- `openclaw` запускається, або `user` може бачити локальні вкладки Chrome.
|
||||
|
||||
Типові сигнатури в журналах:
|
||||
Поширені сигнатури в журналах:
|
||||
|
||||
- `unknown command "browser"` або `unknown command 'browser'` → встановлено `plugins.allow`, і воно не містить `browser`.
|
||||
- `Failed to start Chrome CDP on port` → не вдалося запустити локальний browser Chrome.
|
||||
- `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → налаштований CDP URL використовує непідтримувану схему.
|
||||
- `browser.cdpUrl has invalid port` → налаштований CDP URL має неправильний або неприпустимий порт.
|
||||
- `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста.
|
||||
- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль attach-only не має активної цілі CDP.
|
||||
- застарілі перевизначення viewport / dark-mode / locale / offline на профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile <name>`, щоб закрити активну керовану сесію й скинути стан емуляції без перезапуску gateway.
|
||||
- `unknown command "browser"` або `unknown command 'browser'` → задано `plugins.allow`, і воно не містить `browser`.
|
||||
- `Failed to start Chrome CDP on port` → не вдалося запустити локальний браузер.
|
||||
- `browser.executablePath not found` → налаштований шлях до бінарного файла неправильний.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему.
|
||||
- `browser.cdpUrl has invalid port` → налаштований URL CDP містить неправильний або недопустимий порт.
|
||||
- `No Chrome tabs found for profile="user"` → у профілі Chrome MCP attach немає відкритих локальних вкладок Chrome.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з цього хоста.
|
||||
- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → для профілю attach-only немає живої цілі CDP.
|
||||
- застарілі перевизначення viewport / dark-mode / locale / offline для профілів attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile <name>`, щоб закрити активну керувальну сесію та звільнити стан емуляції без перезапуску gateway.
|
||||
|
||||
Детальні сторінки:
|
||||
Докладні сторінки:
|
||||
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool)
|
||||
- [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/uk/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser#missing-browser-command-or-tool](/uk/tools/browser#missing-browser-command-or-tool)
|
||||
- [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser-wsl2-windows-remote-cdp-troubleshooting](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting)
|
||||
|
||||
</Accordion>
|
||||
</Accordion>
|
||||
|
||||
</AccordionGroup>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [FAQ](/uk/help/faq) — поширені запитання
|
||||
- [FAQ](/uk/help/faq) — часті запитання
|
||||
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) — проблеми, пов’язані з Gateway
|
||||
- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану й виправлення
|
||||
- [Doctor](/uk/gateway/doctor) — автоматизовані перевірки стану та відновлення
|
||||
- [Усунення несправностей каналів](/uk/channels/troubleshooting) — проблеми з підключенням каналів
|
||||
- [Усунення несправностей автоматизації](/uk/automation/cron-jobs#troubleshooting) — проблеми з Cron і Heartbeat
|
||||
|
||||
@ -1,66 +1,70 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування підтверджень виконання або списків дозволених елементів
|
||||
- Реалізація UX підтвердження виконання в застосунку для macOS
|
||||
- Перегляд запитів на вихід із пісочниці та їхніх наслідків
|
||||
summary: Підтвердження виконання, списки дозволених елементів і запити на вихід із пісочниці
|
||||
title: Підтвердження виконання
|
||||
- Налаштування схвалень виконання або списків дозволених дій
|
||||
- Реалізація UX схвалення виконання в застосунку macOS
|
||||
- Перегляд підказок виходу з пісочниці та їхніх наслідків
|
||||
summary: Підказки щодо схвалення виконання, списків дозволених дій і виходу з пісочниці
|
||||
title: Схвалення виконання
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T17:53:33Z"
|
||||
generated_at: "2026-04-23T18:24:14Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 942d09665ff9d567361b0c5ee195a5a6b8c893ea1c9412caa33a02acd8e5e5be
|
||||
source_hash: 1a5aca24c739cd4edfe5389c4897cb6f2efc07141217a70610c247aaa71a5284
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Підтвердження виконання
|
||||
# Схвалення виконання
|
||||
|
||||
Підтвердження виконання — це **захисний механізм застосунку-компаньйона / хоста node** для надання агенту в пісочниці можливості запускати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли збігаються політика + список дозволених елементів + (необов’язково) підтвердження користувача. Підтвердження виконання накладаються **поверх** політики інструментів і підвищеного доступу (окрім випадку, коли elevated встановлено в `full`, що пропускає підтвердження).
|
||||
Схвалення виконання — це **захисний механізм companion app / хоста вузла** для того, щоб дозволити агенту в пісочниці запускати команди на реальному хості (`gateway` або `node`). Це запобіжник: команди дозволяються лише тоді, коли збігаються політика + список дозволених дій + (необов’язкове) схвалення користувача. Схвалення виконання нашаровуються **поверх** політики інструментів і контролю elevated (якщо тільки elevated не встановлено в `full`, що пропускає схвалення).
|
||||
|
||||
<Note>
|
||||
Ефективна політика є **суворішою** з `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"`.
|
||||
</Note>
|
||||
|
||||
## Перегляд ефективної політики
|
||||
|
||||
- `openclaw approvals get`, `... --gateway`, `... --node <id|name|ip>` — показують запитану політику, джерела політики хоста та ефективний результат.
|
||||
- `openclaw exec-policy show` — об’єднане представлення для локальної машини.
|
||||
- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом підтверджень хоста в один крок.
|
||||
- `openclaw exec-policy show` — об’єднане подання для локальної машини.
|
||||
- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом схвалень хоста за один крок.
|
||||
|
||||
Коли локальна область видимості запитує `host=node`, `exec-policy show` повідомляє, що ця область керується node під час виконання, замість того щоб удавати, ніби локальний файл підтверджень є джерелом істини.
|
||||
Коли локальна область запитує `host=node`, `exec-policy show` повідомляє, що ця область під час виконання керується вузлом, замість того щоб удавати, ніби локальний файл схвалень є джерелом істини.
|
||||
|
||||
Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, який зазвичай вимагав би підтвердження, обробляється через **резервний режим ask** (типово: deny).
|
||||
Якщо UI companion app **недоступний**, будь-який запит, який зазвичай мав би викликати запит на схвалення, вирішується через **резервний режим ask** (типово: deny).
|
||||
|
||||
<Tip>
|
||||
Нативні клієнти підтвердження в чаті можуть додавати специфічні для каналу елементи керування до повідомлення про очікуване підтвердження. Наприклад, Matrix додає швидкі реакції (`✅`
|
||||
дозволити один раз, `❌` відхилити, `♾️` завжди дозволяти), водночас залишаючи команди `/approve ...` у повідомленні як запасний варіант.
|
||||
Нативні клієнти схвалення в чаті можуть додавати специфічні для каналу зручності до повідомлення з очікуванням схвалення. Наприклад, Matrix додає скорочення через реакції (`✅`
|
||||
дозволити один раз, `❌` відхилити, `♾️` дозволити завжди), водночас залишаючи в повідомленні команди `/approve ...` як запасний варіант.
|
||||
</Tip>
|
||||
|
||||
## Де це застосовується
|
||||
|
||||
Підтвердження виконання застосовуються локально на хості виконання:
|
||||
Схвалення виконання примусово застосовуються локально на хості виконання:
|
||||
|
||||
- **хост gateway** → процес `openclaw` на машині gateway
|
||||
- **хост node** → раннер node (застосунок-компаньйон для macOS або безголовий хост node)
|
||||
- **хост gateway** → процес `openclaw` на машині Gateway
|
||||
- **хост node** → раннер вузла (macOS companion app або headless-хост вузла)
|
||||
|
||||
Примітка щодо моделі довіри:
|
||||
|
||||
- Викликаючі сторони, автентифіковані через Gateway, є довіреними операторами для цього Gateway.
|
||||
- Прив’язані nodes поширюють цю можливість довіреного оператора на хост node.
|
||||
- Підтвердження виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні користувача.
|
||||
- Схвалені запуски на хості node прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, де це застосовно.
|
||||
- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту.
|
||||
- Ця прив’язка файлу навмисно реалізована за принципом максимально можливого наближення, а не як повна семантична модель для кожного шляху завантаження інтерпретатора/середовища виконання. Якщо режим підтвердження не може точно визначити один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підкріплений підтвердженням, замість того щоб удавати повне покриття.
|
||||
- Викликачі, автентифіковані через Gateway, є довіреними операторами для цього Gateway.
|
||||
- Спарені вузли розширюють цю можливість довіреного оператора на хост вузла.
|
||||
- Схвалення виконання знижують ризик випадкового виконання, але не є межею автентифікації на рівні окремого користувача.
|
||||
- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, де це застосовно.
|
||||
- Для shell-скриптів і прямих викликів файлів через інтерпретатор/середовище виконання OpenClaw також намагається прив’язати
|
||||
один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після схвалення, але до виконання,
|
||||
запуск відхиляється замість виконання зміненого вмісту.
|
||||
- Ця файлова прив’язка навмисно є best-effort, а не повною семантичною моделлю для кожного
|
||||
шляху завантаження інтерпретатора/середовища виконання. Якщо режим схвалення не може точно визначити один конкретний локальний
|
||||
файл для прив’язки, він відмовляється створювати запуск із підкріпленням схваленням, замість того щоб удавати повне покриття.
|
||||
|
||||
Поділ у macOS:
|
||||
Розділення на macOS:
|
||||
|
||||
- **служба хоста node** пересилає `system.run` до **застосунку macOS** через локальний IPC.
|
||||
- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI.
|
||||
- **служба хоста вузла** пересилає `system.run` до **застосунку macOS** через локальний IPC.
|
||||
- **застосунок macOS** застосовує схвалення + виконує команду в контексті UI.
|
||||
|
||||
## Налаштування і зберігання
|
||||
## Налаштування та зберігання
|
||||
|
||||
Підтвердження зберігаються в локальному JSON-файлі на хості виконання:
|
||||
Схвалення зберігаються в локальному JSON-файлі на хості виконання:
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
|
||||
@ -99,27 +103,27 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
## Режим "YOLO" без підтверджень
|
||||
## Режим "YOLO" без схвалень
|
||||
|
||||
Якщо ви хочете, щоб виконання на хості працювало без запитів на підтвердження, потрібно відкрити **обидва** шари політики:
|
||||
Якщо ви хочете, щоб виконання на хості працювало без запитів на схвалення, потрібно відкрити **обидва** шари політики:
|
||||
|
||||
- запитану політику виконання в конфігурації OpenClaw (`tools.exec.*`)
|
||||
- локальну політику підтверджень хоста в `~/.openclaw/exec-approvals.json`
|
||||
- запитана політика виконання в конфігурації OpenClaw (`tools.exec.*`)
|
||||
- локальна для хоста політика схвалень у `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою:
|
||||
|
||||
- `tools.exec.security`: `full` на `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
- `host askFallback`: `full`
|
||||
- хостове `askFallback`: `full`
|
||||
|
||||
Важлива відмінність:
|
||||
|
||||
- `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=...` явно.
|
||||
- `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=...` явно.
|
||||
|
||||
Якщо вам потрібне більш консервативне налаштування, зробіть будь-який із шарів суворішим, повернувши `allowlist` / `on-miss`
|
||||
Якщо вам потрібніше більш консервативне налаштування, знову зробіть будь-який із шарів суворішим, установивши `allowlist` / `on-miss`
|
||||
або `deny`.
|
||||
|
||||
Постійне налаштування "ніколи не запитувати" для хоста gateway:
|
||||
@ -131,7 +135,7 @@ openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Потім налаштуйте файл підтверджень хоста відповідним чином:
|
||||
Потім налаштуйте файл схвалень хоста так, щоб він відповідав цьому:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
@ -146,22 +150,22 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Локальний скорочений варіант для тієї ж політики хоста gateway на поточній машині:
|
||||
Локальне скорочення для тієї самої політики хоста gateway на поточній машині:
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
```
|
||||
|
||||
Цей локальний скорочений варіант оновлює обидва значення:
|
||||
Це локальне скорочення оновлює обидва параметри:
|
||||
|
||||
- локальні `tools.exec.host/security/ask`
|
||||
- локальні типові значення в `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Він навмисно працює лише локально. Якщо вам потрібно змінити підтвердження хоста gateway або хоста node
|
||||
віддалено, і надалі використовуйте `openclaw approvals set --gateway` або
|
||||
Воно навмисно працює лише локально. Якщо вам потрібно змінити схвалення хоста gateway або хоста node
|
||||
віддалено, продовжуйте використовувати `openclaw approvals set --gateway` або
|
||||
`openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
Для хоста node застосуйте той самий файл підтверджень на цьому node:
|
||||
Для хоста вузла застосуйте той самий файл схвалень на цьому вузлі:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -176,45 +180,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Важливе обмеження лише для локального використання:
|
||||
Важливе обмеження лише для локальної машини:
|
||||
|
||||
- `openclaw exec-policy` не синхронізує підтвердження node
|
||||
- `openclaw exec-policy` не синхронізує схвалення вузла
|
||||
- `openclaw exec-policy set --host node` відхиляється
|
||||
- підтвердження виконання для node отримуються з node під час виконання, тому оновлення, націлені на node, потрібно виконувати через `openclaw approvals --node ...`
|
||||
- схвалення виконання на вузлі отримуються з вузла під час виконання, тому оновлення, націлені на вузол, потрібно робити через `openclaw approvals --node ...`
|
||||
|
||||
Скорочений варіант лише для сеансу:
|
||||
Скорочення лише для сеансу:
|
||||
|
||||
- `/exec security=full ask=off` змінює лише поточний сеанс.
|
||||
- `/elevated full` — це аварійний скорочений варіант, який також пропускає підтвердження виконання для цього сеансу.
|
||||
- `/elevated full` — це аварійне скорочення, яке також пропускає схвалення виконання для цього сеансу.
|
||||
|
||||
Якщо файл підтверджень хоста залишається суворішим за конфігурацію, все одно перемагає суворіша політика хоста.
|
||||
Якщо файл схвалень хоста залишається суворішим за конфігурацію, усе одно застосовується суворіша політика хоста.
|
||||
|
||||
## Перемикачі політики
|
||||
## Параметри політики
|
||||
|
||||
### Security (`exec.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 fallback (`askFallback`)
|
||||
### Резервний режим Ask (`askFallback`)
|
||||
|
||||
Якщо потрібне підтвердження, але жоден UI недосяжний, резервний режим визначає результат:
|
||||
Якщо потрібен запит на схвалення, але UI недосяжний, резервний режим визначає дію:
|
||||
|
||||
- **deny**: блокувати.
|
||||
- **allowlist**: дозволяти лише за збігу зі списком дозволених елементів.
|
||||
- **allowlist**: дозволяти лише за наявності збігу зі списком дозволених дій.
|
||||
- **full**: дозволяти.
|
||||
|
||||
### Посилений режим для inline eval в інтерпретаторах (`tools.exec.strictInlineEval`)
|
||||
### Посилення для inline eval інтерпретатора (`tools.exec.strictInlineEval`)
|
||||
|
||||
Коли `tools.exec.strictInlineEval=true`, OpenClaw трактує форми inline code-eval як такі, що потребують лише явного підтвердження, навіть якщо сам бінарний файл інтерпретатора додано до списку дозволених елементів.
|
||||
Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують окремого схвалення, навіть якщо сам виконуваний файл інтерпретатора є в allowlist.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -226,15 +230,18 @@ EOF
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються однозначно з одним стабільним файловим операндом. У строгому режимі:
|
||||
Це захист у глибину для завантажувачів інтерпретаторів, які не прив’язуються чисто до одного стабільного файлового операнда. У строгому режимі:
|
||||
|
||||
- ці команди все одно потребують явного підтвердження;
|
||||
- `allow-always` не зберігає автоматично нові записи списку дозволених елементів для них.
|
||||
- ці команди все одно потребують явного схвалення;
|
||||
- `allow-always` не зберігає для них нові записи allowlist автоматично.
|
||||
|
||||
## Список дозволених елементів (для кожного агента)
|
||||
## Список дозволених дій (для кожного агента)
|
||||
|
||||
Списки дозволених елементів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, який редагується, у застосунку для macOS. Шаблони — це **глоб-збіги без урахування регістру**. Шаблони мають вказувати на **шляхи до бінарних файлів** (записи лише з базовою назвою ігноруються). Застарілі записи `agents.default` мігрують у `agents.main` під час завантаження.
|
||||
Shell-ланцюжки на кшталт `echo ok && pwd` однаково вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволених елементів.
|
||||
Списки дозволених дій є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть, якого агента ви
|
||||
редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**.
|
||||
Шаблони повинні розгортатися до **шляхів до двійкових файлів** (записи лише з базовою назвою ігноруються).
|
||||
Застарілі записи `agents.default` під час завантаження мігрують до `agents.main`.
|
||||
Ланцюжки shell, наприклад `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам allowlist.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -242,37 +249,37 @@ Shell-ланцюжки на кшталт `echo ok && pwd` однаково ви
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
Кожен запис списку дозволених елементів відстежує:
|
||||
Кожен запис allowlist відстежує:
|
||||
|
||||
- **id** — стабільний UUID для ідентичності в UI (необов’язково)
|
||||
- **останнє використання** — часову позначку
|
||||
- **остання використана команда**
|
||||
- **останній визначений шлях**
|
||||
- **id** — стабільний UUID, що використовується для ідентичності в UI (необов’язково)
|
||||
- **last used** — мітка часу останнього використання
|
||||
- **last used command**
|
||||
- **last resolved path**
|
||||
|
||||
## Автодозвіл для CLI зі Skills
|
||||
|
||||
Коли ввімкнено **Автодозвіл для CLI зі Skills**, виконувані файли, на які посилаються відомі Skills,
|
||||
вважаються такими, що входять до списку дозволених елементів на nodes (macOS node або безголовий хост node). Для цього використовується
|
||||
`skills.bins` через Gateway RPC, щоб отримати список бінарних файлів Skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволених елементів.
|
||||
вважаються такими, що входять до allowlist на вузлах (macOS node або headless-хост вузла). Для цього використовується
|
||||
`skills.bins` через Gateway RPC, щоб отримати список bin зі Skills. Вимкніть це, якщо вам потрібні суворі ручні allowlist.
|
||||
|
||||
Важливі примітки щодо довіри:
|
||||
|
||||
- Це **неявний зручний список дозволених елементів**, окремий від ручних записів списку шляхів.
|
||||
- Він призначений для середовищ довірених операторів, де Gateway і node перебувають в одній межі довіри.
|
||||
- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволених шляхів.
|
||||
- Це **неявний допоміжний allowlist**, окремий від ручних записів allowlist за шляхами.
|
||||
- Він призначений для довірених операторських середовищ, де Gateway і вузол перебувають в одній межі довіри.
|
||||
- Якщо вам потрібна сувора явна довіра, залишайте `autoAllowSkills: false` і використовуйте лише ручні записи allowlist за шляхами.
|
||||
|
||||
## Safe bins (лише stdin)
|
||||
## Безпечні bin (лише stdin)
|
||||
|
||||
`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад,
|
||||
`cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволених елементів. Safe bins відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тож
|
||||
вони можуть працювати лише з вхідним потоком. Сприймайте це як вузький швидкий шлях для
|
||||
`tools.exec.safeBins` визначає невеликий список **двійкових файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів allowlist.
|
||||
Безпечні bin відхиляють позиційні файлові аргументи й токени, схожі на шляхи, тому
|
||||
можуть працювати лише з вхідним потоком. Розглядайте це як вузький швидкий шлях для
|
||||
потокових фільтрів, а не як загальний список довіри.
|
||||
|
||||
<Warning>
|
||||
**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад `python3`, `node`,
|
||||
`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда може обчислювати код,
|
||||
виконувати підкоманди або читати файли за своєю природою, надавайте перевагу явним записам у списку дозволених елементів
|
||||
і залишайте запити на підтвердження ввімкненими. Користувацькі safe bins мають визначати явний
|
||||
**Не** додавайте двійкові файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`,
|
||||
`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код,
|
||||
виконувати підкоманди або читати файли, віддавайте перевагу явним записам allowlist
|
||||
і залишайте запити на схвалення увімкненими. Користувацькі safe bins мають визначати явний
|
||||
профіль у `tools.exec.safeBinProfiles.<bin>`.
|
||||
</Warning>
|
||||
|
||||
@ -284,291 +291,284 @@ Shell-ланцюжки на кшталт `echo ok && pwd` однаково ви
|
||||
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні
|
||||
записи списку дозволених елементів для їхніх робочих сценаріїв, відмінних від stdin. Для `grep` у режимі safe-bin
|
||||
`grep` і `sort` не входять до типового списку. Якщо ви явно їх увімкнете, залишайте явні
|
||||
записи allowlist для їхніх сценаріїв, що не обмежуються stdin. Для `grep` у режимі safe-bin
|
||||
вказуйте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється,
|
||||
щоб файлові операнди не можна було приховано передати як неоднозначні позиційні аргументи.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Перевірка argv і заборонені прапорці">
|
||||
Перевірка є детермінованою лише за формою argv (без перевірок існування
|
||||
файлів у файловій системі хоста), що запобігає поведінці оракула існування файлів через відмінності між
|
||||
дозволом і відмовою. Для типових safe bins файлово-орієнтовані параметри заборонені; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці й неоднозначні скорочення відхиляються).
|
||||
### Перевірка Argv і заборонені прапорці
|
||||
|
||||
Заборонені прапорці за профілем safe-bin:
|
||||
Перевірка є детермінованою лише за формою argv (без перевірок наявності файлів у файловій системі хоста),
|
||||
що запобігає поведінці файлового оракула через відмінності між allow/deny.
|
||||
Параметри, орієнтовані на файли, для типових safe bins заборонені; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці та неоднозначні скорочення
|
||||
відхиляються).
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
|
||||
Заборонені прапорці за профілем 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`
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
Safe bins також примусово трактують токени argv як **буквальний текст** під
|
||||
час виконання (без globbing і без розгортання `$VARS`) для сегментів лише зі stdin,
|
||||
тому шаблони на кшталт `*` або `$HOME/...` не можна використати для прихованого читання
|
||||
файлів.
|
||||
Safe bins також змушують обробляти токени argv як **буквальний текст** під час виконання
|
||||
(без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони
|
||||
на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів.
|
||||
|
||||
</Accordion>
|
||||
### Довірені каталоги двійкових файлів
|
||||
|
||||
<Accordion title="Довірені каталоги бінарних файлів">
|
||||
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`.
|
||||
</Accordion>
|
||||
Безпечні bin мають розгортатися з довірених каталогів двійкових файлів (системні типові значення плюс
|
||||
необов’язковий `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично.
|
||||
Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо
|
||||
ваш виконуваний файл safe-bin знаходиться в шляхах менеджера пакетів/користувача (наприклад
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх
|
||||
явно до `tools.exec.safeBinTrustedDirs`.
|
||||
|
||||
<Accordion title="Shell-ланцюжки, обгортки та мультиплексори">
|
||||
Shell-ланцюжки (`&&`, `||`, `;`) дозволені, якщо кожен сегмент верхнього рівня
|
||||
відповідає списку дозволених елементів
|
||||
(включно з safe bins або автодозволом для Skills).
|
||||
Перенаправлення в режимі allowlist, як і раніше, не підтримуються. Підстановка команд
|
||||
(`$()` / зворотні лапки) відхиляється під час аналізу allowlist, зокрема всередині
|
||||
подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`.
|
||||
### Ланцюжки shell, обгортки та мультиплексори
|
||||
|
||||
У підтвердженнях застосунку-компаньйона для macOS необроблений shell-текст, що містить shell-керування
|
||||
або синтаксис розгортання (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`,
|
||||
`)`), вважається промахом allowlist, якщо сам shell-бінарний файл не входить до
|
||||
списку дозволених елементів.
|
||||
Ланцюжки shell (`&&`, `||`, `;`) дозволені, коли кожен сегмент верхнього рівня
|
||||
відповідає allowlist (зокрема safe bins або автодозвіл для Skills). Переспрямування
|
||||
залишаються непідтримуваними в режимі allowlist. Підстановка команд (`$()` / зворотні лапки)
|
||||
відхиляється під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні
|
||||
лапки, якщо вам потрібен буквальний текст `$()`.
|
||||
|
||||
Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту
|
||||
зводяться до невеликого явного списку дозволених елементів (`TERM`, `LANG`,
|
||||
`LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
У схваленнях companion app на macOS сирий текст shell, що містить керувальний або
|
||||
розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`),
|
||||
вважається промахом allowlist, якщо сам двійковий файл shell не входить до allowlist.
|
||||
|
||||
Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях внутрішнього виконуваного файла
|
||||
замість шляху обгортки. Shell-мультиплексори (`busybox`, `toybox`)
|
||||
так само розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо
|
||||
обгортку або мультиплексор неможливо безпечно розгорнути, запис allowlist не зберігається автоматично.
|
||||
Для обгорток shell (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту
|
||||
зводяться до невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`,
|
||||
`NO_COLOR`, `FORCE_COLOR`).
|
||||
|
||||
Якщо ви додаєте до allowlist інтерпретатори на кшталт `python3` або `node`, краще
|
||||
встановити `tools.exec.strictInlineEval=true`, щоб inline eval і далі вимагав
|
||||
явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі
|
||||
виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються.
|
||||
Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери (`env`,
|
||||
`nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях до внутрішнього виконуваного файла
|
||||
замість шляху до обгортки. Мультиплексори shell (`busybox`, `toybox`) розгортаються для
|
||||
аплетів shell (`sh`, `ash` тощо) таким самим чином. Якщо обгортку або мультиплексор
|
||||
не можна безпечно розгорнути, жоден запис allowlist не зберігається автоматично.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
Якщо ви додаєте до allowlist інтерпретатори на кшталт `python3` або `node`, надавайте перевагу
|
||||
`tools.exec.strictInlineEval=true`, щоб inline eval і далі вимагав явного
|
||||
схвалення. У строгому режимі `allow-always` усе ще може зберігати нешкідливі
|
||||
виклики інтерпретатора/скрипта, але носії inline-eval не зберігаються
|
||||
автоматично.
|
||||
|
||||
### Safe bins порівняно зі списком allowlist
|
||||
### Безпечні bin проти allowlist
|
||||
|
||||
| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Мета | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів |
|
||||
| Тип збігу | Ім’я виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла |
|
||||
| Обсяг аргументів | Обмежений профілем 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` для агента). Ключі профілю для агента перевизначають глобальні ключі.
|
||||
- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents.<id>.allowlist` (або через Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` попереджає за допомогою `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів.
|
||||
- `openclaw doctor --fix` може створити відсутні користувацькі записи `safeBinProfiles.<bin>` у вигляді `{}` (після цього перегляньте й посильте їх). Бінарні файли інтерпретатора/середовища виконання автоматично не створюються.
|
||||
- `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.<id>.allowlist` (або через UI Control / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли двійкові файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів.
|
||||
- `openclaw doctor --fix` може створити заготовки для відсутніх користувацьких записів `safeBinProfiles.<bin>` як `{}` (після цього перегляньте й посильте їх). Для двійкових файлів інтерпретатора/середовища виконання заготовки автоматично не створюються.
|
||||
|
||||
Приклад користувацького профілю:
|
||||
__OC_I18N_900005__
|
||||
Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє вбудовану команду `env` у режимі safe-bin,
|
||||
Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin,
|
||||
щоб `jq -n env` не міг вивантажити середовище процесу хоста без явного шляху allowlist
|
||||
або запиту на підтвердження.
|
||||
або запиту на схвалення.
|
||||
|
||||
## Редагування в Control UI
|
||||
## Редагування в UI Control
|
||||
|
||||
Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення
|
||||
для окремих агентів і списки allowlist. Виберіть область видимості (типові значення або агент), змініть політику,
|
||||
додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **останнього використання**
|
||||
для кожного шаблону, щоб список було зручно підтримувати в порядку.
|
||||
Використовуйте картку **UI Control → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення для окремих агентів
|
||||
і allowlist. Виберіть область (типові значення або агента), скоригуйте політику,
|
||||
додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **last used**
|
||||
для кожного шаблону, щоб список залишався впорядкованим.
|
||||
|
||||
Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Nodes
|
||||
мають оголошувати `system.execApprovals.get/set` (застосунок для macOS або безголовий хост node).
|
||||
Якщо node ще не оголошує підтримку підтверджень виконання, редагуйте його локальний
|
||||
`~/.openclaw/exec-approvals.json` безпосередньо.
|
||||
Селектор цілі вибирає **Gateway** (локальні схвалення) або **Node**. Вузли
|
||||
мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост вузла).
|
||||
Якщо вузол ще не оголошує схвалення виконання, відредагуйте його локальний
|
||||
`~/.openclaw/exec-approvals.json` напряму.
|
||||
|
||||
CLI: `openclaw approvals` підтримує редагування для gateway або node (див. [CLI підтверджень](/cli/approvals)).
|
||||
CLI: `openclaw approvals` підтримує редагування gateway або вузла (див. [CLI схвалень](/cli/approvals)).
|
||||
|
||||
## Потік підтвердження
|
||||
## Потік схвалення
|
||||
|
||||
Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам-операторам.
|
||||
Control UI і застосунок для macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає
|
||||
схвалений запит до хоста node.
|
||||
Коли потрібен запит на схвалення, gateway транслює `exec.approval.requested` клієнтам операторів.
|
||||
UI Control і застосунок macOS розв’язують його через `exec.approval.resolve`, а потім gateway пересилає
|
||||
схвалений запит на хост вузла.
|
||||
|
||||
Для `host=node` запити на підтвердження включають канонічне корисне навантаження `systemRunPlan`. Gateway використовує
|
||||
Для `host=node` запити на схвалення містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує
|
||||
цей план як авторитетний контекст команди/cwd/сеансу під час пересилання схвалених запитів `system.run`.
|
||||
|
||||
Це важливо для затримки асинхронного підтвердження:
|
||||
Це важливо для затримки асинхронного схвалення:
|
||||
|
||||
- шлях виконання node заздалегідь готує один канонічний план
|
||||
- запис підтвердження зберігає цей план і його метадані прив’язки
|
||||
- після схвалення остаточний пересланий виклик `system.run` повторно використовує збережений план,
|
||||
замість того щоб довіряти пізнішим змінам викликача
|
||||
- шлях виконання вузла готує один канонічний план наперед
|
||||
- запис схвалення зберігає цей план і його метадані прив’язки
|
||||
- після схвалення фінальний пересланий виклик `system.run` повторно використовує збережений план
|
||||
замість довіри до пізніших змін викликача
|
||||
- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
`sessionKey` після створення запиту на підтвердження, gateway відхиляє
|
||||
пересланий запуск як невідповідність підтвердженню
|
||||
`sessionKey` після створення запиту на схвалення, gateway відхиляє
|
||||
пересланий запуск як невідповідність схваленню
|
||||
|
||||
## Команди інтерпретатора/середовища виконання
|
||||
|
||||
Запуски інтерпретатора/середовища виконання, підкріплені підтвердженням, навмисно зроблено консервативними:
|
||||
Запуски інтерпретатора/середовища виконання, підкріплені схваленням, навмисно є консервативними:
|
||||
|
||||
- Точний контекст argv/cwd/env завжди прив’язується.
|
||||
- Форми прямого shell-скрипта і прямого файла середовища виконання прив’язуються за принципом максимально можливого наближення до одного конкретного
|
||||
знімка локального файла.
|
||||
- Поширені форми обгорток менеджерів пакетів, які все ще визначаються до одного прямого локального файла (наприклад
|
||||
- Завжди прив’язуються точний контекст argv/cwd/env.
|
||||
- Форми прямих shell-скриптів і прямих файлів середовища виконання прив’язуються за best-effort до одного конкретного локального
|
||||
знімка файла.
|
||||
- Типові форми обгорток менеджерів пакетів, які все ще розгортаються до одного прямого локального файла (наприклад
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою.
|
||||
- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання
|
||||
(наприклад, для пакетних скриптів, форм eval, специфічних для середовища виконання ланцюжків завантаження або неоднозначних багатофайлових
|
||||
форм), виконання, підкріплене підтвердженням, відхиляється замість того, щоб заявляти семантичне покриття, якого
|
||||
(наприклад скрипти пакетів, форми eval, специфічні для середовища виконання ланцюжки завантаження або неоднозначні форми
|
||||
з кількома файлами), виконання, підкріплене схваленням, відхиляється замість заяви про семантичне покриття, якого
|
||||
насправді немає.
|
||||
- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний довірений
|
||||
процес allowlist/full, де оператор приймає ширшу семантику середовища виконання.
|
||||
- Для таких сценаріїв надавайте перевагу пісочниці, окремій межі хоста або явному
|
||||
довіреному процесу allowlist/full, де оператор приймає ширшу семантику середовища виконання.
|
||||
|
||||
Коли потрібні підтвердження, інструмент exec відразу повертає id підтвердження. Використовуйте цей id, щоб
|
||||
зіставляти пізніші системні події (`Exec finished` / `Exec denied`). Якщо до завершення
|
||||
тайм-ауту не надходить рішення, запит вважається тайм-аутом підтвердження і відображається як причина відмови.
|
||||
Коли потрібні схвалення, інструмент exec одразу повертає ідентифікатор схвалення. Використовуйте цей ідентифікатор, щоб
|
||||
співвідносити пізніші системні події (`Exec finished` / `Exec denied`). Якщо рішення не надходить до завершення
|
||||
часу очікування, запит вважається тайм-аутом схвалення й відображається як причина відмови.
|
||||
|
||||
### Поведінка доставки подальших повідомлень
|
||||
|
||||
Після завершення схваленого асинхронного виконання OpenClaw надсилає подальший хід `agent` до того самого сеансу.
|
||||
Після завершення схваленого асинхронного exec OpenClaw надсилає подальший хід `agent` у той самий сеанс.
|
||||
|
||||
- Якщо існує дійсна зовнішня ціль доставки (канал, який підтримує доставку, плюс ціль `to`), доставка подальших повідомлень використовує цей канал.
|
||||
- У потоках лише webchat або внутрішнього сеансу без зовнішньої цілі доставка подальших повідомлень залишається лише в межах сеансу (`deliver: false`).
|
||||
- Якщо викликач явно запитує сувору зовнішню доставку без зовнішнього каналу, який можна визначити, запит завершується помилкою `INVALID_REQUEST`.
|
||||
- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не вдається визначити, доставка знижується до лише-сеансової замість помилки.
|
||||
- Якщо існує коректна зовнішня ціль доставки (канал доставки плюс ціль `to`), подальша доставка використовує цей канал.
|
||||
- У потоках лише webchat або внутрішніх сеансів без зовнішньої цілі подальша доставка залишається лише в межах сеансу (`deliver: false`).
|
||||
- Якщо викликач явно вимагає сувору зовнішню доставку без можливості розв’язати зовнішній канал, запит завершується помилкою `INVALID_REQUEST`.
|
||||
- Якщо ввімкнено `bestEffortDeliver` і неможливо розв’язати жоден зовнішній канал, доставка знижується до режиму лише для сеансу замість помилки.
|
||||
|
||||
Діалог підтвердження містить:
|
||||
|
||||
- команду + аргументи
|
||||
- cwd
|
||||
- id агента
|
||||
- визначений шлях до виконуваного файла
|
||||
- хост + метадані політики
|
||||
- розгорнутий шлях до виконуваного файла
|
||||
- метадані хоста + політики
|
||||
|
||||
Дії:
|
||||
|
||||
- **Allow once** → запустити зараз
|
||||
- **Always allow** → додати до allowlist + запустити
|
||||
- **Allow once** → виконати зараз
|
||||
- **Always allow** → додати до allowlist + виконати
|
||||
- **Deny** → заблокувати
|
||||
|
||||
## Пересилання підтверджень до чат-каналів
|
||||
## Пересилання схвалення до чат-каналів
|
||||
|
||||
Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати
|
||||
Ви можете пересилати запити на схвалення exec до будь-якого чат-каналу (зокрема каналів Plugin) і схвалювати
|
||||
їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки.
|
||||
|
||||
Конфігурація:
|
||||
__OC_I18N_900006__
|
||||
Відповідь у чаті:
|
||||
__OC_I18N_900007__
|
||||
Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin. Якщо ID не збігається з очікуваним підтвердженням exec, вона автоматично перевіряє підтвердження Plugin.
|
||||
Команда `/approve` обробляє і схвалення exec, і схвалення Plugin. Якщо ідентифікатор не відповідає жодному очікуваному схваленню exec, вона автоматично перевіряє схвалення Plugin.
|
||||
|
||||
### Пересилання підтверджень Plugin
|
||||
### Пересилання схвалень Plugin
|
||||
|
||||
Пересилання підтверджень Plugin використовує той самий конвеєр доставки, що й підтвердження exec, але має власну
|
||||
Пересилання схвалень 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` у тому самому чаті, але ці канали все ще використовують свій
|
||||
визначений список затверджувачів для авторизації, навіть коли нативну доставку підтверджень вимкнено.
|
||||
розв’язаний список схвалювачів для авторизації, навіть коли нативну доставку схвалень вимкнено.
|
||||
|
||||
Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway безпосередньо,
|
||||
цей запасний механізм навмисно обмежено помилками типу «підтвердження не знайдено». Справжня
|
||||
відмова/помилка підтвердження exec не повторюється мовчки як підтвердження Plugin.
|
||||
Для Telegram та інших нативних клієнтів схвалення, які звертаються безпосередньо до Gateway,
|
||||
цей запасний варіант навмисно обмежений помилками типу «схвалення не знайдено». Реальна
|
||||
відмова/помилка схвалення exec не повторюється мовчки як схвалення Plugin.
|
||||
|
||||
### Нативна доставка підтверджень
|
||||
### Нативна доставка схвалень
|
||||
|
||||
Деякі канали також можуть діяти як нативні клієнти підтвердження. Нативні клієнти додають DM для затверджувачів, fanout до початкового чату
|
||||
та специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve`
|
||||
Деякі канали також можуть діяти як нативні клієнти схвалення. Нативні клієнти додають DM схвалювачам, fanout у чаті походження
|
||||
та специфічний для каналу інтерактивний UX схвалення поверх спільного потоку `/approve`
|
||||
у тому самому чаті.
|
||||
|
||||
Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним
|
||||
шляхом, видимим агенту. Агент також не повинен дублювати звичайну чат-команду
|
||||
`/approve`, якщо результат інструмента не вказує, що чат-підтвердження недоступні або
|
||||
ручне підтвердження є єдиним шляхом, що залишився.
|
||||
Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним
|
||||
шляхом для агента. Агент також не повинен дублювати звичайну чат-команду
|
||||
`/approve`, якщо тільки результат інструмента не вказує, що чат-схвалення недоступні або
|
||||
ручне схвалення є єдиним шляхом, що залишився.
|
||||
|
||||
Загальна модель:
|
||||
|
||||
- політика виконання на хості все одно визначає, чи потрібне підтвердження exec
|
||||
- `approvals.exec` керує пересиланням запитів на підтвердження до інших чат-цілей
|
||||
- `channels.<channel>.execApprovals` керує тим, чи діє цей канал як нативний клієнт підтвердження
|
||||
- політика виконання на хості все ще визначає, чи потрібне схвалення exec
|
||||
- `approvals.exec` керує пересиланням запитів на схвалення до інших цілей чату
|
||||
- `channels.<channel>.execApprovals` керує тим, чи діє цей канал як нативний клієнт схвалення
|
||||
|
||||
Нативні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі наведені умови істинні:
|
||||
Нативні клієнти схвалення автоматично вмикають доставку спочатку в DM, коли всі наведені умови істинні:
|
||||
|
||||
- канал підтримує нативну доставку підтверджень
|
||||
- затверджувачів можна визначити з явних `execApprovals.approvers` або з документованих резервних джерел цього
|
||||
каналу
|
||||
- `channels.<channel>.execApprovals.enabled` не встановлено або має значення `"auto"`
|
||||
- канал підтримує нативну доставку схвалень
|
||||
- схвалювачів можна розв’язати з явних `execApprovals.approvers` або з
|
||||
документованих резервних джерел цього каналу
|
||||
- `channels.<channel>.execApprovals.enabled` не задано або дорівнює `"auto"`
|
||||
|
||||
Установіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Установіть `enabled: true`, щоб примусово
|
||||
увімкнути його, коли затверджувачі визначаються. Публічна доставка до початкового чату й надалі явно керується через
|
||||
Установіть `enabled: false`, щоб явно вимкнути нативний клієнт схвалення. Установіть `enabled: true`, щоб примусово
|
||||
увімкнути його, коли схвалювачів вдається розв’язати. Публічна доставка в чаті походження залишається явною через
|
||||
`channels.<channel>.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` для direct-message, де це підтримується)
|
||||
- затверджувачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom`
|
||||
- нативні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть визначати підтвердження Plugin
|
||||
без другого локального для Slack резервного шару
|
||||
- нативна маршрутизація Matrix у DM/канал і швидкі реакції обробляють як підтвердження exec, так і Plugin;
|
||||
авторизація Plugin і далі надходить із `channels.matrix.dm.allowFrom`
|
||||
- запитувач не обов’язково має бути затверджувачем
|
||||
- початковий чат може підтвердити запит безпосередньо через `/approve`, коли цей чат уже підтримує команди та відповіді
|
||||
- нативні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять
|
||||
безпосередньо до підтверджень Plugin, усе інше — до підтверджень exec
|
||||
- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve`
|
||||
- коли нативний `target` вмикає доставку до початкового чату, запити на підтвердження включають текст команди
|
||||
- очікувані підтвердження exec типово спливають через 30 хвилин
|
||||
- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, підтвердження переходить до `askFallback`
|
||||
- коли нативний клієнт схвалення вмикається автоматично, типовою ціллю нативної доставки є DM схвалювачів
|
||||
- для Discord і Telegram лише розв’язані схвалювачі можуть схвалювати або відхиляти
|
||||
- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom`
|
||||
- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації owner (`allowFrom`, а також `defaultTo` для direct-message, де це підтримується)
|
||||
- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom`
|
||||
- нативні кнопки Slack зберігають тип id схвалення, тому id `plugin:` можуть розв’язувати схвалення Plugin
|
||||
без другого локального для Slack резервного рівня
|
||||
- нативна маршрутизація DM/каналу й скорочення через реакції в Matrix обробляють і exec, і схвалення Plugin;
|
||||
авторизація Plugin усе ще надходить із `channels.matrix.dm.allowFrom`
|
||||
- запитувач не обов’язково має бути схвалювачем
|
||||
- чат походження може схвалити запит безпосередньо через `/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 зберігає тему для запиту на схвалення та подальшого повідомлення після схвалення.
|
||||
|
||||
Дивіться:
|
||||
Див. також:
|
||||
|
||||
- [Discord](/channels/discord)
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Потік IPC у macOS
|
||||
### Потік IPC на macOS
|
||||
__OC_I18N_900009__
|
||||
Примітки щодо безпеки:
|
||||
|
||||
- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`.
|
||||
- Перевірка однотипного UID.
|
||||
- Режим Unix socket `0600`, token зберігається в `exec-approvals.json`.
|
||||
- Перевірка однотипного UID вузла.
|
||||
- Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL.
|
||||
|
||||
## Системні події
|
||||
@ -579,34 +579,34 @@ __OC_I18N_900009__
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Вони публікуються в сеансі агента після того, як node повідомляє про подію.
|
||||
Підтвердження exec на хості gateway генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, під час виконання довше за поріг).
|
||||
Exec, які проходять через підтвердження, повторно використовують id підтвердження як `runId` у цих повідомленнях для зручного зіставлення.
|
||||
Вони публікуються в сеанс агента після того, як вузол повідомляє про подію.
|
||||
Схвалення виконання для хоста gateway генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг).
|
||||
Exec із контролем схвалення повторно використовують id схвалення як `runId` у цих повідомленнях для зручної кореляції.
|
||||
|
||||
## Поведінка при відхиленні підтвердження
|
||||
## Поведінка у разі відхиленого схвалення
|
||||
|
||||
Коли асинхронне підтвердження exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати
|
||||
Коли асинхронне схвалення exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати
|
||||
вивід будь-якого попереднього запуску тієї самої команди в межах сеансу. Причина відмови
|
||||
передається з явною вказівкою, що жодного виводу команди немає, що зупиняє
|
||||
агента від заяв про новий вивід або повторення відхиленої команди зі
|
||||
передається з явною вказівкою, що вивід команди недоступний, що не дає
|
||||
агенту стверджувати, ніби новий вивід існує, або повторювати відхилену команду зі
|
||||
застарілими результатами попереднього успішного запуску.
|
||||
|
||||
## Наслідки
|
||||
|
||||
- **full** має широкі повноваження; де можливо, віддавайте перевагу allowlist.
|
||||
- **ask** тримає вас у контурі, водночас дозволяючи швидкі підтвердження.
|
||||
- Списки allowlist для окремих агентів не дають підтвердженням одного агента просочуватися до інших.
|
||||
- Підтвердження застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть викликати `/exec`.
|
||||
- `/exec security=full` — це зручний варіант на рівні сеансу для авторизованих операторів, який навмисно пропускає підтвердження. Щоб жорстко заблокувати host exec, установіть для security підтверджень значення `deny` або забороніть інструмент `exec` через політику інструментів.
|
||||
- **full** має широкі можливості; за можливості віддавайте перевагу allowlist.
|
||||
- **ask** залишає вас у циклі ухвалення рішень, водночас дозволяючи швидкі схвалення.
|
||||
- Окремі allowlist для кожного агента запобігають витоку схвалень одного агента до інших.
|
||||
- Схвалення застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`.
|
||||
- `/exec security=full` — це зручність на рівні сеансу для авторизованих операторів, яка навмисно пропускає схвалення. Щоб жорстко заблокувати host exec, установіть для схвалень безпеку `deny` або забороніть інструмент `exec` через політику інструментів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Інструмент Exec" href="/uk/tools/exec" icon="terminal">
|
||||
<Card title="Інструмент exec" href="/uk/tools/exec" icon="terminal">
|
||||
Інструмент виконання shell-команд.
|
||||
</Card>
|
||||
<Card title="Режим elevated" href="/uk/tools/elevated" icon="shield-exclamation">
|
||||
Аварійний шлях, який також пропускає підтвердження.
|
||||
Аварійний шлях, який також пропускає схвалення.
|
||||
</Card>
|
||||
<Card title="Пісочниця" href="/uk/gateway/sandboxing" icon="box">
|
||||
Режими пісочниці та доступ до робочого простору.
|
||||
@ -615,7 +615,7 @@ Exec, які проходять через підтвердження, повт
|
||||
Модель безпеки та посилення захисту.
|
||||
</Card>
|
||||
<Card title="Пісочниця vs політика інструментів vs elevated" href="/uk/gateway/sandbox-vs-tool-policy-vs-elevated" icon="sliders">
|
||||
Коли слід використовувати кожен із цих механізмів керування.
|
||||
Коли варто використовувати кожен із цих механізмів контролю.
|
||||
</Card>
|
||||
<Card title="Skills" href="/uk/tools/skills" icon="sparkles">
|
||||
Поведінка автодозволу на основі Skills.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user