diff --git a/docs/uk/tools/acp-agents-setup.md b/docs/uk/tools/acp-agents-setup.md index eedd2aac2..fbd66508a 100644 --- a/docs/uk/tools/acp-agents-setup.md +++ b/docs/uk/tools/acp-agents-setup.md @@ -6,17 +6,17 @@ read_when: summary: 'Налаштування агентів ACP: конфігурація acpx harness, налаштування Plugin, дозволи' title: Агенти ACP — налаштування x-i18n: - generated_at: "2026-04-24T02:43:40Z" + generated_at: "2026-04-25T04:14:00Z" model: gpt-5.4 provider: openai - source_hash: 7f1b34217b0709c85173ca13d952e996676b73b7ac7b9db91a5069e19ff76013 + source_hash: 5ddbcfb035f1d0a1902b49b9b292511adf496a35dd3bfd4c008cc335bbce0ebe source_path: tools/acp-agents-setup.md workflow: 15 --- -Огляд, операторський runbook і концепції див. у [ACP agents](/uk/tools/acp-agents). -Ця сторінка охоплює конфігурацію acpx harness, налаштування Plugin для мостів MCP і -налаштування дозволів. +Щоб переглянути огляд, operator runbook і концепції, див. [Агенти ACP](/uk/tools/acp-agents). +На цій сторінці описано конфігурацію acpx harness, налаштування Plugin для мостів MCP і +конфігурацію дозволів. ## Підтримка acpx harness (поточна) @@ -37,10 +37,10 @@ x-i18n: - `pi` - `qwen` -Коли OpenClaw використовує бекенд acpx, надавайте перевагу цим значенням для `agentId`, якщо тільки ваша конфігурація acpx не визначає власні псевдоніми агентів. -Якщо ваша локальна інсталяція Cursor досі надає ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого значення за замовчуванням. +Коли OpenClaw використовує бекенд acpx, надавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено власні псевдоніми агентів. +Якщо ваша локальна інсталяція Cursor досі показує ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого значення за замовчуванням. -Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent `, але цей необроблений обхідний шлях є функцією CLI acpx (а не звичайним шляхом OpenClaw `agentId`). +Пряме використання CLI acpx також може звертатися до довільних адаптерів через `--agent `, але цей необроблений обхідний механізм є функцією CLI acpx (а не звичайним шляхом OpenClaw `agentId`). ## Обов’язкова конфігурація @@ -50,7 +50,7 @@ x-i18n: { acp: { enabled: true, - // Необов’язково. За замовчуванням true; установіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp. + // Необов’язково. Значення за замовчуванням — true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp. dispatch: { enabled: true }, backend: "acpx", defaultAgent: "codex", @@ -82,7 +82,7 @@ x-i18n: } ``` -Конфігурація прив’язки потоків залежить від адаптера каналу. Приклад для Discord: +Конфігурація прив’язки потоків залежить від конкретного адаптера каналу. Приклад для Discord: ```json5 { @@ -108,13 +108,13 @@ x-i18n: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` -Прив’язки до поточної розмови не потребують створення дочірнього потоку. Вони потребують активного контексту розмови та адаптера каналу, який надає прив’язки розмов ACP. +Прив’язки до поточної розмови не потребують створення дочірнього потоку. Для них потрібен активний контекст розмови й адаптер каналу, який надає прив’язки розмов ACP. -Див. [Configuration Reference](/uk/gateway/configuration-reference). +Див. [Довідник із конфігурації](/uk/gateway/configuration-reference). -## Налаштування Plugin для бекенда acpx +## Налаштування Plugin для бекенду acpx -Свіжі інсталяції постачаються з увімкненим укомплектованим runtime Plugin `acpx` за замовчуванням, тому ACP +Свіжі інсталяції постачаються з увімкненим за замовчуванням вбудованим runtime Plugin `acpx`, тому ACP зазвичай працює без кроку ручного встановлення Plugin. Почніть із: @@ -123,21 +123,21 @@ x-i18n: /acp doctor ``` -Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny` або хочете -переключитися на локальну checkout-версію для розробки, використайте явний шлях Plugin: +Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny`, або хочете +переключитися на локальну checkout-версію для розробки, використовуйте явний шлях Plugin: ```bash openclaw plugins install acpx openclaw config set plugins.entries.acpx.enabled true ``` -Інсталяція локального workspace під час розробки: +Локальне встановлення з workspace під час розробки: ```bash openclaw plugins install ./path/to/local/acpx-plugin ``` -Потім перевірте стан бекенда: +Потім перевірте стан бекенду: ```text /acp doctor @@ -145,7 +145,7 @@ openclaw plugins install ./path/to/local/acpx-plugin ### Конфігурація команди та версії acpx -За замовчуванням укомплектований Plugin `acpx` використовує свій локальний закріплений бінарний файл (`node_modules/.bin/acpx` усередині пакета Plugin). Під час запуску бекенд реєструється як неготовий, а фонове завдання перевіряє `acpx --version`; якщо бінарний файл відсутній або не збігається за версією, воно запускає `npm install --omit=dev --no-save acpx@` і виконує повторну перевірку. Gateway увесь цей час залишається неблокувальним. +За замовчуванням вбудований Plugin `acpx` використовує свій локальний для Plugin зафіксований бінарний файл (`node_modules/.bin/acpx` усередині пакета Plugin). Під час запуску бекенд реєструється як неготовий, а фонове завдання перевіряє `acpx --version`; якщо бінарний файл відсутній або не збігається, виконується `npm install --omit=dev --no-save acpx@` і повторна перевірка. Увесь цей час Gateway залишається неблокувальним. Перевизначте команду або версію в конфігурації Plugin: @@ -165,23 +165,22 @@ openclaw plugins install ./path/to/local/acpx-plugin } ``` -- `command` приймає абсолютний шлях, відносний шлях (який обчислюється від workspace OpenClaw) або назву команди. +- `command` приймає абсолютний шлях, відносний шлях (обчислюється від workspace OpenClaw) або назву команди. - `expectedVersion: "any"` вимикає сувору перевірку відповідності версії. -- Власні шляхи `command` вимикають автоінсталяцію, локальну для Plugin. +- Власні шляхи `command` вимикають автоматичне встановлення, локальне для Plugin. Див. [Plugins](/uk/tools/plugin). ### Автоматичне встановлення залежностей -Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx -(платформозалежні бінарні файли) встановлюються автоматично -через хук postinstall. Якщо автоматичне встановлення не вдається, gateway усе одно запускається -нормально і повідомляє про відсутню залежність через `openclaw acp doctor`. +Коли ви встановлюєте OpenClaw глобально за допомогою `npm install -g openclaw`, runtime-залежності acpx +(бінарні файли для конкретної платформи) встановлюються автоматично +через хук postinstall. Якщо автоматичне встановлення не вдається, Gateway все одно запускається +нормально й повідомляє про відсутню залежність через `openclaw acp doctor`. -### Міст MCP інструментів Plugin +### Міст MCP для інструментів Plugin -За замовчуванням сеанси ACPX **не** надають інструменти, зареєстровані Plugin OpenClaw, до -ACP harness. +За замовчуванням сеанси ACPX **не** надають ACP harness доступу до інструментів, зареєстрованих Plugin OpenClaw. Якщо ви хочете, щоб агенти ACP, такі як Codex або Claude Code, могли викликати встановлені інструменти Plugin OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст: @@ -192,24 +191,22 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true Що це робить: -- Впроваджує вбудований MCP-сервер з назвою `openclaw-plugin-tools` у bootstrap - сеансу ACPX. -- Надає інструменти Plugin, уже зареєстровані встановленими й увімкненими Plugin - OpenClaw. -- Зберігає цю функцію явною та вимкненою за замовчуванням. +- Впроваджує вбудований сервер MCP з назвою `openclaw-plugin-tools` у bootstrap сеансу ACPX. +- Надає доступ до інструментів Plugin, уже зареєстрованих установленими й увімкненими Plugin OpenClaw. +- Зберігає цю можливість явною та вимкненою за замовчуванням. Примітки щодо безпеки та довіри: - Це розширює поверхню інструментів ACP harness. -- Агенти ACP отримують доступ лише до інструментів Plugin, які вже активні в gateway. -- Розглядайте це як ту саму межу довіри, що й дозвіл цим Plugin виконуватися в - самому OpenClaw. -- Перегляньте встановлені Plugin перед увімкненням. +- Агенти ACP отримують доступ лише до інструментів Plugin, які вже активні в Gateway. +- Розглядайте це як ту саму межу довіри, що й дозвіл цим Plugins виконуватися + у самому OpenClaw. +- Перевірте встановлені Plugins перед увімкненням. Власні `mcpServers` і далі працюють як раніше. Вбудований міст plugin-tools є -додатковою зручною функцією з явним увімкненням, а не заміною загальної конфігурації MCP-сервера. +додатковою зручною можливістю з явним увімкненням, а не заміною загальної конфігурації сервера MCP. -### Міст MCP інструментів OpenClaw +### Міст MCP для інструментів OpenClaw За замовчуванням сеанси ACPX також **не** надають вбудовані інструменти OpenClaw через MCP. Увімкніть окремий міст core-tools, коли агенту ACP потрібні вибрані @@ -221,60 +218,60 @@ openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true Що це робить: -- Впроваджує вбудований MCP-сервер з назвою `openclaw-tools` у bootstrap - сеансу ACPX. -- Надає вибрані вбудовані інструменти OpenClaw. Початковий сервер надає `cron`. -- Зберігає надання core-інструментів явним і вимкненим за замовчуванням. +- Впроваджує вбудований сервер MCP з назвою `openclaw-tools` у bootstrap сеансу ACPX. +- Надає доступ до вибраних вбудованих інструментів OpenClaw. Початковий сервер надає `cron`. +- Зберігає надання доступу до інструментів core явним і вимкненим за замовчуванням. ### Конфігурація тайм-ауту runtime -Укомплектований Plugin `acpx` за замовчуванням встановлює тайм-аут 120 секунд -для вбудованих turns runtime. Це дає достатньо часу повільнішим harness, таким як Gemini CLI, щоб завершити -запуск і ініціалізацію ACP. Перевизначте це значення, якщо вашому хосту потрібне інше +За замовчуванням вбудований Plugin `acpx` встановлює для вбудованих циклів runtime +тайм-аут 120 секунд. Це дає повільнішим harness, таким як Gemini CLI, достатньо часу для завершення +запуску й ініціалізації ACP. Перевизначте це значення, якщо вашому хосту потрібне інше обмеження runtime: ```bash openclaw config set plugins.entries.acpx.config.timeoutSeconds 180 ``` -Після зміни цього значення перезапустіть gateway. +Після зміни цього значення перезапустіть Gateway. -### Конфігурація агента для перевірки працездатності +### Конфігурація агента для probe перевірки стану -Укомплектований Plugin `acpx` перевіряє одного harness-агента, поки визначає, чи готовий -бекенд вбудованого runtime. За замовчуванням це `codex`. Якщо ваше розгортання використовує -інший агент ACP за замовчуванням, установіть для агента перевірки той самий id: +Вбудований Plugin `acpx` перевіряє один агент harness, коли визначає, чи готовий +бекенд вбудованого runtime. Якщо встановлено `acp.allowedAgents`, за замовчуванням використовується +перший дозволений агент; інакше за замовчуванням використовується `codex`. Якщо вашому розгортанню +потрібен інший агент ACP для перевірок стану, явно встановіть probe-агента: ```bash openclaw config set plugins.entries.acpx.config.probeAgent claude ``` -Після зміни цього значення перезапустіть gateway. +Після зміни цього значення перезапустіть Gateway. -## Налаштування дозволів +## Конфігурація дозволів -Сеанси ACP працюють у неінтерактивному режимі — TTY для схвалення або відхилення запитів на дозвіл запису у файли й виконання shell-команд відсутній. Plugin acpx надає два ключі конфігурації, які керують обробкою дозволів: +Сеанси ACP працюють у неінтерактивному режимі — TTY для підтвердження або відхилення запитів на дозволи запису файлів і виконання shell-команд відсутній. Plugin acpx надає два ключі конфігурації, які керують обробкою дозволів: -Ці дозволи ACPX harness є окремими від схвалень виконання OpenClaw і окремими від прапорців обходу постачальника CLI-бекенда, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP. +Ці дозволи harness ACPX є окремими від підтверджень виконання OpenClaw і окремими від прапорців обходу постачальника для CLI-бекенду, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP. ### `permissionMode` Керує тим, які операції агент harness може виконувати без запиту. -| Value | Behavior | +| Значення | Поведінка | | --------------- | --------------------------------------------------------- | -| `approve-all` | Автоматично схвалює всі записи у файли й shell-команди. | -| `approve-reads` | Автоматично схвалює лише читання; запис і exec потребують запитів. | -| `deny-all` | Відхиляє всі запити на дозвіл. | +| `approve-all` | Автоматично підтверджує всі записи файлів і shell-команди. | +| `approve-reads` | Автоматично підтверджує лише читання; запис і exec потребують запитів. | +| `deny-all` | Відхиляє всі запити на дозволи. | ### `nonInteractivePermissions` -Керує тим, що відбувається, коли мав би бути показаний запит на дозвіл, але інтерактивний TTY недоступний (що для сеансів ACP так є завжди). +Керує тим, що відбувається, коли має бути показано запит на дозвіл, але інтерактивний TTY недоступний (що для сеансів ACP так є завжди). -| Value | Behavior | -| ------ | ----------------------------------------------------------------- | -| `fail` | Перериває сеанс з `AcpRuntimeError`. **(за замовчуванням)** | -| `deny` | Мовчки відхиляє дозвіл і продовжує роботу (плавна деградація). | +| Значення | Поведінка | +| -------- | ---------------------------------------------------------------- | +| `fail` | Перериває сеанс з `AcpRuntimeError`. **(за замовчуванням)** | +| `deny` | Мовчки відхиляє дозвіл і продовжує роботу (плавна деградація). | ### Конфігурація @@ -285,14 +282,14 @@ openclaw config set plugins.entries.acpx.config.permissionMode approve-all openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail ``` -Після зміни цих значень перезапустіть gateway. +Після зміни цих значень перезапустіть Gateway. -> **Важливо:** OpenClaw наразі за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сеансах ACP будь-який запис або exec, що викликає запит на дозвіл, може завершитися з помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. +> **Важливо:** Зараз OpenClaw за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сеансах ACP будь-який запис або exec, що викликає запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`. > > Якщо вам потрібно обмежити дозволи, установіть `nonInteractivePermissions` у `deny`, щоб сеанси деградували плавно замість аварійного завершення. ## Пов’язане -- [ACP agents](/uk/tools/acp-agents) — огляд, операторський runbook, концепції +- [Агенти ACP](/uk/tools/acp-agents) — огляд, operator runbook, концепції - [Sub-agents](/uk/tools/subagents) -- [Multi-agent routing](/uk/concepts/multi-agent) +- [Маршрутизація між кількома агентами](/uk/concepts/multi-agent)