diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md index 7eef91b5b..092264298 100644 --- a/docs/uk/tools/index.md +++ b/docs/uk/tools/index.md @@ -2,126 +2,126 @@ read_when: - Ви хочете зрозуміти, які інструменти надає OpenClaw - Вам потрібно налаштувати, дозволити або заборонити інструменти - - Ви обираєте між вбудованими інструментами, skills і plugins -summary: 'Огляд інструментів і Plugins OpenClaw: що може робити агент і як його розширювати' -title: Інструменти та Plugins + - 'Ви вирішуєте, що вибрати: вбудовані інструменти, Skills чи плагіни' +summary: 'Огляд інструментів і плагінів OpenClaw: що агент може робити і як його розширити' +title: Інструменти та плагіни x-i18n: - generated_at: "2026-04-23T21:15:25Z" + generated_at: "2026-04-25T00:15:16Z" model: gpt-5.4 provider: openai - source_hash: f9ab57fcb1b58875866721fbadba63093827698ed980afeb14274da601b34f11 + source_hash: 045b6b0744e02938ed6bb9e0ad956add11883be926474e78872ca928b32af090 source_path: tools/index.md workflow: 15 --- -Усе, що агент робить понад генерацію тексту, відбувається через **інструменти**. -Інструменти — це спосіб, у який агент читає файли, запускає команди, переглядає веб, -надсилає повідомлення та взаємодіє з пристроями. +Усе, що агент робить понад генерування тексту, відбувається через **інструменти**. +Інструменти — це спосіб, у який агент читає файли, запускає команди, переглядає вебсторінки, надсилає +повідомлення та взаємодіє з пристроями. -## Інструменти, skills і Plugins +## Інструменти, Skills і плагіни OpenClaw має три шари, які працюють разом: - Інструмент — це типізована функція, яку агент може викликати (наприклад `exec`, `browser`, + Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`, `web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а - plugins можуть реєструвати додаткові. + плагіни можуть реєструвати додаткові. - Агент бачить інструменти як структуровані визначення функцій, надіслані до model API. + Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі. - Skill — це markdown-файл (`SKILL.md`), що вставляється в системний запит. - Skills дають агенту контекст, обмеження і покрокові вказівки для - ефективного використання інструментів. Skills живуть у вашому робочому просторі, у спільних теках - або постачаються всередині Plugins. + Skill — це markdown-файл (`SKILL.md`), що вбудовується в системний промпт. + Skills надають агенту контекст, обмеження та покрокові вказівки для + ефективного використання інструментів. Skills зберігаються у вашому робочому просторі, у спільних теках + або постачаються всередині плагінів. [Довідник зі Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) - - Plugin — це пакет, який може реєструвати будь-яку комбінацію можливостей: - канали, провайдерів моделей, інструменти, skills, мовлення, realtime transcription, - realtime voice, media understanding, генерацію зображень, генерацію відео, - web fetch, web search та інше. Деякі Plugins — **core** (постачаються з - OpenClaw), інші — **external** (публікуються спільнотою в npm). + + Плагін — це пакет, який може реєструвати будь-яку комбінацію можливостей: + канали, провайдери моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, + голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео, + отримання даних з вебу, вебпошук тощо. Деякі плагіни є **основними** (постачаються з + OpenClaw), інші — **зовнішніми** (опублікованими в npm спільнотою). - [Установлення і налаштування Plugins](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) + [Встановлення та налаштування плагінів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) ## Вбудовані інструменти -Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких Plugins: +Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких плагінів: | Інструмент | Що він робить | Сторінка | | ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------ | -| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Exec Approvals](/uk/tools/exec-approvals) | -| `code_execution` | Запускає sandboxed remote Python analysis | [Code Execution](/uk/tools/code-execution) | -| `browser` | Керує browser на базі Chromium (перехід, клік, screenshot) | [Browser](/uk/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Пошук у вебі, пошук дописів X, отримання вмісту сторінок | [Web](/uk/tools/web), [Web Fetch](/uk/tools/web-fetch) | -| `read` / `write` / `edit` | Файловий I/O у робочому просторі | | -| `apply_patch` | Patch-і файлів з кількома фрагментами | [Apply Patch](/uk/tools/apply-patch) | -| `message` | Надсилає повідомлення в усі канали | [Agent Send](/uk/tools/agent-send) | +| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec), [Схвалення Exec](/uk/tools/exec-approvals) | +| `code_execution` | Виконує ізольований віддалений Python-аналіз | [Виконання коду](/uk/tools/code-execution) | +| `browser` | Керує браузером Chromium (перехід, клік, знімок екрана) | [Браузер](/uk/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web), [Отримання з вебу](/uk/tools/web-fetch) | +| `read` / `write` / `edit` | Ввід/вивід файлів у робочому просторі | | +| `apply_patch` | Багатофрагментні файлові патчі | [Apply Patch](/uk/tools/apply-patch) | +| `message` | Надсилає повідомлення через усі канали | [Надсилання агентом](/uk/tools/agent-send) | | `canvas` | Керує node Canvas (present, eval, snapshot) | | -| `nodes` | Виявляє та націлює pair-пристрої | | -| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, patch-ить, перезапускає або оновлює gateway | | +| `nodes` | Виявляє та вибирає спарені пристрої | | +| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює Gateway | | | `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | | `music_generate` | Генерує музичні треки | [Генерація музики](/uk/tools/music-generation) | | `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | -| `tts` | Одноразове перетворення text-to-speech | [TTS](/uk/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) | -| `session_status` | Легковагове зчитування у стилі `/status` і перевизначення моделі для сесії | [Інструменти сесії](/uk/concepts/session-tool) | +| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Керування сеансами, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) | +| `session_status` | Полегшене зчитування стану у стилі `/status` і перевизначення моделі для сеансу | [Інструменти сеансу](/uk/concepts/session-tool) | -Для роботи із зображеннями використовуйте `image` для аналізу і `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого нетипового провайдера зображень, спочатку налаштуйте автентифікацію/API key цього провайдера. +Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви використовуєте `openai/*`, `google/*`, `fal/*` або іншого нестандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого нетипового музичного провайдера, спочатку налаштуйте автентифікацію/API key цього провайдера. +Для роботи з музикою використовуйте `music_generate`. Якщо ви використовуєте `google/*`, `minimax/*` або іншого нестандартного провайдера музики, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нетипового провайдера відео, спочатку налаштуйте автентифікацію/API key цього провайдера. +Для роботи з відео використовуйте `video_generate`. Якщо ви використовуєте `qwen/*` або іншого нестандартного провайдера відео, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для workflow-driven генерації аудіо використовуйте `music_generate`, коли його -реєструє Plugin на кшталт ComfyUI. Це відокремлено від `tts`, який є text-to-speech. +Для генерації аудіо на основі робочих процесів використовуйте `music_generate`, коли його реєструє +плагін, наприклад ComfyUI. Це окремо від `tts`, яке є перетворенням тексту на мовлення. -`session_status` — це легковаговий інструмент status/readback у групі sessions. -Він відповідає на запитання у стилі `/status` про поточну сесію і може -за бажанням установлювати перевизначення моделі для сесії; `model=default` очищає це -перевизначення. Як і `/status`, він може дозаповнювати неповні лічильники токенів/кешу і -мітку активної runtime-моделі з останнього запису використання transcript. +`session_status` — це полегшений інструмент стану/зчитування у групі сеансів. +Він відповідає на запитання у стилі `/status` про поточний сеанс і може +за потреби встановити перевизначення моделі для окремого сеансу; `model=default` скасовує це +перевизначення. Як і `/status`, він може доповнювати відсутні лічильники токенів/кешу та +мітку активної моделі середовища виконання з останнього запису використання в транскрипті. -`gateway` — це owner-only runtime tool для операцій gateway: +`gateway` — це інструмент середовища виконання лише для власника для операцій Gateway: -- `config.schema.lookup` для одного path-scoped піддерева конфігурації перед редагуванням -- `config.get` для поточного знімка конфігурації + hash +- `config.schema.lookup` для одного піддерева конфігурації з обмеженням за шляхом перед редагуванням +- `config.get` для поточного знімка конфігурації + хешу - `config.patch` для часткових оновлень конфігурації з перезапуском - `config.apply` лише для повної заміни конфігурації -- `update.run` для явного self-update + restart +- `update.run` для явного самооновлення + перезапуску Для часткових змін віддавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте -`config.apply` лише тоді, коли ви свідомо замінюєте всю конфігурацію. +`config.apply` лише тоді, коли ви навмисно замінюєте всю конфігурацію. Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec. -### Інструменти, надані Plugin +### Інструменти, надані плагінами -Plugins можуть реєструвати додаткові інструменти. Деякі приклади: +Плагіни можуть реєструвати додаткові інструменти. Деякі приклади: -- [Diffs](/uk/tools/diffs) — переглядач і рендерер diff +- [Diffs](/uk/tools/diffs) — переглядач і візуалізатор diff - [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу -- [Lobster](/uk/tools/lobster) — typed workflow runtime з resumable approvals -- [Music Generation](/uk/tools/music-generation) — спільний інструмент `music_generate` з workflow-backed провайдерами -- [OpenProse](/uk/prose) — markdown-first orchestration робочих процесів -- [Tokenjuice](/uk/tools/tokenjuice) — компактні результати інструментів `exec` і `bash` з великою кількістю шуму +- [Lobster](/uk/tools/lobster) — типізоване середовище виконання робочих процесів із відновлюваними схваленнями +- [Генерація музики](/uk/tools/music-generation) — спільний інструмент `music_generate` із провайдерами на основі робочих процесів +- [OpenProse](/uk/prose) — оркестрація робочих процесів із пріоритетом markdown +- [Tokenjuice](/uk/tools/tokenjuice) — стискає шумні результати інструментів `exec` і `bash` -## Конфігурація інструментів +## Налаштування інструментів -### Allow і deny списки +### Списки дозволів і заборон Керуйте тим, які інструменти агент може викликати, через `tools.allow` / `tools.deny` у -конфігурації. Deny завжди має пріоритет над allow. +конфігурації. Заборона завжди має пріоритет над дозволом. ```json5 { @@ -132,56 +132,62 @@ Plugins можуть реєструвати додаткові інструме } ``` +OpenClaw працює за принципом fail closed, коли явний список дозволів не дає жодного доступного для виклику інструмента. +Наприклад, `tools.allow: ["query_db"]` працює лише тоді, якщо завантажений плагін справді +реєструє `query_db`. Якщо жоден вбудований інструмент, інструмент плагіна або вбудований MCP-інструмент не відповідає +списку дозволів, виконання зупиняється до виклику моделі, замість того щоб продовжитися як запуск лише з +текстом, який міг би галюцинувати результати інструментів. + ### Профілі інструментів -`tools.profile` встановлює базовий allowlist до застосування `allow`/`deny`. -Перевизначення для кожного агента: `agents.list[].tools.profile`. +`tools.profile` встановлює базовий список дозволів перед застосуванням `allow`/`deny`. +Перевизначення для окремого агента: `agents.list[].tools.profile`. -| Профіль | Що він включає | -| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Без обмежень (те саме, що не встановлено) | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | Лише `session_status` | +| Профіль | Що він містить | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `full` | Без обмежень (те саме, що не задано) | +| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | +| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `minimal` | Лише `session_status` | -Профілі `coding` і `messaging` також дозволяють налаштовані bundle MCP tools -під ключем Plugin `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, коли ви -хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP tools. -Профіль `minimal` не включає bundle MCP tools. +Профілі `coding` і `messaging` також дозволяють налаштовані bundled MCP-інструменти +під ключем плагіна `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, якщо ви +хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP-інструменти. +Профіль `minimal` не містить bundled MCP-інструментів. ### Групи інструментів Використовуйте скорочення `group:*` у списках allow/deny: -| Група | Інструменти | -| ----------------- | --------------------------------------------------------------------------------------------------------- | -| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | read, write, edit, apply_patch | -| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | -| `group:memory` | memory_search, memory_get | -| `group:web` | web_search, x_search, web_fetch | -| `group:ui` | browser, canvas | -| `group:automation`| cron, gateway | -| `group:messaging` | message | -| `group:nodes` | nodes | -| `group:agents` | agents_list | -| `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Усі вбудовані інструменти OpenClaw (без інструментів Plugin) | +| Група | Інструменти | +| ------------------ | ---------------------------------------------------------------------------------------------------------- | +| `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | +| `group:fs` | read, write, edit, apply_patch | +| `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | +| `group:memory` | memory_search, memory_get | +| `group:web` | web_search, x_search, web_fetch | +| `group:ui` | browser, canvas | +| `group:automation` | cron, gateway | +| `group:messaging` | message | +| `group:nodes` | nodes | +| `group:agents` | agents_list | +| `group:media` | image, image_generate, music_generate, video_generate, tts | +| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти плагінів) | -`sessions_history` повертає обмежений, safety-filtered вигляд recall. Він видаляє -теґи thinking, каркас ``, XML-пейлоади викликів інструментів у звичайному тексті -(включно з `...`, +`sessions_history` повертає обмежене, відфільтроване з погляду безпеки представлення для пригадування. +Воно видаляє теги мислення, каркас ``, XML-пейлоади викликів інструментів у відкритому тексті +(зокрема `...`, `...`, `...`, -`...` і усіченими блоками викликів інструментів), -понижений каркас викликів інструментів, leaked ASCII/full-width токени -керування моделлю і некоректний XML викликів інструментів MiniMax з тексту помічника, а потім застосовує -редагування/усікання і за потреби placeholder-и для надто великих рядків замість того, щоб поводитися -як сирий дамп transcript. +`...` та усічені блоки викликів інструментів), +понижений каркас викликів інструментів, витіклі ASCII/повноширинні токени керування +моделлю та некоректний XML викликів інструментів MiniMax із тексту асистента, а потім застосовує +редагування/усічення та, за потреби, заповнювачі для надто великих рядків, замість того щоб діяти +як необроблений дамп транскрипту. -### Обмеження, специфічні для провайдера +### Обмеження для конкретних провайдерів Використовуйте `tools.byProvider`, щоб обмежувати інструменти для конкретних провайдерів без -зміни глобальних типових значень: +зміни глобальних значень за замовчуванням: ```json5 { diff --git a/docs/uk/tools/multi-agent-sandbox-tools.md b/docs/uk/tools/multi-agent-sandbox-tools.md index 51816379b..a3382d128 100644 --- a/docs/uk/tools/multi-agent-sandbox-tools.md +++ b/docs/uk/tools/multi-agent-sandbox-tools.md @@ -1,31 +1,29 @@ --- read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.” status: active -summary: «Sandbox та обмеження інструментів для окремого агента, пріоритетність і приклади» -title: Sandbox і Tools для кількох агентів +summary: «Пісочниця та обмеження інструментів для кожного агента, пріоритетність і приклади» +title: Пісочниця багатьох агентів і інструменти x-i18n: - generated_at: "2026-04-24T03:49:18Z" + generated_at: "2026-04-25T00:15:14Z" model: gpt-5.4 provider: openai - source_hash: 7239e28825759efb060b821f87f5ebd9a7f3b720b30ff16dc076b186e47fcde9 + source_hash: 4473b8ea0f10c891b08cb56c9ba5a073f79c55b42f5b348b69ffb3c3d94c8f88 source_path: tools/multi-agent-sandbox-tools.md workflow: 15 --- -# Конфігурація Sandbox і Tools для кількох агентів +# Конфігурація пісочниці та інструментів для багатьох агентів -Кожен агент у конфігурації з кількома агентами може перевизначати глобальні -policy sandbox і tools. На цій сторінці описано конфігурацію для окремого агента, правила -пріоритетності та приклади. +Кожен агент у конфігурації з багатьма агентами може перевизначати глобальну політику пісочниці та інструментів. На цій сторінці описано конфігурацію для окремих агентів, правила пріоритетності та приклади. -- **Backend і режими sandbox**: див. [Ізоляція](/uk/gateway/sandboxing). -- **Діагностика заблокованих інструментів**: див. [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) і `openclaw sandbox explain`. -- **Elevated exec**: див. [Режим Elevated](/uk/tools/elevated). +- **Бекенди та режими пісочниці**: див. [Пісочниця](/uk/gateway/sandboxing). +- **Налагодження заблокованих інструментів**: див. [Пісочниця vs політика інструментів vs підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) і `openclaw sandbox explain`. +- **Підвищене виконання**: див. [Підвищений режим](/uk/tools/elevated). -Автентифікація є окремою для кожного агента: кожен агент читає зі свого сховища auth у `agentDir` -за шляхом `~/.openclaw/agents//agent/auth-profiles.json`. -Облікові дані **не** спільні між агентами. Ніколи не використовуйте той самий `agentDir` для кількох агентів. -Якщо ви хочете поділитися обліковими даними, скопіюйте `auth-profiles.json` в `agentDir` іншого агента. +Auth є окремою для кожного агента: кожен агент читає зі свого сховища auth у `agentDir` за адресою +`~/.openclaw/agents//agent/auth-profiles.json`. +Облікові дані **не** спільні між агентами. Ніколи не використовуйте один `agentDir` повторно для кількох агентів. +Якщо ви хочете поділитися обліковими даними, скопіюйте `auth-profiles.json` до `agentDir` іншого агента. --- @@ -77,12 +75,12 @@ policy sandbox і tools. На цій сторінці описано конфі **Результат:** -- Агент `main`: працює на хості, повний доступ до інструментів -- Агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read` +- агент `main`: працює на хості, має повний доступ до інструментів +- агент `family`: працює в Docker (один контейнер на агента), лише інструмент `read` --- -### Приклад 2: робочий агент зі спільним sandbox +### Приклад 2: робочий агент зі спільною пісочницею ```json { @@ -113,7 +111,7 @@ policy sandbox і tools. На цій сторінці описано конфі --- -### Приклад 2b: глобальний профіль coding + агент лише для messaging +### Приклад 2b: глобальний профіль для кодування + агент лише для повідомлень ```json { @@ -131,19 +129,19 @@ policy sandbox і tools. На цій сторінці описано конфі **Результат:** -- типові агенти отримують інструменти coding -- агент `support` працює лише з messaging (+ інструмент Slack) +- типові агенти отримують інструменти для кодування +- агент `support` призначений лише для повідомлень (+ інструмент Slack) --- -### Приклад 3: різні режими sandbox для різних агентів +### Приклад 3: різні режими пісочниці для різних агентів ```json { "agents": { "defaults": { "sandbox": { - "mode": "non-main", // Global default + "mode": "non-main", // Глобальне значення за замовчуванням "scope": "session" } }, @@ -152,14 +150,14 @@ policy sandbox і tools. На цій сторінці описано конфі "id": "main", "workspace": "~/.openclaw/workspace", "sandbox": { - "mode": "off" // Override: main never sandboxed + "mode": "off" // Перевизначення: main ніколи не в пісочниці } }, { "id": "public", "workspace": "~/.openclaw/workspace-public", "sandbox": { - "mode": "all", // Override: public always sandboxed + "mode": "all", // Перевизначення: public завжди в пісочниці "scope": "agent" }, "tools": { @@ -176,11 +174,11 @@ policy sandbox і tools. На цій сторінці описано конфі ## Пріоритетність конфігурації -Коли одночасно існують глобальні (`agents.defaults.*`) і специфічні для агента (`agents.list[].*`) конфігурації: +Коли існують і глобальні (`agents.defaults.*`), і агент-специфічні (`agents.list[].*`) конфігурації: -### Конфігурація Sandbox +### Конфігурація пісочниці -Налаштування для окремого агента мають пріоритет над глобальними: +Налаштування окремого агента перевизначають глобальні: ``` agents.list[].sandbox.mode > agents.defaults.sandbox.mode @@ -194,35 +192,41 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.* **Примітки:** -- `agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область sandbox розв’язується як `"shared"`). +- `agents.list[].sandbox.{docker,browser,prune}.*` перевизначає `agents.defaults.sandbox.{docker,browser,prune}.*` для цього агента (ігнорується, коли область дії пісочниці зводиться до `"shared"`). ### Обмеження інструментів Порядок фільтрації такий: 1. **Профіль інструментів** (`tools.profile` або `agents.list[].tools.profile`) -2. **Профіль інструментів provider** (`tools.byProvider[provider].profile` або `agents.list[].tools.byProvider[provider].profile`) -3. **Глобальна policy інструментів** (`tools.allow` / `tools.deny`) -4. **Policy інструментів provider** (`tools.byProvider[provider].allow/deny`) -5. **Policy інструментів для окремого агента** (`agents.list[].tools.allow/deny`) -6. **Policy provider для агента** (`agents.list[].tools.byProvider[provider].allow/deny`) -7. **Policy інструментів sandbox** (`tools.sandbox.tools` або `agents.list[].tools.sandbox.tools`) -8. **Policy інструментів субагента** (`tools.subagents.tools`, якщо застосовується) +2. **Профіль інструментів провайдера** (`tools.byProvider[provider].profile` або `agents.list[].tools.byProvider[provider].profile`) +3. **Глобальна політика інструментів** (`tools.allow` / `tools.deny`) +4. **Політика інструментів провайдера** (`tools.byProvider[provider].allow/deny`) +5. **Політика інструментів для окремого агента** (`agents.list[].tools.allow/deny`) +6. **Політика провайдера для агента** (`agents.list[].tools.byProvider[provider].allow/deny`) +7. **Політика інструментів пісочниці** (`tools.sandbox.tools` або `agents.list[].tools.sandbox.tools`) +8. **Політика інструментів субагента** (`tools.subagents.tools`, якщо застосовується) -Кожен рівень може додатково обмежувати інструменти, але не може знову дозволити інструменти, заборонені на попередніх рівнях. +Кожен рівень може додатково обмежувати інструменти, але не може повернути інструменти, заборонені на попередніх рівнях. Якщо задано `agents.list[].tools.sandbox.tools`, воно замінює `tools.sandbox.tools` для цього агента. Якщо задано `agents.list[].tools.profile`, воно перевизначає `tools.profile` для цього агента. -Ключі інструментів provider приймають або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`). +Ключі інструментів провайдера приймають або `provider` (наприклад, `google-antigravity`), або `provider/model` (наприклад, `openai/gpt-5.4`). -Policy інструментів підтримують скорочення `group:*`, які розгортаються в кілька інструментів. Повний список див. у [Групи інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands). +Якщо будь-який явний список дозволів у цьому ланцюжку призводить до того, що для запуску не лишається жодного викликного інструмента, +OpenClaw зупиняється до надсилання запиту моделі. Це зроблено навмисно: +агент, налаштований із відсутнім інструментом на кшталт +`agents.list[].tools.allow: ["query_db"]`, має завершуватися з явною помилкою, доки не буде ввімкнено Plugin, +який реєструє `query_db`, а не продовжувати працювати як агент лише з текстом. -Перевизначення elevated для окремого агента (`agents.list[].tools.elevated`) можуть додатково обмежувати elevated exec для конкретних агентів. Докладніше див. [Режим Elevated](/uk/tools/elevated). +Політики інструментів підтримують скорочення `group:*`, які розгортаються у кілька інструментів. Повний список див. у [Групи інструментів](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands). + +Перевизначення підвищеного режиму для окремого агента (`agents.list[].tools.elevated`) можуть додатково обмежувати підвищене виконання для конкретних агентів. Докладніше див. у [Підвищений режим](/uk/tools/elevated). --- ## Міграція з одного агента -**Було (один агент):** +**До (один агент):** ```json { @@ -245,7 +249,7 @@ Policy інструментів підтримують скорочення `gro } ``` -**Стало (кілька агентів із різними профілями):** +**Після (багато агентів із різними профілями):** ```json { @@ -262,11 +266,11 @@ Policy інструментів підтримують скорочення `gro } ``` -Застарілі конфігурації `agent.*` мігруються через `openclaw doctor`; надалі віддавайте перевагу `agents.defaults` + `agents.list`. +Застарілі конфігурації `agent.*` мігруються командою `openclaw doctor`; надалі віддавайте перевагу `agents.defaults` + `agents.list`. --- -## Приклади обмежень інструментів +## Приклади обмеження інструментів ### Агент лише для читання @@ -302,37 +306,36 @@ Policy інструментів підтримують скорочення `gro } ``` -` sessions_history` у цьому профілі все одно повертає обмежений, санітизований вигляд -відновлення, а не необроблений дамп транскрипту. Відновлення асистента прибирає теги thinking, -структуру ``, XML-payload викликів інструментів у звичайному тексті +`sessions_history` у цьому профілі все одно повертає обмежене, очищене представлення згадування, а не сирий дамп транскрипту. Згадування помічника прибирає thinking-теги, +каркас ``, +простотекстові XML-пейлоади викликів інструментів (включно з `...`, `...`, `...`, -`...` і обрізаними блоками викликів інструментів), -понижену структуру викликів інструментів, витоки ASCII/повноширинних токенів керування моделлю -та некоректний XML викликів інструментів MiniMax до редагування/обрізання. +`...`, а також обрізаними блоками викликів інструментів), +понижений каркас викликів інструментів, витоки ASCII/повноширинних +керувальних токенів моделі та некоректний MiniMax XML викликів інструментів перед редагуванням/обрізанням. --- -## Поширена пастка: "non-main" +## Поширена помилка: `"non-main"` `agents.defaults.sandbox.mode: "non-main"` базується на `session.mainKey` (типово `"main"`), а не на id агента. Сесії груп/каналів завжди отримують власні ключі, тому -вважаються неосновними й працюватимуть у sandbox. Якщо ви хочете, щоб агент ніколи не працював у -sandbox, задайте `agents.list[].sandbox.mode: "off"`. +вони вважаються не-main і будуть запускатися в пісочниці. Якщо ви хочете, щоб агент ніколи не використовував пісочницю, встановіть `agents.list[].sandbox.mode: "off"`. --- ## Тестування -Після налаштування sandbox і tools для кількох агентів: +Після налаштування пісочниці та інструментів для багатьох агентів: -1. **Перевірте розв’язання агента:** +1. **Перевірте визначення агента:** ```exec openclaw agents list --bindings ``` -2. **Перевірте sandbox контейнери:** +2. **Переконайтеся в наявності контейнерів пісочниці:** ```exec docker ps --filter "name=openclaw-sbx-" @@ -342,7 +345,7 @@ sandbox, задайте `agents.list[].sandbox.mode: "off"`. - Надішліть повідомлення, яке потребує обмежених інструментів - Переконайтеся, що агент не може використовувати заборонені інструменти -4. **Слідкуйте за логами:** +4. **Відстежуйте логи:** ```exec tail -f "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/logs/gateway.log" | grep -E "routing|sandbox|tools" @@ -350,31 +353,31 @@ sandbox, задайте `agents.list[].sandbox.mode: "off"`. --- -## Діагностика +## Усунення несправностей -### Агент не працює в sandbox попри `mode: "all"` +### Агент не запускається в пісочниці попри `mode: "all"` - Перевірте, чи немає глобального `agents.defaults.sandbox.mode`, яке це перевизначає -- Конфігурація для окремого агента має пріоритет, тому задайте `agents.list[].sandbox.mode: "all"` +- Конфігурація окремого агента має вищий пріоритет, тож встановіть `agents.list[].sandbox.mode: "all"` -### Інструменти все ще доступні попри список deny +### Інструменти все ще доступні попри список заборон -- Перевірте порядок фільтрації інструментів: global → agent → sandbox → subagent -- Кожен рівень може лише додатково обмежувати, а не повертати дозвіл -- Перевірте через логи: `[tools] filtering tools for agent:${agentId}` +- Перевірте порядок фільтрації інструментів: глобальний → агент → пісочниця → субагент +- Кожен рівень може лише додатково обмежувати, а не повертати дозволи +- Перевірте в логах: `[tools] filtering tools for agent:${agentId}` -### Контейнер не ізольований на рівні агента +### Контейнер не ізольований для кожного агента -- Задайте `scope: "agent"` у конфігурації sandbox для окремого агента -- Типове значення — `"session"`, що створює один контейнер на сесію +- Встановіть `scope: "agent"` в агент-специфічній конфігурації пісочниці +- Типове значення — `"session"`, яке створює один контейнер на сесію --- ## Пов’язане -- [Ізоляція](/uk/gateway/sandboxing) -- повний довідник sandbox (режими, області, backend, image) -- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- діагностика «чому це заблоковано?» -- [Режим Elevated](/uk/tools/elevated) -- [Маршрутизація кількох агентів](/uk/concepts/multi-agent) -- [Конфігурація Sandbox](/uk/gateway/config-agents#agentsdefaultssandbox) +- [Пісочниця](/uk/gateway/sandboxing) -- повний довідник щодо пісочниці (режими, області, бекенди, образи) +- [Пісочниця vs політика інструментів vs підвищений режим](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) -- налагодження питання «чому це заблоковано?» +- [Підвищений режим](/uk/tools/elevated) +- [Маршрутизація багатьох агентів](/uk/concepts/multi-agent) +- [Конфігурація пісочниці](/uk/gateway/config-agents#agentsdefaultssandbox) - [Керування сесіями](/uk/concepts/session)