--- read_when: - Налаштування інтеграцій IDE на основі ACP - Налагодження маршрутизації сеансів ACP до Gateway summary: Запустіть міст ACP для інтеграцій з IDE title: ACP x-i18n: generated_at: "2026-07-12T13:03:27Z" model: gpt-5.6 postprocess_version: locale-links-v1 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`](/uk/cli/mcp). ## Чим це не є `openclaw acp` означає, що OpenClaw працює як сервер ACP: IDE або клієнт ACP підключається до OpenClaw, а OpenClaw пересилає цю роботу до сеансу Gateway. Це відрізняється від [агентів ACP](/uk/tools/acp-agents), де OpenClaw запускає зовнішнє середовище, як-от Codex або Claude Code, через `acpx`. Коротке правило: - редактор або клієнт має взаємодіяти з OpenClaw через ACP: використовуйте `openclaw acp` - OpenClaw має запускати Codex/Claude/Gemini як середовище ACP: використовуйте `/acp spawn` та [агенти ACP](/uk/tools/acp-agents) ## Матриця сумісності | Область ACP | Стан | Примітки | | --------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `initialize`, `newSession`, `prompt`, `cancel` | Реалізовано | Основний потік моста через stdio до операцій чату, надсилання та переривання Gateway. | | `listSessions`, команди з косою рискою | Реалізовано | Список сеансів працює зі станом сеансів Gateway із обмеженою сторінковою навігацією за курсором і фільтруванням за `cwd`, якщо рядки сеансів Gateway містять метадані робочого простору; команди оголошуються через `available_commands_update`. | | Метадані походження сеансів | Реалізовано | Списки сеансів і знімки відомостей про сеанси містять у `_meta` дані OpenClaw про батьківські й дочірні зв’язки, щоб клієнти 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` у межах активного `cwd`, а також інструменти пошуку лише для читання (`search`, `web_search`, `memory_search`). Невідомі або неосновні інструменти, читання поза дозволеною областю, інструменти з можливістю виконання команд, інструменти площини керування, інструменти, що змінюють дані, та інтерактивні потоки завжди потребують явного схвалення запиту. - Надане сервером значення `toolCall.kind` вважається недовіреними метаданими, а не джерелом авторизації. - Ця політика моста ACP відокремлена від дозволів середовища ACPX. Якщо ви запускаєте OpenClaw через бекенд `acpx`, `plugins.entries.acpx.config.permissionMode=approve-all` є аварійним перемикачем режиму «без обмежень» для цього сеансу середовища. ## Базове тестування протоколу Для налагодження на рівні протоколу запустіть 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`, увімкніть MCP-мости ACPX на боці Gateway замість спроб передати `mcpServers` для окремого сеансу. Див. [Агенти ACP](/uk/tools/acp-agents-setup#plugin-tools-mcp-bridge) і [MCP-міст інструментів OpenClaw](/uk/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 # One-shot request into your default OpenClaw ACP session acpx openclaw exec "Summarize the active OpenClaw session state." # Persistent named session for follow-up turns acpx openclaw sessions ensure --name codex-bridge acpx openclaw -s codex-bridge --cwd /path/to/repo \ "Ask my OpenClaw work agent for recent context relevant to this repo." ``` Якщо потрібно, щоб `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