> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # агенты ACP [Сеансы Agent Client Protocol (ACP)](https://agentclientprotocol.com/) позволяют OpenClaw запускать внешние среды выполнения для кодинга (например Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI и другие поддерживаемые ACPX-среды) через backend-Plugin ACP. Каждый запуск ACP-сеанса отслеживается как [фоновая задача](/ru/automation/tasks). **ACP — это путь для внешних сред выполнения, а не стандартный путь Codex.** Нативный Plugin сервера приложения Codex владеет элементами управления `/codex ...` и стандартной встроенной средой выполнения `openai/gpt-*` для ходов агента; ACP владеет элементами управления `/acp ...` и сеансами `sessions_spawn({ runtime: "acp" })`. Если вы хотите, чтобы Codex или Claude Code подключались как внешний MCP-клиент напрямую к существующим беседам каналов OpenClaw, используйте [`openclaw mcp serve`](/ru/cli/mcp) вместо ACP. ## Какая страница мне нужна? | Вы хотите… | Используйте | Примечания | | -------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Привязать или управлять Codex в текущей беседе | `/codex bind`, `/codex threads` | Нативный путь сервера приложения Codex, когда Plugin `codex` включен; включает привязанные ответы чата, пересылку изображений, model/fast/permissions, stop и steer. ACP — явный fallback | | Запустить Claude Code, Gemini CLI, явный Codex ACP или другую внешнюю среду *через* OpenClaw | Эту страницу | Сеансы, привязанные к чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фоновые задачи, управление средой выполнения | | Предоставить сеанс OpenClaw Gateway *как* ACP-сервер для редактора или клиента | [`openclaw acp`](/ru/cli/acp) | Режим моста. IDE/клиент общается с OpenClaw по ACP через stdio/WebSocket | | Переиспользовать локальный AI CLI как текстовую fallback-модель | [CLI Backends](/ru/gateway/cli-backends) | Не ACP. Нет инструментов OpenClaw, нет элементов управления ACP, нет среды выполнения harness | ## Это работает из коробки? Да, после установки официального Plugin среды выполнения ACP: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins install @openclaw/acpx openclaw config set plugins.entries.acpx.enabled true ``` Исходные checkout-версии могут использовать локальный workspace-Plugin `extensions/acpx` после `pnpm install`. Запустите `/acp doctor` для проверки готовности. OpenClaw сообщает агентам о запуске ACP только когда ACP **действительно можно использовать**: ACP должен быть включен, dispatch не должен быть отключен, текущий сеанс не должен быть заблокирован sandbox, и backend среды выполнения должен быть загружен. Если эти условия не выполнены, Skills ACP Plugin и подсказки ACP для `sessions_spawn` остаются скрытыми, чтобы агент не предлагал недоступный backend. * Если задан `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, который может выполняться без участия пользователя. Инструменты OpenClaw Plugin и встроенные инструменты OpenClaw **не** предоставляются ACP-средам по умолчанию. Включайте явные MCP-мосты в [ACP agents - setup](/ru/tools/acp-agents-setup) только когда среда выполнения должна вызывать эти инструменты напрямую. ## Поддерживаемые целевые среды выполнения С backend `acpx` используйте эти id сред выполнения как цели `/acp spawn ` или `sessions_spawn({ runtime: "acp", agentId: "" })`: | Id среды | Типичный backend | Примечания | | ---------- | ------------------------------------------ | ------------------------------------------------------------------------------------------- | | `claude` | Адаптер Claude Code ACP | Требует auth Claude Code на хосте. | | `codex` | Адаптер Codex ACP | Только явный ACP fallback, когда нативный `/codex` недоступен или запрошен ACP. | | `copilot` | Адаптер GitHub Copilot ACP | Требует auth Copilot CLI/runtime. | | `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Переопределите команду acpx, если локальная установка предоставляет другую точку входа ACP. | | `droid` | Factory Droid CLI | Требует auth Factory/Droid или `FACTORY_API_KEY` в окружении среды выполнения. | | `gemini` | Адаптер Gemini CLI ACP | Требует auth Gemini CLI или настройки API-ключа. | | `iflow` | iFlow CLI | Доступность адаптера и управление моделями зависят от установленного CLI. | | `kilocode` | Kilo Code CLI | Доступность адаптера и управление моделями зависят от установленного CLI. | | `kimi` | Kimi/Moonshot CLI | Требует auth Kimi/Moonshot на хосте. | | `kiro` | Kiro CLI | Доступность адаптера и управление моделями зависят от установленного CLI. | | `opencode` | Адаптер OpenCode ACP | Требует auth OpenCode CLI/provider. | | `openclaw` | Мост OpenClaw Gateway через `openclaw acp` | Позволяет ACP-совместимой среде выполнения обращаться обратно к сеансу OpenClaw Gateway. | | `qwen` | Qwen Code / Qwen CLI | Требует Qwen-совместимый auth на хосте. | Пользовательские aliases агентов acpx можно настроить в самом acpx, но политика OpenClaw все равно проверяет `acp.allowedAgents` и любое сопоставление `agents.list[].runtime.acp.agent` перед dispatch. ## Runbook оператора Быстрый поток `/acp` из чата: `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` или явный `/acp spawn codex --bind here`. Продолжайте в привязанной беседе или thread (либо явно укажите ключ сеанса). `/acp status` `/acp model `, `/acp permissions `, `/acp timeout `. Без замены контекста: `/acp steer tighten logging and continue`. `/acp cancel` (текущий ход) или `/acp close` (сеанс + привязки). * 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 ``." * "Покажи 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](/ru/plugins/codex-harness-runtime#v1-support-contract). * устаревшие ссылки на модели 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` как базовый идентификатор обвязки. ## ACP и суб-агенты Используйте ACP, когда вам нужна внешняя среда выполнения обвязки. Используйте **нативный app-server Codex** для привязки/управления разговором Codex, когда Plugin `codex` включен. Используйте **суб-агентов**, когда вам нужны нативные для OpenClaw делегированные запуски. | Область | Сессия ACP | Запуск суб-агента | | ------------------ | ---------------------------------- | ----------------------------------------------- | | Среда выполнения | Бэкенд-Plugin ACP (например, acpx) | Нативная среда выполнения суб-агентов OpenClaw | | Ключ сессии | `agent::acp:` | `agent::subagent:` | | Основные команды | `/acp ...` | `/subagents ...` | | Инструмент запуска | `sessions_spawn` с `runtime:"acp"` | `sessions_spawn` (стандартная среда выполнения) | См. также [Суб-агенты](/ru/tools/subagents). ## Как ACP запускает Claude Code Для Claude Code через ACP стек выглядит так: 1. Плоскость управления сессиями OpenClaw ACP. 2. Официальный Plugin среды выполнения `@openclaw/acpx`. 3. Адаптер Claude ACP. 4. Механизмы среды выполнения/сессии на стороне Claude. ACP Claude - это **сессия обвязки** с элементами управления ACP, возобновлением сессии, отслеживанием фоновых задач и опциональной привязкой разговора/треда. Бэкенды CLI - это отдельные текстовые локальные резервные среды выполнения - см. [Бэкенды CLI](/ru/gateway/cli-backends). Для операторов практическое правило такое: * **Нужны `/acp spawn`, привязываемые сессии, элементы управления средой выполнения или постоянная работа обвязки?** Используйте ACP. * **Нужен простой локальный текстовый резерв через необработанный CLI?** Используйте бэкенды CLI. ## Привязанные сессии ### Ментальная модель * **Поверхность чата** - где люди продолжают общаться (канал Discord, тема Telegram, чат iMessage). * **Сессия ACP** - долговременное состояние среды выполнения Codex/Claude/Gemini, в которое OpenClaw маршрутизирует сообщения. * **Дочерний тред/тема** - опциональная дополнительная поверхность сообщений, создаваемая только через `--thread ...`. * **Рабочая область среды выполнения** - расположение в файловой системе (`cwd`, checkout репозитория, рабочая область бэкенда), где запускается обвязка. Не зависит от поверхности чата. ### Привязки текущего разговора `/acp spawn --bind here` закрепляет текущий разговор за созданной сессией ACP - без дочернего треда, на той же поверхности чата. OpenClaw продолжает управлять транспортом, аутентификацией, безопасностью и доставкой. Последующие сообщения в этом разговоре маршрутизируются в ту же сессию; `/new` и `/reset` сбрасывают сессию на месте; `/acp close` удаляет привязку. Примеры: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /codex bind # native Codex bind, route future messages here /codex model gpt-5.4 # tune the bound native Codex thread /codex stop # control the active native Codex turn /acp spawn codex --bind here # explicit ACP fallback for Codex /acp spawn codex --thread auto # may create a child thread/topic and bind there /acp spawn codex --bind here --cwd /workspace/repo # same chat binding, Codex runs in /workspace/repo ``` * `--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 в записях верхнего уровня `bindings[]`. ### Модель привязки Помечает постоянную привязку разговора ACP. Определяет целевой разговор. Формы по каналам: * **Канал/тред Discord:** `match.channel="discord"` + `match.peer.id=""` * **Канал/DM Slack:** `match.channel="slack"` + `match.peer.id="|#|userId|user:|slack:|<@userId>>"`. Предпочитайте стабильные идентификаторы Slack; привязки каналов также сопоставляют ответы внутри тредов этого канала. * **Форумная тема Telegram:** `match.channel="telegram"` + `match.peer.id=":topic:"` * **DM/группа WhatsApp:** `match.channel="whatsapp"` + `match.peer.id=""`. Используйте номера E.164, такие как `+15555550123`, для прямых чатов и JID групп WhatsApp, такие как `120363424282127706@g.us`, для групп. * **DM/группа iMessage:** `match.channel="imessage"` + `match.peer.id=""`. Предпочитайте `chat_id:*` для стабильных привязок групп. Идентификатор владеющего агента OpenClaw. Опциональное переопределение ACP. Опциональная метка для оператора. Опциональный рабочий каталог среды выполнения. Опциональное переопределение бэкенда. ### Стандартные значения среды выполнения для каждого агента Используйте `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`) ### Пример ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { agents: { list: [ { id: "codex", runtime: { type: "acp", acp: { agent: "codex", backend: "acpx", mode: "persistent", cwd: "/workspace/openclaw", }, }, }, { id: "claude", runtime: { type: "acp", acp: { agent: "claude", backend: "acpx", mode: "persistent" }, }, }, ], }, bindings: [ { type: "acp", agentId: "codex", match: { channel: "discord", accountId: "default", peer: { kind: "channel", id: "222222222222222222" }, }, acp: { label: "codex-main" }, }, { type: "acp", agentId: "claude", match: { channel: "telegram", accountId: "default", peer: { kind: "group", id: "-1001234567890:topic:42" }, }, acp: { cwd: "/workspace/repo-b" }, }, { type: "route", agentId: "main", match: { channel: "discord", accountId: "default" }, }, { type: "route", agentId: "main", match: { channel: "telegram", accountId: "default" }, }, ], channels: { discord: { guilds: { "111111111111111111": { channels: { "222222222222222222": { requireMention: false }, }, }, }, }, telegram: { groups: { "-1001234567890": { topics: { "42": { requireMention: false } }, }, }, }, }, } ``` ### Поведение * OpenClaw гарантирует, что настроенная сессия ACP существует после допуска для конкретного канала и перед использованием. * Сообщения в этом канале, теме или чате направляются в настроенную сессию ACP. * Настроенные привязки ACP владеют своим маршрутом сессии. Широковещательная рассылка канала веером не заменяет настроенную сессию ACP для совпавшей привязки. * В привязанных разговорах `/new` и `/reset` сбрасывают тот же ключ сессии ACP на месте. * Временные привязки среды выполнения (например, созданные потоками фокусировки на треде) по-прежнему применяются там, где присутствуют. * Для межагентных запусков ACP без явного `cwd` OpenClaw наследует рабочую область целевого агента из конфигурации агента. * Отсутствующие унаследованные пути рабочей области откатываются к стандартному cwd backend; ошибки доступа для существующих путей выдаются как ошибки запуска. ## Запуск сессий ACP Два способа запустить сессию ACP: Используйте `runtime: "acp"`, чтобы запустить сессию ACP из хода агента или вызова инструмента. ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "task": "Open the repo and summarize failing tests", "runtime": "acp", "agentId": "codex", "thread": true, "mode": "session" } ``` По умолчанию `runtime` имеет значение `subagent`, поэтому для сессий ACP явно задавайте `runtime: "acp"`. Если `agentId` пропущен, OpenClaw использует `acp.defaultAgent`, когда он настроен. `mode: "session"` требует `thread: true`, чтобы сохранить постоянный привязанный разговор. Используйте `/acp spawn` для явного операторского управления из чата. ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /acp spawn codex --mode persistent --thread auto /acp spawn codex --mode oneshot --thread off /acp spawn codex --bind here /acp spawn codex --thread here ``` Ключевые флаги: * `--mode persistent|oneshot` * `--bind here|off` * `--thread auto|here|off` * `--cwd ` * `--label ` См. [слэш-команды](/ru/tools/slash-commands). ### Параметры `sessions_spawn` Начальный prompt, отправляемый в сессию ACP. Для сессий ACP должно быть `"acp"`. Идентификатор целевого harness ACP. Откатывается к `acp.defaultAgent`, если он задан. Запрашивает поток привязки треда там, где он поддерживается. `"run"` является одноразовым; `"session"` является постоянным. Если `thread: true`, а `mode` пропущен, OpenClaw может по умолчанию использовать постоянное поведение для соответствующего пути среды выполнения. `mode: "session"` требует `thread: true`. Запрошенный рабочий каталог среды выполнения (проверяется политикой backend/среды выполнения). Если параметр пропущен, запуск ACP наследует рабочую область целевого агента, когда она настроена; отсутствующие унаследованные пути откатываются к значениям backend по умолчанию, а реальные ошибки доступа возвращаются. Метка, видимая оператору, которая используется в тексте сессии/баннера. Возобновляет существующую сессию ACP вместо создания новой. Агент повторно воспроизводит историю разговора через `session/load`. Требует `runtime: "acp"`. `"parent"` транслирует начальные сводки прогресса запуска ACP обратно в сессию запрашивающего как системные события. Принятые ответы включают `streamLogPath`, указывающий на JSONL-журнал в области сессии (`.acp-stream.jsonl`), который можно отслеживать для полной истории ретрансляции. Родительские потоки прогресса по умолчанию показывают комментарии assistant и прогресс статуса ACP, если только `streaming.progress.commentary=false`. Discord также по умолчанию переводит родительские предпросмотры в режим прогресса, когда режим потока не настроен. Прогресс статуса по-прежнему соблюдает `acp.stream.tagVisibility`, поэтому такие теги, как `plan`, остаются скрытыми, если они не включены явно. Запуски ACP через `sessions_spawn` используют `agents.defaults.subagents.runTimeoutSeconds` для стандартного лимита дочернего хода. Инструмент не принимает переопределения тайм-аута для отдельного вызова. Явное переопределение модели для дочерней сессии ACP. Запуски Codex ACP нормализуют ссылки OpenAI, такие как `openai/gpt-5.4`, в стартовую конфигурацию Codex ACP перед `session/new`; слэш-формы, такие как `openai/gpt-5.4/high`, также задают усилие рассуждения Codex ACP. Если параметр пропущен, `sessions_spawn({ runtime: "acp" })` использует существующие значения модели по умолчанию для subagent (`agents.defaults.subagents.model` или `agents.list[].subagents.model`), когда они настроены; иначе ACP harness использует собственную модель по умолчанию. Другие harness должны объявлять ACP `models` и поддерживать `session/set_model`; иначе OpenClaw/acpx явно завершится ошибкой вместо скрытого отката к значению целевого агента по умолчанию. Явное усилие thinking/reasoning. Для Codex ACP `minimal` сопоставляется с низким усилием, `low`/`medium`/`high`/`xhigh` сопоставляются напрямую, а `off` пропускает стартовое переопределение reasoning-effort. Если параметр пропущен, запуски ACP используют существующие значения thinking по умолчанию для subagent и помодельный параметр `agents.defaults.models["provider/model"].params.thinking` для выбранной модели. ## Режимы привязки запуска и треда | Режим | Поведение | | ------ | ------------------------------------------------------------------------------------------ | | `here` | Привязать текущую активную беседу на месте; завершиться ошибкой, если активной беседы нет. | | `off` | Не создавать привязку текущей беседы. | Примечания: * `--bind here` — самый простой путь оператора для «сделать этот канал или чат поддерживаемым Codex». * `--bind here` не создает дочернюю ветку. * `--bind here` доступен только в каналах, которые предоставляют поддержку привязки текущей беседы. * `--bind` и `--thread` нельзя объединять в одном вызове `/acp spawn`. | Режим | Поведение | | ------ | -------------------------------------------------------------------------------------------------------- | | `auto` | В активной ветке: привязать эту ветку. Вне ветки: создать/привязать дочернюю ветку, если поддерживается. | | `here` | Требовать текущую активную ветку; завершиться ошибкой, если вы не в ветке. | | `off` | Без привязки. Сеанс запускается непривязанным. | Примечания: * На поверхностях привязки без веток поведение по умолчанию фактически равно `off`. * Запуск с привязкой к ветке требует поддержки политики канала: * Discord: `channels.discord.threadBindings.spawnSessions=true` * Telegram: `channels.telegram.threadBindings.spawnSessions=true` * Используйте `--bind here`, когда нужно закрепить текущую беседу без создания дочерней ветки. ## Модель доставки Сеансы ACP могут быть либо интерактивными рабочими пространствами, либо фоновой работой, принадлежащей родителю. Путь доставки зависит от этой формы. Интерактивные сеансы предназначены для продолжения общения на видимой поверхности чата: * `/acp spawn ... --bind here` привязывает текущую беседу к сеансу ACP. * `/acp spawn ... --thread ...` привязывает ветку/тему канала к сеансу ACP. * Постоянно настроенные `bindings[].type="acp"` маршрутизируют совпадающие беседы в тот же сеанс ACP. Последующие сообщения в привязанной беседе направляются напрямую в сеанс ACP, а вывод ACP доставляется обратно в тот же канал/ветку/тему. Что OpenClaw отправляет в исполнительную среду: * Обычные привязанные последующие сообщения отправляются как текст запроса, с вложениями только тогда, когда исполнительная среда/бэкенд их поддерживает. * Команды управления `/acp` и локальные команды Gateway перехватываются до отправки в ACP. * События завершения, сгенерированные средой выполнения, материализуются для каждой цели. Агенты OpenClaw получают внутреннюю оболочку контекста среды выполнения OpenClaw; внешние исполнительные среды ACP получают обычный запрос с результатом дочерней задачи и инструкцией. Необработанная оболочка `<<>>` никогда не должна отправляться во внешние исполнительные среды или сохраняться как текст пользовательской расшифровки 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`, поэтому продолжает с полным контекстом того, что было раньше. ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "task": "Continue where we left off - fix the remaining test failures", "runtime": "acp", "agentId": "codex", "resumeSessionId": "" } ``` Типичные сценарии использования: * Передайте сессию 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 являются отдельными более насыщенными интеграционными проходами. ## Совместимость с песочницей Сессии ACP сейчас выполняются в среде выполнения хоста, **не** внутри песочницы OpenClaw. **Граница безопасности:** * Внешний harness может читать/писать в соответствии с собственными разрешениями CLI и выбранным `cwd`. * Политика песочницы OpenClaw **не** оборачивает выполнение ACP harness. * OpenClaw по-прежнему применяет feature gate 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 * затем label 2. Текущая привязка thread (если этот разговор/thread привязан к сессии ACP). 3. Резервная сессия текущего запрашивающего. Привязки текущего разговора и thread-привязки обе участвуют в шаге 2. Если цель не разрешается, OpenClaw возвращает понятную ошибку (`Unable to resolve session target: ...`). ## Элементы управления ACP | Команда | Что она делает | Пример | | -------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------- | | `/acp spawn` | Создать сессию ACP; необязательная текущая привязка или thread-привязка. | `/acp spawn codex --bind here --cwd /repo` | | `/acp cancel` | Отменить выполняющийся ход для целевой сессии. | `/acp cancel agent:codex:acp:` | | `/acp steer` | Отправить управляющую инструкцию в выполняющуюся сессию. | `/acp steer --session support inbox prioritize failing tests` | | `/acp close` | Закрыть сессию и отвязать цели thread. | `/acp close` | | `/acp status` | Показать backend, режим, состояние, параметры среды выполнения, возможности. | `/acp status` | | `/acp set-mode` | Задать режим среды выполнения для целевой сессии. | `/acp set-mode plan` | | `/acp set` | Записать общий параметр конфигурации среды выполнения. | `/acp set model openai/gpt-5.4` | | `/acp cwd` | Задать переопределение рабочего каталога среды выполнения. | `/acp cwd /Users/user/Projects/repo` | | `/acp permissions` | Задать профиль политики утверждений. | `/acp permissions strict` | | `/acp timeout` | Задать тайм-аут среды выполнения (в секундах). | `/acp timeout 120` | | `/acp model` | Задать переопределение модели среды выполнения. | `/acp model anthropic/claude-opus-4-6` | | `/acp reset-options` | Удалить переопределения параметров среды выполнения сессии. | `/acp reset-options` | | `/acp sessions` | Перечислить недавние сессии ACP из хранилища. | `/acp sessions` | | `/acp doctor` | Состояние backend, возможности, применимые исправления. | `/acp doctor` | | `/acp install` | Вывести детерминированные шаги установки и включения. | `/acp install` | `/acp status` показывает эффективные параметры среды выполнения, а также идентификаторы сессии уровня среды выполнения и уровня backend. Ошибки неподдерживаемых элементов управления отображаются понятно, когда backend не имеет возможности. `/acp sessions` читает хранилище для текущей привязанной сессии или сессии запрашивающего; целевые токены (`session-key`, `session-id` или `session-label`) разрешаются через обнаружение сессий gateway, включая пользовательские корни `session.store` для каждого агента. ### Сопоставление параметров среды выполнения `/acp` имеет удобные команды и общий setter. Эквивалентные операции: | Команда | Сопоставляется с | Примечания | | ---------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/acp model ` | ключ конфигурации среды выполнения `model` | Для Codex ACP OpenClaw нормализует `openai/` в идентификатор модели адаптера и сопоставляет суффиксы reasoning через косую черту, такие как `openai/gpt-5.4/high`, с `reasoning_effort`. | | `/acp set thinking ` | канонический параметр `thinking` | OpenClaw отправляет эквивалент, объявленный backend, когда он присутствует, предпочитая `thinking`, затем `effort`, `reasoning_effort` или `thought_level`. Для Codex ACP адаптер сопоставляет значения с `reasoning_effort`. | | `/acp permissions ` | канонический параметр `permissionProfile` | OpenClaw отправляет эквивалент, объявленный backend, когда он присутствует, например `approval_policy`, `permission_profile`, `permissions` или `permission_mode`. | | `/acp timeout ` | канонический параметр `timeoutSeconds` | OpenClaw отправляет эквивалент, объявленный backend, когда он присутствует, например `timeout` или `timeout_seconds`. | | `/acp cwd ` | переопределение cwd среды выполнения | Прямое обновление. | | `/acp set ` | общий | `key=cwd` использует путь переопределения cwd. | | `/acp reset-options` | очищает все переопределения среды выполнения | - | ## acpx harness, настройка Plugin и разрешения О настройке acpx harness (алиасы Claude Code / Codex / Gemini CLI), MCP-мостах plugin-tools и OpenClaw-tools, а также режимах разрешений ACP см. [Агенты ACP - настройка](/ru/tools/acp-agents-setup). ## Устранение неполадок | Симптом | Вероятная причина | Исправление | | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ACP runtime backend is not configured` | Backend-plugin отсутствует, отключен или заблокирован `plugins.allow`. | Установите и включите backend-plugin, добавьте `acpx` в `plugins.allow`, если этот allowlist задан, затем выполните `/acp doctor`. | | `ACP is disabled by policy (acp.enabled=false)` | ACP глобально отключен. | Установите `acp.enabled=true`. | | `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Автоматическая диспетчеризация из обычных сообщений потока отключена. | Установите `acp.dispatch.enabled=true`, чтобы возобновить автоматическую маршрутизацию потоков; явные вызовы `sessions_spawn({ runtime: "acp" })` по-прежнему работают. | | `ACP agent "" is not allowed by policy` | Агент отсутствует в allowlist. | Используйте разрешенный `agentId` или обновите `acp.allowedAgents`. | | `/acp doctor` сообщает, что backend не готов сразу после запуска | Backend-plugin отсутствует, отключен, заблокирован политикой allow/deny, или его настроенный исполняемый файл недоступен. | Установите/включите backend-plugin, повторно выполните `/acp doctor` и проверьте ошибку установки backend или политики, если он остается неработоспособным. | | Команда harness не найдена | CLI-адаптер не установлен, внешний plugin отсутствует или первый запуск `npx` не смог получить данные для адаптера не-Codex. | Выполните `/acp doctor`, установите/предварительно прогрейте адаптер на хосте Gateway или явно настройте команду агента acpx. | | Ошибка model-not-found от harness | Идентификатор модели допустим для другого провайдера/harness, но не для этой цели ACP. | Используйте модель, перечисленную этим harness, настройте модель в harness или не задавайте переопределение. | | Ошибка аутентификации поставщика от harness | OpenClaw работоспособен, но целевой CLI/провайдер не авторизован. | Авторизуйтесь или предоставьте требуемый ключ провайдера в окружении хоста Gateway. | | `Unable to resolve session target: ...` | Некорректный ключ/идентификатор/токен метки. | Выполните `/acp sessions`, скопируйте точный ключ/метку и повторите попытку. | | `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` использован без активной привязываемой беседы. | Перейдите в целевой чат/канал и повторите попытку либо используйте запуск без привязки. | | `Conversation bindings are unavailable for .` | У адаптера нет возможности ACP-привязки к текущей беседе. | Используйте `/acp spawn ... --thread ...`, где это поддерживается, настройте верхнеуровневые `bindings[]` или перейдите в поддерживаемый канал. | | `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` использован вне контекста потока. | Перейдите в целевой поток или используйте `--thread auto`/`off`. | | `Only can rebind this channel/conversation/thread.` | Другой пользователь владеет активной целью привязки. | Выполните повторную привязку от имени владельца или используйте другую беседу либо поток. | | `Thread bindings are unavailable for .` | У адаптера нет возможности привязки потока. | Используйте `--thread off` или перейдите на поддерживаемый адаптер/канал. | | `Sandboxed sessions cannot spawn ACP sessions ...` | Среда выполнения ACP находится на стороне хоста; запрашивающая сессия изолирована в sandbox. | Используйте `runtime="subagent"` из изолированных сессий или выполните запуск ACP из неизолированной сессии. | | `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для среды выполнения ACP запрошено `sandbox="require"`. | Используйте `runtime="subagent"` для обязательной изоляции или используйте ACP с `sandbox="inherit"` из неизолированной сессии. | | `Cannot apply --model ... did not advertise model support` | Целевой harness не предоставляет универсальное переключение моделей ACP. | Используйте harness, который объявляет ACP `models`/`session/set_model`, используйте ссылки моделей Codex ACP или настройте модель напрямую в harness, если у него есть собственный флаг запуска. | | Отсутствуют метаданные ACP для привязанной сессии | Устаревшие/удаленные метаданные сессии ACP. | Создайте заново с помощью `/acp spawn`, затем повторно привяжите/сфокусируйте поток. | | `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокирует запись/выполнение в неинтерактивной сессии ACP. | Установите `plugins.entries.acpx.config.permissionMode` в `approve-all` и перезапустите gateway. См. [конфигурацию разрешений](/ru/tools/acp-agents-setup#permission-configuration). | | Сессия ACP рано завершается с малым объемом вывода | Запросы разрешений заблокированы `permissionMode`/`nonInteractivePermissions`. | Проверьте журналы gateway на наличие `AcpRuntimeError`. Для полных разрешений установите `permissionMode=approve-all`; для плавной деградации установите `nonInteractivePermissions=deny`. | | Сессия ACP зависает на неопределенное время после завершения работы | Процесс harness завершился, но сессия ACP не сообщила о завершении. | Обновите OpenClaw; текущая очистка acpx при закрытии и запуске Gateway убирает устаревшие процессы-обертки и процессы адаптеров, принадлежащие OpenClaw. | | Harness видит `<<>>` | Внутренняя оболочка события просочилась через границу ACP. | Обновите OpenClaw и повторно выполните поток завершения; внешние harness должны получать только обычные подсказки завершения. | `Command blocked by PreToolUse hook: Native hook relay unavailable` относится к нативному ретранслятору хуков Codex, а не к ACP/acpx. В привязанном чате Codex начните новую сессию с `/new` или `/reset`; если это сработает один раз, а затем вернется при следующем нативном вызове инструмента, перезапустите app-server Codex или Gateway OpenClaw вместо повторения `/new`. См. [устранение неполадок harness Codex](/ru/plugins/codex-harness#troubleshooting). ## Связанное * [Агенты ACP — настройка](/ru/tools/acp-agents-setup) * [Отправка агенту](/ru/tools/agent-send) * [CLI Backends](/ru/gateway/cli-backends) * [Harness Codex](/ru/plugins/codex-harness) * [Среда выполнения harness Codex](/ru/plugins/codex-harness-runtime) * [Инструменты sandbox для нескольких агентов](/ru/tools/multi-agent-sandbox-tools) * [`openclaw acp` (режим моста)](/ru/cli/acp) * [Субагенты](/ru/tools/subagents)