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

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

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

• 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 # Віддалений Gatewayopenclaw 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 # Спрямування запущеного моста до віддаленого Gatewayopenclaw 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.

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

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

openclaw config set gateway.remote.url wss://gateway-host:18789openclaw 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:mainopenclaw acp --session agent:design:mainopenclaw 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.

Типова послідовність:

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

Приклади:

# One-shot request into your default OpenClaw ACP sessionacpx openclaw exec "Summarize the active OpenClaw session state." # Persistent named session for follow-up turnsacpx openclaw sessions ensure --name codex-bridgeacpx 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
• Агенти ACP