​

Агенти 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 у гілці й тримай його зосередженим».
• «Виконай це як одноразовий сеанс Claude Code ACP і підсумуй результат».
• «Прив’яжи цей чат iMessage до Codex і зберігай наступні повідомлення в тому самому робочому просторі».
• «Використай Gemini CLI для цього завдання в гілці, а потім зберігай наступні повідомлення в цій самій гілці».

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

​

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

​

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

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

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

​

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

​

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

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

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

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

• /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 доставляється назад у ту саму гілку.
• Розфокусування, закриття, архівування, тайм-аут бездіяльності або завершення max-age прибирає прив’язку.

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

​

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

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

​

Налаштування для конкретних каналів

​

Модель прив’язки

• bindings[].type="acp" позначає постійну ACP-прив’язку розмови.
• bindings[].match визначає цільову розмову:
  • канал або гілка Discord: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • форумна тема Telegram: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • чат BlueBubbles DM/груповий чат: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Для стабільних прив’язок груп віддавайте перевагу chat_id:* або chat_identifier:*.
  • чат iMessage DM/груповий чат: 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 успадковує робочий простір цільового агента з конфігурації агента.
• Відсутні успадковані шляхи до робочого простору призводять до повернення до стандартного cwd бекенду; невідсутні помилки доступу повертаються як помилки запуску.

​

Запуск сеансів 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 (обов’язково): початковий промпт, надісланий до сеансу ACP.
• runtime (обов’язково для ACP): має бути "acp".
• agentId (необов’язково): id цільового harness ACP. Якщо не вказано, використовується acp.defaultAgent, якщо налаштовано.
• thread (необов’язково, за замовчуванням false): запитати потік прив’язки до гілки там, де це підтримується.
• mode (необов’язково): run (одноразовий) або session (постійний).
  • за замовчуванням використовується run
  • якщо thread: true і mode не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання
  • mode: "session" вимагає thread: true
• cwd (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, під час запуску ACP успадковується робочий простір цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних параметрів бекенду, а реальні помилки доступу повертаються.
• 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 з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
• Продовжити сеанс кодування, який ви почали інтерактивно в CLI, а тепер хочете виконувати безголово через агента
• Відновити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності

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

​

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

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

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" для базового бар’єра. Цей шлях залежить від можливостей запитувача/сеансу й є окремою інтеграційною перевіркою.
• Розглядайте тестування 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)
   • спочатку пробує ключ
   • потім session id у форматі UUID
   • потім мітку
2. Прив’язка поточної гілки (якщо ця розмова/гілка прив’язана до сеансу ACP)
3. Резервний варіант: поточний сеанс запитувача

​

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

• --bind here — найпростіший операторський шлях для «зробити цей канал або чат підкріпленим Codex».
• --bind here не створює дочірню гілку.
• --bind here доступний лише в каналах, які підтримують прив’язку до поточної розмови.
• --bind і --thread не можна поєднувати в одному виклику /acp 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.
    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).
• Відносні шляхи визначаються від директорії робочого простору 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.
• Перевіряйте встановлені плагіни перед увімкненням цієї функції.

​

Конфігурація дозволів

​

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, щоб сеанси плавно деградували замість аварійного завершення.

​

Усунення несправностей