OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Агенты ACP

Сеансы Agent Client Protocol (ACP) позволяют OpenClaw запускать внешние среды для программирования (Claude Code, Cursor, Copilot, Droid, OpenClaw ACP, OpenCode, Gemini CLI и другие поддерживаемые ACPX среды) через серверный плагин 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 Режим моста: IDE/клиент взаимодействует с OpenClaw по ACP через stdio/WebSocket
Повторно использовать локальный AI CLI как резервную модель только для текста Серверные части CLI Не ACP: без инструментов OpenClaw, элементов управления ACP и среды выполнения внешней среды

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

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

bash
openclaw plugins install @openclaw/acpxopenclaw config set plugins.entries.acpx.enabled true

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

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

Особенности первого запуска
  • Если задан 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 или доступа к сети, загрузка адаптеров при первом запуске завершается с ошибкой, пока кэши не будут предварительно заполнены или адаптер не будет установлен другим способом.
Требования к среде выполнения

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

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

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

Инструменты плагинов OpenClaw и встроенные инструменты OpenClaw по умолчанию не предоставляются средам ACP. Включайте явные мосты MCP в разделе Агенты ACP — настройка, только если среда должна вызывать эти инструменты напрямую.

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

С серверной частью 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 из чата:

  • Запуск

    /acp spawn claude --bind here, /acp spawn gemini --mode persistent --thread auto или явно /acp spawn codex --bind here.

  • Работа

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

  • Проверка состояния

    /acp status

  • Настройка

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

  • Корректировка

    Без замены контекста: /acp steer tighten logging and continue.

  • Остановка

    /acp cancel (текущий ход) или /acp close (сеанс и привязки).

    • Сведения о жизненном цикле
    • Создание запускает или возобновляет сеанс среды выполнения 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.
    Правила маршрутизации нативного 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.

    Краткая памятка по выбору модели, провайдера и среды выполнения
    • устаревшие ссылки на модели Codex — устаревший маршрут модели Codex OAuth/подписки, исправляемый командой doctor.
    • openai/* — встроенная нативная среда выполнения app-server Codex для ходов агента OpenAI.
    • /codex ... — нативное управление беседой Codex.
    • /acp ... или runtime: "acp" — явное управление ACP/acpx.
    Триггеры маршрутизации 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 (стандартная среда выполнения)

    См. также Субагенты.

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

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

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

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

    Серверные части CLI — отдельные локальные резервные среды выполнения только для текста; см. Серверные части CLI.

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

    • Нужны /acp spawn, привязываемые сеансы, управление средой выполнения или постоянная работа управляющей среды? Используйте ACP.
    • Нужен простой локальный текстовый резервный вариант через необработанный CLI? Используйте серверные части CLI.

    Привязанные сеансы

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

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

    Привязки к текущей беседе

    /acp spawn <harness> --bind here закрепляет текущую беседу за созданным сеансом ACP — без дочерней ветки, в том же интерфейсе чата. OpenClaw продолжает управлять транспортом, аутентификацией, безопасностью и доставкой. Последующие сообщения в этой беседе направляются в тот же сеанс; /new и /reset сбрасывают сеанс на месте; /acp close удаляет привязку.

    Примеры:

    text
    /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
    Правила привязки и взаимоисключение
    • --bind here и --thread ... взаимоисключающие.
    • --bind here работает только в каналах, которые объявляют поддержку привязки к текущей беседе; в противном случае OpenClaw возвращает понятное сообщение об отсутствии поддержки. Привязки сохраняются после перезапуска Gateway.
    • В Discord параметр spawnSessions управляет созданием дочерних веток для --thread auto|here, но не для --bind here.
    • Если создать сеанс для другого агента ACP без --cwd, OpenClaw по умолчанию наследует рабочую область целевого агента. Отсутствующие унаследованные пути (ENOENT/ENOTDIR) заменяются стандартным значением серверной части; другие ошибки доступа (например, EACCES) возвращаются как ошибки создания.
    • Команды управления Gateway остаются локальными в привязанных беседах: команды /acp ... обрабатываются OpenClaw, даже когда обычный текст последующих сообщений направляется в привязанный сеанс ACP; /status и /unfocus также остаются локальными, когда обработка команд включена для этого интерфейса.
    Сеансы, привязанные к веткам

    Когда для адаптера канала включены привязки к веткам:

    • OpenClaw привязывает ветку к целевому сеансу ACP.
    • Последующие сообщения в этой ветке направляются в привязанный сеанс ACP.
    • Вывод ACP доставляется обратно в ту же ветку.
    • Снятие фокуса, закрытие, архивирование, тайм-аут бездействия или истечение максимального срока удаляет привязку.
    • /acp close, /acp cancel, /acp status, /status и /unfocus — команды Gateway, а не запросы к управляющей среде ACP.

    Обязательные флаги функций для ACP, привязанного к веткам:

    • acp.enabled=true
    • acp.dispatch.enabled включён по умолчанию (задайте false, чтобы приостановить автоматическую диспетчеризацию веток ACP; явные вызовы sessions_spawn({ runtime: "acp" }) продолжат работать).
    • Создание сеансов веток адаптером канала включено (по умолчанию: true):
      • Discord: channels.discord.threadBindings.spawnSessions=true
      • Telegram: channels.telegram.threadBindings.spawnSessions=true

    Поддержка привязки к веткам зависит от адаптера. Если активный адаптер канала не поддерживает привязки к веткам, OpenClaw возвращает понятное сообщение об отсутствии поддержки или доступности.

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

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

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

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

    bindings[].type"acp"

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

    bindings[].matchobject

    Определяет целевую беседу. Форматы для отдельных каналов:

    • Канал/ветка 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="&lt;E.164|group JID&gt;". Для личных чатов используйте номера в формате 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[].agentIdstring

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

    bindings[].acp.mode"persistent" | "oneshot"

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

    bindings[].acp.labelstring

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

    bindings[].acp.cwdstring

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

    bindings[].acp.backendstring

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

    Значения среды выполнения по умолчанию для каждого агента

    Используйте 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
    {  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 можно запустить двумя способами:

    Из sessions_spawn

    Используйте runtime: "acp", чтобы запустить сеанс ACP из хода агента или вызова инструмента.

    json
    {  "task": "Открой репозиторий и кратко опиши непройденные тесты",  "runtime": "acp",  "agentId": "codex",  "thread": true,  "mode": "session"}

    Из команды /acp

    Используйте /acp spawn для явного управления оператором из чата.

    text
    /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>

    См. Команды с косой чертой.

    Параметры sessions_spawn

    taskstringrequired

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

    runtime"acp"required

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

    agentIdstring

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

    threadbooleandefault: false

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

    mode"run" | "session"default: run

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

    cwdstring

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

    labelstring

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

    resumeSessionIdstring

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

    modelstring

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

    thinkingstring

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

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

    --bind here|off

    Режим Поведение
    here Привязать текущую активную беседу без её замены; завершить с ошибкой, если активной беседы нет.
    off Не создавать привязку текущей беседы.

    Примечания:

    • --bind here — самый простой путь для оператора, чтобы «подключить Codex к этому каналу или чату».
    • --bind here не создаёт дочернюю ветку.
    • --bind here доступен только в каналах, поддерживающих привязку текущей беседы.
    • --bind и --thread нельзя сочетать в одном вызове /acp spawn.

    --thread auto|here|off

    Режим Поведение
    auto В активной ветке: привязать эту ветку. Вне ветки: создать/привязать дочернюю ветку, если это поддерживается.
    here Требовать наличия текущей активной ветки; завершить с ошибкой, если её нет.
    off Без привязки. Сеанс запускается непривязанным.

    Примечания:

    • На поверхностях без поддержки привязки к веткам поведение по умолчанию фактически соответствует off.
    • Для создания сеанса с привязкой к ветке требуется поддержка в политике канала:
      • Discord: channels.discord.threadBindings.spawnSessions=true
      • Telegram: channels.telegram.threadBindings.spawnSessions=true
    • Используйте --bind here, если хотите закрепить текущую беседу без создания дочерней ветки.

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

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

    Интерактивные сеансы ACP

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

    • /acp spawn ... --bind here привязывает текущую беседу к сеансу ACP.
    • /acp spawn ... --thread ... привязывает ветку/тему канала к сеансу ACP.
    • Постоянно настроенные bindings[].type="acp" направляют совпадающие беседы в один и тот же сеанс ACP.

    Последующие сообщения в привязанной беседе направляются непосредственно в сеанс ACP, а вывод ACP доставляется обратно в тот же канал/ветку/тему.

    Что OpenClaw отправляет в среду:

    • Обычные связанные последующие сообщения отправляются как текст запроса, а вложения — только если они поддерживаются средой выполнения или бэкендом.
    • Команды управления /acp и локальные команды Gateway перехватываются до передачи в ACP.
    • События завершения, создаваемые средой выполнения, материализуются отдельно для каждой цели. Агенты OpenClaw получают внутренний конверт контекста среды выполнения OpenClaw; внешние среды выполнения ACP получают обычный запрос с результатом дочернего процесса и инструкцией. Необработанный конверт <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> никогда не должен отправляться во внешние среды выполнения или сохраняться в тексте пользовательской расшифровки ACP.
    • Записи расшифровки ACP используют видимый пользователю текст триггера или обычный запрос о завершении. Метаданные внутренних событий по возможности остаются структурированными в OpenClaw и не считаются содержимым чата, созданным пользователем.
    Одноразовые сеансы ACP, принадлежащие родителю

    Одноразовые сеансы ACP, запущенные другим выполнением агента, являются фоновыми дочерними процессами, подобными субагентам:

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

    Не рассматривайте этот путь как одноранговый чат между родителем и дочерним процессом. У дочернего процесса уже есть канал передачи результата родителю.

    sessions_send и доставка A2A

    sessions_send может обращаться к другому сеансу после запуска. Для обычных одноранговых сеансов OpenClaw использует путь последующего взаимодействия между агентами (A2A) после внедрения сообщения:

    • Дождаться ответа целевого сеанса.
    • При необходимости разрешить запрашивающей и целевой сторонам обменяться ограниченным числом последующих ходов.
    • Попросить целевую сторону сформировать сообщение-уведомление.
    • Доставить это уведомление в видимый канал или ветку.

    Этот путь A2A служит резервным вариантом для одноранговых отправок, когда отправителю требуется видимое последующее сообщение. Он остаётся включённым, когда несвязанный сеанс может видеть целевой объект ACP и отправлять ему сообщения, например при широких настройках tools.sessions.visibility.

    OpenClaw пропускает последующее взаимодействие A2A только тогда, когда запрашивающая сторона является родителем собственного одноразового дочернего процесса ACP, принадлежащего родителю. В этом случае запуск A2A поверх механизма завершения задачи может активировать родителя с результатом дочернего процесса, переслать ответ родителя обратно дочернему процессу и создать цикл эха между родителем и дочерним процессом. Результат sessions_send сообщает delivery.status="skipped" для такого принадлежащего родителю дочернего процесса, поскольку за результат уже отвечает путь завершения.

    Возобновление существующего сеанса

    Используйте resumeSessionId, чтобы продолжить предыдущий сеанс ACP вместо запуска нового. Агент воспроизводит историю диалога через session/load, поэтому продолжает работу с полным контекстом предыдущих действий.

    json
    {  "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 поддерживают).
    • Если идентификатор сеанса не найден, запуск завершается с понятной ошибкой — без неявного перехода к новому сеансу.
    Проверка работоспособности после развёртывания

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

    Текущие ограничения:

    • Если запрашивающий сеанс изолирован в песочнице, запуск 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.

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

    Симптом Вероятная причина Решение
    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. См. Настройка разрешений.
    Сеанс ACP завершается с ошибкой на раннем этапе и почти ничего не выводит Запросы разрешений блокируются параметрами permissionMode/nonInteractivePermissions. Проверьте журналы Gateway на наличие AcpRuntimeError. Для полного набора разрешений задайте permissionMode=approve-all; для корректной работы с ограниченными возможностями задайте nonInteractivePermissions=deny.
    Сеанс ACP зависает на неопределённое время после завершения работы Процесс обвязки завершился, но сеанс ACP не сообщил о завершении. Обновите OpenClaw; текущая очистка acpx при закрытии и запуске Gateway завершает устаревшие процессы оболочки и адаптера, принадлежащие OpenClaw.
    Обвязка получает <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> Внутренняя оболочка события вышла за границу ACP. Обновите OpenClaw и повторно запустите процесс завершения; внешние обвязки должны получать только обычные запросы завершения.

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

    Was this useful?
    On this page

    On this page