Агенты ACP — настройка

Обзор, руководство оператора и основные понятия см. в разделе Агенты ACP. На этой странице описаны конфигурация среды acpx, настройка плагина для мостов MCP и настройка разрешений. Используйте эту страницу только при настройке маршрута ACP/acpx. Для настройки среды выполнения нативного app-server Codex используйте раздел Среда Codex. Для настройки ключей OpenAI API или поставщика моделей Codex OAuth используйте раздел OpenAI. У Codex есть два маршрута OpenClaw:

Маршрут	Конфигурация/команда	Страница настройки
Нативный app-server Codex	Ссылки на агенты `/codex ...`, `openai/gpt-*`	Среда Codex
Явный адаптер Codex ACP	`/acp spawn codex`, `runtime: "acp", agentId: "codex"`	Эта страница

Отдавайте предпочтение нативному маршруту, если вам явно не требуется поведение ACP/acpx.

Поддержка среды acpx (текущая)

Встроенные псевдонимы среды acpx (из закреплённой зависимости acpx):

Псевдоним	Оборачивает
`claude`	Claude Code
`codex`	Codex CLI
`copilot`	GitHub Copilot CLI
`cursor`	Cursor CLI (`cursor-agent acp`)
`droid`	Factory Droid
`fast-agent`	fast-agent
`gemini`	Gemini CLI
`iflow`	iFlow CLI
`kilocode`	Kilocode
`kimi`	Kimi CLI
`kiro`	Kiro CLI
`mux`	Mux
`opencode`	OpenCode
`openclaw`	Мост OpenClaw ACP (нативный `openclaw acp`)
`pi`	Агент программирования Pi
`qoder`	Qoder CLI
`qwen`	Qwen Code
`trae`	Trae CLI

factory-droid и factorydroid также разрешаются во встроенный адаптер droid. Когда OpenClaw использует бэкенд acpx, отдавайте предпочтение этим значениям для agentId, если в вашей конфигурации acpx не определены пользовательские псевдонимы агентов. Если локальная установка Cursor по-прежнему предоставляет ACP как agent acp, переопределите команду агента cursor в конфигурации acpx вместо изменения встроенного значения по умолчанию. При прямом использовании CLI acpx можно также обращаться к произвольным адаптерам через --agent <command>, но этот низкоуровневый обходной механизм является функцией CLI acpx (а не обычным маршрутом OpenClaw agentId). Управление моделью зависит от возможностей адаптера. Ссылки на модели Codex ACP нормализуются OpenClaw перед запуском. Другим средам необходимы поддержка ACP models и session/set_model; если среда не предоставляет ни эту возможность ACP, ни собственный флаг модели при запуске, OpenClaw/acpx не может принудительно выбрать модель.

Обязательная конфигурация

Базовая конфигурация ядра ACP:

{
  acp: {
    enabled: true,
    // Необязательно. По умолчанию true; установите false, чтобы приостановить диспетчеризацию ACP, сохранив элементы управления /acp.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      // Значения по умолчанию: coalesceIdleMs: 350, maxChunkChars: 1800; здесь они указаны явно.
      coalesceIdleMs: 350,
      maxChunkChars: 1800,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Конфигурация привязки к веткам зависит от адаптера канала. Пример для Discord:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        // По умолчанию уже true; здесь указано явно.
        spawnSessions: true,
      },
    },
  },
}

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

Discord: channels.discord.threadBindings.spawnSessions=true

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

Настройка плагина для бэкенда acpx

Пакетные установки используют официальный плагин среды выполнения @openclaw/acpx для ACP. Установите и включите его перед использованием сеансов среды ACP:

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

В исходных рабочих копиях после pnpm install также можно использовать локальный плагин рабочего пространства. Начните с:

/acp doctor

Если вы отключили acpx, запретили его через plugins.allow / plugins.deny или хотите вернуться к пакетному плагину, используйте явный путь пакета:

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

Установка локального рабочего пространства во время разработки:

openclaw plugins install ./path/to/local/acpx-plugin

Затем проверьте работоспособность бэкенда:

/acp doctor

Проверка запуска среды выполнения acpx

Плагин acpx напрямую встраивает среду выполнения ACP (нет отдельного двоичного файла или версии acpx, которые нужно настраивать). По умолчанию он регистрирует встроенный бэкенд во время запуска Gateway и ожидает проверку запуска до сигнала gateway ready. Устанавливайте OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=0 или OPENCLAW_SKIP_ACPX_RUNTIME_PROBE=1 только для скриптов или сред, в которых проверка запуска намеренно отключена. Выполните /acp doctor для явной проверки по запросу. Переопределяйте команду отдельного агента ACP с помощью структурированных аргументов, если путь или значение флага должны оставаться одним токеном argv:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "agents": {
            "claude": {
              "command": "node",
              "args": ["/path/to/custom adapter.mjs", "--verbose"]
            }
          }
        }
      }
    }
  }
}

agents.<id>.command — исполняемый файл или существующая строка команды для этого агента ACP.
agents.<id>.args — необязательный параметр. Каждый элемент массива заключается в кавычки оболочки, прежде чем OpenClaw передаст его через текущий реестр строк команд acpx.

См. Плагины.

Автоматическая загрузка адаптера

acpx автоматически загружает адаптеры ACP (например, мосты Claude и Codex ACP) через npx при первом использовании. Устанавливать пакеты адаптеров вручную не требуется, и для самого OpenClaw нет отдельного шага после установки. Если загрузка или запуск адаптера завершается ошибкой, /acp doctor сообщает об этом.

Мост MCP для инструментов плагинов

По умолчанию сеансы ACPX не предоставляют зарегистрированные плагинами OpenClaw инструменты среде ACP. Если требуется, чтобы агенты ACP, например Codex или Claude Code, могли вызывать инструменты установленных плагинов OpenClaw, такие как извлечение или сохранение данных в памяти, включите выделенный мост:

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

Что он делает:

Внедряет встроенный сервер MCP с именем openclaw-plugin-tools при инициализации сеанса ACPX.
Предоставляет инструменты плагинов, уже зарегистрированные установленными и включёнными плагинами OpenClaw.
Передаёт активный идентификатор сеанса ACP фабрикам инструментов плагинов, чтобы инструменты уровня агента оставались в пространстве имён этого агента.
Оставляет функцию явно включаемой и по умолчанию отключённой.

Примечания о безопасности и доверии:

Это расширяет набор инструментов среды ACP.
Агенты ACP получают доступ только к инструментам плагинов, уже активным в Gateway.
Считайте это той же границей доверия, что и разрешение этим плагинам выполняться в самом OpenClaw.
Перед включением проверьте установленные плагины.

Пользовательские mcpServers продолжают работать как прежде. Встроенный мост инструментов плагинов — это дополнительная удобная возможность, включаемая по желанию, а не замена общей конфигурации сервера MCP.

Мост MCP для инструментов OpenClaw

По умолчанию сеансы ACPX также не предоставляют встроенные инструменты OpenClaw через MCP. Включите отдельный мост инструментов ядра, если агенту ACP требуются выбранные встроенные инструменты, например cron:

openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true

Что он делает:

Внедряет встроенный сервер MCP с именем openclaw-tools при инициализации сеанса ACPX.
Предоставляет выбранные встроенные инструменты OpenClaw. Первоначальная версия сервера предоставляет cron.
Оставляет предоставление инструментов ядра явно включаемым и по умолчанию отключённым.

Настройка тайм-аута операций среды выполнения

Плагин acpx по умолчанию предоставляет встроенной среде выполнения 120 секунд на запуск и операции управления. Это даёт более медленным средам, таким как Gemini CLI, достаточно времени для завершения запуска и инициализации ACP. Переопределите это значение, если узлу требуется другой предел времени выполнения операции:

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

Рабочие циклы среды выполнения используют тайм-ауты агентов и запусков OpenClaw, включая /acp timeout. sessions_spawn не принимает переопределения тайм-аута для отдельных вызовов; для оператора предназначен путь agents.defaults.subagents.runTimeoutSeconds. Перезапустите Gateway после изменения timeoutSeconds.

Настройка агента проверки работоспособности

Когда /acp doctor или проверка запуска проверяет бэкенд, входящий в комплект плагин acpx проверяет один агент среды. Если задано acp.allowedAgents, по умолчанию используется первый разрешённый агент; в противном случае по умолчанию используется codex. Если для проверок работоспособности в развёртывании необходим другой агент ACP, укажите агента проверки явно:

openclaw config set plugins.entries.acpx.config.probeAgent claude

Перезапустите Gateway после изменения этого значения.

Настройка разрешений

Сеансы ACP выполняются неинтерактивно — TTY для подтверждения или отклонения запросов разрешений на запись файлов и выполнение команд оболочки отсутствует. Плагин acpx предоставляет два ключа конфигурации, управляющих обработкой разрешений: Эти разрешения среды ACPX не связаны с подтверждениями выполнения в OpenClaw и флагами обхода ограничений поставщика для бэкендов CLI, такими как Claude CLI --permission-mode bypassPermissions. Параметр ACPX approve-all — это аварийный переключатель на уровне среды для сеансов ACP. Более подробное сравнение tools.exec.mode в OpenClaw, подтверждений Codex Guardian и разрешений среды ACPX см. в разделе Режимы разрешений.

`permissionMode`

Управляет тем, какие операции агент среды может выполнять без запроса подтверждения.

Значение	Поведение
`approve-all`	Автоматически разрешать любую запись файлов и все команды оболочки.
`approve-reads`	Автоматически разрешать только чтение; запись и выполнение требуют подтверждения.
`deny-all`	Отклонять все запросы разрешений.

`nonInteractivePermissions`

Управляет поведением в ситуации, когда должен отображаться запрос разрешения, но интерактивный TTY недоступен (что всегда справедливо для сеансов ACP).

Значение	Поведение
`fail`	Прервать сеанс с ошибкой `PermissionPromptUnavailableError`. (по умолчанию)
`deny`	Без уведомления отклонить разрешение и продолжить работу (плавная деградация).

Конфигурация

Задайте через конфигурацию плагина:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

После изменения этих значений перезапустите Gateway.

В OpenClaw по умолчанию используются permissionMode=approve-reads и nonInteractivePermissions=fail. В неинтерактивных сеансах ACP любая запись или выполнение, вызывающие запрос разрешения, могут завершиться ошибкой PermissionPromptUnavailableError: Permission prompt unavailable in non-interactive mode.Если требуется ограничить разрешения, установите для nonInteractivePermissions значение deny, чтобы сеансы переходили в режим плавной деградации, а не аварийно завершались.

См. также

Агенты ACP — обзор, руководство оператора, основные понятия
Субагенты
Маршрутизация между несколькими агентами

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Агенты ACP — настройка

Поддержка среды acpx (текущая)

Обязательная конфигурация

Настройка плагина для бэкенда acpx

Проверка запуска среды выполнения acpx

Автоматическая загрузка адаптера

Мост MCP для инструментов плагинов

Мост MCP для инструментов OpenClaw

Настройка тайм-аута операций среды выполнения

Настройка агента проверки работоспособности

Настройка разрешений

`permissionMode`

`nonInteractivePermissions`

Конфигурация

См. также

​Поддержка среды acpx (текущая)

​Обязательная конфигурация

​Настройка плагина для бэкенда acpx

​Проверка запуска среды выполнения acpx

​Автоматическая загрузка адаптера

​Мост MCP для инструментов плагинов

​Мост MCP для инструментов OpenClaw

​Настройка тайм-аута операций среды выполнения

​Настройка агента проверки работоспособности

​Настройка разрешений

​permissionMode

​nonInteractivePermissions

​Конфигурация

​См. также

Поддержка среды acpx (текущая)

Обязательная конфигурация

Настройка плагина для бэкенда acpx

Проверка запуска среды выполнения acpx

Автоматическая загрузка адаптера

Мост MCP для инструментов плагинов

Мост MCP для инструментов OpenClaw

Настройка тайм-аута операций среды выполнения

Настройка агента проверки работоспособности

Настройка разрешений

`permissionMode`

`nonInteractivePermissions`

Конфигурация

См. также