Конфигурация бэкенда ACP
Что такое ACP?
ACP (Agent Client Protocol) — это протокол для взаимодействия с бэкендами агентов. Zotero Agents взаимодействует с локально запущенными процессами агентов (такими как Codex, Claude Code, OpenCode и т.д.) через протокол ACP для обеспечения диалогов и выполнения навыков.
Бэкенд ACP — это рекомендуемый способ настройки — если у вас установлен любой совместимый с ACP инструмент агента на вашем компьютере, вы можете использовать его напрямую без дополнительной настройки.
Впервые с Agent?
Если вы впервые работаете с инструментами Agent и не знаете, какой выбрать или как установить, обратитесь к этому руководству:
Руководство по началу работы с Agent
Почему сначала ACP?
- Нулевая нагрузка по настройке: Не нужно развёртывать дополнительные сервисы; используйте инструменты агентов, уже имеющиеся на вашем компьютере
- Автоматическое управление процессами: Плагин указывает команду запуска в конфигурации и автоматически управляет жизненным циклом процесса агента
- Поддержка нескольких агентов: Настройте несколько различных бэкендов агентов одновременно и переключайтесь между ними по мере необходимости
- Изоляция конфигурации: Некоторые агенты (такие как OpenCode и Codex) поддерживают изоляцию каталогов конфигурации и каталогов постоянных сессий через переменные окружения
Шаги настройки
- Убедитесь, что у вас установлен хотя бы один совместимый с ACP инструмент агента CLI на вашем компьютере
- Откройте Инструменты → Менеджер бэкендов
- Переключитесь на вкладку ACP
- Выберите ваш инструмент агента из выпадающего списка Добавить из пресета или нажмите Добавить ACP для ручной настройки
- Заполните следующие поля:
- Отображаемое имя: Понятное имя (например, "Мой OpenCode")
- Команда: Команда для запуска бэкенда ACP (пресеты заполняют автоматически, но вы также можете изменить вручную)
- Аргументы: Дополнительные аргументы для команды (необязательно)
- Переменные окружения: Дополнительные переменные окружения (необязательно, используются для изоляции конфигурации и т.д.)
- Нажмите Сохранить в правом нижнем углу
Проверка подключения
После сохранения плагин автоматически обнаруживает возможности бэкенда:
- Проверяет существование команды
- Подключается и инициализируется
- Получает список доступных моделей и режимов
- Вычисляет отпечаток конфигурации для обнаружения последующих изменений
Если обнаружение не удалось, проверьте, что CLI агента установлен правильно и формат команды верен.
Поддерживаемые пресеты агентов
Плагин предоставляет несколько встроенных пресетов. После нажатия Добавить из пресета выберите агента слева; справа отображаются параметры запуска и предварительный просмотр конфигурации только для чтения.
Запустить через npx переключает команду на формат npx <package> и показывает уведомление о необходимости установки Node.js и npm. Codex и Claude Code по умолчанию используют npx, так как зависят от ACP-адаптера; остальные агенты по умолчанию используют обычную команду. При включении npx к отображаемому имени профиля добавляется суффикс (npm).
Изолированная среда доступна только для агентов, поддерживающих изоляцию. При включении плагин добавляет в предварительный просмотр задокументированные переменные окружения изоляции или аргументы каталога сессии и показывает уведомление о том, что параметры агента и аутентификацию необходимо управлять самостоятельно в этом каталоге. При включении изоляции к отображаемому имени профиля добавляется суффикс (Isolated).
| Пресет | Команда по умолчанию | Описание |
|---|---|---|
| OpenCode | opencode acp | ACP-бэкенд OpenCode; поддерживает изоляцию каталога конфигурации через OPENCODE_CONFIG_DIR |
| Codex | npx -y @agentclientprotocol/codex-acp@latest | ACP-адаптер для OpenAI Codex |
| Claude Code | npx -y @agentclientprotocol/claude-agent-acp@latest | ACP-адаптер для Claude Code |
| Gemini CLI | gemini --experimental-acp | Режим ACP Gemini CLI |
| Hermes | hermes acp | ACP-бэкенд Hermes Agent |
| Qwen Code | qwen --acp --experimental-skills | Режим ACP Qwen Code |
| GitHub Copilot | copilot --acp --stdio | Режим ACP GitHub Copilot CLI |
| Qoder CLI | qodercli --acp | Режим ACP Qoder CLI; поддерживает изоляцию каталога конфигурации через QODER_CONFIG_DIR |
| Cursor Agent ACP | cursor-agent-acp | ACP-адаптер Cursor Agent; поддерживает изоляцию каталога сессии через --session-dir |
| DeepAgents | deepagents-acp | ACP-адаптер DeepAgents |
| Auggie | auggie --acp | Режим ACP Auggie |
| Kilo | kilo acp | Режим ACP Kilo Code |
| Cline | cline --acp | Режим ACP Cline |
| CodeBuddy | codebuddy --acp | Режим ACP CodeBuddy |
| Grok | grok agent stdio | Режим stdio Grok Agent |
Протестированы только OpenCode, Codex, Claude Code, Gemini CLI, Qwen Code и Hermes Agent. Доступность других ACP-бэкендов зависит от их реализации и не гарантируется этим плагином. При возникновении проблем вы можете самостоятельно настроить аргументы команды и переменные окружения; руководствуйтесь протоколом ACP и официальной документацией бэкенда.
После выбора пресета вы всё ещё можете вручную изменить любое поле.
Рекомендации по настройке переменных окружения
Некоторые агенты поддерживают изоляцию конфигурации и постоянные сессии через переменные окружения; просто добавьте их в редакторе переменных окружения:
| Переменная окружения | Агент | Назначение |
|---|---|---|
OPENCODE_CONFIG | OpenCode | Указать независимый каталог конфигурации |
OPENCODE_SESSION_DIR | OpenCode | Указать каталог постоянных сессий |
CODEX_CONFIG_DIR | Codex | Указать независимый каталог конфигурации |
Бесплатные модели
Несколько движков предлагают бесплатный доступ к моделям — идеально для начала без оплаты:
| Движок | Бесплатная опция | Как это работает |
|---|---|---|
| Kilo Code | Режим Auto Free | Встроенный режим Auto Free в Kilo Code автоматически направляет каждый запрос к подходящей бесплатной модели. Включите в настройках Kilo Code — ключ API не требуется |
| OpenCode Zen | Встроенные бесплатные модели | Версия OpenCode Zen включает бесплатный доступ к моделям без подписки API |
| OpenCode + OpenRouter | Бесплатные модели OpenRouter | Настройте OpenCode на использование OpenRouter и выберите бесплатные модели (напр., Gemini 2.5 Flash, DeepSeek V3). Требуется бесплатная учётная запись OpenRouter |
Ограничения бесплатного тарифа
Бесплатных моделей достаточно для эпизодического использования, но учитывайте следующие ограничения:
| Ограничение | Чего ожидать |
|---|---|
| Ограничение скорости | Запросы могут замедляться — обычно 5–20 запросов в минуту в зависимости от нагрузки провайдера. Пакетная обработка значительно замедляется |
| Параллельность | Обычно ограничено одним одновременным запросом. Одновременный запуск нескольких рабочих процессов может поставить их в очередь или привести к сбою |
| Доступность моделей | Пулы бесплатных моделей могут быть исчерпаны в часы пик. Возможны ошибки «модель недоступна» или «превышена ёмкость» |
| Смена моделей | Провайдеры могут незаметно заменять бесплатные модели (повышение или понижение) без предупреждения. Качество вывода может различаться между запусками |
| Отсутствие SLA / Надёжность | Бесплатные тарифы не гарантируют доступность. Сервисы могут быть временно недоступны или прекращены |
Если вам нужна надёжная пакетная обработка или промышленное использование, рассмотрите платный план, например OpenCode Go ($10/мес.) или Coding Plan (Bailian, Zhipu и др.). Стоимость одной статьи ничтожна по сравнению с экономией времени.
Типы запросов
Бэкенд ACP поддерживает два типа запросов:
acp.prompt.v1— Диалоговое взаимодействие (ACP Чат)acp.skill.run.v1— Выполнение навыков (Навыки ACP)
Один и тот же бэкенд ACP может использоваться как для диалогов, так и для запусков навыков одновременно.
Управление сессиями
- Каждый бэкенд может иметь несколько сессий (диалогов), которые постоянно хранятся в базе данных плагина
- Различные бэкенды ACP могут работать одновременно, не мешая друг другу
- Сессиями можно управлять в ACP Чате
Следующие шаги
После завершения настройки вы можете:
- Общаться с бэкендом в Боковой панели ACP Чата
- Просматривать запуски навыков ACP в Панели мониторинга
- Использовать бэкенд ACP для выполнения задач в Списке Workflow