ACP

Запустіть міст Agent Client Protocol (ACP), який взаємодіє з OpenClaw Gateway. openclaw acp використовує ACP через stdio для IDE та пересилає запити до Gateway через WebSocket, зіставляючи сеанси ACP із ключами сеансів Gateway. Це міст ACP на основі Gateway, а не повноцінне нативне середовище виконання редактора ACP: він зосереджений на маршрутизації сеансів, доставленні запитів і потоковому передаванні оновлень. Якщо потрібно, щоб зовнішній клієнт MCP безпосередньо взаємодіяв із розмовами в каналах OpenClaw, а не розміщував сеанс середовища ACP, натомість використовуйте openclaw mcp serve.

Чим це не є

openclaw acp означає, що OpenClaw працює як сервер ACP: IDE або клієнт ACP підключається до OpenClaw, а OpenClaw пересилає цю роботу до сеансу Gateway. Це відрізняється від агентів ACP, де OpenClaw запускає зовнішнє середовище, як-от Codex або Claude Code, через acpx. Коротке правило:

редактор або клієнт має взаємодіяти з OpenClaw через ACP: використовуйте openclaw acp
OpenClaw має запускати Codex/Claude/Gemini як середовище ACP: використовуйте /acp spawn та агенти ACP

Матриця сумісності

Область 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:<uuid>.
Стани зупинки Gateway перетворюються на причини зупинки ACP, але це зіставлення менш виразне, ніж у повністю нативному середовищі виконання ACP.
Елементи керування сеансом надають цільову підмножину параметрів Gateway: рівень обдумування, докладність інструментів, міркування, деталізацію використання та привілейовані дії. Вибір моделі й керування середовищем виконання команд не надаються як параметри конфігурації ACP.
session_info_update та usage_update формуються зі знімків сеансів Gateway, а не з оперативного обліку нативного середовища ACP. Дані про використання приблизні, не містять відомостей про вартість і надсилаються лише тоді, коли Gateway позначає загальні дані про токени як актуальні.
Супровідні дані інструментів надаються за можливості: міст показує шляхи до файлів, які трапляються у відомих аргументах або результатах інструментів, але не надає термінали ACP чи структуровані різниці файлів.
Передавання запитів на схвалення виконання обмежене активним зверненням ACP; схвалення з інших сеансів Gateway ігноруються.

Використання

openclaw acp

# Віддалений Gateway
openclaw acp --url wss://gateway-host:18789 --token <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 і дає змогу вводити запити в інтерактивному режимі.

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:

{
  "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.

Переконайтеся, що Gateway працює локально або віддалено.
Налаштуйте цільовий Gateway за допомогою конфігурації або прапорців.
Налаштуйте IDE на запуск openclaw acp через stdio.

Приклад збереженої конфігурації:

openclaw config set gateway.remote.url wss://gateway-host:18789
openclaw config set gateway.remote.token <token>

Приклад безпосереднього запуску без запису конфігурації:

openclaw acp --url wss://gateway-host:18789 --token <token>
# рекомендовано для безпеки локального процесу
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

Вибір агентів

ACP не вибирає агентів безпосередньо. Він маршрутизує запити за ключем сеансу Gateway. Використовуйте ключі сеансів із областю агента, щоб вибрати конкретного агента:

openclaw acp --session agent:main:main
openclaw acp --session agent:design:main
openclaw acp --session agent:qa:bug-123

Кожен сеанс ACP зіставляється з одним ключем сеансу Gateway. Один агент може мати багато сеансів; типово ACP використовує ізольований сеанс acp-bridge:<uuid>, якщо ви не перевизначите ключ або мітку. mcpServers для окремих сеансів не підтримуються в режимі мосту. Якщо клієнт ACP надсилає їх під час newSession або loadSession, міст повертає чітке повідомлення про помилку, а не мовчки ігнорує їх. Якщо потрібно, щоб сеанси на базі ACPX бачили інструменти плагінів OpenClaw або вибрані вбудовані інструменти, як-от cron, увімкніть MCP-мости ACPX на боці Gateway замість спроб передати mcpServers для окремого сеансу. Див. Агенти ACP і MCP-міст інструментів OpenClaw.

Використання з `acpx` (Codex, Claude та інші клієнти ACP)

Якщо потрібно, щоб агент програмування, як-от Codex або Claude Code, взаємодіяв із вашим ботом OpenClaw через ACP, використовуйте acpx із вбудованою ціллю openclaw. Типова послідовність:

Запустіть Gateway і переконайтеся, що міст ACP може підключитися до нього.
Спрямуйте acpx openclaw на openclaw acp.
Укажіть ключ сеансу OpenClaw, який має використовувати агент програмування.

Приклади:

# 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:

{
  "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 залишався чистим:

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):

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

Щоб указати певний Gateway або агента:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url",
        "wss://gateway-host:18789",
        "--token",
        "<token>",
        "--session",
        "agent:design:main"
      ],
      "env": {}
    }
  }
}

У Zed відкрийте панель Agent і виберіть “OpenClaw ACP”, щоб розпочати гілку розмови.

Зіставлення сеансів

За замовчуванням сеанси мосту ACP отримують ізольований ключ сеансу Gateway із префіксом acp-bridge:. Ці синтетичні й тимчасові сеанси мосту зі звичайною моделлю підлягають очищенню застарілих записів і не вважаються захищеними поверхнями розмов із людьми. Щоб повторно використати відомий сеанс, передайте ключ або мітку сеансу:

--session <key>: використовувати певний ключ сеансу Gateway.
--session-label <label>: знайти наявний сеанс за міткою.
--reset-session: створити новий ідентифікатор сеансу для цього ключа (той самий ключ, нова стенограма).

Якщо ваш клієнт ACP підтримує метадані, їх можна перевизначити для окремого сеансу:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

Докладніше про ключі сеансів див. на сторінці /concepts/session.

Параметри

--url <url>: URL WebSocket для Gateway (типово використовується gateway.remote.url, якщо його налаштовано).
--token <token>: токен автентифікації Gateway.
--token-file <path>: зчитати токен автентифікації Gateway із файлу.
--password <password>: пароль автентифікації Gateway.
--password-file <path>: зчитати пароль автентифікації Gateway із файлу.
--session <key>: стандартний ключ сеансу.
--session-label <label>: стандартна мітка для пошуку сеансу.
--require-existing: завершити роботу з помилкою, якщо ключ або мітка сеансу не існує.
--reset-session: скинути ключ сеансу перед першим використанням.
--no-prefix-cwd: не додавати робочий каталог як префікс до запитів.
--provenance <off|meta|meta+receipt>: додавати метадані походження ACP або квитанції.
--verbose, -v: докладне журналювання до stderr.

Примітка щодо безпеки:

--token і --password у деяких системах можуть бути видимими в локальних списках процесів. Надавайте перевагу --token-file/--password-file або змінним середовища (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
Визначення даних автентифікації Gateway відповідає спільному контракту, який використовують інші клієнти Gateway:
- локальний режим: спочатку змінні середовища (OPENCLAW_GATEWAY_*), потім gateway.auth.*; повернення до gateway.remote.* відбувається лише тоді, коли gateway.auth.* не задано (налаштований, але невизначений локальний SecretRef призводить до безпечної відмови замість мовчазного повернення до запасного варіанта)
- віддалений режим: gateway.remote.* із поверненням до змінних середовища або конфігурації відповідно до правил пріоритету віддаленого режиму
- перевизначення через --url є безпечним і не використовує неявні облікові дані з конфігурації або змінних середовища; явно передайте --token/--password (або варіанти з файлами)

Параметри `acp client`

--cwd <dir>: робочий каталог для сеансу ACP.
--server <command>: команда сервера ACP (типово: openclaw).
--server-args <args...>: додаткові аргументи, що передаються серверу ACP.
--server-verbose: увімкнути докладне журналювання на сервері ACP.
--verbose, -v: докладне журналювання клієнта.
openclaw acp client задає OPENCLAW_SHELL=acp-client для породженого процесу мосту, що можна використовувати для контекстно-залежних правил оболонки або профілю.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Чим це не є

Матриця сумісності

Відомі обмеження

Використання

Клієнт ACP (налагодження)

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

Як це використовувати

Вибір агентів

Використання з `acpx` (Codex, Claude та інші клієнти ACP)

Налаштування редактора Zed

Зіставлення сеансів

Параметри

Параметри `acp client`

Пов’язані матеріали

​Чим це не є

​Матриця сумісності

​Відомі обмеження

​Використання

​Клієнт ACP (налагодження)

​Базове тестування протоколу

​Як це використовувати

​Вибір агентів

​Використання з acpx (Codex, Claude та інші клієнти ACP)

​Налаштування редактора Zed

​Зіставлення сеансів

​Параметри

​Параметри acp client

​Пов’язані матеріали

Чим це не є

Матриця сумісності

Відомі обмеження

Використання

Клієнт ACP (налагодження)

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

Як це використовувати

Вибір агентів

Використання з `acpx` (Codex, Claude та інші клієнти ACP)

Налаштування редактора Zed

Зіставлення сеансів

Параметри

Параметри `acp client`

Пов’язані матеріали