> ## 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 среды)
через серверный плагин ACP. Каждый запуск отслеживается как
[фоновая задача](https://docs2.openclaw.ai/ru/automation/tasks.md).

> [!NOTE]
>
> **ACP — это путь для внешних сред, а не путь Codex по умолчанию.** Нативный
> плагин сервера приложений Codex отвечает за элементы управления `/codex ...` и встроенную среду выполнения
> `openai/gpt-*` по умолчанию для ходов агента; ACP отвечает за элементы управления `/acp ...`
> и сеансы `sessions_spawn({ runtime: "acp" })`.
>
> Чтобы Codex или Claude Code могли подключаться как внешний клиент MCP напрямую к
> существующим обсуждениям каналов OpenClaw, используйте
> [`openclaw mcp serve`](https://docs2.openclaw.ai/ru/cli/mcp) вместо ACP.

## Какая страница мне нужна?

| Вы хотите... | Используйте | Примечания |
| - | - | - |
| Привязать Codex к текущему обсуждению или управлять им | `/codex bind`, `/codex threads` | Нативный путь сервера приложений Codex при включённом плагине `codex`: ответы в привязанном чате, пересылка изображений, модель/быстрый режим/разрешения, остановка и корректировка. ACP — явный резервный вариант |
| Запустить Claude Code, Gemini CLI, явно Codex ACP или другую внешнюю среду *через* OpenClaw | Эта страница | Сеансы, привязанные к чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фоновые задачи, элементы управления средой выполнения |
| Предоставить сеанс OpenClaw Gateway *как* сервер ACP для редактора или клиента | [`openclaw acp`](https://docs2.openclaw.ai/ru/cli/acp) | Режим моста: IDE/клиент взаимодействует с OpenClaw по ACP через stdio/WebSocket |
| Повторно использовать локальный AI CLI как резервную модель только для текста | [Серверные части CLI](https://docs2.openclaw.ai/ru/gateway/cli-backends.md) | Не ACP: без инструментов OpenClaw, элементов управления ACP и среды выполнения внешней среды |

## Работает ли это сразу после установки?

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```

В рабочих копиях исходного кода можно использовать локальный плагин рабочего пространства `extensions/acpx` после
`pnpm install`. Выполните `/acp doctor`, чтобы проверить готовность.

OpenClaw сообщает агентам о запуске ACP, только когда ACP **действительно можно использовать**:
ACP должен быть включён, диспетчеризация не должна быть отключена, текущий сеанс не должен
блокироваться песочницей, а серверная часть среды выполнения должна быть загружена и исправна. Если
какое-либо условие не выполнено, Skills ACP и руководство по ACP для `sessions_spawn` остаются скрытыми,
чтобы агент не предлагал недоступную серверную часть.

> [accordion] Особенности первого запуска
>
> * Если задан `plugins.allow`, он представляет собой ограничительный перечень плагинов и **должен** включать `acpx`, иначе установленная серверная часть ACP намеренно блокируется (`/acp doctor` сообщает об отсутствующей записи в списке разрешённых).
> * Адаптер Codex ACP поставляется с плагином `acpx` и по возможности запускается локально.
> * Codex ACP работает с изолированным `CODEX_HOME`. OpenClaw копирует доверенные записи о доверии к проектам и безопасную конфигурацию маршрутизации моделей и поставщиков (`model`, `model_provider`, `model_reasoning_effort`, `sandbox_mode` и безопасные поля `model_providers.<name>`) из конфигурации Codex на хосте; аутентификация, уведомления и перехватчики остаются только в конфигурации хоста.
> * Адаптеры других целевых сред могут загружаться по требованию с помощью `npx` при первом использовании.
> * Аутентификация поставщика для этой среды уже должна быть настроена на хосте.
> * Если на хосте нет npm или доступа к сети, загрузка адаптеров при первом запуске завершается с ошибкой, пока кэши не будут предварительно заполнены или адаптер не будет установлен другим способом.

> [accordion] Требования к среде выполнения
>
> ACP запускает реальный процесс внешней среды. OpenClaw отвечает за маршрутизацию,
> состояние фоновых задач, доставку, привязки и политики; внешняя среда отвечает
> за вход в систему поставщика, каталог моделей, работу с файловой системой и нативные инструменты.
>
> Прежде чем считать причиной OpenClaw, проверьте:
>
> * `/acp doctor` сообщает о включённой и исправной серверной части.
> * Целевой идентификатор разрешён параметром `acp.allowedAgents`, если этот список разрешённых задан.
> * Команда внешней среды может запускаться на хосте Gateway.
> * Для этой среды настроена аутентификация поставщика (`claude`, `codex`, `gemini`, `opencode`, `droid` и т. д.).
> * Выбранная модель существует для этой среды — идентификаторы моделей нельзя переносить между средами.
> * Запрошенный `cwd` существует и доступен; иначе опустите `cwd`, чтобы серверная часть использовала значение по умолчанию.
> * Режим разрешений соответствует работе. Неинтерактивные сеансы не могут нажимать кнопки в нативных запросах разрешений, поэтому для запусков программирования с интенсивной записью и выполнением обычно требуется профиль разрешений ACPX, позволяющий продолжать работу без интерфейса.

Инструменты плагинов OpenClaw и встроенные инструменты OpenClaw по умолчанию
**не** предоставляются средам ACP. Включайте явные мосты MCP в разделе
[Агенты ACP — настройка](https://docs2.openclaw.ai/ru/tools/acp-agents-setup.md), только если среда должна
вызывать эти инструменты напрямую.

## Поддерживаемые целевые среды

С серверной частью `acpx` используйте эти идентификаторы как цели `/acp spawn <id>` или
`sessions_spawn({ runtime: "acp", agentId: "<id>" })`:

| Идентификатор среды | Типичная серверная часть | Примечания |
| - | - | - |
| `claude` | Адаптер Claude Code ACP | Требует аутентификации Claude Code на хосте. |
| `codex` | Адаптер Codex ACP | Только явный резервный вариант ACP, когда нативный `/codex` недоступен или запрошен ACP. |
| `copilot` | Адаптер GitHub Copilot ACP | Требует аутентификации CLI/среды выполнения Copilot. |
| `cursor` | Cursor CLI ACP (`cursor-agent acp`) | Переопределите команду acpx, если локальная установка предоставляет другую точку входа ACP. |
| `droid` | Factory Droid CLI | Требует аутентификации Factory/Droid или `FACTORY_API_KEY` в окружении среды. |
| `fast-agent` | Адаптер fast-agent-mcp ACP | Загружается по требованию с помощью `uvx`. |
| `gemini` | Адаптер Gemini CLI ACP | Требует аутентификации Gemini CLI или настройки ключа API. |
| `iflow` | iFlow CLI | Доступность адаптера и управление моделью зависят от установленного CLI. |
| `kilocode` | Kilo Code CLI | Доступность адаптера и управление моделью зависят от установленного CLI. |
| `kimi` | Kimi/Moonshot CLI | Требует аутентификации Kimi/Moonshot на хосте. |
| `kiro` | Kiro CLI | Доступность адаптера и управление моделью зависят от установленного CLI. |
| `mux` | Адаптер Mux CLI ACP | Загружается по требованию с помощью `npx`. |
| `opencode` | Адаптер OpenCode ACP | Требует аутентификации CLI/поставщика OpenCode. |
| `openclaw` | Мост OpenClaw Gateway через `openclaw acp` | Позволяет среде с поддержкой ACP взаимодействовать с сеансом OpenClaw Gateway. |
| `qoder` | Qoder CLI | Доступность адаптера и управление моделью зависят от установленного CLI. |
| `qwen` | Qwen Code / Qwen CLI | Требует совместимой с Qwen аутентификации на хосте. |
| `trae` | Адаптер Trae CLI ACP | Доступность адаптера и управление моделью зависят от установленного CLI. |

`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` (сеанс и привязки).

> [accordion] Сведения о жизненном цикле
>
> * Создание запускает или возобновляет сеанс среды выполнения ACP, записывает метаданные ACP в хранилище сеансов OpenClaw и может создать фоновую задачу, если запуск принадлежит родительской задаче.
> * Сеансы ACP, принадлежащие родительской задаче, считаются фоновой работой, даже если сеанс среды выполнения постоянный; завершение и доставка между интерфейсами выполняются через механизм уведомлений родительской задачи, а не как в обычном пользовательском сеансе чата.
> * Обслуживание задач закрывает завершённые или оставшиеся без родительской задачи одноразовые сеансы ACP, принадлежащие родительской задаче. Постоянные сеансы ACP сохраняются, пока действует активная привязка к беседе; устаревшие постоянные сеансы без активной привязки закрываются, чтобы их нельзя было незаметно возобновить после завершения владеющей ими задачи или удаления записи о ней.
> * Последующие сообщения из привязанной беседы направляются непосредственно в сеанс ACP, пока привязка не будет закрыта, снята с фокуса, сброшена или не истечёт.
> * Команды Gateway остаются локальными. `/acp ...`, `/status` и `/unfocus` никогда не отправляются привязанной управляющей среде ACP как обычный текст запроса.
> * `cancel` прерывает активный ход, если серверная часть поддерживает отмену; эта команда не удаляет привязку или метаданные сеанса.
> * `close` завершает сеанс ACP с точки зрения OpenClaw и удаляет привязку. Управляющая среда может по-прежнему хранить собственную историю на вышестоящей стороне, если поддерживает возобновление.
> * Плагин acpx очищает принадлежащие OpenClaw деревья процессов оболочки и адаптера после `close`, а также удаляет устаревшие осиротевшие процессы ACPX, принадлежащие OpenClaw, при запуске Gateway.
> * Неактивные рабочие процессы среды выполнения могут быть очищены после `acp.runtime.ttlMinutes`; сохранённые метаданные сеанса остаются доступными для `/acp sessions`.

> [accordion] Правила маршрутизации нативного Codex
>
> Триггеры на естественном языке, которые должны направляться в **нативный плагин 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` ретранслируются в
> `before_agent_finalize` OpenClaw, где плагины могут запросить ещё один проход модели,
> прежде чем Codex завершит свой ответ. Ретранслятор намеренно действует консервативно:
> он не изменяет аргументы нативных инструментов Codex и не перезаписывает записи веток
> Codex. Используйте ACP явно, только если вам нужна модель среды выполнения и сеансов
> ACP. Граница поддержки встроенного Codex описана в
> [контракте поддержки управляющей среды Codex v1](https://docs2.openclaw.ai/ru/plugins/codex-harness-runtime.md#v1-support-contract).

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

> [accordion] Триггеры маршрутизации ACP на естественном языке
>
> Триггеры, которые должны направляться в среду выполнения 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, когда нужна внешняя среда выполнения управляющей среды. Используйте
**нативный app-server Codex** для привязки беседы Codex и управления ею, когда включён
плагин `codex`. Используйте **субагентов**, когда нужны делегированные запуски
в среде OpenClaw.

| Область | Сеанс ACP | Запуск субагента |
| - | - | - |
| Среда выполнения | Плагин серверной части ACP (например, acpx) | Нативная среда выполнения субагентов OpenClaw |
| Ключ сеанса | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Основные команды | `/acp ...` | `/subagents ...` |
| Инструмент создания | `sessions_spawn` с `runtime:"acp"` | `sessions_spawn` (стандартная среда выполнения) |

См. также [Субагенты](https://docs2.openclaw.ai/ru/tools/subagents.md).

## Как ACP запускает Claude Code

Для Claude Code через ACP стек выглядит так:

1. Плоскость управления сеансами ACP OpenClaw.
2. Официальный плагин среды выполнения `@openclaw/acpx`.
3. Адаптер Claude ACP.
4. Механизмы среды выполнения и сеансов на стороне Claude.

ACP Claude — это **сеанс управляющей среды** с элементами управления ACP,
возобновлением сеанса, отслеживанием фоновых задач и необязательной привязкой
к беседе или ветке.

Серверные части CLI — отдельные локальные резервные среды выполнения только для текста;
см. [Серверные части CLI](https://docs2.openclaw.ai/ru/gateway/cli-backends.md).

Практическое правило для операторов:

* **Нужны `/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` удаляет привязку.

Примеры:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/codex bind                                              # нативная привязка Codex, направлять сюда будущие сообщения
/codex model gpt-5.4                                     # настроить привязанную нативную ветку Codex
/codex stop                                              # управлять активным нативным ходом Codex
/acp spawn codex --bind here                             # явный резервный вариант ACP для Codex
/acp spawn codex --thread auto                           # может создать дочернюю ветку или тему и выполнить привязку там
/acp spawn codex --bind here --cwd /workspace/repo       # та же привязка чата, Codex работает в /workspace/repo
```

> [accordion] Правила привязки и взаимоисключение
>
> * `--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` также остаются локальными, когда обработка команд включена для этого интерфейса.

> [accordion] Сеансы, привязанные к веткам
>
> Когда для адаптера канала включены привязки к веткам:
>
> * 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 возвращает понятное сообщение
> об отсутствии поддержки или доступности.

> [accordion] Каналы с поддержкой веток
>
> * Любой адаптер канала, предоставляющий возможность привязки сеансов или веток.
> * Текущая встроенная поддержка: ветки и каналы **Discord**, темы **Telegram** (темы форумов в группах и супергруппах, а также темы личных сообщений).
> * Плагины каналов могут добавить поддержку через тот же интерфейс привязки.

## Постоянные привязки каналов

Для неэфемерных рабочих процессов настройте постоянные привязки ACP в записях
верхнего уровня `bindings[]`.

### Модель привязки

**bindings\[].type** `"acp"`

Обозначает постоянную привязку беседы ACP.

**bindings\[].match** `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:*`.

**bindings\[].agentId** `string`

Идентификатор агента OpenClaw, которому принадлежит привязка.

**bindings\[].acp.mode** `"persistent" | "oneshot"`

Необязательное переопределение ACP.

**bindings\[].acp.label** `string`

Необязательная метка для оператора.

**bindings\[].acp.cwd** `string`

Необязательный рабочий каталог среды выполнения.

**bindings\[].acp.backend** `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`)

### Пример

```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 наследует рабочее пространство целевого агента из конфигурации агента.
* Если унаследованный путь к рабочему пространству отсутствует, используется рабочий каталог бэкенда по умолчанию; ошибки доступа к существующему пути возвращаются как ошибки создания сеанса.

## Запуск сеансов ACP

Сеанс ACP можно запустить двумя способами:

> [tab] Из sessions\_spawn
>
> Используйте `runtime: "acp"`, чтобы запустить сеанс ACP из хода агента или
> вызова инструмента.
>
> ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   "task": "Открой репозиторий и кратко опиши непройденные тесты",
>   "runtime": "acp",
>   "agentId": "codex",
>   "thread": true,
>   "mode": "session"
> }
> ```
>
> > [!NOTE]
> >
> > Значением `runtime` по умолчанию является `subagent`, поэтому для
> > сеансов ACP задавайте `runtime: "acp"` явно. Если `agentId` опущен,
> > OpenClaw использует `acp.defaultAgent`, когда он настроен. Для сохранения
> > постоянной привязанной беседы `mode: "session"` требует `thread: true`.

> [tab] Из команды /acp
>
> Используйте `/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 <absolute-path>`
> * `--label <name>`
>
> См. [Команды с косой чертой](https://docs2.openclaw.ai/ru/tools/slash-commands.md).

### Параметры `sessions_spawn`

**task** `string` *required*

Исходный запрос, отправляемый в сеанс ACP.

**runtime** `"acp"` *required*

Для сеансов ACP должно быть указано `"acp"`.

**agentId** `string`

Идентификатор целевой среды ACP. Если задан `acp.defaultAgent`, используется он.

**thread** `boolean` (default: false)

Запрашивает процесс привязки к ветке там, где он поддерживается.

**mode** `"run" | "session"` (default: run)

`"run"` выполняется однократно, а `"session"` является постоянным. Если указан `thread: true`,
а `mode` опущен, OpenClaw может по умолчанию использовать постоянный режим в зависимости от
пути среды выполнения. Для `mode: "session"` требуется `thread: true`.

**cwd** `string`

Запрошенный рабочий каталог среды выполнения (проверяется политикой бэкенда/среды выполнения).
Если он опущен, создаваемый сеанс ACP наследует рабочее пространство целевого агента, когда оно настроено;
при отсутствии унаследованного пути используются значения бэкенда по умолчанию, а фактические ошибки
доступа возвращаются вызывающей стороне.

**label** `string`

Метка для оператора, используемая в тексте сеанса/баннера.

**resumeSessionId** `string`

Возобновляет существующий сеанс ACP вместо создания нового. Агент
повторно воспроизводит историю беседы через `session/load`. Требуется
`runtime: "acp"`.

**streamTo** `"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` отклоняются с ошибкой,
предписывающей настроить значение по умолчанию).

**model** `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 возвращает
понятную ошибку вместо неявного перехода к модели целевого агента по умолчанию.

**thinking** `string`

Явная интенсивность обдумывания/рассуждений. Для Codex ACP `minimal` соответствует низкой
интенсивности, `low`/`medium`/`high`/`xhigh` сопоставляются напрямую, а `off` исключает
переопределение интенсивности рассуждений при запуске. Если параметр опущен, создаваемые сеансы ACP используют существующие
значения обдумывания субагента по умолчанию и заданное для каждой модели
`agents.defaults.models["provider/model"].params.thinking` для выбранной
модели.

## Режимы привязки и веток при создании сеанса

> [tab] --bind here|off
>
> | Режим | Поведение |
> | - | - |
> | `here` | Привязать текущую активную беседу без её замены; завершить с ошибкой, если активной беседы нет. |
> | `off` | Не создавать привязку текущей беседы. |
>
> Примечания:
>
> * `--bind here` — самый простой путь для оператора, чтобы «подключить Codex к этому каналу или чату».
> * `--bind here` не создаёт дочернюю ветку.
> * `--bind here` доступен только в каналах, поддерживающих привязку текущей беседы.
> * `--bind` и `--thread` нельзя сочетать в одном вызове `/acp spawn`.

> [tab] --thread auto|here|off
>
> | Режим | Поведение |
> | - | - |
> | `auto` | В активной ветке: привязать эту ветку. Вне ветки: создать/привязать дочернюю ветку, если это поддерживается. |
> | `here` | Требовать наличия текущей активной ветки; завершить с ошибкой, если её нет. |
> | `off` | Без привязки. Сеанс запускается непривязанным. |
>
> Примечания:
>
> * На поверхностях без поддержки привязки к веткам поведение по умолчанию фактически соответствует `off`.
> * Для создания сеанса с привязкой к ветке требуется поддержка в политике канала:
>   * Discord: `channels.discord.threadBindings.spawnSessions=true`
>   * Telegram: `channels.telegram.threadBindings.spawnSessions=true`
> * Используйте `--bind here`, если хотите закрепить текущую беседу без создания дочерней ветки.

## Модель доставки

Сеансы ACP могут быть интерактивными рабочими пространствами или фоновой
работой под управлением родительского сеанса. Путь доставки зависит от этого вида.

> [accordion] Интерактивные сеансы 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 и не считаются содержимым чата, созданным пользователем.

> [accordion] Одноразовые сеансы ACP, принадлежащие родителю
>
> Одноразовые сеансы ACP, запущенные другим выполнением агента, являются фоновыми
> дочерними процессами, подобными субагентам:
>
> * Родитель запрашивает выполнение работы с помощью `sessions_spawn({ runtime: "acp", mode: "run" })`.
> * Дочерний процесс выполняется в собственном сеансе среды выполнения ACP.
> * Ходы дочернего процесса выполняются в той же фоновой очереди, что и запуски нативных субагентов, поэтому медленная среда выполнения ACP не блокирует несвязанную работу основного сеанса.
> * Отчёт о завершении возвращается через путь уведомления о завершении задачи. Перед отправкой во внешнюю среду выполнения OpenClaw преобразует внутренние метаданные завершения в обычный запрос ACP, поэтому среды выполнения не видят маркеры контекста среды выполнения, предназначенные только для OpenClaw.
> * Родитель переформулирует результат дочернего процесса обычным голосом ассистента, если требуется ответ для пользователя.
>
> **Не** рассматривайте этот путь как одноранговый чат между родителем и
> дочерним процессом. У дочернего процесса уже есть канал передачи результата родителю.

> [accordion] sessions\_send и доставка A2A
>
> `sessions_send` может обращаться к другому сеансу после запуска. Для обычных одноранговых
> сеансов OpenClaw использует путь последующего взаимодействия между агентами (A2A) после
> внедрения сообщения:
>
> * Дождаться ответа целевого сеанса.
> * При необходимости разрешить запрашивающей и целевой сторонам обменяться ограниченным числом последующих ходов.
> * Попросить целевую сторону сформировать сообщение-уведомление.
> * Доставить это уведомление в видимый канал или ветку.
>
> Этот путь A2A служит резервным вариантом для одноранговых отправок, когда отправителю требуется
> видимое последующее сообщение. Он остаётся включённым, когда несвязанный сеанс может видеть
> целевой объект ACP и отправлять ему сообщения, например при широких настройках
> `tools.sessions.visibility`.
>
> OpenClaw пропускает последующее взаимодействие A2A только тогда, когда запрашивающая сторона является родителем
> собственного одноразового дочернего процесса ACP, принадлежащего родителю. В этом случае запуск A2A поверх
> механизма завершения задачи может активировать родителя с результатом дочернего процесса, переслать
> ответ родителя обратно дочернему процессу и создать цикл эха между родителем и дочерним
> процессом. Результат `sessions_send` сообщает `delivery.status="skipped"` для
> такого принадлежащего родителю дочернего процесса, поскольку за результат уже отвечает путь завершения.

> [accordion] Возобновление существующего сеанса
>
> Используйте `resumeSessionId`, чтобы продолжить предыдущий сеанс ACP вместо
> запуска нового. Агент воспроизводит историю диалога через
> `session/load`, поэтому продолжает работу с полным контекстом предыдущих действий.
>
> ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   "task": "Продолжи с того места, где мы остановились, — исправь оставшиеся сбои тестов",
>   "runtime": "acp",
>   "agentId": "codex",
>   "resumeSessionId": "<previous-session-id>"
> }
> ```
>
> Распространённые варианты использования:
>
> * Передайте сеанс Codex с ноутбука на телефон — попросите агента продолжить с того места, где вы остановились.
> * Продолжите сеанс программирования, начатый интерактивно в CLI, теперь в безголовом режиме через агента.
> * Возобновите работу, прерванную перезапуском Gateway или тайм-аутом бездействия.
>
> Примечания:
>
> * `resumeSessionId` применяется только при `runtime: "acp"`; среда выполнения субагентов по умолчанию игнорирует это поле, предназначенное только для ACP.
> * `streamTo` применяется только при `runtime: "acp"`; среда выполнения субагентов по умолчанию игнорирует это поле, предназначенное только для ACP.
> * `resumeSessionId` — это локальный для хоста идентификатор возобновления ACP/среды выполнения, а не ключ сеанса канала OpenClaw; перед передачей OpenClaw по-прежнему проверяет политику запуска ACP и политику целевого агента, а за авторизацию загрузки этого вышестоящего идентификатора отвечает бэкенд ACP или среда выполнения.
> * `resumeSessionId` восстанавливает историю вышестоящего диалога ACP; `thread` и `mode` по-прежнему обычным образом применяются к создаваемому новому сеансу OpenClaw, поэтому для `mode: "session"` всё ещё требуется `thread: true`.
> * Целевой агент должен поддерживать `session/load` (Codex и Claude Code поддерживают).
> * Если идентификатор сеанса не найден, запуск завершается с понятной ошибкой — без неявного перехода к новому сеансу.

> [accordion] Проверка работоспособности после развёртывания
>
> После развёртывания 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.

> [!WARNING]
>
> **Граница безопасности:**
>
> * Внешняя среда выполнения может читать и записывать данные в соответствии с собственными разрешениями 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

| Команда | Назначение | Пример |
| - | - | - |
| `/acp spawn` | Создать сеанс ACP; необязательная привязка к текущему диалогу или ветке. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | Отменить выполняющийся ход целевого сеанса. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | Отправить корректирующую инструкцию выполняющемуся сеансу. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Закрыть сеанс и удалить привязки целей ветки. | `/acp close` |
| `/acp status` | Показать бэкенд, режим, состояние, параметры среды выполнения и возможности. | `/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` | Показать состояние бэкенда, возможности и применимые исправления. | `/acp doctor` |
| `/acp install` | Вывести детерминированные шаги установки и включения. | `/acp install` |

Для элементов управления средой выполнения (`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` содержит команды быстрого доступа и универсальную команду установки. Эквивалентные операции:

| Команда | Соответствует | Примечания |
| - | - | - |
| `/acp model <id>` | ключ конфигурации среды выполнения `model` | Для Codex ACP OpenClaw нормализует `openai/<model>` в идентификатор модели адаптера и преобразует суффиксы уровня рассуждений после косой черты, например `openai/gpt-5.4/high`, в `reasoning_effort`. |
| `/acp set thinking <level>` | канонический параметр `thinking` | OpenClaw отправляет эквивалент, объявленный бэкендом, если он присутствует, отдавая предпочтение `thinking`, затем `effort`, `reasoning_effort` или `thought_level`. Для Codex ACP адаптер преобразует значения в `reasoning_effort`. |
| `/acp permissions <profile>` | канонический параметр `permissionProfile` | OpenClaw отправляет эквивалент, объявленный бэкендом, если он присутствует, например `approval_policy`, `permission_profile`, `permissions` или `permission_mode`. |
| `/acp timeout <seconds>` | канонический параметр `timeoutSeconds` | OpenClaw отправляет эквивалент, объявленный бэкендом, если он присутствует, например `timeout` или `timeout_seconds`. |
| `/acp cwd <path>` | переопределение рабочего каталога среды выполнения | Прямое обновление. |
| `/acp set <key> <value>` | общий | `key=cwd` использует путь переопределённого рабочего каталога. |
| `/acp reset-options` | сбрасывает все переопределения среды выполнения | - |

## Обвязка acpx, настройка плагина и разрешения

Сведения о настройке обвязки acpx (псевдонимы Claude Code / Codex / Gemini CLI),
MCP-мостах plugin-tools и OpenClaw-tools, а также режимах разрешений ACP
см. в разделе [Настройка агентов ACP](https://docs2.openclaw.ai/ru/tools/acp-agents-setup.md).

## Устранение неполадок

| Симптом | Вероятная причина | Решение |
| - | - | - |
| `ACP runtime backend is not configured` | Плагин бэкенда отсутствует, отключён или заблокирован параметром `plugins.allow`. | Установите и включите плагин бэкенда; если задан этот список разрешённых плагинов, добавьте `acpx` в `plugins.allow`, затем выполните `/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 "<id>" is not allowed by policy` | Агент отсутствует в списке разрешённых. | Используйте разрешённый `agentId` или обновите `acp.allowedAgents`. |
| `/acp doctor` сообщает, что бэкенд не готов сразу после запуска | Плагин бэкенда отсутствует, отключён, заблокирован политикой разрешений/запретов либо настроенный для него исполняемый файл недоступен. | Установите или включите плагин бэкенда, повторно выполните `/acp doctor` и, если он по-прежнему неисправен, изучите ошибку установки бэкенда или политики. |
| Команда обвязки не найдена | CLI адаптера не установлен, внешний плагин отсутствует либо при первом запуске не удалось получить `npx` для адаптера, отличного от Codex. | Выполните `/acp doctor`, установите или предварительно прогрейте адаптер на хосте Gateway либо явно настройте команду агента acpx. |
| Обвязка сообщает, что модель не найдена | Идентификатор модели действителен для другого провайдера или другой обвязки, но не для этой цели ACP. | Используйте модель из списка этой обвязки, настройте модель в обвязке либо не задавайте переопределение. |
| Обвязка сообщает об ошибке аутентификации у поставщика | 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 <channel>.` | Адаптер не поддерживает привязку ACP к текущему диалогу. | Используйте `/acp spawn ... --thread ...`, где это поддерживается, настройте верхнеуровневый параметр `bindings[]` либо перейдите в поддерживаемый канал. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` используется вне контекста ветки. | Перейдите в целевую ветку или используйте `--thread auto`/`off`. |
| `Only <user-id> can rebind this channel/conversation/thread.` | Цель активной привязки принадлежит другому пользователю. | Выполните повторную привязку от имени владельца либо используйте другой диалог или ветку. |
| `Thread bindings are unavailable for <channel>.` | Адаптер не поддерживает привязку веток. | Используйте `--thread off` либо перейдите на поддерживаемый адаптер или канал. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | Среда выполнения ACP работает на стороне хоста, а сеанс отправителя изолирован в песочнице. | Используйте `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` | Целевая обвязка не предоставляет универсальное переключение моделей ACP. | Используйте обвязку, объявляющую ACP `models`/`session/set_model`, ссылки на модели Codex ACP либо настройте модель непосредственно в обвязке, если у неё есть собственный флаг запуска. |
| Отсутствуют метаданные ACP для привязанного сеанса | Метаданные сеанса ACP устарели или удалены. | Создайте сеанс заново с помощью `/acp spawn`, затем повторно привяжите ветку или переведите на неё фокус. |
| `PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокирует запись и выполнение команд в неинтерактивном сеансе ACP. | Задайте для `plugins.entries.acpx.config.permissionMode` значение `approve-all` и перезапустите Gateway. См. [Настройка разрешений](https://docs2.openclaw.ai/ru/tools/acp-agents-setup.md#permission-configuration). |
| Сеанс ACP завершается с ошибкой на раннем этапе и почти ничего не выводит | Запросы разрешений блокируются параметрами `permissionMode`/`nonInteractivePermissions`. | Проверьте журналы Gateway на наличие `AcpRuntimeError`. Для полного набора разрешений задайте `permissionMode=approve-all`; для корректной работы с ограниченными возможностями задайте `nonInteractivePermissions=deny`. |
| Сеанс ACP зависает на неопределённое время после завершения работы | Процесс обвязки завершился, но сеанс ACP не сообщил о завершении. | Обновите OpenClaw; текущая очистка acpx при закрытии и запуске Gateway завершает устаревшие процессы оболочки и адаптера, принадлежащие OpenClaw. |
| Обвязка получает `<<<BEGIN_OPENCLAW_INTERNAL_CONTEXT>>>` | Внутренняя оболочка события вышла за границу ACP. | Обновите OpenClaw и повторно запустите процесс завершения; внешние обвязки должны получать только обычные запросы завершения. |

> [!NOTE]
>
> `Command blocked by PreToolUse hook: Native hook relay unavailable` относится к
> нативной ретрансляции хуков Codex, а не к ACP/acpx. В привязанном чате Codex запустите
> новый сеанс с помощью `/new` или `/reset`; если это срабатывает один раз, а затем ошибка возвращается при
> следующем вызове нативного инструмента, перезапустите сервер приложения Codex или Gateway OpenClaw
> вместо повторного выполнения `/new`. См.
> [Устранение неполадок обвязки Codex](https://docs2.openclaw.ai/ru/plugins/codex-harness.md#troubleshooting).

## Связанные материалы

* [Агенты ACP — настройка](https://docs2.openclaw.ai/ru/tools/acp-agents-setup.md)
* [Отправка агенту](https://docs2.openclaw.ai/ru/tools/agent-send.md)
* [Бэкенды CLI](https://docs2.openclaw.ai/ru/gateway/cli-backends.md)
* [Среда Codex](https://docs2.openclaw.ai/ru/plugins/codex-harness.md)
* [Среда выполнения Codex](https://docs2.openclaw.ai/ru/plugins/codex-harness-runtime.md)
* [Инструменты песочницы для нескольких агентов](https://docs2.openclaw.ai/ru/tools/multi-agent-sandbox-tools.md)
* [`openclaw acp` (режим моста)](https://docs2.openclaw.ai/ru/cli/acp)
* [Субагенты](https://docs2.openclaw.ai/ru/tools/subagents.md)