​

ACP-агенти

​

Яка сторінка мені потрібна?

​

Чи працює це одразу після встановлення?

• Свіжі інсталяції тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання acpx.
• Вбудований плагін acpx віддає перевагу своєму локально закріпленому двійковому файлу acpx.
• Під час запуску OpenClaw перевіряє цей двійковий файл і за потреби самостійно відновлює його.
• Почніть із /acp doctor, якщо хочете швидко перевірити готовність.

• Адаптер цільового harness може бути завантажений за потреби через npx під час першого використання цього harness.
• На хості все одно має бути налаштована автентифікація постачальника для цього harness.
• Якщо хост не має доступу до npm/мережі, перше завантаження адаптера може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.

• /acp spawn codex: OpenClaw має бути готовий ініціалізувати acpx, але адаптер Codex ACP усе ще може потребувати першого завантаження.
• /acp spawn claude: те саме для адаптера Claude ACP, плюс автентифікація Claude на цьому хості.

​

Швидкий робочий процес оператора

1. Запустіть сесію:
   • /acp spawn codex --bind here
   • /acp spawn codex --mode persistent --thread auto
2. Працюйте в прив’язаній розмові або треді (або явно вкажіть ключ цієї сесії).
3. Перевірте стан середовища виконання:
   • /acp status
4. За потреби налаштуйте параметри середовища виконання:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. Скоригуйте активну сесію без заміни контексту:
   • /acp steer tighten logging and continue
6. Зупиніть роботу:
   • /acp cancel (зупинити поточний хід), або
   • /acp close (закрити сесію та прибрати прив’язки)

​

Швидкий старт для людей

• «Прив’яжи цей канал Discord до Codex.»
• «Запусти тут постійну сесію Codex у треді й тримай її сфокусованою.»
• «Запусти це як одноразову ACP-сесію Claude Code і підсумуй результат.»
• «Прив’яжи цей чат iMessage до Codex і зберігай подальші звернення в тому самому workspace.»
• «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші звернення в тому самому треді.»

1. Вибрати runtime: "acp".
2. Визначити цільовий harness (agentId, наприклад codex).
3. Якщо запитано прив’язування поточної розмови і активний канал це підтримує, прив’язати ACP-сесію до цієї розмови.
4. Інакше, якщо запитано прив’язування треду і поточний канал це підтримує, прив’язати ACP-сесію до треду.
5. Спрямовувати подальші прив’язані повідомлення до тієї самої ACP-сесії, доки її не буде розфокусовано/закрито/прострочено.

​

ACP проти субагентів

​

Як ACP запускає Claude Code

1. Площина керування ACP-сесією OpenClaw
2. вбудований плагін середовища виконання acpx
3. адаптер Claude ACP
4. механізм середовища виконання/сесії Claude

• ACP Claude — це harness-сесія з елементами керування ACP, відновленням сесій, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду.
• CLI backends — це окремі локальні текстові резервні середовища виконання. Див. CLI Backends.

• хочете /acp spawn, сесії з прив’язкою, елементи керування середовищем виконання або постійну роботу harness: використовуйте ACP
• хочете простий локальний текстовий fallback через сирий CLI: використовуйте CLI backends

​

Прив’язані сесії

​

Прив’язки до поточної розмови

• OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою.
• Поточна розмова закріплюється за ключем створеної ACP-сесії.
• Подальші повідомлення в цій розмові спрямовуються до тієї самої ACP-сесії.
• /new і /reset скидають ту саму прив’язану ACP-сесію на місці.
• /acp close закриває сесію та прибирає прив’язку поточної розмови.

• --bind here зберігає ту саму поверхню чату. У Discord поточний канал лишається тим самим каналом.
• --bind here усе одно може створити нову ACP-сесію, якщо ви запускаєте нову роботу. Прив’язка приєднує цю сесію до поточної розмови.
• --bind here сам по собі не створює дочірній тред Discord або тему Telegram.
• Середовище виконання ACP усе одно може мати власну робочу директорію (cwd) або workspace на диску, яким керує бекенд. Цей workspace середовища виконання відокремлений від поверхні чату й не означає створення нового треду повідомлень.
• Якщо ви запускаєте роботу в іншому ACP-агенті й не передаєте --cwd, OpenClaw за замовчуванням успадковує workspace цільового агента, а не того, хто ініціював запит.
• Якщо шлях до успадкованого workspace відсутній (ENOENT/ENOTDIR), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево.
• Якщо успадкований workspace існує, але до нього немає доступу (наприклад EACCES), spawn повертає реальну помилку доступу замість відкидання cwd.

• поверхня чату: місце, де люди продовжують спілкуватися (Discord channel, Telegram topic, iMessage chat)
• ACP-сесія: довготривалий стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw маршрутизує запити
• дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, яка створюється лише через --thread ...
• workspace середовища виконання: розташування у файловій системі, де працює harness (cwd, checkout репозиторію, workspace бекенду)

• /acp spawn codex --bind here: залишити цей чат, створити або приєднати сесію Codex ACP і маршрутизувати сюди майбутні повідомлення
• /acp spawn codex --thread auto: OpenClaw може створити дочірній тред/тему й прив’язати до нього ACP-сесію
• /acp spawn codex --bind here --cwd /workspace/repo: та сама прив’язка чату, що й вище, але Codex працює в /workspace/repo

• Канали чату/повідомлень, які оголошують підтримку прив’язки до поточної розмови, можуть використовувати --bind here через спільний шлях прив’язування розмов.
• Канали з власною семантикою тредів/тем усе одно можуть надавати канально-специфічну канонізацію за тією самою спільною інтерфейсною моделлю.
• --bind here завжди означає «прив’язати поточну розмову на місці».
• Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і зберігаються після звичайних перезапусків gateway.

• --bind here і --thread ... взаємовиключні в /acp spawn.
• У Discord --bind here прив’язує поточний канал або тред на місці. spawnAcpSessions потрібен лише тоді, коли OpenClaw має створити дочірній тред для --thread auto|here.
• Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримку.
• Питання resume і «нова сесія» — це питання ACP-сесії, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату.

​

Прив’язані до треду сесії

• OpenClaw прив’язує тред до цільової ACP-сесії.
• Подальші повідомлення в цьому треді спрямовуються до прив’язаної ACP-сесії.
• Вивід ACP доставляється назад у той самий тред.
• Розфокусування/закриття/архівування/тайм-аут бездіяльності або завершення максимального віку прибирає прив’язку.

• acp.enabled=true
• acp.dispatch.enabled увімкнено за замовчуванням (установіть false, щоб призупинити диспетчеризацію ACP)
• Увімкнений прапорець запуску ACP-тредів у адаптері каналу (залежить від адаптера)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Канали з підтримкою тредів

• Будь-який адаптер каналу, який надає можливість прив’язки сесій/тредів.
• Поточна вбудована підтримка:
  • треди/канали Discord
  • теми Telegram (forum topics у групах/supergroups і DM topics)
• Канали плагінів можуть додавати підтримку через той самий інтерфейс прив’язки.

​

Налаштування, специфічні для каналів

​

Модель прив’язування

• bindings[].type="acp" позначає постійну прив’язку ACP-розмови.
• bindings[].match визначає цільову розмову:
  • канал або тред Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • тема форуму Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • чат DM/груповий чат BlueBubbles: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Для стабільних групових прив’язок віддавайте перевагу chat_id:* або chat_identifier:*.
  • чат DM/груповий чат iMessage: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Для стабільних групових прив’язок віддавайте перевагу chat_id:*.
• bindings[].agentId — це id агента OpenClaw, якому належить прив’язка.
• Необов’язкові перевизначення ACP розміщуються в bindings[].acp:
  • mode (persistent або oneshot)
  • label
  • cwd
  • backend

​

Стандартні параметри середовища виконання для агента

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (id harness, наприклад codex або claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. глобальні стандартні параметри ACP (наприклад acp.backend)

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

• OpenClaw перед використанням гарантує існування налаштованої ACP-сесії.
• Повідомлення в цьому каналі або темі спрямовуються до налаштованої ACP-сесії.
• У прив’язаних розмовах /new і /reset скидають той самий ключ ACP-сесії на місці.
• Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування треду) усе одно застосовуються, де вони є.
• Для міжагентних ACP-запусків без явного cwd OpenClaw успадковує workspace цільового агента з конфігурації агента.
• Відсутні шляхи успадкованого workspace повертаються до стандартного cwd бекенду; збої доступу до наявних шляхів повертаються як помилки spawn.

​

Запуск ACP-сесій (інтерфейси)

​

Із sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime за замовчуванням має значення subagent, тому для ACP-сесій явно встановлюйте runtime: "acp".
• Якщо agentId пропущено, OpenClaw використовує acp.defaultAgent, якщо його налаштовано.
• mode: "session" вимагає thread: true, щоб зберегти постійну прив’язану розмову.

• task (обов’язково): початковий prompt, що надсилається до ACP-сесії.
• runtime (обов’язково для ACP): має бути "acp".
• agentId (необов’язково): id цільового ACP-harness. Якщо не вказано, використовується acp.defaultAgent, якщо налаштовано.
• thread (необов’язково, за замовчуванням false): запросити процес прив’язки треду, де це підтримується.
• mode (необов’язково): run (одноразово) або session (постійно).
  • за замовчуванням використовується run
  • якщо thread: true і режим не вказано, OpenClaw може за замовчуванням увімкнути постійну поведінку залежно від шляху середовища виконання
  • mode: "session" вимагає thread: true
• cwd (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, ACP spawn успадковує workspace цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних значень бекенду, тоді як реальні помилки доступу повертаються користувачу.
• label (необов’язково): операторська мітка, що використовується в тексті сесії/банера.
• resumeSessionId (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через session/load. Потрібно runtime: "acp".
• streamTo (необов’язково): "parent" передає підсумки прогресу початкового виконання ACP назад до сесії-запитувача як системні події.
  • Якщо доступно, прийнятні відповіді містять streamLogPath, який вказує на JSONL-журнал у межах сесії (<sessionId>.acp-stream.jsonl), який можна відстежувати для повної історії ретрансляції.

​

Відновлення наявної сесії

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• Передати сесію Codex з вашого ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
• Продовжити coding-сесію, яку ви почали інтерактивно в CLI, а тепер хочете продовжити безголово через агента
• Відновити роботу, перервану через перезапуск gateway або тайм-аут бездіяльності

• resumeSessionId вимагає runtime: "acp" — повертається помилка, якщо його використовувати з середовищем виконання субагента.
• resumeSessionId відновлює історію розмови в ACP на верхньому рівні; thread і mode як і раніше застосовуються до нової сесії OpenClaw, яку ви створюєте, тому mode: "session" все ще вимагає thread: true.
• Цільовий агент має підтримувати session/load (Codex і Claude Code підтримують).
• Якщо id сесії не знайдено, spawn завершується з чіткою помилкою — без мовчазного fallback до нової сесії.

​

Операторський smoke test

1. Перевірте розгорнуту версію/коміт gateway на цільовому хості.
2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у src/gateway/sessions-patch.ts (subagent:* or acp:* sessions).
3. Відкрийте тимчасову сесію ACPX bridge до живого агента (наприклад razor(main) на jpclawhq).
4. Попросіть цього агента викликати sessions_spawn з:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. Переконайтеся, що агент повідомляє:
   • accepted=yes
   • реальний childSessionKey
   • без помилки validator
6. Очистьте тимчасову сесію ACPX bridge.

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• Для цього smoke test використовуйте mode: "run", якщо ви не тестуєте навмисно постійні ACP-сесії, прив’язані до треду.
• Не вимагайте streamTo: "parent" для базового gate. Цей шлях залежить від можливостей сесії/запитувача і є окремою перевіркою інтеграції.
• Тестування mode: "session", прив’язаного до треду, розглядайте як другий, більш насичений етап інтеграції з реального треду Discord або теми Telegram.

​

Сумісність із sandbox

• Якщо сесія-запитувач працює в sandbox, ACP-запуски блокуються як для sessions_spawn({ runtime: "acp" }), так і для /acp spawn.
  • Помилка: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn з runtime: "acp" не підтримує sandbox: "require".
  • Помилка: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

Із команди /acp

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Визначення цілі сесії

1. Явний аргумент цілі (або --session для /acp steer)
   • спочатку пробує ключ
   • потім id сесії у форматі UUID
   • потім мітку
2. Поточна прив’язка треду (якщо цю розмову/тред прив’язано до ACP-сесії)
3. Поточна резервна сесія-запитувач

​

Режими прив’язування під час spawn

• --bind here — найпростіший операторський шлях для «зроби цей канал або чат підкріпленим Codex».
• --bind here не створює дочірній тред.
• --bind here доступний лише в каналах, які надають підтримку прив’язки до поточної розмови.
• --bind і --thread не можна поєднувати в одному виклику /acp spawn.

​

Режими тредів під час spawn

• На поверхнях без прив’язки тредів поведінка за замовчуванням фактично відповідає off.
• Запуск із прив’язкою до треду вимагає підтримки політики каналу:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Використовуйте --bind here, коли хочете закріпити поточну розмову без створення дочірнього треду.

​

Елементи керування ACP

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

​

Книга рецептів для команд ACP

​

Відображення параметрів середовища виконання

• /acp model <id> відповідає ключу конфігурації середовища виконання model.
• /acp permissions <profile> відповідає ключу конфігурації середовища виконання approval_policy.
• /acp timeout <seconds> відповідає ключу конфігурації середовища виконання timeout.
• /acp cwd <path> безпосередньо оновлює перевизначення cwd середовища виконання.
• /acp set <key> <value> — це загальний шлях.
  • Особливий випадок: key=cwd використовує шлях перевизначення cwd.
• /acp reset-options очищає всі перевизначення середовища виконання для цільової сесії.

​

Підтримка harness у acpx (поточна)

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

Обов’язкова конфігурація

{
  acp: {
    enabled: true,
    // Необов’язково. За замовчуванням true; установіть false, щоб призупинити диспетчеризацію ACP, залишивши /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Налаштування плагіна для бекенду acpx

/acp doctor

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

Налаштування команди та версії acpx

1. За замовчуванням команда вказує на локальний для плагіна node_modules/.bin/acpx усередині пакета плагіна ACPX.
2. Очікувана версія за замовчуванням відповідає закріпленню розширення.
3. Під час запуску реєструється бекенд ACP як одразу not-ready.
4. Фонове ensure-завдання перевіряє acpx --version.
5. Якщо локальний для плагіна двійковий файл відсутній або не збігається, виконується: npm install --omit=dev --no-save acpx@<pinned> і повторна перевірка.

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command приймає абсолютний шлях, відносний шлях або ім’я команди (acpx).
• Відносні шляхи визначаються відносно директорії workspace OpenClaw.
• expectedVersion: "any" вимикає сувору перевірку збігу версії.
• Коли command вказує на власний двійковий файл/шлях, автоматичне локальне встановлення плагіна вимикається.
• Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду.

​

Автоматичне встановлення залежностей

​

MCP-міст інструментів плагінів

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• Вбудовує в bootstrap сесії ACPX вбудований MCP-сервер з назвою openclaw-plugin-tools.
• Надає доступ до інструментів плагінів, які вже зареєстровані встановленими та увімкненими плагінами OpenClaw.
• Зберігає цю можливість явно ввімкненою і вимкненою за замовчуванням.

• Це розширює поверхню інструментів ACP-harness.
• ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway.
• Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися у самому OpenClaw.
• Перегляньте встановлені плагіни перед увімкненням.

​

Налаштування тайм-ауту середовища виконання

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

Налаштування дозволів

​

permissionMode

​

nonInteractivePermissions

​

Конфігурація

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Важливо: Зараз OpenClaw за замовчуванням використовує permissionMode=approve-reads і nonInteractivePermissions=fail. У неінтерактивних ACP-сесіях будь-який запис або exec, що викликає запит дозволу, може завершитися помилкою AcpRuntimeError: Permission prompt unavailable in non-interactive mode. Якщо вам потрібно обмежити дозволи, установіть nonInteractivePermissions у deny, щоб сесії деградували плавно, а не аварійно завершувалися.

​

Усунення неполадок