chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6ea44bb9b8
commit
adf4554da8
@ -1,192 +1,199 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск coding harnesses через ACP
|
||||
- Налаштування прив’язаних до розмови сесій ACP на каналах обміну повідомленнями
|
||||
- Прив’язування розмови в каналі обміну повідомленнями до постійної сесії ACP
|
||||
- Усунення несправностей backend ACP і підключення Plugin
|
||||
- Налагодження доставки завершення ACP або циклів agent-to-agent
|
||||
- Використання команд /acp у чаті
|
||||
summary: Використовуйте сесії runtime ACP для Claude Code, Cursor, Gemini CLI, явного fallback Codex ACP, OpenClaw ACP та інших harness-агентів
|
||||
title: Агенти ACP
|
||||
- Налаштування ACP-сеансів, прив’язаних до розмови, у каналах обміну повідомленнями
|
||||
- Прив’язка розмови в каналі повідомлень до постійного сеансу ACP
|
||||
- Усунення несправностей бекенду ACP і підключення Plugin-ів
|
||||
- Налагодження доставки завершень ACP або циклів агент-до-агента
|
||||
- Використання команд `/acp` у чаті
|
||||
summary: Використовуйте сеанси виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, ACP OpenClaw та інших агентів harness
|
||||
title: агенти ACP
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T04:20:02Z"
|
||||
generated_at: "2026-04-24T15:52:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6d59c5aa858e7888c9188ec9fc7dd5bcb9c8a5458f40d6458a5157ebc16332c2
|
||||
source_hash: e453b4b1c58d0705313b6a9d39af4c4f5579575715d06b44b830bf6d001e6bfb
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через backend Plugin ACP.
|
||||
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через ACP backend Plugin.
|
||||
|
||||
Якщо ви просите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові, OpenClaw має використовувати native Plugin app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`). Якщо ви просите `/acp`, ACP, acpx або фонову дочірню сесію Codex, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожне породження сесії ACP відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Якщо ви попросите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові, OpenClaw має використати нативний Plugin app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`). Якщо ви просите `/acp`, ACP, acpx або фоновий дочірній сеанс Codex, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
Якщо ви просите OpenClaw звичайною мовою «запустити Claude Code у thread» або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до runtime ACP (а не до native runtime підагента).
|
||||
Якщо ви попросите OpenClaw звичайною мовою «запустити Claude Code у thread» або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання sub-agent).
|
||||
|
||||
Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP client безпосередньо
|
||||
до наявних розмов каналів OpenClaw, використовуйте [`openclaw mcp serve`](/uk/cli/mcp)
|
||||
Якщо ви хочете, щоб Codex або Claude Code підключався як зовнішній клієнт MCP безпосередньо
|
||||
до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/uk/cli/mcp)
|
||||
замість ACP.
|
||||
|
||||
## Яку сторінку мені потрібно?
|
||||
## Яка сторінка мені потрібна?
|
||||
|
||||
Поруч є три поверхні, які легко переплутати:
|
||||
Поруч є три поверхні, які легко сплутати:
|
||||
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| ---------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Шлях native app-server Codex; включає прив’язані відповіді в чаті, переспрямування зображень, model/fast/permissions, stop і елементи steer. ACP — явний fallback |
|
||||
| Запустити Claude Code, Gemini CLI, явний Codex ACP або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сесії, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime |
|
||||
| Відкрити сесію Gateway OpenClaw _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим bridge. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket |
|
||||
| Повторно використати локальний AI CLI як текстовий fallback model | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Немає інструментів OpenClaw, немає елементів керування ACP, немає runtime harness |
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| ----------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex; включає прив’язані відповіді в чаті, пересилання зображень, model/fast/permissions, stop і steer controls. ACP — явний резервний варіант |
|
||||
| Запустити Claude Code, Gemini CLI, явний ACP Codex або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування runtime |
|
||||
| Відкрити сеанс Gateway OpenClaw _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим моста. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket |
|
||||
| Повторно використати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без runtime harness |
|
||||
|
||||
## Чи працює це одразу після встановлення?
|
||||
## Це працює одразу після встановлення?
|
||||
|
||||
Зазвичай так. Свіжі встановлення постачаються з увімкненим за замовчуванням вбудованим runtime Plugin `acpx`, із зафіксованим `acpx` binary на рівні Plugin, який OpenClaw перевіряє та самостійно відновлює під час запуску. Виконайте `/acp doctor` для перевірки готовності.
|
||||
Зазвичай так. У свіжих встановленнях bundled Plugin runtime `acpx` увімкнено за замовчуванням, із закріпленим локально для Plugin бінарником `acpx`, який OpenClaw перевіряє та самостійно відновлює під час запуску. Виконайте `/acp doctor`, щоб перевірити готовність.
|
||||
|
||||
Поширені нюанси першого запуску:
|
||||
|
||||
- Адаптери цільових harnesses (Codex, Claude тощо) можуть бути завантажені на вимогу через `npx` під час першого використання.
|
||||
- Автентифікація постачальника все одно має бути наявною на хості для цього harness.
|
||||
- Якщо хост не має npm або доступу до мережі, завантаження адаптерів під час першого запуску не вдасться, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
|
||||
- Адаптери цільового harness (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання.
|
||||
- Авторизація постачальника для цього harness усе ще має бути налаштована на хості.
|
||||
- Якщо на хості немає npm або доступу до мережі, завантаження адаптера під час першого запуску завершиться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
|
||||
|
||||
## Операторський runbook
|
||||
|
||||
Швидкий процес `/acp` із чату:
|
||||
Швидкий потік `/acp` із чату:
|
||||
|
||||
1. **Породити** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here`
|
||||
2. **Працювати** у прив’язаній розмові або thread (або явно вказати ключ сесії).
|
||||
3. **Перевірити стан** — `/acp status`
|
||||
4. **Налаштувати** — `/acp model <provider/model>`, `/acp permissions <profile>`, `/acp timeout <seconds>`
|
||||
5. **Скерувати** без заміни context — `/acp steer tighten logging and continue`
|
||||
6. **Зупинити** — `/acp cancel` (поточний хід) або `/acp close` (сесія + прив’язки)
|
||||
1. **Запуск** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here`
|
||||
2. **Працюйте** у прив’язаній розмові або thread (або явно вкажіть ключ сеансу).
|
||||
3. **Перевірте стан** — `/acp status`
|
||||
4. **Налаштуйте** — `/acp model <provider/model>`, `/acp permissions <profile>`, `/acp timeout <seconds>`
|
||||
5. **Скоригуйте** без заміни контексту — `/acp steer tighten logging and continue`
|
||||
6. **Зупиніть** — `/acp cancel` (поточний turn) або `/acp close` (сеанс + прив’язки)
|
||||
|
||||
Тригери природною мовою, які мають маршрутизуватися до native Plugin Codex:
|
||||
Тригери природною мовою, які мають маршрутизуватися до нативного Plugin Codex:
|
||||
|
||||
- "Bind this Discord channel to Codex."
|
||||
- "Attach this chat to Codex thread `<id>`."
|
||||
- "Show Codex threads, then bind this one."
|
||||
- «Прив’яжи цей канал Discord до Codex.»
|
||||
- «Під’єднай цей чат до thread Codex `<id>`.»
|
||||
- «Покажи threads Codex, а потім прив’яжи цей.»
|
||||
|
||||
Native прив’язка розмови Codex — це типовий шлях керування чатом, але він навмисно консервативний для інтерактивних потоків погодження/інструментів Codex: dynamic tools OpenClaw і prompts погодження поки що не доступні через цей шлях прив’язаного чату, тому такі запити відхиляються з чітким поясненням. Використовуйте шлях harness Codex або явний fallback ACP, коли робочий процес залежить від dynamic tools OpenClaw або довготривалих інтерактивних погоджень.
|
||||
Нативна прив’язка розмов Codex є типовим шляхом керування чатом. Динамічні інструменти OpenClaw, як і раніше, виконуються через OpenClaw, тоді як нативні інструменти Codex, як-от
|
||||
shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw
|
||||
впроваджує relay нативних hook-ів для кожного turn, щоб hook-и Plugin могли блокувати
|
||||
`before_tool_call`, спостерігати за `after_tool_call` і маршрутизувати події Codex
|
||||
`PermissionRequest` через погодження OpenClaw. Relay v1
|
||||
навмисно консервативний: він не змінює аргументи нативних інструментів Codex,
|
||||
не переписує записи thread Codex і не контролює фінальні відповіді/Stop hook-и. Використовуйте явний
|
||||
ACP лише тоді, коли вам потрібна модель runtime/сеансів ACP.
|
||||
|
||||
Тригери природною мовою, які мають маршрутизуватися до runtime ACP:
|
||||
|
||||
- "Run this as a one-shot Claude Code ACP session and summarize the result."
|
||||
- "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."
|
||||
- "Run Codex through ACP in a background thread."
|
||||
- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат.»
|
||||
- «Використай Gemini CLI для цього завдання у thread, а потім зберігай подальші звернення в тому самому thread.»
|
||||
- «Запусти Codex через ACP у фоновому thread.»
|
||||
|
||||
OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язується до поточної розмови або thread, коли це підтримується, і маршрутизує подальші повідомлення до цієї сесії до закриття/завершення строку дії. Codex слідує цим шляхом лише тоді, коли ACP указано явно або коли запитуваний фоновий runtime усе ще потребує ACP.
|
||||
OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язується до поточної розмови або thread, коли це підтримується, і маршрутизує подальші звернення до цього сеансу до його закриття або завершення строку дії. Codex переходить цим шляхом лише тоді, коли ACP запитано явно або коли для потрібного фонового runtime усе ще потрібен ACP.
|
||||
|
||||
## ACP проти підагентів
|
||||
## ACP проти sub-agents
|
||||
|
||||
Використовуйте ACP, коли вам потрібен зовнішній runtime harness. Використовуйте native app-server Codex для прив’язки/керування розмовами Codex. Використовуйте підагентів, коли вам потрібні делеговані запуски, native для OpenClaw.
|
||||
Використовуйте ACP, коли вам потрібен зовнішній runtime harness. Використовуйте нативний app-server Codex для прив’язки/керування розмовами Codex. Використовуйте sub-agents, коли вам потрібні делеговані запуски всередині OpenClaw.
|
||||
|
||||
| Область | Сесія ACP | Запуск підагента |
|
||||
| ------------- | ------------------------------------- | ----------------------------------- |
|
||||
| Runtime | backend Plugin ACP (наприклад acpx) | native runtime підагента OpenClaw |
|
||||
| Ключ сесії | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент spawn | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типовий runtime) |
|
||||
| Область | Сеанс ACP | Запуск sub-agent |
|
||||
| ------------- | -------------------------------------- | ----------------------------------- |
|
||||
| Runtime | ACP backend Plugin (наприклад acpx) | Нативний runtime sub-agent OpenClaw |
|
||||
| Ключ сеансу | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) |
|
||||
|
||||
Див. також [Підагенти](/uk/tools/subagents).
|
||||
Див. також [Sub-agents](/uk/tools/subagents).
|
||||
|
||||
## Як ACP запускає Claude Code
|
||||
|
||||
Для Claude Code через ACP стек такий:
|
||||
|
||||
1. Площина керування сесією ACP OpenClaw
|
||||
2. вбудований runtime Plugin `acpx`
|
||||
3. адаптер Claude ACP
|
||||
4. механіка runtime/сесії на боці Claude
|
||||
1. Площина керування сеансами ACP OpenClaw
|
||||
2. bundled Plugin runtime `acpx`
|
||||
3. ACP-адаптер Claude
|
||||
4. Механізм runtime/сеансів на боці Claude
|
||||
|
||||
Важлива відмінність:
|
||||
Важливе розрізнення:
|
||||
|
||||
- ACP Claude — це сесія harness з елементами керування ACP, відновленням сесії, відстеженням фонового завдання та необов’язковою прив’язкою розмови/thread.
|
||||
- CLI backends — це окремі локальні runtime fallback лише для тексту. Див. [CLI Backends](/uk/gateway/cli-backends).
|
||||
- ACP Claude — це сеанс harness із керуванням ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/thread.
|
||||
- CLI backends — це окремі локальні runtime лише для текстового резервного режиму. Див. [CLI Backends](/uk/gateway/cli-backends).
|
||||
|
||||
Для операторів практичне правило таке:
|
||||
|
||||
- якщо потрібні `/acp spawn`, сесії з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP
|
||||
- якщо потрібен простий локальний текстовий fallback через raw CLI: використовуйте CLI backends
|
||||
- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP
|
||||
- потрібен простий локальний текстовий резервний режим через сирий CLI: використовуйте CLI backends
|
||||
|
||||
## Прив’язані сесії
|
||||
## Прив’язані сеанси
|
||||
|
||||
### Прив’язки до поточної розмови
|
||||
|
||||
`/acp spawn <harness> --bind here` прикріплює поточну розмову до породженої сесії ACP — без дочірнього thread, та сама поверхня чату. OpenClaw продовжує володіти transport, auth, safety і доставкою; подальші повідомлення в цій розмові маршрутизуються до тієї самої сесії; `/new` і `/reset` скидають сесію на місці; `/acp close` прибирає прив’язку.
|
||||
`/acp spawn <harness> --bind here` закріплює поточну розмову за створеним сеансом ACP — без дочірнього thread, у тій самій поверхні чату. OpenClaw продовжує відповідати за transport, auth, safety і доставку; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` знімає прив’язку.
|
||||
|
||||
Ментальна модель:
|
||||
|
||||
- **поверхня чату** — де люди продовжують спілкуватися (канал Discord, topic Telegram, чат iMessage).
|
||||
- **сесія ACP** — довговічний стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw.
|
||||
- **дочірній thread/topic** — необов’язкова додаткова поверхня обміну повідомленнями, створювана лише через `--thread ...`.
|
||||
- **робочий простір runtime** — розташування файлової системи (`cwd`, checkout repo, робочий простір backend), де працює harness. Воно не залежить від поверхні чату.
|
||||
- **поверхня чату** — місце, де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage).
|
||||
- **сеанс ACP** — стійкий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw.
|
||||
- **дочірній thread/topic** — необов’язкова додаткова поверхня обміну повідомленнями, яка створюється лише через `--thread ...`.
|
||||
- **робочий простір runtime** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір backend), де працює harness. Не залежить від поверхні чату.
|
||||
|
||||
Приклади:
|
||||
|
||||
- `/codex bind` — зберегти цей чат, породити або приєднати native app-server Codex, маршрутизувати майбутні повідомлення сюди.
|
||||
- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштовувати прив’язаний native thread Codex із чату.
|
||||
- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним ходом native Codex.
|
||||
- `/acp spawn codex --bind here` — явний fallback ACP для Codex.
|
||||
- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній thread/topic і прив’язати там.
|
||||
- `/codex bind` — залишити цей чат, запустити або приєднати нативний app-server Codex, маршрутизувати сюди майбутні повідомлення.
|
||||
- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштувати прив’язаний нативний thread Codex із чату.
|
||||
- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним turn нативного Codex.
|
||||
- `/acp spawn codex --bind here` — явний резервний варіант ACP для Codex.
|
||||
- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній thread/topic і прив’язати його там.
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка чату, Codex працює в `/workspace/repo`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` і `--thread ...` взаємовиключні.
|
||||
- `--bind here` працює лише на каналах, які оголошують прив’язку до поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язки зберігаються після перезапусків gateway.
|
||||
- `--bind here` працює лише в каналах, які оголошують підтримку прив’язки до поточної розмови; інакше OpenClaw повертає чітке повідомлення про відсутність підтримки. Прив’язки зберігаються після перезапусків Gateway.
|
||||
- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній thread для `--thread auto|here`, а не для `--bind here`.
|
||||
- Якщо ви породжуєте інший ACP agent без `--cwd`, OpenClaw типово успадковує робочий простір **цільового agent**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) переводяться на типовий backend; інші помилки доступу (наприклад `EACCES`) показуються як помилки spawn.
|
||||
- Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до стандартного значення backend; інші помилки доступу (наприклад `EACCES`) відображаються як помилки запуску.
|
||||
|
||||
### Сесії, прив’язані до thread
|
||||
### Сеанси, прив’язані до thread
|
||||
|
||||
Коли прив’язки thread увімкнено для adapter каналу, сесії ACP можна прив’язувати до threads:
|
||||
Коли для адаптера каналу ввімкнено прив’язки до thread, сеанси ACP можна прив’язувати до thread:
|
||||
|
||||
- OpenClaw прив’язує thread до цільової сесії ACP.
|
||||
- Подальші повідомлення в цьому thread маршрутизуються до прив’язаної сесії ACP.
|
||||
- OpenClaw прив’язує thread до цільового сеансу ACP.
|
||||
- Подальші повідомлення в цьому thread маршрутизуються до прив’язаного сеансу ACP.
|
||||
- Вивід ACP доставляється назад у той самий thread.
|
||||
- Втрата фокуса/закриття/архівування/тайм-аут бездіяльності або завершення максимального строку дії прибирає прив’язку.
|
||||
- Зняття фокуса/закриття/архівування/завершення часу очікування бездіяльності або завершення максимального строку дії знімає прив’язку.
|
||||
|
||||
Підтримка прив’язки thread залежить від adapter. Якщо активний adapter каналу не підтримує прив’язки thread, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність.
|
||||
Підтримка прив’язки до thread залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до thread, OpenClaw повертає чітке повідомлення про відсутність підтримки/недоступність.
|
||||
|
||||
Потрібні feature flags для ACP, прив’язаного до thread:
|
||||
Обов’язкові feature flags для ACP, прив’язаного до thread:
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` увімкнено типово (встановіть `false`, щоб призупинити dispatch ACP)
|
||||
- Увімкнений прапорець породження ACP thread у channel-adapter (залежить від adapter)
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP)
|
||||
- Увімкнено прапорець запуску ACP thread у адаптері каналу (залежить від адаптера)
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
### Канали з підтримкою thread
|
||||
|
||||
- Будь-який adapter каналу, який надає можливість прив’язки session/thread.
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/thread.
|
||||
- Поточна вбудована підтримка:
|
||||
- threads/channels Discord
|
||||
- topics Telegram (forum topics у groups/supergroups і DM topics)
|
||||
- Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язки.
|
||||
- topics Telegram (теми форуму в групах/supergroups і DM topics)
|
||||
- Канали Plugin можуть додати підтримку через той самий інтерфейс прив’язки.
|
||||
|
||||
## Налаштування, специфічні для каналу
|
||||
## Налаштування для конкретних каналів
|
||||
|
||||
Для неплинних робочих процесів налаштовуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`.
|
||||
Для неепhemeralних робочих процесів налаштовуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`.
|
||||
|
||||
### Модель прив’язки
|
||||
|
||||
- `bindings[].type="acp"` позначає постійну прив’язку розмови ACP.
|
||||
- `bindings[].match` ідентифікує цільову розмову:
|
||||
- канал або thread Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- forum topic Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- DM/group chat BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Надавайте перевагу `chat_id:*` або `chat_identifier:*` для стабільних прив’язок груп.
|
||||
- DM/group chat iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Надавайте перевагу `chat_id:*` для стабільних прив’язок груп.
|
||||
- `bindings[].agentId` — це id agent OpenClaw, якому належить прив’язка.
|
||||
- Необов’язкові перевизначення ACP містяться в `bindings[].acp`:
|
||||
- `bindings[].match` визначає цільову розмову:
|
||||
- Канал або thread Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок віддавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw-власника.
|
||||
- Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`:
|
||||
- `mode` (`persistent` або `oneshot`)
|
||||
- `label`
|
||||
- `cwd`
|
||||
- `backend`
|
||||
|
||||
### Типові значення runtime для кожного agent
|
||||
### Значення runtime за замовчуванням для кожного агента
|
||||
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного agent:
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента:
|
||||
|
||||
- `agents.list[].runtime.type="acp"`
|
||||
- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`)
|
||||
@ -194,7 +201,7 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
|
||||
- `agents.list[].runtime.acp.mode`
|
||||
- `agents.list[].runtime.acp.cwd`
|
||||
|
||||
Пріоритет перевизначення для прив’язаних сесій ACP:
|
||||
Порядок пріоритету перевизначень для прив’язаних сеансів ACP:
|
||||
|
||||
1. `bindings[].acp.*`
|
||||
2. `agents.list[].runtime.acp.*`
|
||||
@ -282,18 +289,18 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw гарантує, що налаштована сесія ACP існує перед використанням.
|
||||
- Повідомлення в цьому каналі або topic маршрутизуються до налаштованої сесії ACP.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сесії ACP на місці.
|
||||
- Тимчасові прив’язки runtime (наприклад створені потоками thread-focus) усе ще застосовуються, де вони є.
|
||||
- Для міжагентних ACP spawn без явного `cwd` OpenClaw успадковує робочий простір цільового agent із config agent.
|
||||
- Відсутні успадковані шляхи робочого простору переводяться на типовий `cwd` backend; помилки доступу для наявних шляхів повертаються як помилки spawn.
|
||||
- OpenClaw забезпечує існування налаштованого сеансу ACP перед використанням.
|
||||
- Повідомлення в цьому каналі або topic маршрутизуються до налаштованого сеансу ACP.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці.
|
||||
- Тимчасові прив’язки runtime (наприклад, створені потоками thread-focus) усе ще застосовуються там, де вони присутні.
|
||||
- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи робочого простору повертаються до стандартного `cwd` backend; помилки доступу за наявного шляху відображаються як помилки запуску.
|
||||
|
||||
## Запуск сесій ACP (інтерфейси)
|
||||
## Запуск сеансів ACP (інтерфейси)
|
||||
|
||||
### Із `sessions_spawn`
|
||||
|
||||
Використовуйте `runtime: "acp"`, щоб запустити сесію ACP із ходу agent або виклику tool.
|
||||
Використовуйте `runtime: "acp"` для запуску сеансу ACP з turn агента або виклику інструмента.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -307,68 +314,68 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
|
||||
|
||||
Примітки:
|
||||
|
||||
- `runtime` типово має значення `subagent`, тому для сесій ACP явно вказуйте `runtime: "acp"`.
|
||||
- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, коли його налаштовано.
|
||||
- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову.
|
||||
- Типовим значенням `runtime` є `subagent`, тому для сеансів ACP явно вказуйте `runtime: "acp"`.
|
||||
- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано.
|
||||
- `mode: "session"` вимагає `thread: true`, щоб зберігати постійну прив’язану розмову.
|
||||
|
||||
Деталі інтерфейсу:
|
||||
Докладніше про інтерфейс:
|
||||
|
||||
- `task` (обов’язковий): початковий prompt, що надсилається до сесії ACP.
|
||||
- `runtime` (обов’язковий для ACP): має бути `"acp"`.
|
||||
- `agentId` (необов’язковий): id цільового harness ACP. Використовує `acp.defaultAgent` як fallback, якщо його задано.
|
||||
- `thread` (необов’язковий, типово `false`): запитати потік прив’язки thread, де це підтримується.
|
||||
- `mode` (необов’язковий): `run` (одноразовий запуск) або `session` (постійний).
|
||||
- `task` (обов’язково): початковий prompt, надісланий до сеансу ACP.
|
||||
- `runtime` (обов’язково для ACP): має бути `"acp"`.
|
||||
- `agentId` (необов’язково): id цільового harness ACP. Якщо задано, використовується `acp.defaultAgent`.
|
||||
- `thread` (необов’язково, типово `false`): запит потоку прив’язки до thread, якщо підтримується.
|
||||
- `mode` (необов’язково): `run` (одноразовий запуск) або `session` (постійний).
|
||||
- типове значення — `run`
|
||||
- якщо `thread: true` і mode пропущено, OpenClaw може типово вибирати постійну поведінку залежно від шляху runtime
|
||||
- якщо `thread: true` і mode не вказано, OpenClaw може типово використовувати постійну поведінку залежно від шляху runtime
|
||||
- `mode: "session"` вимагає `thread: true`
|
||||
- `cwd` (необов’язковий): запитуваний робочий каталог runtime (перевіряється політикою backend/runtime). Якщо пропущено, ACP spawn успадковує робочий простір цільового agent, коли його налаштовано; відсутні успадковані шляхи переводяться на типові значення backend, тоді як реальні помилки доступу повертаються.
|
||||
- `label` (необов’язковий): мітка для оператора, яка використовується в тексті сесії/банера.
|
||||
- `resumeSessionId` (необов’язковий): відновити наявну сесію ACP замість створення нової. Agent відтворює історію своєї розмови через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язковий): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сесії-запитувача як системні події.
|
||||
- Якщо доступно, прийняті відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сесії (`<sessionId>.acp-stream.jsonl`), який можна переглядати для повної історії relay.
|
||||
- `model` (необов’язковий): явне перевизначення model для дочірньої сесії ACP. Враховується для `runtime: "acp"`, щоб дочірня сесія використовувала запитану model замість неявного fallback до типового значення цільового agent.
|
||||
- `cwd` (необов’язково): запитуваний робочий каталог runtime (перевіряється політикою backend/runtime). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень backend, а реальні помилки доступу повертаються.
|
||||
- `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює історію своєї розмови через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` транслює зведення прогресу початкового запуску ACP назад до сеансу-запитувача як системні події.
|
||||
- Якщо доступно, прийняті відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна переглядати для повної історії relay.
|
||||
- `model` (необов’язково): явне перевизначення model для дочірнього сеансу ACP. Використовується для `runtime: "acp"`, щоб дочірній сеанс використовував запитану model замість тихого повернення до типового значення цільового агента.
|
||||
|
||||
## Модель доставки
|
||||
|
||||
Сесії ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить parent. Шлях доставки залежить від цієї форми.
|
||||
Сеанси ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківському процесу. Шлях доставки залежить від цієї форми.
|
||||
|
||||
### Інтерактивні сесії ACP
|
||||
### Інтерактивні сеанси ACP
|
||||
|
||||
Інтерактивні сесії призначені для продовження спілкування на видимій поверхні чату:
|
||||
Інтерактивні сеанси призначені для продовження спілкування на видимій поверхні чату:
|
||||
|
||||
- `/acp spawn ... --bind here` прив’язує поточну розмову до сесії ACP.
|
||||
- `/acp spawn ... --thread ...` прив’язує thread/topic каналу до сесії ACP.
|
||||
- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до тієї самої сесії ACP.
|
||||
- `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP.
|
||||
- `/acp spawn ... --thread ...` прив’язує thread/topic каналу до сеансу ACP.
|
||||
- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP.
|
||||
|
||||
Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сесії ACP, а вивід ACP доставляється назад до того самого каналу/thread/topic.
|
||||
Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/thread/topic.
|
||||
|
||||
### Одноразові сесії ACP, що належать parent
|
||||
### Одноразові сеанси ACP, що належать батьківському процесу
|
||||
|
||||
Одноразові сесії ACP, породжені іншим запуском agent, є фоновими дочірніми сесіями, подібно до підагентів:
|
||||
Одноразові сеанси ACP, запущені іншим агентом, є фоновими дочірніми процесами, подібно до sub-agents:
|
||||
|
||||
- Parent запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`.
|
||||
- Дочірня сесія виконується у власній сесії harness ACP.
|
||||
- Завершення повідомляється назад через внутрішній шлях сповіщення про завершення завдання.
|
||||
- Parent переписує результат дочірньої сесії звичайним голосом assistant, коли потрібна відповідь для користувача.
|
||||
- Батьківський процес запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`.
|
||||
- Дочірній процес працює у власному сеансі harness ACP.
|
||||
- Завершення повертається через внутрішній шлях оголошення завершення завдання.
|
||||
- Батьківський процес переписує результат дочірнього процесу у звичайному голосі помічника, коли потрібна відповідь для користувача.
|
||||
|
||||
Не розглядайте цей шлях як peer-to-peer чат між parent і child. Дочірня сесія вже має канал завершення назад до parent.
|
||||
Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім процесами. Дочірній процес уже має канал завершення назад до батьківського процесу.
|
||||
|
||||
### `sessions_send` і доставка A2A
|
||||
|
||||
`sessions_send` може націлюватися на іншу сесію після spawn. Для звичайних peer-сесій OpenClaw використовує шлях подальшої взаємодії agent-to-agent (A2A) після вставлення повідомлення:
|
||||
`sessions_send` може бути націлено на інший сеанс після запуску. Для звичайних peer-сеансів OpenClaw використовує шлях подальших дій agent-to-agent (A2A) після впровадження повідомлення:
|
||||
|
||||
- чекати відповіді цільової сесії
|
||||
- за потреби дозволити запитувачу й цілі обмінятися обмеженою кількістю подальших ходів
|
||||
- попросити цільову сесію створити announce message
|
||||
- доставити це announce у видимий канал або thread
|
||||
- очікує відповіді цільового сеансу
|
||||
- за потреби дозволяє запитувачу та цілі обмінятися обмеженою кількістю додаткових turn-ів
|
||||
- просить цільовий сеанс створити повідомлення-оголошення
|
||||
- доставляє це оголошення у видимий канал або thread
|
||||
|
||||
Цей шлях A2A є fallback для peer-відправлень, де відправнику потрібна видима подальша відповідь. Він залишається ввімкненим, коли непов’язана сесія може бачити й надсилати повідомлення до цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`.
|
||||
Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібна видима подальша дія. Він залишається увімкненим, коли непов’язаний сеанс може бачити й надсилати повідомлення ACP-цілі, наприклад за широких налаштувань `tools.sessions.visibility`.
|
||||
|
||||
OpenClaw пропускає подальшу взаємодію A2A лише тоді, коли запитувач є parent власної одноразової дочірньої сесії ACP, що йому належить. У такому разі запуск A2A поверх завершення завдання може пробудити parent результатом child, переслати відповідь parent назад у child і створити цикл echo між parent і child. Результат `sessions_send` повідомляє `delivery.status="skipped"` для такого випадку owned-child, оскільки шлях завершення вже відповідає за результат.
|
||||
OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським процесом власного одноразового дочірнього процесу ACP. У такому разі запуск A2A поверх завершення завдання може пробудити батьківський процес результатом дочірнього, переслати відповідь батьківського процесу назад у дочірній і створити цикл echo між батьківським і дочірнім процесами. Результат `sessions_send` повідомляє `delivery.status="skipped"` для такого випадку власного дочірнього процесу, оскільки за результат уже відповідає шлях завершення.
|
||||
|
||||
### Відновлення наявної сесії
|
||||
### Відновлення наявного сеансу
|
||||
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередню сесію ACP замість запуску з нуля. Agent відтворює історію своєї розмови через `session/load`, тому підхоплює роботу з повним context того, що було раніше.
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює історію своєї розмови через `session/load`, тому продовжує з повним контекстом попередньої роботи.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -379,45 +386,45 @@ OpenClaw пропускає подальшу взаємодію A2A лише т
|
||||
}
|
||||
```
|
||||
|
||||
Поширені сценарії використання:
|
||||
Поширені варіанти використання:
|
||||
|
||||
- Передати сесію Codex з ноутбука на телефон — попросіть свого agent продовжити з того місця, де ви зупинилися
|
||||
- Продовжити coding session, яку ви почали інтерактивно в CLI, а тепер — безголово через свого agent
|
||||
- Відновити роботу, яку було перервано перезапуском gateway або тайм-аутом бездіяльності
|
||||
- Передати сеанс Codex з ноутбука на телефон — попросіть свого агента продовжити з того місця, де ви зупинилися
|
||||
- Продовжити coding session, який ви почали інтерактивно в CLI, тепер у безголовому режимі через агента
|
||||
- Продовжити роботу, яку перервав перезапуск gateway або idle timeout
|
||||
|
||||
Примітки:
|
||||
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується з runtime підагента.
|
||||
- `resumeSessionId` відновлює історію розмови ACP вище за потоком; `thread` і `mode` усе одно застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` як і раніше вимагає `thread: true`.
|
||||
- Цільовий agent має підтримувати `session/load` (Codex і Claude Code підтримують).
|
||||
- Якщо id сесії не знайдено, spawn завершується з чіткою помилкою — без тихого fallback до нової сесії.
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується з runtime sub-agent.
|
||||
- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще звичайно застосовуються до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
|
||||
- Якщо id сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нового сеансу.
|
||||
|
||||
<Accordion title="Smoke-тест після розгортання">
|
||||
|
||||
Після розгортання gateway виконайте живу наскрізну перевірку замість того, щоб покладатися лише на модульні тести:
|
||||
Після розгортання gateway виконайте повну живу перевірку, а не покладайтеся лише на unit-тести:
|
||||
|
||||
1. Перевірте версію та commit розгорнутого gateway на цільовому хості.
|
||||
2. Відкрийте тимчасову bridge-сесію ACPX до live agent.
|
||||
3. Попросіть цього agent викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`.
|
||||
2. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента.
|
||||
3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`.
|
||||
4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки validator.
|
||||
5. Очистіть тимчасову bridge-сесію.
|
||||
5. Очистьте тимчасовий bridge-сеанс.
|
||||
|
||||
Залишайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — прив’язані до thread `mode: "session"` і шляхи relay потоку є окремими, багатшими інтеграційними перевірками.
|
||||
Для цієї перевірки використовуйте `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи `mode: "session"`, прив’язані до thread, і relay потоку є окремими, багатшими інтеграційними проходами.
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Сумісність із sandbox
|
||||
|
||||
Сесії ACP зараз працюють у runtime хоста, а не всередині sandbox OpenClaw.
|
||||
Наразі сеанси ACP працюють у runtime хоста, а не всередині sandbox OpenClaw.
|
||||
|
||||
Поточні обмеження:
|
||||
|
||||
- Якщо сесія-запитувач перебуває в sandbox, ACP spawn блокується як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Якщо сеанс-запитувач працює в sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Помилка: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
|
||||
- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`.
|
||||
- Помилка: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
|
||||
|
||||
Використовуйте `runtime: "subagent"`, коли вам потрібне виконання з примусовим sandbox.
|
||||
Використовуйте `runtime: "subagent"`, коли вам потрібне виконання з примусовим застосуванням sandbox.
|
||||
|
||||
### Із команди `/acp`
|
||||
|
||||
@ -438,80 +445,80 @@ OpenClaw пропускає подальшу взаємодію A2A лише т
|
||||
- `--cwd <absolute-path>`
|
||||
- `--label <name>`
|
||||
|
||||
Див. [Косі команди](/uk/tools/slash-commands).
|
||||
Див. [Slash Commands](/uk/tools/slash-commands).
|
||||
|
||||
## Визначення цілі сесії
|
||||
## Визначення цілі сеансу
|
||||
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, `session-id` або `session-label`).
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`).
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
1. Явний аргумент цілі (або `--session` для `/acp steer`)
|
||||
- спочатку пробує key
|
||||
- потім session id у формі UUID
|
||||
- спочатку пробує ключ
|
||||
- потім session id у форматі UUID
|
||||
- потім label
|
||||
2. Поточна прив’язка thread (якщо ця розмова/thread прив’язана до сесії ACP)
|
||||
3. Fallback до поточної сесії-запитувача
|
||||
2. Поточна прив’язка thread (якщо ця розмова/thread прив’язана до сеансу ACP)
|
||||
3. Резервний варіант із поточним сеансом запитувача
|
||||
|
||||
Прив’язки до поточної розмови й прив’язки thread обидві беруть участь у кроці 2.
|
||||
Прив’язки до поточної розмови й прив’язки до thread беруть участь у кроці 2.
|
||||
|
||||
Якщо не вдається визначити жодної цілі, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
|
||||
## Режими прив’язки spawn
|
||||
## Режими прив’язки під час запуску
|
||||
|
||||
`/acp spawn` підтримує `--bind here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ----------------------------------------------------------------------- |
|
||||
| Режим | Поведінка |
|
||||
| ------ | --------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` — найпростіший операторський шлях для «зробити цей канал або чат таким, що працює через Codex».
|
||||
- `--bind here` — це найпростіший шлях для оператора для сценарію «зробити цей канал або чат підключеним до Codex».
|
||||
- `--bind here` не створює дочірній thread.
|
||||
- `--bind here` доступний лише на каналах, які надають підтримку прив’язки до поточної розмови.
|
||||
- `--bind here` доступний лише в каналах, що підтримують прив’язку до поточної розмови.
|
||||
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
|
||||
|
||||
## Режими thread для spawn
|
||||
## Режими thread під час запуску
|
||||
|
||||
`/acp spawn` підтримує `--thread auto|here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | В активному thread: прив’язати цей thread. Поза thread: створити/прив’язати дочірній thread, де це підтримується. |
|
||||
| `here` | Вимагати поточний активний thread; завершитися помилкою, якщо ви не в ньому. |
|
||||
| `off` | Без прив’язки. Сесія запускається без прив’язки. |
|
||||
| Режим | Поведінка |
|
||||
| ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | В активному thread: прив’язати цей thread. Поза thread: створити/прив’язати дочірній thread, якщо підтримується. |
|
||||
| `here` | Вимагати поточний активний thread; завершитися помилкою, якщо ви не в ньому. |
|
||||
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- На поверхнях без прив’язки thread типова поведінка фактично дорівнює `off`.
|
||||
- Spawn, прив’язаний до thread, вимагає підтримки політики каналу:
|
||||
- На поверхнях без прив’язки до thread типовою поведінкою фактично є `off`.
|
||||
- Запуск із прив’язкою до thread вимагає підтримки політики каналу:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірнього thread.
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього thread.
|
||||
|
||||
## Елементи керування ACP
|
||||
## Керування ACP
|
||||
|
||||
| Команда | Що вона робить | Приклад |
|
||||
| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створити сесію ACP; необов’язкова поточна прив’язка або прив’язка thread. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасувати хід, що виконується, для цільової сесії. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надіслати інструкцію steer до сесії, що виконується. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Закрити сесію та відв’язати цілі thread. | `/acp close` |
|
||||
| `/acp status` | Показати backend, mode, state, параметри runtime, можливості. | `/acp status` |
|
||||
| `/acp set-mode` | Установити mode runtime для цільової сесії. | `/acp set-mode plan` |
|
||||
| `/acp set` | Загальний запис параметра config runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Установити перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Установити профіль політики погодження. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Установити тайм-аут runtime (секунди). | `/acp timeout 120` |
|
||||
| `/acp model` | Установити перевизначення model runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Видалити перевизначення параметрів runtime для сесії. | `/acp reset-options` |
|
||||
| `/acp sessions` | Показати недавні сесії ACP зі сховища. | `/acp sessions` |
|
||||
| `/acp doctor` | Стан здоров’я backend, можливості, практичні виправлення. | `/acp doctor` |
|
||||
| `/acp install` | Вивести детерміновані кроки встановлення та ввімкнення. | `/acp install` |
|
||||
| Команда | Що вона робить | Приклад |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до thread. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасовує turn у процесі виконання для цільового сеансу. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надсилає інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Закриває сеанс і знімає прив’язку з цільових thread. | `/acp close` |
|
||||
| `/acp status` | Показує backend, режим, стан, параметри runtime, можливості. | `/acp status` |
|
||||
| `/acp set-mode` | Встановлює режим runtime для цільового сеансу. | `/acp set-mode plan` |
|
||||
| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Встановлює перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Встановлює профіль політики погодження. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Встановлює timeout runtime (у секундах). | `/acp timeout 120` |
|
||||
| `/acp model` | Встановлює перевизначення model runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Видаляє перевизначення параметрів runtime для сеансу. | `/acp reset-options` |
|
||||
| `/acp sessions` | Перелічує нещодавні сеанси ACP зі сховища. | `/acp sessions` |
|
||||
| `/acp doctor` | Стан backend, можливості, дієві способи виправлення. | `/acp doctor` |
|
||||
| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` |
|
||||
|
||||
`/acp status` показує ефективні параметри runtime, а також ідентифікатори сесій рівня runtime і рівня backend. Помилки unsupported-control чітко показуються, коли backend не має певної можливості. `/acp sessions` читає сховище для поточної прив’язаної сесії або сесії-запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через виявлення сесій gateway, включно з користувацькими коренями `session.store` для окремих agent.
|
||||
`/acp status` показує ефективні параметри runtime, а також ідентифікатори сеансу на рівні runtime і backend. Помилки непідтримуваних елементів керування відображаються чітко, якщо backend не має відповідної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів.
|
||||
|
||||
## Відображення параметрів runtime
|
||||
|
||||
@ -519,43 +526,43 @@ OpenClaw пропускає подальшу взаємодію A2A лише т
|
||||
|
||||
Еквівалентні операції:
|
||||
|
||||
- `/acp model <id>` відповідає ключу config runtime `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу config runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу config runtime `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення `cwd` runtime.
|
||||
- `/acp model <id>` відображається на ключ конфігурації runtime `model`.
|
||||
- `/acp permissions <profile>` відображається на ключ конфігурації runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` відображається на ключ конфігурації runtime `timeout`.
|
||||
- `/acp cwd <path>` напряму оновлює перевизначення cwd runtime.
|
||||
- `/acp set <key> <value>` — це загальний шлях.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`.
|
||||
- `/acp reset-options` очищає всі перевизначення runtime для цільової сесії.
|
||||
- Спеціальний випадок: `key=cwd` використовує шлях перевизначення cwd.
|
||||
- `/acp reset-options` очищає всі перевизначення runtime для цільового сеансу.
|
||||
|
||||
## acpx harness, налаштування Plugin і дозволи
|
||||
## acpx harness, налаштування Plugin, і permissions
|
||||
|
||||
Щодо конфігурації harness acpx (псевдоніми Claude Code / Codex / Gemini CLI),
|
||||
bridge plugin-tools і OpenClaw-tools MCP, а також режимів дозволів ACP див.
|
||||
Щоб налаштувати acpx harness (аліаси Claude Code / Codex / Gemini CLI),
|
||||
мости MCP plugin-tools і OpenClaw-tools, а також режими permissions ACP, див.
|
||||
[Агенти ACP — налаштування](/uk/tools/acp-agents-setup).
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
| Симптом | Імовірна причина | Виправлення |
|
||||
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ACP runtime backend is not configured` | Backend Plugin відсутній або вимкнений. | Установіть і ввімкніть backend Plugin, а потім виконайте `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch зі звичайних повідомлень thread вимкнено. | Установіть `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Agent відсутній у allowlist. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть до цільового чату/каналу й повторіть спробу або використовуйте spawn без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Adapter не підтримує прив’язку ACP до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом thread. | Перейдіть до цільового thread або використовуйте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використовуйте іншу розмову чи thread. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Adapter не підтримує прив’язку thread. | Використовуйте `--thread off` або перейдіть до підтримуваного adapter/каналу. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP працює на боці хоста; сесія-запитувач перебуває в sandbox. | Використовуйте `runtime="subagent"` із sandboxed сесій або виконуйте ACP spawn із сесії без sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandboxing або ACP із `sandbox="inherit"` із сесії без sandbox. |
|
||||
| Missing ACP metadata for bound session | Застарілі/видалені метадані сесії ACP. | Повторно створіть через `/acp spawn`, а потім знову прив’яжіть/сфокусуйте thread. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує записи/exec у неінтерактивній сесії ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування дозволів](/uk/tools/acp-agents-setup#permission-configuration). |
|
||||
| ACP session fails early with little output | Prompts дозволів заблоковано через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але сесія ACP не повідомила про завершення. | Спостерігайте через `ps aux \| grep acpx`; вручну завершуйте застарілі процеси. |
|
||||
| Симптом | Імовірна причина | Виправлення |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ACP runtime backend is not configured` | Backend Plugin відсутній або вимкнений. | Установіть і ввімкніть Plugin backend, потім виконайте `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Встановіть `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень thread вимкнено. | Встановіть `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Агент відсутній у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Адаптер не підтримує можливість ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом thread. | Перейдіть у цільовий thread або використайте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Інший користувач володіє поточною ціллю прив’язки. | Повторно прив’яжіть як власник або використайте іншу розмову чи thread. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не підтримує можливість прив’язки до thread. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime працює на боці хоста; сеанс запитувача виконується в sandbox. | Використовуйте `runtime="subagent"` із сеансів у sandbox або запускайте ACP із сеансу поза sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або використовуйте ACP із `sandbox="inherit"` із сеансу поза sandbox. |
|
||||
| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, потім повторно прив’яжіть/focus thread. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/виконання в неінтерактивному сеансі ACP. | Встановіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування permissions](/uk/tools/acp-agents-setup#permission-configuration). |
|
||||
| ACP session fails early with little output | Запити permissions блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних permissions встановіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані сторінки
|
||||
|
||||
- [Підагенти](/uk/tools/subagents)
|
||||
- [Інструменти sandbox для кількох агентів](/uk/tools/multi-agent-sandbox-tools)
|
||||
- [Надсилання агенту](/uk/tools/agent-send)
|
||||
- [Sub-agents](/uk/tools/subagents)
|
||||
- [Multi-agent sandbox tools](/uk/tools/multi-agent-sandbox-tools)
|
||||
- [Agent send](/uk/tools/agent-send)
|
||||
|
||||
@ -2,24 +2,20 @@
|
||||
read_when:
|
||||
- Встановлення або налаштування плагінів
|
||||
- Розуміння правил виявлення та завантаження плагінів
|
||||
- Робота з сумісними з Codex/Claude наборами плагінів
|
||||
- Робота з наборами плагінів, сумісними з Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw
|
||||
title: Плагіни
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T14:42:43Z"
|
||||
generated_at: "2026-04-24T15:52:25Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 947bb7ffc13280fd63f79bb68cb18a37c6614144b91a83afd38e5ac3c5187aed
|
||||
source_hash: f86476ea9d091271ca1dc925773ee1c32d0a545be5b2f700ebd944b3157881dc
|
||||
source_path: tools/plugin.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
|
||||
каркаси агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному
|
||||
часі, розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук
|
||||
та інше. Деякі плагіни є **core** (постачаються з OpenClaw), інші —
|
||||
**external** (опубліковані в npm спільнотою).
|
||||
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей, каркаси агентів, інструменти, навички, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання вебсторінок, вебпошук тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші — **external** (публікуються спільнотою в npm).
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -52,7 +48,7 @@ x-i18n:
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Якщо ви надаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте:
|
||||
Якщо ви віддаєте перевагу керуванню через чат, увімкніть `commands.plugins: true` і використовуйте:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:@openclaw/voice-call
|
||||
@ -60,47 +56,47 @@ x-i18n:
|
||||
/plugin enable voice-call
|
||||
```
|
||||
|
||||
Шлях встановлення використовує той самий механізм визначення, що й CLI: локальний
|
||||
шлях/архів, явний `clawhub:<pkg>` або специфікація пакета без префікса (спочатку ClawHub, потім резервний варіант через npm).
|
||||
Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний шлях/архів, явний
|
||||
`clawhub:<pkg>` або проста специфікація пакета (спочатку ClawHub, потім резервний перехід на npm).
|
||||
|
||||
Якщо конфігурація невалідна, встановлення зазвичай завершується безпечним блокуванням і
|
||||
вказує вам на `openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого плагіна
|
||||
для плагінів, які явно підтримують
|
||||
Якщо конфігурація недійсна, встановлення зазвичай завершується безпечною відмовою та вказує на
|
||||
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях
|
||||
перевстановлення вбудованого плагіна для плагінів, які підтримують
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
Пакетні встановлення OpenClaw не виконують завчасне встановлення всього дерева
|
||||
залежностей часу виконання кожного вбудованого плагіна. Коли вбудований плагін OpenClaw активний через
|
||||
конфігурацію плагінів, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням,
|
||||
відновлення під час запуску виправляє лише оголошені залежності часу виконання цього плагіна перед його імпортом.
|
||||
External-плагіни та власні шляхи завантаження, як і раніше, потрібно встановлювати через
|
||||
Упаковані встановлення OpenClaw не виконують завчасне встановлення всього дерева
|
||||
залежностей середовища виконання кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через
|
||||
конфігурацію плагіна, застарілу конфігурацію каналу або типовий увімкнений маніфест,
|
||||
під час запуску відновлюються лише оголошені залежності середовища виконання цього плагіна перед його імпортом.
|
||||
Зовнішні плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через
|
||||
`openclaw plugins install`.
|
||||
|
||||
## Типи плагінів
|
||||
|
||||
OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + модуль часу виконання; виконується в процесі | Офіційні плагіни, пакети npm від спільноти |
|
||||
| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| Формат | Як це працює | Приклади |
|
||||
| ---------- | -------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в тому самому процесі | Офіційні плагіни, пакети npm від спільноти |
|
||||
| **Bundle** | макет, сумісний із Codex/Claude/Cursor; зіставляється з функціями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Обидва відображаються в `openclaw plugins list`. Докладніше про bundles див. у [Набори плагінів](/uk/plugins/bundles).
|
||||
Обидва відображаються в `openclaw plugins list`. Докладніше про набори плагінів див. у [Plugin Bundles](/uk/plugins/bundles).
|
||||
|
||||
Якщо ви пишете native-плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins)
|
||||
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
|
||||
Якщо ви пишете native-плагін, почніть із [Building Plugins](/uk/plugins/building-plugins)
|
||||
та [Plugin SDK Overview](/uk/plugins/sdk-overview).
|
||||
|
||||
## Офіційні плагіни
|
||||
|
||||
### Доступні для встановлення (npm)
|
||||
|
||||
| Плагін | Пакет | Документація |
|
||||
| --------------- | --------------------- | ----------------------------------- |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
|
||||
| --------------- | ---------------------- | ------------------------------------ |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
|
||||
|
||||
### Core (постачаються з OpenClaw)
|
||||
|
||||
@ -114,8 +110,8 @@ OpenClaw розпізнає два формати плагінів:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук у пам’яті (за замовчуванням через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять із встановленням за потреби та автоматичним згадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
- `memory-core` — вбудований пошук пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять із встановленням за потреби, автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
@ -123,12 +119,12 @@ OpenClaw розпізнає два формати плагінів:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `browser` — вбудований браузерний Plugin для browser tool, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
|
||||
- `browser` — вбудований браузерний плагін для інструмента браузера, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання браузера та типової служби керування браузером (увімкнений за замовчуванням; вимкніть його перед заміною)
|
||||
- `copilot-proxy` — міст VS Code Copilot Proxy (за замовчуванням вимкнений)
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community).
|
||||
Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community).
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -148,40 +144,40 @@ OpenClaw розпізнає два формати плагінів:
|
||||
|
||||
| Поле | Опис |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Головний перемикач (за замовчуванням: `true`) |
|
||||
| `enabled` | Головний перемикач (типово: `true`) |
|
||||
| `allow` | Список дозволених плагінів (необов’язково) |
|
||||
| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) |
|
||||
| `load.paths` | Додаткові файли/каталоги плагінів |
|
||||
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `slots` | Вибір ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Перемикачі та конфігурація для окремого плагіна |
|
||||
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з
|
||||
відстеженням конфігурації та увімкненим перезапуском у процесі (типовий шлях `openclaw gateway`),
|
||||
такий перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
|
||||
Підтримуваного шляху гарячого перезавантаження для native runtime-коду плагінів або lifecycle hooks немає;
|
||||
перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
|
||||
очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, сервіси або
|
||||
хуки постачальника/runtime почнуть виконуватися.
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з відстеженням
|
||||
конфігурації та ввімкненим перезапуском у процесі (типовий шлях `openclaw gateway`),
|
||||
цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
|
||||
Підтримуваного шляху гарячого перезавантаження для коду середовища виконання native-плагінів або
|
||||
хуків життєвого циклу немає; перезапустіть процес Gateway, який обслуговує активний канал,
|
||||
перш ніж очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, служби або
|
||||
хуки постачальника/середовища виконання почнуть працювати.
|
||||
|
||||
`openclaw plugins list` — це локальний знімок CLI/конфігурації. Плагін зі станом `loaded`
|
||||
там означає, що плагін можна виявити та завантажити з конфігурації/файлів, видимих для цього
|
||||
запуску CLI. Це не доводить, що вже запущений віддалений дочірній процес Gateway
|
||||
було перезапущено в той самий код плагіна. У конфігураціях VPS/контейнерів з процесами-обгортками
|
||||
надсилайте перезапуск фактичному процесу `openclaw gateway run` або використовуйте
|
||||
`openclaw gateway restart` щодо запущеного Gateway.
|
||||
`openclaw plugins list` — це локальний знімок CLI/конфігурації. `loaded` плагін там
|
||||
означає, що плагін можна виявити та завантажити з конфігурації/файлів, які бачить це
|
||||
виконання CLI. Це не доводить, що вже запущений віддалений дочірній Gateway
|
||||
перезапустився з тим самим кодом плагіна. У налаштуваннях VPS/контейнерів з обгортками
|
||||
надсилайте перезапуски фактичному процесу `openclaw gateway run` або використовуйте
|
||||
`openclaw gateway restart` для запущеного Gateway.
|
||||
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній, невалідний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який виявлення не знайшло.
|
||||
- **Невалідний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній, недійсний">
|
||||
- **Disabled**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Missing**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
|
||||
- **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
</Accordion>
|
||||
|
||||
## Виявлення та пріоритет
|
||||
|
||||
OpenClaw сканує плагіни в такому порядку (перше збігле входження має пріоритет):
|
||||
OpenClaw сканує плагіни в такому порядку (перше збігання перемагає):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи конфігурації">
|
||||
<Step title="Шляхи з конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлу або каталогу.
|
||||
</Step>
|
||||
|
||||
@ -204,41 +200,41 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
- `plugins.enabled: false` вимикає всі плагіни
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.entries.\<id\>.enabled: false` вимикає цей плагін
|
||||
- Плагіни з походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані плагіни дотримуються вбудованого набору значень за замовчуванням, якщо це не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний плагін для цього слота
|
||||
- Деякі вбудовані opt-in-плагіни вмикаються автоматично, коли конфігурація вказує
|
||||
поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або
|
||||
runtime каркаса
|
||||
- Плагіни з робочого простору **типово вимкнені** (їх потрібно явно ввімкнути)
|
||||
- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо його не перевизначено
|
||||
- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін
|
||||
- Деякі вбудовані плагіни з добровільним підключенням автоматично вмикаються, коли конфігурація називає
|
||||
поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або середовище виконання
|
||||
каркаса
|
||||
- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів:
|
||||
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін
|
||||
app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
|
||||
посилання на моделі `codex/*`
|
||||
посилання на модель `codex/*`
|
||||
|
||||
## Усунення проблем із runtime hooks
|
||||
## Усунення проблем із хуками середовища виконання
|
||||
|
||||
Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або hooks
|
||||
не виконуються в реальному трафіку чату, спочатку перевірте таке:
|
||||
Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки
|
||||
не спрацьовують у трафіку активного чату, спершу перевірте таке:
|
||||
|
||||
- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях конфігурації та процес — саме ті, які ви редагуєте.
|
||||
- Перезапустіть активний Gateway після змін встановлення/конфігурації/коду плагіна. У контейнерах
|
||||
з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
|
||||
URL Gateway, профіль, шлях до конфігурації та процес — саме ті, які ви редагуєте.
|
||||
- Перезапустіть активний Gateway після змін установлення/конфігурації/коду плагіна. У контейнерах
|
||||
з обгорткою PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
|
||||
процесу `openclaw gateway run`.
|
||||
- Використовуйте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації hooks і
|
||||
діагностику. Для не вбудованих хуків розмови, таких як `llm_input`,
|
||||
`llm_output` і `agent_end`, потрібне
|
||||
- Використайте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрацію хуків і
|
||||
діагностику. Для невбудованих хуків розмови, таких як `llm_input`,
|
||||
`llm_output` і `agent_end`, потрібен
|
||||
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до
|
||||
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується до
|
||||
визначення моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
|
||||
сформує відповідь помічника.
|
||||
- Щоб підтвердити ефективну модель сесії, використовуйте `openclaw sessions` або
|
||||
поверхні сесії/стану Gateway, а під час налагодження payload-даних постачальника запускайте
|
||||
створить відповідь помічника.
|
||||
- Щоб підтвердити ефективну модель сеансу, використовуйте `openclaw sessions` або
|
||||
поверхні сеансу/статусу Gateway і, під час налагодження корисних навантажень постачальника, запускайте
|
||||
Gateway з `--raw-stream --raw-stream-path <path>`.
|
||||
|
||||
## Слоти плагінів (ексклюзивні категорії)
|
||||
|
||||
Деякі категорії є ексклюзивними (одночасно активним може бути лише один плагін):
|
||||
Деякі категорії є ексклюзивними (одночасно може бути активною лише одна):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -251,32 +247,32 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
}
|
||||
```
|
||||
|
||||
| Слот | Що він контролює | Значення за замовчуванням |
|
||||
| --------------- | --------------------- | ------------------------- |
|
||||
| `memory` | Active Memory плагін | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
| Слот | Що він контролює | Типове значення |
|
||||
| --------------- | ------------------------ | ------------------- |
|
||||
| `memory` | Плагін Active Memory | `memory-core` |
|
||||
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
|
||||
|
||||
## Довідка CLI
|
||||
|
||||
```bash
|
||||
openclaw plugins list # компактний перелік
|
||||
openclaw plugins list # компактний список
|
||||
openclaw plugins list --enabled # лише завантажені плагіни
|
||||
openclaw plugins list --verbose # докладні рядки для кожного плагіна
|
||||
openclaw plugins list --json # машиночитаний перелік
|
||||
openclaw plugins list --verbose # рядки з докладною інформацією про кожен плагін
|
||||
openclaw plugins list --json # машинозчитуваний список
|
||||
openclaw plugins inspect <id> # докладна інформація
|
||||
openclaw plugins inspect <id> --json # машиночитаний формат
|
||||
openclaw plugins inspect --all # таблиця для всього набору
|
||||
openclaw plugins info <id> # псевдонім inspect
|
||||
openclaw plugins inspect <id> --json # машинозчитуваний формат
|
||||
openclaw plugins inspect --all # таблиця по всьому набору
|
||||
openclaw plugins info <id> # псевдонім для inspect
|
||||
openclaw plugins doctor # діагностика
|
||||
|
||||
openclaw plugins install <package> # встановлення (спочатку ClawHub, потім npm)
|
||||
openclaw plugins install clawhub:<pkg> # встановлення лише з ClawHub
|
||||
openclaw plugins install <spec> --force # перезаписати наявне встановлення
|
||||
openclaw plugins install <path> # встановлення з локального шляху
|
||||
openclaw plugins install -l <path> # підключення (без копіювання) для розробки
|
||||
openclaw plugins install <path> # встановити з локального шляху
|
||||
openclaw plugins install -l <path> # підключити (без копіювання) для розробки
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # зафіксувати точну визначену специфікацію npm
|
||||
openclaw plugins install <spec> --pin # зафіксувати точну розв’язану npm-специфікацію
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # оновити один плагін
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
@ -291,58 +287,59 @@ openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser
|
||||
Plugin). Інші вбудовані плагіни, як і раніше, потребують `openclaw plugins enable <id>`.
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований браузерний
|
||||
плагін). Інші вбудовані плагіни все одно потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений плагін або набір hook-пакетів на місці. Використовуйте
|
||||
`--force` перезаписує наявний встановлений плагін або пакунок хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
|
||||
плагінів. Він не підтримується разом із `--link`, який повторно використовує вихідний шлях
|
||||
плагінів. Цей параметр не підтримується разом із `--link`, який повторно використовує вихідний шлях
|
||||
замість копіювання в керовану ціль встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, тому встановлені плагіни
|
||||
можна одразу завантажувати після перезапуску.
|
||||
Коли `plugins.allow` вже задано, `openclaw plugins install` додає
|
||||
ідентифікатор встановленого плагіна до цього списку дозволів перед його ввімкненням, тож встановлені плагіни
|
||||
можна одразу завантажити після перезапуску.
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із записом відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
|
||||
назад до запису відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
|
||||
Передавання назви пакета без версії переводить точно зафіксоване встановлення назад на
|
||||
типову лінійку релізів реєстру. Якщо встановлений npm-плагін уже відповідає
|
||||
визначеній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або переписування конфігурації.
|
||||
типову лінійку випусків реєстру. Якщо встановлений npm-плагін уже відповідає визначеній
|
||||
версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
без завантаження, перевстановлення або перезапису конфігурації.
|
||||
|
||||
`--pin` доступний лише для npm. Він не підтримується з `--marketplace`, оскільки
|
||||
встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
|
||||
`--pin` стосується лише npm. Він не підтримується з `--marketplace`, тому що
|
||||
встановлення з marketplace зберігають метадані джерела marketplace, а не npm-специфікацію.
|
||||
|
||||
`--dangerously-force-unsafe-install` — це аварійний обхідний параметр для хибних
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє встановленням і оновленням плагінів
|
||||
продовжуватися попри вбудовані критичні знахідки `critical`, але все одно
|
||||
не обходить блокування політики плагіна `before_install` або блокування через помилки сканування.
|
||||
спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення
|
||||
та оновлення плагінів попри вбудовані результати `critical`, але все одно
|
||||
не обходить блокування політики плагіна `before_install` або блокування через помилку сканування.
|
||||
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Установлення залежностей Skills
|
||||
через Gateway натомість використовують відповідний параметр запиту `dangerouslyForceUnsafeInstall`,
|
||||
тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills через ClawHub.
|
||||
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення
|
||||
залежностей Skills через Gateway натомість використовує відповідний параметр перевизначення запиту
|
||||
`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком
|
||||
завантаження/встановлення Skills із ClawHub.
|
||||
|
||||
Сумісні bundles беруть участь у тому самому потоці list/inspect/enable/disable
|
||||
плагінів. Поточна підтримка runtime включає bundle Skills, command-Skills для Claude,
|
||||
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
|
||||
`lspServers`, оголошені в маніфесті, command-Skills для Cursor і сумісні каталоги hook-ів Codex.
|
||||
Сумісні набори плагінів беруть участь у тому самому потоці list/inspect/enable/disable для плагінів. Поточна
|
||||
підтримка середовища виконання включає bundle Skills, command-skills Claude,
|
||||
типові значення Claude `settings.json`, Claude `.lsp.json` і типові значення
|
||||
`lspServers`, оголошені в маніфесті, command-skills Cursor і сумісні каталоги хуків Codex.
|
||||
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості bundle, а також
|
||||
підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі bundles.
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості набору плагінів, а також
|
||||
підтримувані або непідтримувані записи MCP і серверів LSP для плагінів на основі наборів.
|
||||
|
||||
Джерелами marketplace можуть бути відома для Claude назва marketplace з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до
|
||||
Джерелами marketplace можуть бути відома назва marketplace Claude з
|
||||
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях
|
||||
`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub
|
||||
або URL git. Для віддалених marketplace записи плагінів мають залишатися всередині
|
||||
клонованого репозиторію marketplace та використовувати лише відносні шляхи джерел.
|
||||
клонованого репозиторію marketplace й використовувати лише відносні джерела шляхів.
|
||||
|
||||
Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins).
|
||||
|
||||
## Огляд API плагінів
|
||||
|
||||
Native-плагіни експортують об’єкт entry, який надає `register(api)`. Старіші
|
||||
плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але новим плагінам слід
|
||||
Native-плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
|
||||
плагіни можуть і далі використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні
|
||||
використовувати `register`.
|
||||
|
||||
```typescript
|
||||
@ -363,49 +360,54 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw завантажує об’єкт entry і викликає `register(api)` під час
|
||||
активації плагіна. Завантажувач усе ще використовує резервний перехід до `activate(api)` для старіших плагінів,
|
||||
але вбудовані плагіни та нові external-плагіни мають вважати `register`
|
||||
публічним контрактом.
|
||||
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
|
||||
активації плагіна. Завантажувач і далі використовує резервний перехід до `activate(api)` для старіших плагінів,
|
||||
але вбудовані плагіни та нові зовнішні плагіни мають розглядати `register` як
|
||||
публічний контракт.
|
||||
|
||||
Поширені методи реєстрації:
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | ------------------------------ |
|
||||
| `registerProvider` | Постачальник моделей (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Lifecycle hooks |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потокове STT |
|
||||
| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Постачальник web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP endpoint |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фонова служба |
|
||||
| Метод | Що він реєструє |
|
||||
| --------------------------------------- | --------------------------- |
|
||||
| `registerProvider` | Постачальник моделей (LLM) |
|
||||
| `registerChannel` | Канал чату |
|
||||
| `registerTool` | Інструмент агента |
|
||||
| `registerHook` / `on(...)` | Хуки життєвого циклу |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | Потокове STT |
|
||||
| `registerRealtimeVoiceProvider` | Двонапрямний голос у реальному часі |
|
||||
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
|
||||
| `registerImageGenerationProvider` | Генерація зображень |
|
||||
| `registerMusicGenerationProvider` | Генерація музики |
|
||||
| `registerVideoGenerationProvider` | Генерація відео |
|
||||
| `registerWebFetchProvider` | Постачальник отримання / скрапінгу вебданих |
|
||||
| `registerWebSearchProvider` | Вебпошук |
|
||||
| `registerHttpRoute` | HTTP-ендпойнт |
|
||||
| `registerCommand` / `registerCli` | Команди CLI |
|
||||
| `registerContextEngine` | Рушій контексту |
|
||||
| `registerService` | Фонова служба |
|
||||
|
||||
Поведінка guard-умов hook-ів для типізованих lifecycle hooks:
|
||||
Поведінка захисних умов хуків для типізованих хуків життєвого циклу:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: `{ block: false }` не виконує жодної дії і не скасовує попереднє блокування.
|
||||
- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: `{ block: false }` не виконує жодної дії і не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: `{ cancel: false }` не виконує жодної дії і не скасовує попереднє попереднє скасування.
|
||||
- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує попереднє скасування.
|
||||
|
||||
Повну інформацію про поведінку типізованих hook-ів див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
Native Codex app-server повертає події інструментів Codex-native через міст назад у цю
|
||||
поверхню хуків. Плагіни можуть блокувати інструменти Codex-native через `before_tool_call`,
|
||||
спостерігати результати через `after_tool_call` і брати участь у схваленнях
|
||||
`PermissionRequest` Codex. Міст поки що не переписує аргументи інструментів Codex-native.
|
||||
|
||||
Повну інформацію про поведінку типізованих хуків див. у [SDK Overview](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
|
||||
- [Набори плагінів](/uk/plugins/bundles) — сумісність bundles Codex/Claude/Cursor
|
||||
- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагіні
|
||||
- [Внутрішня будова плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Плагіни спільноти](/uk/plugins/community) — сторонні переліки
|
||||
- [Building Plugins](/uk/plugins/building-plugins) — створення власного плагіна
|
||||
- [Plugin Bundles](/uk/plugins/bundles) — сумісність наборів плагінів Codex/Claude/Cursor
|
||||
- [Plugin Manifest](/uk/plugins/manifest) — схема маніфесту
|
||||
- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагін
|
||||
- [Plugin Internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
|
||||
- [Community Plugins](/uk/plugins/community) — сторонні списки
|
||||
|
||||
Loading…
Reference in New Issue
Block a user