Агенти ACP

• Якщо задано plugins.allow, це обмежувальний перелік Plugin, і він обов’язково має містити acpx, інакше встановлений серверний компонент ACP навмисно блокуватиметься (/acp doctor повідомляє про відсутній запис у списку дозволених).
• Адаптер Codex ACP постачається разом із Plugin acpx і за можливості запускається локально.
• Codex ACP працює з ізольованим CODEX_HOME. OpenClaw копіює довірені записи про довіру до проєкту та безпечну конфігурацію маршрутизації моделі/постачальника (model, model_provider, model_reasoning_effort, sandbox_mode і безпечні поля model_providers.<name>) із конфігурації Codex хоста; автентифікація, сповіщення та перехоплювачі залишаються лише в конфігурації хоста.
• Адаптери інших цільових середовищ можуть завантажуватися на вимогу через npx під час першого використання.
• Автентифікаційні дані постачальника для цього середовища вже мають бути наявні на хості.
• Якщо хост не має доступу до npm або мережі, завантаження адаптерів під час першого запуску завершуватиметься помилкою, доки кеші не буде попередньо заповнено або адаптер не буде встановлено іншим способом.

ACP запускає справжній зовнішній процес середовища. OpenClaw відповідає за маршрутизацію, стан фонових завдань, доставлення, прив’язки та політики; середовище відповідає за вхід до постачальника, каталог моделей, поведінку файлової системи та нативні інструменти.

Перш ніж звинувачувати OpenClaw, перевірте:

• /acp doctor повідомляє про увімкнений і справний серверний компонент.
• Ідентифікатор цілі дозволено в acp.allowedAgents, якщо цей список дозволених задано.
• Команда середовища може запуститися на хості Gateway.
• Автентифікація постачальника наявна для цього середовища (claude, codex, gemini, opencode, droid тощо).
• Вибрана модель існує для цього середовища — ідентифікатори моделей не переносяться між середовищами.
• Запитаний cwd існує й доступний; або не вказуйте cwd, щоб серверний компонент використав стандартне значення.
• Режим дозволів відповідає роботі. Неінтерактивні сеанси не можуть натискати нативні запити дозволів, тому запуски програмування з інтенсивним записом або виконанням зазвичай потребують профілю дозволів ACPX, здатного працювати без інтерфейсу.

• Запуск створює або відновлює сеанс середовища виконання ACP, записує метадані ACP у сховище сеансів OpenClaw і може створити фонове завдання, якщо запуск належить батьківському процесу.
• Сеанси ACP, що належать батьківському процесу, вважаються фоновою роботою, навіть коли сеанс середовища виконання постійний; завершення та доставлення між поверхнями відбуваються через сповіщувач батьківського завдання, а не як у звичайному користувацькому сеансі чату.
• Обслуговування завдань закриває завершені або осиротілі одноразові сеанси ACP, що належать батьківському процесу. Постійні сеанси ACP зберігаються, доки лишається активна прив’язка до розмови; застарілі постійні сеанси без активної прив’язки закриваються, щоб їх не можна було непомітно відновити після завершення відповідного завдання або зникнення його запису.
• Прив’язані наступні повідомлення надходять безпосередньо до сеансу ACP, доки прив’язку не закрито, не позбавлено фокуса, не скинуто або доки не завершився строк її дії.
• Команди Gateway залишаються локальними. /acp ..., /status і /unfocus ніколи не надсилаються як звичайний текст запиту до прив’язаного середовища ACP.
• cancel перериває активний хід, якщо серверний компонент підтримує скасування; він не видаляє прив’язку чи метадані сеансу.
• close завершує сеанс ACP з погляду OpenClaw і видаляє прив’язку. Середовище може й надалі зберігати власну віддалену історію, якщо підтримує відновлення.
• Plugin acpx очищає дерева процесів обгорток і адаптерів, що належать OpenClaw, після close, а також прибирає застарілі осиротілі процеси ACPX, що належать OpenClaw, під час запуску Gateway.
• Неактивні виконавці середовища виконання можуть бути очищені після acp.runtime.ttlMinutes; збережені метадані сеансів залишаються доступними для /acp sessions.

Тригери природною мовою, які мають спрямовуватися до нативного Plugin Codex, коли його увімкнено:

• "Прив’яжи цей канал Discord до Codex."
• "Під’єднай цей чат до гілки Codex <id>."
• "Покажи гілки Codex, а потім прив’яжи цю."

Нативне прив’язування розмов Codex є типовим шляхом керування чатом. Динамічні інструменти OpenClaw і надалі виконуються через OpenClaw, тоді як нативні інструменти Codex, як-от shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw додає для кожного ходу нативний ретранслятор хуків, щоб хуки плагінів могли блокувати before_tool_call, спостерігати за after_tool_call і спрямовувати події Codex PermissionRequest через механізм схвалень OpenClaw. Хуки Codex Stop ретранслюються до OpenClaw before_agent_finalize, де плагіни можуть запросити ще один прохід моделі, перш ніж Codex завершить відповідь. Ретранслятор навмисно залишається консервативним: він не змінює аргументи нативних інструментів Codex і не переписує записи потоків Codex. Використовуйте явний ACP лише тоді, коли потрібна модель середовища виконання/сеансу ACP. Межу вбудованої підтримки Codex описано в контракті підтримки середовища Codex версії 1.

• застарілі посилання на моделі Codex — застарілий маршрут моделі Codex OAuth/підписки, який виправляє doctor.
• openai/* — вбудоване нативне середовище виконання сервера застосунку Codex для ходів агента OpenAI.
• /codex ... — нативне керування розмовою Codex.
• /acp ... або runtime: "acp" — явне керування ACP/acpx.

Тригери, які мають спрямовувати запит до середовища виконання ACP:

• "Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат."
• "Використай Gemini CLI для цього завдання в потоці, а подальші запити залиш у тому самому потоці."
• "Запусти Codex через ACP у фоновому потоці."

OpenClaw вибирає runtime: "acp", визначає agentId середовища, прив’язується до поточної розмови або потоку, якщо це підтримується, і спрямовує подальші запити до цього сеансу до його закриття або завершення терміну дії. Codex використовує цей шлях лише тоді, коли ACP/acpx вказано явно або нативний плагін Codex недоступний для запитаної операції.

Для sessions_spawn значення runtime: "acp" оголошується лише тоді, коли ACP увімкнено, ініціатор запиту не перебуває в пісочниці й завантажено бекенд середовища виконання ACP. acp.dispatch.enabled=false призупиняє автоматичну диспетчеризацію потоків ACP, але не приховує й не блокує явні виклики sessions_spawn({ runtime: "acp" }). Вони спрямовуються на ідентифікатори середовищ ACP, як-от codex, claude, droid, gemini або opencode. Не передавайте звичайний ідентифікатор агента з конфігурації OpenClaw, отриманий через agents_list, якщо цей запис явно не налаштовано за допомогою agents.list[].runtime.type="acp"; інакше використовуйте типове середовище виконання субагента. Коли агент OpenClaw налаштований із runtime.type="acp", OpenClaw використовує runtime.acp.agent як базовий ідентифікатор середовища.

• --bind here і --thread ... є взаємовиключними.
• --bind here працює лише в каналах, які оголошують підтримку прив’язування поточної розмови; інакше OpenClaw повертає чітке повідомлення про відсутність підтримки. Прив’язування зберігаються після перезапусків Gateway.
• У Discord параметр spawnSessions керує створенням дочірніх потоків для --thread auto|here, але не для --bind here.
• Якщо ви створюєте сеанс для іншого агента ACP без --cwd, OpenClaw типово успадковує робочий простір цільового агента. Відсутні успадковані шляхи (ENOENT/ENOTDIR) призводять до використання типового значення бекенду; інші помилки доступу (наприклад, EACCES) повертаються як помилки створення сеансу.
• Команди керування Gateway залишаються локальними у прив’язаних розмовах — команди /acp ... обробляються OpenClaw, навіть коли звичайний текст подальших повідомлень спрямовується до прив’язаного сеансу ACP; /status і /unfocus також залишаються локальними, коли для цієї поверхні ввімкнено обробку команд.

Коли для адаптера каналу ввімкнено прив’язування потоків:

• OpenClaw прив’язує потік до цільового сеансу ACP.
• Подальші повідомлення в цьому потоці спрямовуються до прив’язаного сеансу ACP.
• Вивід ACP повертається до того самого потоку.
• Зняття фокусу, закриття, архівування, тайм-аут бездіяльності або завершення максимального терміну дії видаляє прив’язування.
• /acp close, /acp cancel, /acp status, /status і /unfocus — це команди Gateway, а не запити до середовища ACP.

Обов’язкові прапорці функцій для ACP, прив’язаного до потоків:

• acp.enabled=true
• acp.dispatch.enabled типово ввімкнено (установіть false, щоб призупинити автоматичну диспетчеризацію потоків ACP; явні виклики sessions_spawn({ runtime: "acp" }) продовжують працювати).
• Створення потокових сеансів адаптером каналу ввімкнено (типове значення: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

Підтримка прив’язування потоків залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язування потоків, OpenClaw повертає чітке повідомлення про відсутність підтримки або недоступність.

• Будь-який адаптер каналу, який надає можливість прив’язування сеансів/потоків.
• Поточна вбудована підтримка: потоки/канали Discord, теми Telegram (форумні теми в групах/супергрупах і теми в приватних повідомленнях).
• Плагіни каналів можуть додавати підтримку через той самий інтерфейс прив’язування.

Інтерактивні сеанси призначені для продовження спілкування у видимому чаті:

• /acp spawn ... --bind here прив’язує поточну розмову до сеансу ACP.
• /acp spawn ... --thread ... прив’язує гілку або тему каналу до сеансу ACP.
• Постійні налаштовані bindings[].type="acp" спрямовують відповідні розмови до того самого сеансу ACP.

Подальші повідомлення в прив’язаній розмові спрямовуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад до того самого каналу, гілки або теми.

Що OpenClaw надсилає до середовища:

• Звичайні прив’язані подальші повідомлення надсилаються як текст запиту, а вкладення додаються лише тоді, коли середовище або бекенд їх підтримує.
• Команди керування /acp і локальні команди Gateway перехоплюються до передавання в ACP.
• Створені середовищем виконання події завершення формуються окремо для кожної цілі. Агенти OpenClaw отримують внутрішню оболонку контексту середовища виконання OpenClaw; зовнішні середовища ACP отримують звичайний запит із результатом дочірнього процесу та інструкцією. Необроблена оболонка <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> ніколи не повинна надсилатися до зовнішніх середовищ або зберігатися як текст користувача в стенограмі ACP.
• Записи стенограми ACP використовують видимий користувачеві текст запуску або звичайний запит про завершення. Внутрішні метадані подій за можливості залишаються структурованими в OpenClaw і не трактуються як вміст чату, створений користувачем.

Одноразові сеанси ACP, породжені іншим запуском агента, є фоновими дочірніми процесами, подібними до субагентів:

• Батьківський сеанс запитує виконання роботи через sessions_spawn({ runtime: "acp", mode: "run" }).
• Дочірній процес виконується у власному сеансі середовища ACP.
• Дочірні ходи виконуються в тій самій фоновій черзі, що й породження нативних субагентів, тому повільне середовище ACP не блокує не пов’язану з ним роботу основного сеансу.
• Завершення повідомляється через шлях оголошення про виконання завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний запит ACP перед надсиланням до зовнішнього середовища, тому середовища не бачать маркерів контексту середовища виконання, призначених лише для OpenClaw.
• Батьківський сеанс переписує результат дочірнього процесу звичайним голосом асистента, коли корисна видима користувачеві відповідь.

Не розглядайте цей шлях як одноранговий чат між батьківським і дочірнім процесами. Дочірній процес уже має канал для повідомлення про завершення батьківському сеансу.

Після породження sessions_send може спрямовувати повідомлення до іншого сеансу. Для звичайних однорангових сеансів OpenClaw використовує шлях подальшої взаємодії між агентами (A2A) після вставлення повідомлення:

• Дочекатися відповіді цільового сеансу.
• За потреби дозволити запитувачу й цільовому сеансу обмінятися обмеженою кількістю подальших ходів.
• Попросити цільовий сеанс створити повідомлення-оголошення.
• Доставити це оголошення до видимого каналу або гілки.

Цей шлях A2A є резервним для надсилання між рівноправними вузлами, коли відправнику потрібне видиме подальше повідомлення. Він залишається ввімкненим, коли непов’язаний сеанс може бачити ціль ACP і надсилати їй повідомлення, наприклад за широких налаштувань tools.sessions.visibility.

OpenClaw пропускає подальше повідомлення A2A лише тоді, коли запитувач є батьківським сеансом для власного одноразового дочірнього сеансу ACP, що належить цьому батьківському сеансу. У такому разі запуск A2A поверх завершення завдання може активувати батьківський сеанс із результатом дочірнього сеансу, переслати відповідь батьківського сеансу назад до дочірнього та створити цикл відлуння між батьківським і дочірнім сеансами. Результат sessions_send повідомляє delivery.status="skipped" для такого дочірнього сеансу, що перебуває у власності, оскільки шлях завершення вже відповідає за результат.

Використовуйте resumeSessionId, щоб продовжити попередній сеанс ACP замість запуску нового. Агент відтворює історію розмови через session/load, тому продовжує роботу з повним контекстом попередньої взаємодії.

{  "task": "Continue where we left off - fix the remaining test failures",  "runtime": "acp",  "agentId": "codex",  "resumeSessionId": "<previous-session-id>"}

Поширені сценарії використання:

• Передайте сеанс Codex із ноутбука на телефон — попросіть агента продовжити з місця, на якому ви зупинилися.
• Продовжте сеанс програмування, який ви інтерактивно розпочали в CLI, тепер у безінтерфейсному режимі через агента.
• Відновіть роботу, перервану через перезапуск Gateway або тайм-аут бездіяльності.

Примітки:

• resumeSessionId застосовується лише за runtime: "acp"; стандартне середовище виконання підагента ігнорує це поле, призначене лише для ACP.
• streamTo застосовується лише за runtime: "acp"; стандартне середовище виконання підагента ігнорує це поле, призначене лише для ACP.
• resumeSessionId — це локальний для хоста ідентифікатор відновлення ACP/обв’язки, а не ключ сеансу каналу OpenClaw; OpenClaw однаково перевіряє політику запуску ACP і політику цільового агента перед передаванням, тоді як серверна частина ACP або обв’язка відповідає за авторизацію завантаження цього зовнішнього ідентифікатора.
• resumeSessionId відновлює історію зовнішньої розмови ACP; thread і mode однаково застосовуються у звичайному порядку до нового сеансу OpenClaw, який ви створюєте, тому mode: "session" усе ще потребує thread: true.
• Цільовий агент має підтримувати session/load (Codex і Claude Code підтримують).
• Якщо ідентифікатор сеансу не знайдено, запуск завершується невдало з чіткою помилкою — без неявного переходу до нового сеансу.

Після розгортання Gateway виконайте наскрізну перевірку в реальному середовищі, а не покладайтеся на модульні тести:

1. Перевірте версію та коміт розгорнутого Gateway на цільовому хості.
2. Відкрийте тимчасовий мостовий сеанс ACPX із активним агентом.
3. Попросіть цього агента викликати sessions_spawn із runtime: "acp", agentId: "codex", mode: "run" і завданням Reply with exactly LIVE-ACP-SPAWN-OK.
4. Перевірте accepted=yes, справжній childSessionKey і відсутність помилки валідатора.
5. Видаліть тимчасовий мостовий сеанс.

Залиште перевірку на mode: "run" і пропустіть streamTo: "parent" — прив’язаний до гілки mode: "session" і шляхи ретрансляції потоку є окремими, повнішими інтеграційними перевірками.