Перейти к содержимому
Pourquoi Pas?Руководство

Программы-агенты: адаптеры, npx и Node.js

Эта страница — о программах-агентах, которые приложение запускает на этом компьютере, и о том, что делать, если программа не запускается. Как подключить агента — «Подключение агентов».

Claude и Codex не говорят по ACP сами — между приложением и их CLI стоит адаптер, который издатель выкладывает в npm: @agentclientprotocol/claude-agent-acp и @agentclientprotocol/codex-acp. Поэтому для этих двух типов на машине нужен Node.js. Antigravity, GitHub Copilot и JetBrains Junie говорят по ACP сами, им адаптер не нужен; «ACP (other)» запускается тем, что вы напишете в поле «Команда, которая запускает его по ACP».

Установка адаптера

Ставить адаптер заранее не обязательно: если его нет, но есть npx, приложение запустит адаптер через него. Под полем «Программа» в форме агента тогда стоит строка вида:

codex-acp не установлен — будет запускаться через npx (первый запуск дольше)

Первый запуск скачивает пакет из сети, дальше он берётся из кэша npm. Кнопка «Установить адаптер» рядом делает то же, что

Terminal window
npm install -g @agentclientprotocol/codex-acp

Во время установки на кнопке написано «Устанавливаю…», по окончании — «Адаптер установлен: …». После установки строка под «Программой» пропадает.

Если не нашлось ни адаптера, ни npx, строка красная и говорит, чего не хватает:

не найден ни codex-acp, ни npx — поставьте Node.js и выполните npm install -g @agentclientprotocol/codex-acp

Где приложение ищет npx и сами CLI

Приложение, запущенное из Finder или из Dock, не наследует ваш PATH: macOS даёт ему только /usr/bin:/bin:/usr/sbin:/sbin. Поэтому при старте приложение один раз спрашивает PATH у вашей оболочки входа (той, что в $SHELL), как если бы вы открыли терминал, — и дальше ищет в нём. Отсюда же ответ на вопрос «почему npx есть в терминале, а приложение его не видит».

Порядок поиска:

  1. «Путь к бинарнику» и «Команда запуска (argv)» у самого агента (в «Ещё настройки») — если заполнены, используются они и ничего не угадывается;
  2. PATH вашей оболочки — то же, что показывает which npx в терминале. Сюда попадают менеджеры версий (nvm, fnm, mise, asdf, volta), если они подключены в ~/.zshrc, ~/.bashrc или ~/.zprofile;
  3. если оболочку спросить не удалось — ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, то есть обычные места установки.

Чего приложение найти не сможет:

  • node, который живёт только внутри одного каталога — direnv, mise или .nvmrc, дающие версию только в одной папке. Приложение спрашивает оболочку не в вашей папке, поэтому видит только версию по умолчанию: сделайте её глобальной (nvm alias default …) или заполните «Путь к бинарнику»;
  • PATH, дописанный не оболочкой, а терминалом — профиль iTerm или настройка VS Code. У оболочки входа такого PATH нет, хотя в окне терминала всё работает; перенесите строку в ~/.zshrc;
  • PATH оболочки, которая не отвечает — не задан $SHELL, оболочка не понимает -ilc, или rc-файл выполняется дольше десяти секунд. Тогда остаются только три каталога из пункта 3.

После изменения PATH перезапустите приложение: оболочка опрашивается один раз, при старте.

То же самое относится к запуску агента на карточке: адаптер ищется в том же PATH, что и npx, а сам CLI — там, где его видит адаптер. На Windows этой проблемы нет — там приложение получает ваше окружение целиком.