ACP в терминале (acpx)

Для скриптов и CI основной путь это встроенный headless-режим waibee run: он ничего не требует сверх самого агента, см. Headless-режим и автоматизация.

Эта страница про другой вариант, если он тебе уже знаком: acpx, сторонний headless-клиент Agent Client Protocol. Это тот же протокол, по которому агент подключается к редакторам, только управляет им командная строка. Waibee Code выступает для него обычным ACP-агентом, командой waibee acp.

Что он даёт поверх waibee run:

• Сессии живут между вызовами. Каждый следующий запрос помнит предыдущий, при этом сам вызов остаётся одной командой в терминале.
• Несколько задач в одной папке. Именованные сессии идут параллельно и не мешают друг другу.
• Поток событий ACP в JSON. Видно, какие инструменты агент вызвал и что запросил на подтверждение, а не только финальный текст.
• Один интерфейс к разным агентам. Полезно, когда рядом с Waibee в скриптах живут другие ACP-агенты.

Установка

npm install -g acpx@latest
acpx --version

Без глобальной установки: npx acpx@latest.

Регистрация Waibee

Waibee не входит в набор встроенных адаптеров acpx, его добавляют в конфиг:

~/.acpx/config.json

{
  "agents": {
    "waibee": {
      "command": "waibee",
      "args": ["acp"]
    }
  }
}

Если waibee не в PATH, укажи полный путь: ~/.local/bin/waibee (macOS/Linux) или %LOCALAPPDATA%\Programs\waibee\waibee.exe (Windows). Конфиг можно положить и рядом с проектом, в файл .acpxrc.json; текущие значения показывает acpx config show.

Ключ агент берёт сам: задай его заранее через waibee config set-api-key или переменной окружения WAIBEE_API_KEY, см. Быстрый старт.

Первый запрос

Разовый запрос без сохранения контекста:

acpx waibee exec 'В трёх пунктах: что делает этот репозиторий?'

Для запросов с продолжением сессию нужно создать явно. Это защита от случайного создания сессий в CI:

acpx waibee sessions new
acpx waibee 'найди самый медленный тест и объясни почему'
acpx waibee 'исправь его'          # помнит предыдущий ответ

Сессии привязаны к агенту и рабочей папке. Параллельные задачи разводятся именами:

acpx waibee sessions new --name backend
acpx waibee -s backend 'починить таймаут в чекауте'

acpx waibee sessions              # список сессий этой папки
acpx waibee status                # процесс агента, модель, время работы
acpx waibee cancel                # прервать текущий запрос

Права

В терминале агенту некому задать вопрос, поэтому политику подтверждений задаёшь ты флагом. По умолчанию acpx разрешает чтение и спрашивает про остальное, а когда спросить не у кого, отклоняет запрос: команда завершится ошибкой PERMISSION_DENIED, даже если ответ уже был получен.

Флаг	Поведение
--approve-reads	Разрешить чтение и поиск, остальное спрашивать. По умолчанию
--approve-all	Разрешить всё: правки файлов и запуск команд без вопросов
--deny-all	Запретить инструменты полностью, только рассуждения по контексту
--permission-policy <json>	Своя политика: списки автоодобрения и автозапрета

--approve-all стоит давать только там, где не жалко изменений: одноразовый клон, worktree, рабочая копия в CI. Запреты из settings.json действуют независимо от флага, см. Права доступа.

Вывод для скриптов

Формат	Что печатает
--format text	Читаемый ход работы. По умолчанию
--format quiet	Только финальный текст ответа
--format json	Поток событий ACP построчным JSON

SUMMARY=$(acpx --format quiet waibee exec 'опиши изменения в ветке одним абзацем')
echo "$SUMMARY"

--json-strict гарантирует, что в stdout нет ничего кроме JSON: удобно, когда вывод сразу уходит в jq. Ещё пригодятся --suppress-reads (не печатать содержимое прочитанных файлов) и --timeout <сек>.

Модель и уровень рассуждений

acpx --model anthropic/claude-sonnet-5 waibee exec 'разбери этот стектрейс'

acpx waibee set model anthropic/claude-haiku-4.5   # на текущую сессию
acpx waibee set thought_level high                 # усилие рассуждений
acpx waibee set mode acceptEdits                   # режим подтверждений

Значения mode: default, acceptEdits, dontAsk, bypassPermissions. Уровни thought_level те же, что у /effort в TUI, и зависят от модели, см. Выбор модели.

Если это для CI

Тогда сравни с waibee run: там не нужен Node, не нужна отдельная установка и есть коды возврата под goal mode. Готовые рецепты для пайплайнов собраны в Headless-режиме. acpx оправдан, когда в CI важен именно разговор с состоянием между шагами или когда пайплайн уже гоняет через acpx нескольких агентов.

Что учесть в любом случае:

• Ограничивай время и число ходов (--timeout, --max-turns): агент в CI не должен висеть до таймаута раннера.
• Читающие проверки запускай с --approve-reads, правки отдельным шагом с явным --approve-all, чтобы случайный коммит не приехал из ревью-джобы.
• Проверяй код возврата. Ненулевой код это отклонённое разрешение, таймаут или ошибка агента, а не «замечаний нет».

Дальше

• Headless-режим: встроенный способ запускать агента из скриптов и CI.
• IDE (ACP): тот же протокол в Zed и JetBrains.
• Goal mode: как заставить агента доводить задачу до проверяемого результата.