агенты ACP

• Если задан plugins.allow, это ограничительный список Plugin, и он должен включать acpx; иначе установленный ACP backend намеренно блокируется, а /acp doctor сообщает об отсутствующей записи allowlist.
• Адаптер Codex ACP поставляется вместе с Plugin acpx и по возможности запускается локально.
• Codex ACP работает с изолированным CODEX_HOME; OpenClaw копирует доверенные записи проектов и безопасную конфигурацию маршрутизации model/provider из конфигурации Codex на хосте, а auth, уведомления и hooks остаются в конфигурации хоста.
• Другие адаптеры целевых сред выполнения могут по-прежнему загружаться по требованию через npx при первом использовании.
• Auth поставщика все равно должен существовать на хосте для этой среды выполнения.
• Если на хосте нет npm или доступа к сети, загрузки адаптеров при первом запуске будут завершаться ошибкой, пока кэши не будут предварительно прогреты или адаптер не будет установлен другим способом.

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

Прежде чем винить OpenClaw, проверьте:

• /acp doctor сообщает о включенном и исправном backend.
• Целевой id разрешен через acp.allowedAgents, когда этот allowlist задан.
• Команда среды выполнения может запуститься на хосте Gateway.
• Auth поставщика присутствует для этой среды выполнения (claude, codex, gemini, opencode, droid и т. д.).
• Выбранная модель существует для этой среды выполнения - id моделей не переносимы между средами.
• Запрошенный cwd существует и доступен; либо не указывайте cwd и дайте backend использовать значение по умолчанию.
• Режим разрешений соответствует работе. Неинтерактивные сеансы не могут нажимать нативные запросы разрешений, поэтому write/exec-насыщенные кодовые запуски обычно требуют профиль разрешений ACPX, который может выполняться без участия пользователя.

• Spawn создает или возобновляет сеанс среды выполнения ACP, записывает метаданные ACP в хранилище сеансов OpenClaw и может создать фоновую задачу, когда запуск принадлежит родителю.
• ACP-сеансы, принадлежащие родителю, рассматриваются как фоновая работа, даже когда сеанс среды выполнения persistent; завершение и доставка между поверхностями проходят через уведомитель родительской задачи, а не ведут себя как обычный пользовательский чат-сеанс.
• Обслуживание задач закрывает terminal или orphaned одноразовые ACP-сеансы, принадлежащие родителю. Persistent ACP-сеансы сохраняются, пока остается активная привязка беседы; stale persistent-сеансы без активной привязки закрываются, чтобы их нельзя было незаметно возобновить после завершения владеющей задачи или исчезновения ее записи.
• Привязанные последующие сообщения идут напрямую в ACP-сеанс, пока привязка не будет закрыта, unfocused, сброшена или не истечет.
• Команды Gateway остаются локальными. /acp ..., /status и /unfocus никогда не отправляются как обычный текст prompt в привязанную ACP-среду.
• cancel прерывает активный ход, когда backend поддерживает отмену; он не удаляет привязку или метаданные сеанса.
• close завершает ACP-сеанс с точки зрения OpenClaw и удаляет привязку. Среда выполнения все еще может сохранять собственную upstream-историю, если поддерживает resume.
• Plugin acpx очищает принадлежащие OpenClaw деревья процессов wrapper и adapter после close, а также убирает stale принадлежащие OpenClaw ACPX orphans при запуске Gateway.
• Idle runtime workers могут быть очищены после acp.runtime.ttlMinutes; сохраненные метаданные сеанса остаются доступны для /acp sessions.

Триггеры на естественном языке, которые должны маршрутизироваться в нативный Codex Plugin, когда он включен:

• "Привяжи этот Discord-канал к Codex."
• "Прикрепи этот чат к Codex thread <id>."
• "Покажи Codex threads, затем привяжи этот."

Нативная привязка разговора Codex является стандартным путем управления чатом. Динамические инструменты OpenClaw по-прежнему выполняются через OpenClaw, а нативные для Codex инструменты, такие как shell/apply-patch, выполняются внутри Codex. Для событий нативных инструментов Codex OpenClaw внедряет для каждого хода нативный ретранслятор хуков, чтобы хуки Plugin могли блокировать before_tool_call, наблюдать after_tool_call и маршрутизировать события Codex PermissionRequest через подтверждения OpenClaw. Хуки Codex Stop ретранслируются в OpenClaw before_agent_finalize, где plugins могут запросить еще один проход модели до того, как Codex завершит свой ответ. Ретранслятор остается намеренно консервативным: он не изменяет аргументы нативных инструментов Codex и не переписывает записи треда Codex. Используйте явный ACP только когда вам нужна модель среды выполнения/сессии ACP. Граница встроенной поддержки Codex задокументирована в контракте поддержки Codex harness v1.

• устаревшие ссылки на модели Codex - маршрут модели устаревших OAuth/подписки Codex, исправляемый doctor.
• openai/* - встроенная среда выполнения нативного app-server Codex для ходов агента OpenAI.
• /codex ... - нативное управление разговором Codex.
• /acp ... или runtime: "acp" - явное управление ACP/acpx.

Триггеры, которые должны направляться в среду выполнения ACP:

• "Запусти это как одноразовую сессию Claude Code ACP и суммируй результат."
• "Используй Gemini CLI для этой задачи в треде, затем оставь последующие сообщения в том же треде."
• "Запусти Codex через ACP в фоновом треде."

OpenClaw выбирает runtime: "acp", разрешает agentId обвязки, привязывается к текущему разговору или треду, если поддерживается, и маршрутизирует последующие сообщения в эту сессию до закрытия/истечения срока. Codex следует этому пути только когда ACP/acpx указан явно или нативный Plugin 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 доставляется обратно в тот же тред.
• Unfocus/close/archive/idle-timeout или истечение max-age удаляет привязку.
• /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 (форумные темы в группах/супергруппах и темы DM).
• Каналы Plugin могут добавить поддержку через тот же интерфейс привязки.

Интерактивные сеансы предназначены для продолжения общения на видимой поверхности чата:

• /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 использует путь последующего сообщения agent-to-agent (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/harness, а не ключ сессии канала OpenClaw; OpenClaw по-прежнему проверяет политику запуска ACP и политику целевого агента перед отправкой, тогда как backend ACP или harness отвечает за авторизацию загрузки этого upstream-идентификатора.
• resumeSessionId восстанавливает upstream-историю разговора ACP; thread и mode по-прежнему обычным образом применяются к новой сессии OpenClaw, которую вы создаете, поэтому mode: "session" по-прежнему требует thread: true.
• Целевой агент должен поддерживать session/load (Codex и Claude Code поддерживают).
• Если идентификатор сессии не найден, запуск завершается понятной ошибкой - без тихого fallback к новой сессии.

После развертывания 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. Очистите временную сессию моста.

Оставьте gate на mode: "run" и пропустите streamTo: "parent" - привязанный к thread mode: "session" и пути stream-relay являются отдельными более насыщенными интеграционными проходами.