Skip to main content
Сеанси Agent Client Protocol (ACP) дають змогу OpenClaw запускати зовнішні середовища для програмування (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані середовища ACPX) через серверний Plugin ACP. Кожен запуск відстежується як фонове завдання.
ACP — це шлях для зовнішніх середовищ, а не стандартний шлях Codex. Нативний Plugin сервера застосунків Codex відповідає за елементи керування /codex ... і стандартне вбудоване середовище виконання openai/gpt-* для ходів агента; ACP відповідає за елементи керування /acp ... і сеанси sessions_spawn({ runtime: "acp" }).Щоб Codex або Claude Code підключалися як зовнішні клієнти MCP безпосередньо до наявних розмов каналів OpenClaw, використовуйте openclaw mcp serve замість ACP.

Яка сторінка мені потрібна?

Чи працює це одразу після встановлення?

Так, після встановлення офіційного Plugin середовища виконання ACP:
Вихідні збірки можуть використовувати локальний Plugin робочого простору extensions/acpx після pnpm install. Запустіть /acp doctor, щоб перевірити готовність. OpenClaw надає агентам відомості про створення ACP лише тоді, коли ACP дійсно придатний до використання: ACP має бути увімкнений, диспетчеризація не повинна бути вимкнена, поточний сеанс не повинен блокуватися пісочницею, а серверний компонент середовища виконання має бути завантажений і справний. Якщо будь-яку умову не виконано, Skills ACP та вказівки ACP для sessions_spawn залишаються прихованими, щоб агент не пропонував недоступний серверний компонент.
  • Якщо задано 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, здатного працювати без інтерфейсу.
Інструменти Plugin OpenClaw і вбудовані інструменти OpenClaw за замовчуванням не надаються середовищам ACP. Увімкніть явні мости MCP у розділі Агенти ACP — налаштування, лише якщо середовище має викликати ці інструменти безпосередньо.

Підтримувані цільові середовища

Із серверним компонентом acpx використовуйте ці ідентифікатори як цілі для /acp spawn <id> або sessions_spawn({ runtime: "acp", agentId: "<id>" }): pi (pi-acp) також зареєстровано в серверному компоненті acpx, але це не середовище програмування в тому самому розумінні, що й наведені вище. Власні псевдоніми агентів acpx можна налаштувати в самому acpx, але політика OpenClaw усе одно перевіряє acp.allowedAgents і будь-яке зіставлення agents.list[].runtime.acp.agent перед диспетчеризацією.

Інструкція для оператора

Швидкий процес /acp із чату:
1

Запустити

/acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto або явно /acp spawn codex --bind here.
2

Працювати

Продовжуйте у прив’язаній розмові чи гілці (або явно вкажіть ключ сеансу).
3

Перевірити стан

/acp status
4

Налаштувати

/acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>.
5

Спрямувати

Без заміни контексту: /acp steer tighten logging and continue.
6

Зупинити

/acp cancel (поточний хід) або /acp close (сеанс і прив’язки).
  • Запуск створює або відновлює сеанс середовища виконання 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 як базовий ідентифікатор середовища.

ACP і субагенти

Використовуйте ACP, коли потрібне зовнішнє середовище виконання. Використовуйте нативний сервер застосунку Codex для прив’язування розмов Codex і керування ними, коли плагін codex увімкнено. Використовуйте субагентів, коли потрібні делеговані запуски, нативні для OpenClaw. Див. також Субагенти.

Як ACP запускає Claude Code

Для Claude Code через ACP стек має такий вигляд:
  1. Площина керування сеансами ACP OpenClaw.
  2. Офіційний плагін середовища виконання @openclaw/acpx.
  3. Адаптер Claude ACP.
  4. Механізми середовища виконання та сеансів на боці Claude.
ACP Claude — це сеанс середовища з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковим прив’язуванням розмови/потоку. Бекенди CLI — це окремі локальні резервні середовища виконання лише для тексту — див. Бекенди CLI. Для операторів практичне правило таке:
  • Потрібні /acp spawn, сеанси з можливістю прив’язування, засоби керування середовищем виконання або тривала робота середовища? Використовуйте ACP.
  • Потрібен простий локальний текстовий резервний шлях через необроблений CLI? Використовуйте бекенди CLI.

Прив’язані сеанси

Ментальна модель

  • Поверхня чату — місце, де люди продовжують спілкування (канал Discord, тема Telegram, чат iMessage).
  • Сеанс ACP — довготривалий стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити.
  • Дочірній потік/тема — необов’язкова додаткова поверхня обміну повідомленнями, яку створює лише --thread ....
  • Робочий простір середовища виконання — розташування у файловій системі (cwd, робоча копія репозиторію, робочий простір бекенду), де працює середовище. Не залежить від поверхні чату.

Прив’язування поточної розмови

/acp spawn <harness> --bind here закріплює поточну розмову за створеним сеансом ACP — без дочірнього потоку, на тій самій поверхні чату. OpenClaw продовжує керувати транспортом, автентифікацією, безпекою та доставкою. Подальші повідомлення в цій розмові спрямовуються до того самого сеансу; /new і /reset скидають сеанс на місці; /acp close видаляє прив’язування. Приклади:
  • --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 у записах верхнього рівня bindings[].

Модель прив’язування

"acp"
Позначає постійне прив’язування розмови ACP.
object
Визначає цільову розмову. Форми для окремих каналів:
  • Канал/потік Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Канал/приватне повідомлення Slack: match.channel="slack" + match.peer.id="<channelId|channel:<channelId>|#<channelId>|userId|user:<userId>|slack:<userId>|<@userId>>". Надавайте перевагу стабільним ідентифікаторам Slack; прив’язування каналів також охоплюють відповіді в потоках цього каналу.
  • Форумна тема Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • Приватне повідомлення/група WhatsApp: match.channel="whatsapp" + match.peer.id="<E.164|group JID>". Використовуйте номери E.164, як-от +15555550123, для прямих чатів та JID груп WhatsApp, як-от 120363424282127706@g.us, для груп.
  • Приватне повідомлення/група iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>". Надавайте перевагу chat_id:* для стабільних прив’язувань груп.
string
Ідентифікатор агента-власника OpenClaw.
"persistent" | "oneshot"
Необов’язкове перевизначення ACP.
string
Необов’язкова мітка для оператора.
string
Необов’язковий робочий каталог середовища виконання.
string
Необов’язкове перевизначення бекенду.

Типові параметри середовища виконання для кожного агента

Використовуйте agents.list[].runtime, щоб один раз визначити типові параметри ACP для кожного агента:
  • agents.list[].runtime.type="acp"
  • agents.list[].runtime.acp.agent (ідентифікатор середовища, наприклад codex або claude)
  • agents.list[].runtime.acp.backend
  • agents.list[].runtime.acp.mode
  • agents.list[].runtime.acp.cwd
Пріоритет перевизначень для прив’язаних сеансів ACP:
  1. bindings[].acp.*
  2. agents.list[].runtime.acp.*
  3. Глобальні типові параметри ACP (наприклад, acp.backend)

Приклад

Поведінка

  • OpenClaw забезпечує наявність налаштованого сеансу ACP після перевірки допуску для конкретного каналу та перед його використанням.
  • Повідомлення в цьому каналі, темі або чаті спрямовуються до налаштованого сеансу ACP.
  • Налаштовані прив’язки ACP керують маршрутом свого сеансу. Розгалужене широкомовне надсилання каналу не замінює налаштований сеанс ACP для відповідної прив’язки.
  • У прив’язаних розмовах /new і /reset скидають той самий ключ сеансу ACP на місці.
  • Тимчасові прив’язки середовища виконання (наприклад, створені процесами фокусування на гілці) усе одно застосовуються, якщо вони наявні.
  • Під час міжагентного породження ACP без явного cwd OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
  • Якщо успадковані шляхи робочого простору відсутні, використовується стандартний поточний робочий каталог бекенду; помилки доступу до наявних шляхів повертаються як помилки породження.

Запуск сеансів ACP

Є два способи запустити сеанс ACP:
Використовуйте runtime: "acp", щоб запустити сеанс ACP із ходу агента або виклику інструмента.
Стандартним значенням runtime є subagent, тому для сеансів ACP явно задавайте runtime: "acp". Якщо agentId не вказано, OpenClaw використовує acp.defaultAgent, якщо його налаштовано. Для mode: "session" потрібне thread: true, щоб зберігати постійну прив’язану розмову.

Параметри sessions_spawn

string
обов'язково
Початковий запит, надісланий до сеансу ACP.
"acp"
обов'язково
Для сеансів ACP значення має бути "acp".
string
Ідентифікатор цільового середовища ACP. Якщо задано acp.defaultAgent, використовується він.
boolean
за замовчуванням:"false"
Запит процесу прив’язки до гілки, якщо це підтримується.
"run" | "session"
за замовчуванням:"run"
"run" — одноразовий режим; "session" — постійний. Якщо задано thread: true, а mode не вказано, OpenClaw може стандартно використовувати постійну поведінку залежно від шляху середовища виконання. Для mode: "session" потрібне thread: true.
string
Запитаний робочий каталог середовища виконання (перевіряється політикою бекенду або середовища виконання). Якщо його не вказано, породжений сеанс ACP успадковує налаштований робочий простір цільового агента; якщо успадковані шляхи відсутні, використовуються стандартні значення бекенду, а справжні помилки доступу повертаються.
string
Видима оператору мітка, що використовується в тексті сеансу або банера.
string
Відновлює наявний сеанс ACP замість створення нового. Агент повторно відтворює історію розмови через session/load. Потрібне runtime: "acp".
"parent"
"parent" передає початкові зведення про перебіг виконання ACP назад до сеансу-запитувача як системні події. Прийняті відповіді містять streamLogPath, що вказує на журнал JSONL у межах сеансу (<sessionId>.acp-stream.jsonl), який можна відстежувати для отримання повної історії ретрансляції. Потоки перебігу для батьківського сеансу стандартно показують коментарі асистента та перебіг стану ACP, якщо не задано streaming.progress.commentary=false. Discord також стандартно використовує режим перебігу для попереднього перегляду в батьківському сеансі, якщо режим потоку не налаштовано. Перебіг стану й надалі враховує acp.stream.tagVisibility, тому такі теги, як plan, залишаються прихованими, доки їх явно не ввімкнено.
Запуски ACP через sessions_spawn використовують agents.defaults.subagents.runTimeoutSeconds як стандартне обмеження тривалості дочірнього ходу. Інструмент не приймає перевизначення часу очікування для окремих викликів (runTimeoutSeconds/timeoutSeconds відхиляються з помилкою, що вимагає налаштувати стандартне значення).
string
Явне перевизначення моделі для дочірнього сеансу ACP. Породження Codex ACP нормалізує посилання OpenAI на кшталт openai/gpt-5.4 у початкову конфігурацію Codex ACP перед session/new; форми зі скісними рисками на кшталт openai/gpt-5.4/high також задають рівень міркування Codex ACP. Якщо параметр не вказано, sessions_spawn({ runtime: "acp" }) використовує наявні стандартні моделі субагентів (agents.defaults.subagents.model або agents.list[].subagents.model), якщо їх налаштовано; інакше середовище ACP використовує власну стандартну модель. Інші середовища мають оголошувати підтримку ACP models і підтримувати session/set_model; інакше OpenClaw/acpx повертає чітку помилку замість непомітного переходу до стандартної моделі цільового агента.
string
Явний рівень обмірковування або міркування. Для Codex ACP значення minimal відповідає низькому рівню, low/medium/high/xhigh передаються безпосередньо, а off не додає початкове перевизначення рівня міркування. Якщо параметр не вказано, породжені сеанси ACP використовують наявні стандартні налаштування обмірковування субагентів і параметр agents.defaults.models["provider/model"].params.thinking для вибраної моделі.

Режими прив’язки та гілки під час породження

Примітки:
  • --bind here — найпростіший шлях для оператора, щоб зробити цей канал або чат керованим Codex.
  • --bind here не створює дочірню гілку.
  • --bind here доступний лише в каналах, які підтримують прив’язку поточної розмови.
  • --bind і --thread не можна поєднувати в одному виклику /acp spawn.

Модель доставлення

Сеанси ACP можуть бути інтерактивними робочими просторами або фоновою роботою, якою керує батьківський сеанс. Шлях доставлення залежить від цього режиму.
Інтерактивні сеанси призначені для продовження спілкування у видимому чаті:
  • /acp spawn ... --bind here прив’язує поточну розмову до сеансу ACP.
  • /acp spawn ... --thread ... прив’язує гілку або тему каналу до сеансу ACP.
  • Постійні налаштовані bindings[].type="acp" спрямовують відповідні розмови до того самого сеансу ACP.
Подальші повідомлення в прив’язаній розмові спрямовуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад до того самого каналу, гілки або теми.Що OpenClaw надсилає до середовища:
  • Звичайні прив’язані подальші повідомлення надсилаються як текст запиту, а вкладення додаються лише тоді, коли середовище або бекенд їх підтримує.
  • Команди керування /acp і локальні команди Gateway перехоплюються до передавання в ACP.
  • Створені середовищем виконання події завершення формуються окремо для кожної цілі. Агенти OpenClaw отримують внутрішню оболонку контексту середовища виконання OpenClaw; зовнішні середовища ACP отримують звичайний запит із результатом дочірнього процесу та інструкцією. Необроблена оболонка <<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>> ніколи не повинна надсилатися до зовнішніх середовищ або зберігатися як текст користувача в стенограмі 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, тому продовжує роботу з повним контекстом попередньої взаємодії.
Поширені сценарії використання:
  • Передайте сеанс 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" і шляхи ретрансляції потоку є окремими, повнішими інтеграційними перевірками.

Сумісність із пісочницею

Сеанси ACP наразі працюють у середовищі виконання хоста, а не всередині пісочниці OpenClaw.
Межа безпеки:
  • Зовнішня обв’язка може читати й записувати відповідно до власних дозволів CLI та вибраного cwd.
  • Політика пісочниці OpenClaw не охоплює виконання обв’язки ACP.
  • OpenClaw однаково забезпечує дотримання функціональних обмежень ACP, списку дозволених агентів, власності сеансів, прив’язок каналів і політики доставлення Gateway.
  • Використовуйте runtime: "subagent" для нативної роботи OpenClaw із примусовим застосуванням пісочниці.
Поточні обмеження:
  • Якщо сеанс запитувача працює в пісочниці, запуск ACP блокується як для sessions_spawn({ runtime: "acp" }), так і для /acp spawn.
  • sessions_spawn із runtime: "acp" не підтримує sandbox: "require".

Визначення цільового сеансу

Більшість дій /acp приймають необов’язкову ціль сеансу (session-key, session-id або session-label). Порядок визначення:
  1. Явний аргумент цілі (або --session для /acp steer)
    • спочатку перевіряє ключ
    • потім ідентифікатор сеансу у форматі UUID
    • потім мітку
  2. Поточна прив’язка гілки (якщо ця розмова/гілка прив’язана до сеансу ACP).
  3. Резервний варіант — поточний сеанс запитувача.
Прив’язки поточної розмови та прив’язки гілки беруть участь у кроці 2. Якщо визначити ціль не вдається, OpenClaw повертає чітку помилку (Unable to resolve session target: ...).

Елементи керування ACP

Елементи керування середовищем виконання (spawn, cancel, steer, close, status, set-mode, set, cwd, permissions, timeout, model і reset-options) потребують ідентичності власника із зовнішніх каналів та operator.admin від внутрішніх клієнтів Gateway. Авторизовані відправники, які не є власниками, однаково можуть використовувати sessions, doctor, install і help. /acp status показує ефективні параметри середовища виконання, а також ідентифікатори сеансу на рівні середовища виконання та серверної частини. Помилки непідтримуваних елементів керування відображаються чітко, коли серверна частина не має відповідної можливості. /acp sessions читає сховище для поточного прив’язаного сеансу або сеансу запитувача; токени цілі (session-key, session-id або session-label) визначаються через виявлення сеансів Gateway, зокрема користувацькі корені session.store для кожного агента.

Зіставлення параметрів середовища виконання

/acp має зручні команди та загальний засіб установлення. Еквівалентні операції:

Обв’язка acpx, налаштування Plugin і дозволи

Щодо конфігурації обв’язки acpx (псевдонімів Claude Code / Codex / Gemini CLI), мостів MCP для інструментів Plugin та OpenClaw і режимів дозволів ACP див. Агенти ACP — налаштування.

Усунення несправностей

Command blocked by PreToolUse hook: Native hook relay unavailable стосується вбудованого ретранслятора хуків Codex, а не ACP/acpx. У прив’язаному чаті Codex запустіть новий сеанс за допомогою /new або /reset; якщо це спрацює один раз, а помилка знову з’явиться під час наступного виклику вбудованого інструмента, перезапустіть сервер застосунку Codex або Gateway OpenClaw замість повторного виконання /new. Див. Усунення несправностей засобу виконання Codex.

Пов’язані матеріали