OpenClaw ACP: как подключить Codex, Claude Code и Gemini CLI прямо в Telegram

ACP в OpenClaw — это режим, в котором задачи на разработку уходят не во встроенную модель OpenClaw, а во внешний coding harness: Codex, Claude Code, Gemini CLI, OpenCode и другие совместимые агенты.

На практике OpenClaw в этой схеме становится оркестратором: принимает запрос, поднимает и маршрутизирует сессии, управляет контекстом и возвращает результат обратно в Telegram. А основную работу по коду выполняет уже внешний агент.

Что такое ACP и зачем он нужен

Чтобы ACP работал стабильно, важно понимать, что в схеме есть два слоя:

• ACP в конфиге OpenClaw — orchestration layer: dispatch, allowed agents, streaming, TTL и session management

• acpx — backend-плагин, который реально запускает внешний harness, например Codex

Это не одна «магическая кнопка», а полноценный слой управления внешними coding-runtime'ами. Если всё настроено правильно, OpenClaw перестаёт тратить встроенные токены на задачи, которые лучше отдать специализированному агенту, а разработкой можно управлять прямо из Telegram.

Два режима работы ACP

В OpenClaw есть два основных сценария использования ACP.

1. Непривязанный ACP-сеанс

Это обычный режим, когда ACP-сессия запускается без жёсткой привязки к конкретному Telegram topic или thread.

Он подходит, если вы хотите:

• запускать разовые one-shot задачи;

• держать несколько persistent-сессий одновременно;

• переключаться между ними по label или session key;

• управлять ими вручную через ACP-команды или программно через sessions_spawn.

Такой вариант удобен, когда из одного диалога нужно вести несколько отдельных coding-сеансов и явно контролировать каждый из них.

2. Thread-bound ACP в Telegram Topics

Более продвинутый сценарий — жёсткая привязка конкретного Telegram topic к одной ACP-сессии.

Например:

• General → основной агент;

• Debug → debug-агент;

• Coding → persistent Codex / Claude Code / Gemini CLI.

В таком режиме topic превращается в постоянную рабочую комнату для coding-agent’а. Все follow-up сообщения продолжают идти в ту же ACP-сессию, поэтому не нужно каждый раз выбирать target вручную.

Что обязательно включить в конфиге

Минимальный рабочий набор выглядит так:

• acp.enabled = true

• acp.dispatch.enabled = true

• acp.backend = "acpx"

• нужный агент добавлен в acp.allowedAgents

• plugins.entries.acpx.enabled = true

Если нужен запуск без явного выбора harness, стоит также указать acp.defaultAgent.

Где настройка ломается чаще всего

Самая частая причина проблем — permissions.

Если ACP-агент запускается, но не может:

• писать файлы;

• выполнять shell-команды;

• нормально работать в проекте,

то в большинстве случаев проблема в конфиге plugins.entries.acpx.config.

Для ACP-сессий слишком строгие разрешения часто бесполезны: они идут non-interactively, поэтому недостаточные permissions быстро превращают «запущенный агент» в почти неработающий runtime.

Как проверить, что всё поднялось правильно

Базовая проверка после установки и настройки:

• openclaw plugins info acpx

• /acp doctor

Именно /acp doctor документация рекомендует как нормальный smoke test для backend health.

Важный нюанс про Telegram Topics

Если вы настраиваете thread-bound ACP-topic, важно не смешивать несколько разных уровней маршрутизации:

• agents.list[] — описывает самого агента;

• bindings[] — отвечает за привязку topic или surface к агенту;

• topics.<id>.agentId — отдельный Telegram routing layer.

Ключевая идея здесь простая: для чистой ACP-схемы обычно лучше, чтобы сама ACP-привязка жила в bindings[], а topic не перебивал её лишним agentId, если это не требуется специально.

Как читать ACP status без лишней путаницы

В ACP status есть несколько разных идентификаторов, и у каждого свой смысл:

• session — основной OpenClaw session key;

• acpx record id — persistent record ACPX;

• acpx session id — runtime/backend session id, который может меняться.

Если меняется только acpx session id, это не обязательно означает, что persistent-логика сломалась. Нередко это просто означает, что backend-процесс перезапустился или переподключился, а сама логическая привязка осталась прежней.

Почему ACP действительно полезен

Если всё настроено правильно, вы получаете удобную схему:

• OpenClaw остаётся единым интерфейсом и оркестратором;

• coding-agent работает в привычном harness runtime;

• Telegram становится удобной точкой входа в разработку;

• persistent topics позволяют разделить роли по рабочим комнатам;

• задачи на код уходят туда, где они реально должны исполняться.

Именно поэтому связка OpenClaw + ACP + Telegram Topics даёт настолько сильный сценарий для практической разработки: один topic можно выделить под кодинг, другой под дебаг, третий под обычную работу с основным агентом.

Что почитать дальше

Полная статья с разбором архитектуры, конфигов, режимов работы и логики thread-bound routing:

<https://telegra.ph/OpenClaw-ACP-nastrojka-rezhimy-raboty-i-Telegram-Topics-03-20>

Актуальная документация OpenClaw по теме:

• ACP Agents

• ACP CLI

• System Prompt

• ACP Thread-Bound Agents

Вывод

ACP в OpenClaw — это не просто «передать задачу в Codex». Это полноценный слой orchestration для внешних coding harness-runtime’ов.

Если понимать, где заканчивается routing, где начинается binding, а где живёт backend acpx, и обычные ACP-сеансы, и persistent Telegram topics настраиваются без мистики и отлаживаются намного спокойнее.