acp

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

Що це не є

Цю сторінку часто плутають із сеансами ACP harness. openclaw acp означає:

OpenClaw працює як ACP-сервер
IDE або ACP-клієнт підключається до OpenClaw
OpenClaw пересилає цю роботу в сеанс Gateway

Це відрізняється від ACP Agents, де OpenClaw запускає зовнішній harness, наприклад Codex або Claude Code, через acpx. Коротке правило:

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

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

Область ACP	Стан	Примітки
`initialize`, `newSession`, `prompt`, `cancel`	Реалізовано	Основний потік роботи мосту через stdio до Gateway chat/send + abort.
`listSessions`, slash-команди	Реалізовано	Список сеансів працює зі станом сеансів Gateway; команди оголошуються через `available_commands_update`.
`loadSession`	Частково	Повторно прив’язує сеанс ACP до ключа сеансу Gateway і відтворює збережену історію текстів користувача/асистента. Історія інструментів/системи поки що не відновлюється.
Вміст запиту (`text`, вбудований `resource`, зображення)	Частково	Текст/ресурси згортаються у вхідні дані чату; зображення стають вкладеннями Gateway.
Режими сеансу	Частково	Підтримується `session/set_mode`, і міст надає початкові елементи керування сеансом на основі Gateway для рівня thought, деталізації інструментів, reasoning, деталізації використання та elevated actions. Ширші нативні поверхні режимів/конфігурації ACP поки що поза межами.
Інформація про сеанс і оновлення використання	Частково	Міст надсилає сповіщення `session_info_update` і `usage_update` у режимі best-effort на основі кешованих знімків сеансів Gateway. Використання приблизне й надсилається лише тоді, коли Gateway позначає загальні підсумки токенів як актуальні.
Потокова передача інструментів	Частково	Події `tool_call` / `tool_call_update` містять необроблений ввід/вивід, текстовий вміст і дані про розташування файлів у режимі best-effort, якщо аргументи/результати інструментів Gateway їх містять. Вбудовані термінали й багатший diff-вивід поки що недоступні.
MCP-сервери для кожного сеансу (`mcpServers`)	Не підтримується	Режим моста відхиляє запити на MCP-сервери для окремих сеансів. Налаштовуйте MCP на шлюзі OpenClaw або в агенті.
Методи файлової системи клієнта (`fs/read_text_file`, `fs/write_text_file`)	Не підтримується	Міст не викликає методи файлової системи ACP-клієнта.
Методи термінала клієнта (`terminal/*`)	Не підтримується	Міст не створює термінали ACP-клієнта і не передає id терміналів через виклики інструментів у потоковому режимі.
Плани сеансу / потокова передача thought	Не підтримується	Наразі міст передає вихідний текст і стан інструментів, а не оновлення планів або thought ACP.

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

loadSession відтворює збережену текстову історію користувача й асистента, але не відновлює історичні виклики інструментів, системні сповіщення або багатші типи подій, нативні для ACP.
Якщо кілька ACP-клієнтів використовують один і той самий ключ сеансу Gateway, маршрутизація подій і скасування працює в режимі best-effort, а не зі строгою ізоляцією для кожного клієнта. Якщо вам потрібні чисті локальні для редактора ходи, віддавайте перевагу типовим ізольованим сеансам acp:<uuid>.
Стани зупинки Gateway перетворюються на причини зупинки ACP, але таке зіставлення менш виразне, ніж у повністю нативному середовищі ACP.
Початкові елементи керування сеансом наразі охоплюють лише вибраний набір параметрів Gateway: рівень thought, деталізацію інструментів, reasoning, деталізацію використання та elevated actions. Вибір моделі й параметри exec-host поки що не доступні як опції конфігурації ACP.
session_info_update і usage_update виводяться зі знімків сеансів Gateway, а не з живого нативного обліку середовища ACP. Дані використання приблизні, не містять відомостей про вартість і надсилаються лише тоді, коли Gateway позначає загальні дані про токени як актуальні.
Дані супроводу інструментів працюють у режимі best-effort. Міст може показувати шляхи до файлів, що з’являються у відомих аргументах/результатах інструментів, але поки що не передає ACP-термінали або структуровані file diff.

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

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

Модель дозволів (режим налагодження клієнта):

Автопогодження базується на allowlist і застосовується лише до довірених id основних інструментів.
Автопогодження read обмежене поточним робочим каталогом (--cwd, якщо вказано).
ACP автоматично погоджує лише вузькі класи операцій лише для читання: обмежені виклики read у межах активного cwd і інструменти пошуку лише для читання (search, web_search, memory_search). Невідомі/неосновні інструменти, читання поза межами області, інструменти з можливістю виконання, інструменти control plane, інструменти зі змінами стану та інтерактивні потоки завжди потребують явного погодження через запит.
Наданий сервером toolCall.kind вважається недовіреними метаданими, а не джерелом авторизації.
Ця політика моста ACP окрема від дозволів ACPX harness. Якщо ви запускаєте OpenClaw через бекенд acpx, то plugins.entries.acpx.config.permissionMode=approve-all є аварійним перемикачем “yolo” для цього сеансу harness.

Як цим користуватися

Використовуйте ACP, коли IDE (або інший клієнт) підтримує Agent Client Protocol і ви хочете, щоб він керував сеансом Gateway OpenClaw.

Переконайтеся, що 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:<uuid>, якщо ви не перевизначите ключ або мітку. mcpServers для окремих сеансів не підтримуються в режимі моста. Якщо ACP-клієнт надсилає їх під час newSession або loadSession, міст повертає зрозумілу помилку замість того, щоб мовчки їх ігнорувати. Якщо ви хочете, щоб сеанси з підтримкою ACPX бачили інструменти Plugin OpenClaw або вибрані вбудовані інструменти, такі як cron, увімкніть MCP-мости ACPX на боці Gateway замість спроби передавати mcpServers для окремих сеансів. Див. ACP Agents і міст MCP інструментів OpenClaw.

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

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

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

Приклади:

# Одноразовий запит до вашого типового ACP-сеансу OpenClaw
acpx openclaw exec "Summarize the active OpenClaw session state."

# Постійний іменований сеанс для подальших ходів
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"
    }
  }
}

Для локальної checkout-копії OpenClaw використовуйте прямий вхід до CLI замість dev runner, щоб потік 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:. Щоб повторно використати відомий сеанс, передайте ключ або мітку сеансу:

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

Якщо ваш 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>: включати метадані provenance ACP або receipts.
--verbose, -v: докладне журналювання у stderr.

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

--token і --password можуть бути видимі у локальних списках процесів у деяких системах.
Віддавайте перевагу --token-file/--password-file або змінним середовища (OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD).
Визначення автентифікації Gateway дотримується спільного контракту, який використовують інші клієнти Gateway:
- локальний режим: env (OPENCLAW_GATEWAY_*) -> gateway.auth.* -> резервне gateway.remote.* лише коли gateway.auth.* не задано (локальні SecretRef, які налаштовані, але не можуть бути визначені, завершуються з помилкою без резервного варіанта)
- віддалений режим: gateway.remote.* з резервним env/config згідно з правилами пріоритету для віддаленого режиму
- --url безпечно перевизначає значення й не використовує неявні облікові дані з config/env; передайте явний --token/--password (або варіанти з файлами)
Дочірні процеси runtime backend ACP отримують OPENCLAW_SHELL=acp, що можна використовувати для контекстно-специфічних правил shell/profile.
openclaw acp client встановлює OPENCLAW_SHELL=acp-client у процесі запущеного моста.

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

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

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

acp

acp

Що це не є

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

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

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

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

Як цим користуватися

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

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

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

Відображення сеансів

Параметри

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

CLI commands

RPC and API

Templates

Technical reference

Concept internals

Project

Release policy

​acp

​Що це не є

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

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

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

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

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

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

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

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

​Відображення сеансів

​Параметри

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

acp

Що це не є

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

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

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

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

Як цим користуватися

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

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

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

Відображення сеансів

Параметри

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