--- read_when: - Настройка интеграций с IDE на основе ACP - Отладка маршрутизации сеансов ACP к Gateway summary: Запуск моста ACP для интеграций с IDE title: ACP x-i18n: generated_at: "2026-07-13T17:59:15Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: becdcfdd1cc62b206cc92e9b8248c79a2ff63cfc3779d8a124b9713e779ad33c source_path: cli/acp.md workflow: 16 --- Запустите мост [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), который взаимодействует с OpenClaw Gateway. `openclaw acp` использует ACP через stdio для IDE и пересылает запросы в Gateway через WebSocket, сопоставляя сеансы ACP с ключами сеансов Gateway. Это мост ACP на базе Gateway, а не полноценная среда редактора с нативной поддержкой ACP: он предназначен для маршрутизации сеансов, доставки запросов и потоковой передачи обновлений. Если вы хотите, чтобы внешний клиент MCP взаимодействовал напрямую с диалогами каналов OpenClaw, а не размещал сеанс среды ACP, используйте [`openclaw mcp serve`](/ru/cli/mcp). ## Чем это не является `openclaw acp` означает, что OpenClaw выступает в роли сервера ACP: IDE или клиент ACP подключается к OpenClaw, а OpenClaw перенаправляет работу в сеанс Gateway. Это отличается от [агентов ACP](/ru/tools/acp-agents), где OpenClaw запускает внешнюю среду, например Codex или Claude Code, через `acpx`. Краткое правило: - редактор или клиент должен взаимодействовать с OpenClaw по ACP: используйте `openclaw acp` - OpenClaw должен запускать Codex, Claude или Gemini как среду ACP: используйте `/acp spawn` и [агентов ACP](/ru/tools/acp-agents) ## Матрица совместимости | Область ACP | Статус | Примечания | | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize`, `newSession`, `prompt`, `cancel` | Реализовано | Основной поток моста через stdio к операциям чата, отправки и прерывания Gateway. | | `listSessions`, команды с косой чертой | Реализовано | Список сеансов работает с состоянием сеансов Gateway, используя ограниченную курсорную пагинацию и фильтрацию по `cwd`, когда строки сеансов Gateway содержат метаданные рабочего пространства; команды объявляются через `available_commands_update`. | | Метаданные происхождения сеанса | Реализовано | Списки сеансов и снимки сведений о сеансах содержат сведения о родительских и дочерних связях OpenClaw в `_meta`, поэтому клиенты ACP могут отображать графы субагентов без закрытых побочных каналов Gateway. | | `resumeSession`, `closeSession` | Реализовано | Возобновление повторно привязывает сеанс ACP к существующему сеансу Gateway без воспроизведения истории. Закрытие отменяет активную работу моста, завершает ожидающие запросы со статусом отмены и освобождает состояние сеанса моста. | | `loadSession` | Частично | Повторно привязывает сеанс ACP к ключу сеанса Gateway и воспроизводит историю журнала событий ACP для сеансов, созданных мостом. Для старых сеансов или сеансов без журнала используются сохранённые тексты пользователя и ассистента. | | Содержимое запроса (`text`, встроенные `resource`, изображения) | Частично | Текст и ресурсы преобразуются в ввод чата; изображения становятся вложениями Gateway. | | Режимы сеанса | Частично | `session/set_mode` поддерживается; мост предоставляет средства управления сеансом на базе Gateway для уровня размышлений, подробности вывода инструментов, рассуждений, детализации использования и действий с повышенными привилегиями. Более широкие нативные поверхности режимов и конфигурации ACP пока не входят в область поддержки. | | Потоковая передача размышлений | Реализовано | Содержимое размышлений модели передаётся потоком как обновления сеанса `agent_thought_chunk`. Нативные планы сеансов ACP не выдаются. | | Обновления сведений о сеансе и использовании | Частично | Мост отправляет уведомления `session_info_update` и, по возможности, `usage_update` из кэшированных снимков сеансов Gateway. Данные об использовании приблизительны и отправляются только тогда, когда суммарные значения токенов Gateway помечены как актуальные. | | Потоковая передача данных инструментов | Частично | События `tool_call`/`tool_call_update` содержат необработанные данные ввода-вывода, текстовое содержимое и, по возможности, расположение файлов, если оно присутствует в аргументах или результатах инструментов Gateway. Встроенные терминалы и более содержательный вывод в нативном формате различий не предоставляются. | | Подтверждения выполнения | Частично | Запросы Gateway на подтверждение выполнения во время активных циклов запросов ACP передаются клиенту ACP через `session/request_permission`. | | Серверы MCP для отдельных сеансов (`mcpServers`) | Не поддерживается | Режим моста отклоняет запросы серверов MCP для отдельных сеансов. Настройте MCP в OpenClaw Gateway или агенте. | | Методы файловой системы клиента (`fs/read_text_file`, `fs/write_text_file`) | Не поддерживается | Мост не вызывает методы файловой системы клиента ACP. | | Терминальные методы клиента (`terminal/*`) | Не поддерживается | Мост не создаёт терминалы клиента ACP и не передаёт идентификаторы терминалов через вызовы инструментов. | ## Известные ограничения - `loadSession` воспроизводит полную историю журнала событий ACP только для сеансов, созданных мостом. Для старых сеансов или сеансов без журнала используется резервная расшифровка, которая не восстанавливает исторические вызовы инструментов и системные уведомления. - Если несколько клиентов ACP используют один ключ сеанса Gateway, маршрутизация событий и отмен выполняется по возможности, а не строго изолированно для каждого клиента. Если нужны чистые локальные для редактора циклы взаимодействия, предпочитайте изолированные по умолчанию сеансы `acp-bridge:`. - Состояния остановки Gateway преобразуются в причины остановки ACP, но это сопоставление менее выразительно, чем в полностью нативной среде ACP. - Средства управления сеансом предоставляют ограниченный набор параметров Gateway: уровень размышлений, подробность вывода инструментов, рассуждения, детализацию использования и действия с повышенными привилегиями. Выбор модели и управление узлом выполнения не предоставляются как параметры конфигурации ACP. - `session_info_update` и `usage_update` формируются на основе снимков сеансов Gateway, а не данных учёта нативной среды ACP в реальном времени. Данные об использовании приблизительны, не содержат сведений о стоимости и выдаются только тогда, когда Gateway помечает общие данные о токенах как актуальные. - Сопутствующие данные инструментов предоставляются по возможности: мост показывает пути к файлам, обнаруженные в известных аргументах или результатах инструментов, но не выдаёт терминалы ACP или структурированные различия файлов. - Передача подтверждений выполнения ограничена активным циклом запроса ACP; подтверждения из других сеансов Gateway игнорируются. ## Использование ```bash openclaw acp # Удалённый Gateway openclaw acp --url wss://gateway-host:18789 --token # Удалённый Gateway (токен из файла) openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Подключение к существующему ключу сеанса openclaw acp --session agent:main:main # Подключение по метке (она уже должна существовать) openclaw acp --session-label "support inbox" # Сброс ключа сеанса перед первым запросом openclaw acp --session agent:main:main --reset-session ``` ## Клиент ACP (отладка) Используйте встроенный клиент ACP для базовой проверки моста без IDE. Он запускает мост ACP и позволяет вводить запросы в интерактивном режиме. ```bash openclaw acp client # Направление запущенного моста на удалённый Gateway openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token # Переопределение команды сервера (по умолчанию: openclaw) openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001 ``` Модель разрешений (режим отладки клиента): - Автоматическое подтверждение основано на списке разрешённых значений и применяется только к доверенным идентификаторам основных инструментов. - Автоматическое подтверждение `read` ограничено текущим рабочим каталогом (`--cwd`, если он задан). - ACP автоматически подтверждает только узкие классы операций, доступных только для чтения: ограниченные вызовы `read` в активном текущем рабочем каталоге, а также инструменты поиска только для чтения (`search`, `web_search`, `memory_search`). Неизвестные и неосновные инструменты, чтение за пределами разрешённой области, инструменты с возможностью выполнения, инструменты плоскости управления, изменяющие инструменты и интерактивные процессы всегда требуют явного подтверждения запроса. - Предоставленное сервером значение `toolCall.kind` считается недоверенными метаданными, а не источником авторизации. - Эта политика моста ACP не связана с разрешениями среды ACPX. Если вы запускаете OpenClaw через бэкенд `acpx`, параметр `plugins.entries.acpx.config.permissionMode=approve-all` служит аварийным переключателем «yolo» для этого сеанса среды. ## Дымовое тестирование протокола Для отладки на уровне протокола запустите Gateway с изолированным состоянием и управляйте `openclaw acp` через stdio с помощью клиента ACP JSON-RPC. Проверьте `initialize`, `session/new`, `session/list` с абсолютным `cwd`, `session/resume`, `session/close`, повторным закрытием и отсутствующим возобновлением. Доказательство должно включать объявленные возможности жизненного цикла, строку сеанса на базе Gateway, уведомления об обновлениях и журнал Gateway `sessions.list`: ```json { "initialize": { "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { "list": {}, "resume": {}, "close": {} } } }, "listSessions": { "sessions": [ { "sessionId": "agent:main:acp-smoke", "cwd": "/path/to/workspace", "_meta": { "sessionKey": "agent:main:acp-smoke", "kind": "direct" } } ], "nextCursor": null }, "notifications": ["session_info_update", "available_commands_update", "usage_update"], "gatewayLogTail": ["[gateway] ready", "[ws] ⇄ res ✓ sessions.list 305ms"] } ``` Не используйте `openclaw gateway call sessions.list` как единственное доказательство работы ACP. Этот путь CLI может запросить повышение области оператора для нового токена; корректность моста ACP подтверждается кадрами ACP через stdio и журналом Gateway `sessions.list`. ## Как это использовать Используйте ACP, когда IDE или другой клиент поддерживает Agent Client Protocol и должен управлять сеансом OpenClaw Gateway. 1. Убедитесь, что Gateway запущен локально или удалённо. 2. Настройте целевой Gateway с помощью конфигурации или флагов. 3. Настройте IDE для запуска `openclaw acp` через stdio. Пример постоянной конфигурации: ```bash openclaw config set gateway.remote.url wss://gateway-host:18789 openclaw config set gateway.remote.token ``` Пример прямого запуска без записи конфигурации: ```bash openclaw acp --url wss://gateway-host:18789 --token # предпочтительный вариант для безопасности локального процесса openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token ``` ## Выбор агентов ACP не выбирает агентов напрямую. Маршрутизация выполняется по ключу сессии Gateway. Чтобы обратиться к конкретному агенту, используйте ключи сессий с областью действия агента: ```bash openclaw acp --session agent:main:main openclaw acp --session agent:design:main openclaw acp --session agent:qa:bug-123 ``` Каждая сессия ACP сопоставляется с одним ключом сессии Gateway. У одного агента может быть много сессий; по умолчанию ACP использует изолированную сессию `acp-bridge:`, если вы не переопределите ключ или метку. Параметры `mcpServers` для отдельных сессий не поддерживаются в режиме моста. Если клиент ACP отправляет их во время `newSession` или `loadSession`, мост возвращает понятную ошибку, а не молча игнорирует их. Чтобы в сеансах на базе ACPX были доступны инструменты плагинов OpenClaw или выбранные встроенные инструменты, например `cron`, включите мосты ACPX MCP на стороне Gateway вместо попытки передать параметры `mcpServers` для отдельных сессий. См. [Агенты ACP](/ru/tools/acp-agents-setup#plugin-tools-mcp-bridge) и [мост MCP для инструментов OpenClaw](/ru/tools/acp-agents-setup#openclaw-tools-mcp-bridge). ## Использование из `acpx` (Codex, Claude и других клиентов ACP) Чтобы агент разработки, например Codex или Claude Code, взаимодействовал с вашим ботом OpenClaw по ACP, используйте `acpx` со встроенной целью `openclaw`. Типичный порядок действий: 1. Запустите Gateway и убедитесь, что мост ACP может к нему подключиться. 2. Направьте `acpx openclaw` на `openclaw acp`. 3. Укажите ключ сессии OpenClaw, который должен использовать агент разработки. Примеры: ```bash # Одноразовый запрос в вашу сессию ACP OpenClaw по умолчанию acpx openclaw exec "Суммируй состояние активной сессии OpenClaw." # Постоянная именованная сессия для последующих запросов acpx openclaw sessions ensure --name codex-bridge acpx openclaw -s codex-bridge --cwd /path/to/repo \ "Запроси у моего рабочего агента OpenClaw недавний контекст, относящийся к этому репозиторию." ``` Чтобы `acpx openclaw` всегда обращался к определённому Gateway и ключу сессии, переопределите команду агента `openclaw` в `~/.acpx/config.json`: ```json { "agents": { "openclaw": { "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main" } } } ``` Для локальной копии репозитория OpenClaw используйте прямую точку входа CLI вместо средства запуска для разработки, чтобы поток ACP оставался чистым: ```bash env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ... ``` Это самый простой способ позволить Codex, Claude Code или другому клиенту с поддержкой ACP получать контекстную информацию от агента OpenClaw без извлечения данных из терминала. ## Настройка редактора Zed Добавьте пользовательского агента ACP в `~/.config/zed/settings.json` (или используйте интерфейс настроек Zed): ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": ["acp"], "env": {} } } } ``` Чтобы указать определённый Gateway или агента: ```json { "agent_servers": { "OpenClaw ACP": { "type": "custom", "command": "openclaw", "args": [ "acp", "--url", "wss://gateway-host:18789", "--token", "", "--session", "agent:design:main" ], "env": {} } } } ``` В Zed откройте панель Agent и выберите "OpenClaw ACP", чтобы начать ветку обсуждения. ## Сопоставление сессий По умолчанию сессии моста ACP получают изолированный ключ сессии Gateway с префиксом `acp-bridge:`. Эти синтетические одноразовые сессии моста обычной модели подлежат удалению при очистке устаревших записей и не считаются защищёнными каналами общения с пользователями. Чтобы повторно использовать известную сессию, передайте ключ или метку сессии: - `--session `: использовать определённый ключ сессии Gateway. - `--session-label