Вопрос

ACP-агенты в OpenClaw: как подключить Claude Code или Codex как воркер

Через протокол ACP OpenClaw запускает внешние кодовые агенты как отдельные сессии. Поставите acpx, проверите связку на одной задаче.

· 4 мин чтения

Коротко

  • ACP — путь к внешним обвязкам вроде Claude Code, Codex, Cursor, Droid, Gemini CLI. Нативный Codex-маршрут через /codex ... живёт отдельно.
  • Ставите плагин @openclaw/acpx, выбираете псевдоним (claude, codex и другие) и спавните сессию через /acp spawn ... или sessions_spawn({ runtime: "acp" }).
  • Контекст и ответы ходят через отдельную сессию agent:<agentId>:acp:<uuid>. Привязать её к чату можно флагом --bind here.
  • ACP-сессия и обычный чат это разные контексты. Без --bind here или bindings[] follow-up чата в ACP-сессию не попадёт.

Сверено с документацией OpenClaw 2026.10.4, 17 октября 2026.

Внешний кодовый агент в OpenClaw запускается как отдельная ACP-сессия (Agent Client Protocol) с собственным ключом и жизненным циклом. Нативный запуск Codex через /codex ... ведёт плагин codex отдельно от ACP. Если нужен именно Claude Code или явно Codex через ACP-плагин, читайте профиль ACP и проверьте связку на одной задаче.

Чем ACP отличается от субагентов

Субагент — это встроенный запуск OpenClaw, команда /subagents ... и сессия agent:<agentId>:subagent:<uuid>. ACP-сессию крутит внешняя обвязка через плагин @openclaw/acpx. Ключ сессии у ACP формата agent:<agentId>:acp:<uuid>. Рантайм у обоих свой, и OpenClaw не претендует на принудительное соблюдение своих опциональных ограничений внутри ACP-агента.

Установка acpx и выбор воркера

Нужны плагин @openclaw/acpx и CLI самой обвязки (Claude Code, Codex CLI и т. д.) на хосте Gateway, залогиненный под тем же пользователем ОС, под которым работает Gateway. Плагин ставится и включается так, а /acp doctor в чате проверяет готовность:

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

Каталог ACP-обвязок шире: claude, codex, copilot, cursor, droid, fast-agent, gemini, grok-build, iflow, kilocode, kimi, kiro, mcode, mux, opencode, openclaw, pi, pool, qoder, qwen, trae, zeroclaw. Если ваш локальный Cursor всё ещё выдаёт ACP как agent acp, переопределите команду в конфиге acpx.

Запуск и привязка к чату

Из чата сессию поднимает /acp spawn с флагом --bind here, ответы внешнего воркера падают в ту же беседу. Через инструмент — это sessions_spawn с runtime: "acp". В обоих случаях OpenClaw управляет только сессией и её отменой, дальше работает выбранная обвязка.

/acp spawn claude --bind here
/acp spawn codex --bind here --cwd /workspace/repo

Права, песочница и подтверждения

Если внешний агент выбран не как ACP-воркер, а как рантайм обычного чата (через список моделей), и он не может обеспечить опциональные настройки OpenClaw (инструменты, песочницу, границы рабочей папки), Control UI предложит администратору пункт Continue for this chat. Подтверждение переключает чат на полный доступ, отключает опциональную песочницу и фиксирует его именно под этот рантайм. Другие чаты и глобальные настройки остаются прежними.

Подтверждение можно не давать, тогда сообщение просто не уходит. Обязательные песочницы, обязательные границы папок и несовместимое удалённое размещение снять этим согласием нельзя. Ограниченный пользователь должен либо выбрать совместимый рантайм, либо попросить администратора.

Как проверить связку на одной задаче

  1. Откройте чат и спавните воркера с привязкой, затем отправьте обычное сообщение в той же беседе.
  2. Проверьте, что follow-up попал в ту же ACP-сессию.
  3. Если что-то не так, запустите /acp doctor и сверьтесь с разделом Troubleshooting в docs (tools/acp-agents/troubleshooting).

Где рвётся передача контекста и когда ACP-воркер не нужен

ACP-сессия и обычный чат это разные контексты. Связать их можно только явно через --bind here или настроенную bindings[]. Если воркер должен видеть ленту канала, настройте долговременную bindings[]-привязку.

ACP не нужен, если вам нужен простой текстовый провайдер вместо модели — это роль CLI Backends. Там нет ни инструментов OpenClaw, ни рантайма обвязки. Для Codex внутри OpenClaw чаще проще встроенный /codex ... и плагин codex. ACP оправдан, когда нужны /acp spawn, привязываемые сессии, возобновление и постоянная работа внешней обвязки.

Частые ошибки

  • Путают нативный Codex-маршрут (/codex ...) и ACP-маршрут (/acp spawn codex). Для большинства задач внутри OpenClaw проще нативный, ACP это отдельный путь.
  • Ставят плагин @openclaw/acpx, но не ставят саму CLI обвязки или не логинятся под пользователем Gateway. Проверьте /acp doctor — он покажет, какой бэкенд не готов.
  • Ждут, что ACP унаследует опциональные запреты OpenClaw на инструменты и папки. Если вы выбрали внешнего агента рантаймом чата, подтверждение «Continue for this chat» включает Full access, и дальше агент работает со своими правами на хосте Gateway.
  • Спавнят воркера без --bind here, а потом удивляются, что follow-up обычного чата не попадает в ACP-сессию.
  • Пытаются жёстко задать модель через OpenClaw. Без поддержки session/set_model или session/set_config_option со стороны обвязки выбор модели из OpenClaw не сработает.