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

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

На этой странице рассматриваются конфигурация среды выполнения acpx, настройка плагина для мостов MCP и настройка разрешений.

Используйте эту страницу только при настройке маршрута ACP/acpx. Для настройки нативной среды выполнения Codex app-server используйте раздел Среда выполнения Codex. Для ключей OpenAI API или настройки поставщика моделей с Codex OAuth используйте раздел OpenAI.

У Codex есть два маршрута OpenClaw:

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

Поддержка среды выполнения acpx (текущая)

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

factory-droid и factorydroid также разрешаются во встроенный адаптер droid.

Когда OpenClaw использует серверную часть acpx, предпочитайте эти значения для agentId, если в вашей конфигурации acpx не определены пользовательские псевдонимы агентов. Если локальная установка Cursor по-прежнему предоставляет ACP как agent acp, переопределите команду агента cursor в конфигурации acpx вместо изменения встроенного значения по умолчанию.

При непосредственном использовании CLI acpx также можно обращаться к произвольным адаптерам через --agent <command>, но этот низкоуровневый обходной путь является функцией CLI acpx (а не обычным маршрутом OpenClaw agentId).

Управление моделью зависит от возможностей адаптера. OpenClaw нормализует ссылки на модели Codex ACP перед запуском. Для других сред выполнения необходимы 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

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

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

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

Начните с:

/acp doctor

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

openclaw plugins install @openclaw/acpxopenclaw 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 (например, мосты ACP для Claude и Codex) через 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 получают доступ только к инструментам плагинов, уже активным в 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.

Более подробное сравнение OpenClaw tools.exec.mode, подтверждений Codex Guardian и разрешений среды ACPX см. в разделе Режимы разрешений.

permissionMode

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

nonInteractivePermissions

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

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

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

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

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

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

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