ACP

Запустіть міст Agent Client Protocol (ACP), який взаємодіє з OmeniaClaw Gateway.

Ця команда використовує ACP через stdio для IDE та пересилає запити до Gateway через WebSocket. Вона зберігає зіставлення ACP-сесій із ключами сесій Gateway.

OmeniaClaw acp — це ACP-міст на базі Gateway, а не повноцінне ACP-нативне середовище виконання редактора. Він зосереджений на маршрутизації сесій, доставленні запитів і базових потокових оновленнях.

Якщо ви хочете, щоб зовнішній MCP-клієнт напряму взаємодіяв із розмовами каналів OmeniaClaw замість розміщення сесії ACP harness, використовуйте OmeniaClaw mcp serve.

Чим це не є

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

OmeniaClaw acp означає:

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

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

Коротке правило:

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

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

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

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

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

OmeniaClaw acp # Remote GatewayOmeniaClaw acp --url wss://gateway-host:18789 --token <token> # Remote Gateway (token from file)OmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Attach to an existing session keyOmeniaClaw acp --session agent:main:main # Attach by label (must already exist)OmeniaClaw acp --session-label "support inbox" # Reset the session key before the first promptOmeniaClaw acp --session agent:main:main --reset-session

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

Використовуйте вбудований ACP-клієнт, щоб перевірити справність моста без IDE. Він запускає ACP-міст і дає змогу вводити запити інтерактивно.

OmeniaClaw acp client # Point the spawned bridge at a remote GatewayOmeniaClaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token # Override the server command (default: OmeniaClaw)OmeniaClaw acp client --server "node" --server-args OmeniaClaw.mjs acp --url ws://127.0.0.1:19001

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

• Автосхвалення базується на списку дозволених і застосовується лише до довірених ідентифікаторів core tool.
• Автосхвалення read обмежене поточним робочим каталогом (--cwd, якщо задано).
• ACP автоматично схвалює лише вузькі readonly-класи: scoped-виклики read у межах активного cwd плюс readonly-інструменти пошуку (search, web_search, memory_search). Невідомі/не-core інструменти, читання поза областю, exec-capable інструменти, control-plane інструменти, mutating інструменти та інтерактивні потоки завжди потребують явного схвалення запиту.
• Наданий сервером toolCall.kind розглядається як ненадійні метадані (не як джерело авторизації).
• Ця політика ACP-моста окрема від дозволів ACPX harness. Якщо ви запускаєте OmeniaClaw через бекенд acpx, plugins.entries.acpx.config.permissionMode=approve-all є break-glass перемикачем "yolo" для цієї сесії harness.

Smoke-тестування протоколу

Для налагодження на рівні протоколу запустіть Gateway з ізольованим станом і керуйте OmeniaClaw acp через stdio за допомогою ACP JSON-RPC-клієнта. Покрийте initialize, session/new, session/list з абсолютним cwd, session/resume, session/close, дубльоване закриття та відсутнє resume.

Доказ має включати оголошені можливості життєвого циклу, рядок сесії на базі 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"]}

Уникайте використання OmeniaClaw gateway call sessions.list як єдиного доказу ACP. Цей шлях CLI може запросити підвищення operator scope для fresh-token; коректність ACP-моста доводиться ACP stdio-кадрами плюс журналом Gateway sessions.list.

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

Використовуйте ACP, коли IDE (або інший клієнт) говорить Agent Client Protocol і ви хочете, щоб він керував сесією OmeniaClaw Gateway.

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

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

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

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

OmeniaClaw acp --url wss://gateway-host:18789 --token <token># preferred for local process safetyOmeniaClaw acp --url wss://gateway-host:18789 --token-file ~/.OmeniaClaw/gateway.token

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

ACP не вибирає агентів напряму. Він маршрутизує за ключем сесії Gateway.

Використовуйте ключі сесій з областю агента, щоб націлитися на конкретного агента:

OmeniaClaw acp --session agent:main:mainOmeniaClaw acp --session agent:design:mainOmeniaClaw acp --session agent:qa:bug-123

Кожен сеанс ACP зіставляється з одним ключем сеансу Gateway. Один агент може мати багато сеансів; ACP за замовчуванням використовує ізольований сеанс acp:<uuid>, якщо ви не перевизначите ключ або мітку.

Посеансові mcpServers не підтримуються в режимі моста. Якщо клієнт ACP надсилає їх під час newSession або loadSession, міст повертає чітку помилку замість того, щоб мовчки їх ігнорувати.

Якщо ви хочете, щоб сеанси на базі ACPX бачили інструменти Plugin OmeniaClaw або вибрані вбудовані інструменти, як-от cron, увімкніть MCP-мости ACPX на боці Gateway замість спроб передати посеансові mcpServers. Див. агенти ACP і MCP-міст інструментів OmeniaClaw.

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

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

Типовий процес:

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

Приклади:

# One-shot request into your default OmeniaClaw ACP sessionacpx OmeniaClaw exec "Summarize the active OmeniaClaw session state." # Persistent named session for follow-up turnsacpx OmeniaClaw sessions ensure --name codex-bridgeacpx OmeniaClaw -s codex-bridge --cwd /path/to/repo \  "Ask my OmeniaClaw work agent for recent context relevant to this repo."

Якщо ви хочете, щоб acpx OmeniaClaw щоразу використовував конкретний Gateway і ключ сеансу, перевизначте команду агента OmeniaClaw у ~/.acpx/config.json:

{  "agents": {    "OmeniaClaw": {      "command": "env OmeniaClaw_HIDE_BANNER=1 OmeniaClaw_SUPPRESS_NOTES=1 OmeniaClaw acp --url ws://127.0.0.1:18789 --token-file ~/.OmeniaClaw/gateway.token --session agent:main:main"    }  }}

Для локальної копії OmeniaClaw у репозиторії використовуйте прямий вхідний пункт CLI замість dev runner, щоб потік ACP залишався чистим. Наприклад:

env OmeniaClaw_HIDE_BANNER=1 OmeniaClaw_SUPPRESS_NOTES=1 node OmeniaClaw.mjs acp ...

Це найпростіший спосіб дозволити Codex, Claude Code або іншому ACP-сумісному клієнту отримувати контекстну інформацію від агента OmeniaClaw без зчитування термінала.

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

Додайте власний агент ACP у ~/.config/zed/settings.json (або скористайтеся UI налаштувань Zed):

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

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

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

У Zed відкрийте панель Agent і виберіть "OmeniaClaw ACP", щоб почати гілку.

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

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

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

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

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

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

Параметри

• --url <url>: WebSocket URL 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: не додавати робочий каталог як префікс до prompt.
• --provenance <off|meta|meta+receipt>: включити метадані або квитанції походження ACP.
• --verbose, -v: докладне журналювання у stderr.

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

• --token і --password у деяких системах можуть бути видимими в локальних списках процесів.
• Надавайте перевагу --token-file/--password-file або змінним середовища (OmeniaClaw_GATEWAY_TOKEN, OmeniaClaw_GATEWAY_PASSWORD).
• Визначення автентифікації Gateway відповідає спільному контракту, який використовують інші клієнти Gateway:
  • локальний режим: env (OmeniaClaw_GATEWAY_*) -> gateway.auth.* -> резервний gateway.remote.* лише коли gateway.auth.* не задано (налаштовані, але нерозв’язані локальні SecretRefs завершуються закрито)
  • віддалений режим: gateway.remote.* з резервом env/config відповідно до правил пріоритету для віддаленого режиму
  • --url безпечно перевизначає і не повторно використовує неявні облікові дані з config/env; передайте явний --token/--password (або файлові варіанти)
• Дочірні процеси бекенда виконання ACP отримують OmeniaClaw_SHELL=acp, що можна використовувати для контекстних правил shell/profile.
• OmeniaClaw acp client задає OmeniaClaw_SHELL=acp-client для запущеного процесу моста.

Параметри acp client

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

Пов’язане

• Довідник CLI
• Агенти ACP