ACP — це шлях для зовнішніх середовищ, а не стандартний шлях Codex. Нативний
Plugin сервера застосунків Codex відповідає за елементи керування
/codex ... і стандартне
вбудоване середовище виконання openai/gpt-* для ходів агента; ACP відповідає за елементи керування /acp ...
і сеанси sessions_spawn({ runtime: "acp" }).Щоб Codex або Claude Code підключалися як зовнішні клієнти MCP безпосередньо до
наявних розмов каналів OpenClaw, використовуйте
openclaw mcp serve замість ACP.Яка сторінка мені потрібна?
Чи працює це одразу після встановлення?
Так, після встановлення офіційного Plugin середовища виконання ACP: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, здатного працювати без інтерфейсу.
Підтримувані цільові середовища
Із серверним компонентом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 status4
Налаштувати
/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.
Правила нативної маршрутизації Codex
Правила нативної маршрутизації Codex
Тригери природною мовою, які мають спрямовуватися до нативного Plugin Codex,
коли його увімкнено:
- “Прив’яжи цей канал Discord до Codex.”
- “Під’єднай цей чат до гілки Codex
<id>.” - “Покажи гілки Codex, а потім прив’яжи цю.”
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
Тригери природною мовою для маршрутизації ACP
Тригери, які мають спрямовувати запит до середовища виконання ACP:
- “Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат.”
- “Використай Gemini CLI для цього завдання в потоці, а подальші запити залиш у тому самому потоці.”
- “Запусти Codex через ACP у фоновому потоці.”
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 стек має такий вигляд:- Площина керування сеансами ACP OpenClaw.
- Офіційний плагін середовища виконання
@openclaw/acpx. - Адаптер Claude ACP.
- Механізми середовища виконання та сеансів на боці Claude.
- Потрібні
/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.enabled=trueacp.dispatch.enabledтипово ввімкнено (установітьfalse, щоб призупинити автоматичну диспетчеризацію потоків ACP; явні викликиsessions_spawn({ runtime: "acp" })продовжують працювати).- Створення потокових сеансів адаптером каналу ввімкнено (типове значення:
true):- Discord:
channels.discord.threadBindings.spawnSessions=true - Telegram:
channels.telegram.threadBindings.spawnSessions=true
- Discord:
Канали з підтримкою потоків
Канали з підтримкою потоків
- Будь-який адаптер каналу, який надає можливість прив’язування сеансів/потоків.
- Поточна вбудована підтримка: потоки/канали 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.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
bindings[].acp.*agents.list[].runtime.acp.*- Глобальні типові параметри ACP (наприклад,
acp.backend)
Приклад
Поведінка
- OpenClaw забезпечує наявність налаштованого сеансу ACP після перевірки допуску для конкретного каналу та перед його використанням.
- Повідомлення в цьому каналі, темі або чаті спрямовуються до налаштованого сеансу ACP.
- Налаштовані прив’язки ACP керують маршрутом свого сеансу. Розгалужене широкомовне надсилання каналу не замінює налаштований сеанс ACP для відповідної прив’язки.
- У прив’язаних розмовах
/newі/resetскидають той самий ключ сеансу ACP на місці. - Тимчасові прив’язки середовища виконання (наприклад, створені процесами фокусування на гілці) усе одно застосовуються, якщо вони наявні.
- Під час міжагентного породження ACP без явного
cwdOpenClaw успадковує робочий простір цільового агента з конфігурації агента. - Якщо успадковані шляхи робочого простору відсутні, використовується стандартний поточний робочий каталог бекенду; помилки доступу до наявних шляхів повертаються як помилки породження.
Запуск сеансів ACP
Є два способи запустити сеанс ACP:- Через sessions_spawn
- Через команду /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, залишаються
прихованими, доки їх явно не ввімкнено.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|off
- --thread auto|here|off
Примітки:
--bind here— найпростіший шлях для оператора, щоб зробити цей канал або чат керованим Codex.--bind hereне створює дочірню гілку.--bind hereдоступний лише в каналах, які підтримують прив’язку поточної розмови.--bindі--threadне можна поєднувати в одному виклику/acp spawn.
Модель доставлення
Сеанси ACP можуть бути інтерактивними робочими просторами або фоновою роботою, якою керує батьківський сеанс. Шлях доставлення залежить від цього режиму.Інтерактивні сеанси ACP
Інтерактивні сеанси ACP
Інтерактивні сеанси призначені для продовження спілкування у видимому чаті:
/acp spawn ... --bind hereприв’язує поточну розмову до сеансу ACP./acp spawn ... --thread ...прив’язує гілку або тему каналу до сеансу ACP.- Постійні налаштовані
bindings[].type="acp"спрямовують відповідні розмови до того самого сеансу ACP.
- Звичайні прив’язані подальші повідомлення надсилаються як текст запиту, а вкладення додаються лише тоді, коли середовище або бекенд їх підтримує.
- Команди керування
/acpі локальні команди Gateway перехоплюються до передавання в ACP. - Створені середовищем виконання події завершення формуються окремо для кожної цілі. Агенти OpenClaw отримують внутрішню оболонку контексту середовища виконання OpenClaw; зовнішні середовища ACP отримують звичайний запит із результатом дочірнього процесу та інструкцією. Необроблена оболонка
<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>ніколи не повинна надсилатися до зовнішніх середовищ або зберігатися як текст користувача в стенограмі ACP. - Записи стенограми ACP використовують видимий користувачеві текст запуску або звичайний запит про завершення. Внутрішні метадані подій за можливості залишаються структурованими в OpenClaw і не трактуються як вміст чату, створений користувачем.
Одноразові сеанси ACP під керуванням батьківського сеансу
Одноразові сеанси ACP під керуванням батьківського сеансу
Одноразові сеанси ACP, породжені іншим запуском агента, є фоновими
дочірніми процесами, подібними до субагентів:
- Батьківський сеанс запитує виконання роботи через
sessions_spawn({ runtime: "acp", mode: "run" }). - Дочірній процес виконується у власному сеансі середовища ACP.
- Дочірні ходи виконуються в тій самій фоновій черзі, що й породження нативних субагентів, тому повільне середовище ACP не блокує не пов’язану з ним роботу основного сеансу.
- Завершення повідомляється через шлях оголошення про виконання завдання. OpenClaw перетворює внутрішні метадані завершення на звичайний запит ACP перед надсиланням до зовнішнього середовища, тому середовища не бачать маркерів контексту середовища виконання, призначених лише для OpenClaw.
- Батьківський сеанс переписує результат дочірнього процесу звичайним голосом асистента, коли корисна видима користувачеві відповідь.
sessions_send і доставлення A2A
sessions_send і доставлення A2A
Після породження
sessions_send може спрямовувати повідомлення до іншого
сеансу. Для звичайних однорангових сеансів OpenClaw використовує шлях
подальшої взаємодії між агентами (A2A) після вставлення повідомлення:- Дочекатися відповіді цільового сеансу.
- За потреби дозволити запитувачу й цільовому сеансу обмінятися обмеженою кількістю подальших ходів.
- Попросити цільовий сеанс створити повідомлення-оголошення.
- Доставити це оголошення до видимого каналу або гілки.
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 виконайте наскрізну перевірку в реальному середовищі, а не покладайтеся
на модульні тести:
- Перевірте версію та коміт розгорнутого Gateway на цільовому хості.
- Відкрийте тимчасовий мостовий сеанс ACPX із активним агентом.
- Попросіть цього агента викликати
sessions_spawnізruntime: "acp",agentId: "codex",mode: "run"і завданнямReply with exactly LIVE-ACP-SPAWN-OK. - Перевірте
accepted=yes, справжнійchildSessionKeyі відсутність помилки валідатора. - Видаліть тимчасовий мостовий сеанс.
mode: "run" і пропустіть streamTo: "parent" —
прив’язаний до гілки mode: "session" і шляхи ретрансляції потоку є окремими, повнішими
інтеграційними перевірками.Сумісність із пісочницею
Сеанси ACP наразі працюють у середовищі виконання хоста, а не всередині пісочниці OpenClaw. Поточні обмеження:- Якщо сеанс запитувача працює в пісочниці, запуск ACP блокується як для
sessions_spawn({ runtime: "acp" }), так і для/acp spawn. sessions_spawnізruntime: "acp"не підтримуєsandbox: "require".
Визначення цільового сеансу
Більшість дій/acp приймають необов’язкову ціль сеансу (session-key,
session-id або session-label).
Порядок визначення:
- Явний аргумент цілі (або
--sessionдля/acp steer)- спочатку перевіряє ключ
- потім ідентифікатор сеансу у форматі UUID
- потім мітку
- Поточна прив’язка гілки (якщо ця розмова/гілка прив’язана до сеансу ACP).
- Резервний варіант — поточний сеанс запитувача.
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.