Распространённые проблемы и устранение неполадок Pi Agent
Ниже приведены распространённые проблемы и решения, возникающие при использовании Pi Agent.
Проблемы при установке
В этом разделе описаны типичные ошибки и способы их решения при установке.
npm install завершается ошибкой
Симптом: команда установки завершается ошибкой на полпути. Распространённые ошибки делятся на три категории: версия, сеть и права доступа.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Слишком низкая версия Node.js. Для Pi Agent требуется Node.js 22.19.0 или выше. | Запуститеnode --version, чтобы проверить текущую версию | Используйте nvm для установки и переключения на 22 LTS или выше |
| Проблема с сетью: доступ к официальному реестру npm из Китая часто приводит к тайм-ауту. | Проверьте, содержит ли ошибка сообщения о тайм-ауте сети, например ETIMEDOUT. | Выполнитеnpm config set registry https://registry.npmmirror.comПереключитесь на зеркальный реестр и переустановите. |
| Проблема с правами доступа: текущий пользователь не может записывать в глобальный каталог установки в macOS/Linux. | Проверьте, содержит ли ошибка ошибки прав доступа EACCES. | Используйте nvm для управления Node.js или настройте префикс npm на пользовательский каталог. Избегайте использования sudo. |
Команда pi не найдена после установки
Симптом: установка сообщает об успехе, но при вводе pi появляется "command not found".
Сначала проверьте глобальный префикс установки npm:
$ npm prefix -g /usr/local
Затем убедитесь, находится ли каталог bin в этом префиксе в PATH:
$ echo $PATH | grep "$(npm prefix -g)/bin" /usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin
Если каталог отсутствует в PATH, эта команда не выводит ничего:
$ echo $PATH | grep "$(npm prefix -g)/bin"
Отсутствие вывода означает, что глобальный каталог bin отсутствует в PATH, поэтому команда pi не может быть найдена.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Глобальный каталог bin не добавлен в PATH. | Используйте приведённую выше команду grep, чтобы проверить, есть ли вывод. | удерживайте$(npm prefix -g)/binДобавьте в~/.zshrcили~/.bashrcв PATH, затем перезапустите терминал, чтобы это вступило в силу. |
| Версия Node изменена, старая символическая ссылка больше недействительна. | Выполнитеls $(npm prefix -g)/binчтобы проверить, существует ли ещё pi | Повторно выполните глобальную установку в текущей версии Node. |
Проблемы аутентификации
В этом разделе описаны пути решения для входа /login и сбоев аутентификации по API Key.
Сбой входа /login
Симптом: после ввода /login браузер не может завершить перенаправление, или интерфейс остаётся в состоянии ожидания авторизации.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Подписка находится в недействительном состоянии. | Войдите на официальный сайт провайдера, чтобы проверить, истёк ли срок подписки. | Продлите подписку или переключитесь на другого провайдера, чтобы войти. |
| Не удаётся получить доступ к серверу аутентификации провайдера. | Откройте сайт провайдера в браузере, чтобы убедиться в доступности сети. | Настройте прокси и повторите попытку. См. раздел «Настройки прокси» ниже. |
| Использование /login при удалённом подключении по SSH | На удалённой машине нет браузера, поэтому обратный вызов OAuth не может быть доставлен. | Скопируйте URL авторизации в локальный браузер, затем вручную вставьте URL обратного вызова, чтобы завершить вход. |
API-ключ не работает
Симптом: переменные среды были экспортированы, но при запуске приложение по-прежнему выдаёт сообщение «not authenticated» или продолжает использовать старые учётные данные.
Проверьте в следующем порядке:
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Переменные среды заданы неправильно. | Выполнитеecho $ANTHROPIC_API_KEY, чтобы просмотреть вывод | Если вывод пуст, добавьте export в конфигурационный файл оболочки, затем снова выполните source. |
| auth.jsonДубликат учётных данных уже существует в [file] и имеет более высокий приоритет, чем переменные среды. | Проверьте~/.pi/agent/auth.json, существует ли уже запись для этого провайдера в [file]. | Выполните/logout, затем очистите старые учётные данные или отредактируйте auth.json напрямую, чтобы обновить Key. |
| Формат API Key неверен. | Проверьте, содержит ли скопированное содержимое лишние пробелы или кавычки. | Скопируйте Key полностью ещё раз и перенастройте. |
auth.jsonУчётные данные, сохранённые в [file], имеют более высокий приоритет, чем переменные среды.
Когда API Key не работает, сначала проверьте~/.pi/agent/auth.json, не ограничивайтесь только переменными среды.
Модель недоступна
Симптом: ожидаемая модель не найдена в списке моделей или при её вызове отображается ошибка прав доступа.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Локальный каталог моделей устарел. | Выполнитеpi update --models, чтобы обновить каталог моделей | После обновления снова откройте средство выбора модели. |
| Не уверены, какие модели сейчас доступны. | Запуститеpi --list-models, чтобы просмотреть список доступных моделей | Выберите из списка модель, доступную для текущей учётной записи. |
| У этого API-ключа нет доступа к соответствующей модели. | В консоли провайдера проверьте область авторизации модели для этого ключа. | Обновите тарифный план или переключитесь на авторизованную модель. |
| Модель GitHub Copilot отображается как «не поддерживается». | Проверьте, включена ли модель в VS Code. | Сначала включите модель в VS Code Copilot Chat, затем вернитесь в Pi Agent, чтобы использовать её. |
Проблемы интерфейса
В этом разделе рассматриваются три типа аномалий интерфейса: рендеринг терминала, отображение изображений и сочетания клавиш.
Неправильное отображение интерфейса (неверные цвета, смещение)
Симптом: цвета выглядят тусклыми или искажёнными, а границы таблиц и текстовых полей смещены.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Терминал не поддерживает True Color. | Выполнитеecho $COLORTERMЕсли вывод — truecolor или 24bit, это означает, что поддержка есть. | Переключитесь на терминал, поддерживающий True Color (iTerm2, Windows Terminal и т. д.). |
| VS Code автоматически скорректировал контраст терминала. | Проверьте параметрterminal.integrated.minimumContrastRatio | Установите для этого параметра значение 1. |
| У текущего терминала плохая совместимость с рендерингом. | Запустите в другом терминале, чтобы проверить, воспроизводится ли проблема. | Смените терминал; рекомендуется iTerm2 или Windows Terminal. |
Изображения не отображаются
Симптом: после отправки или вставки изображения в терминале видны только заполнитель или пустое место.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Терминал не поддерживает протоколы отображения изображений. | Проверьте, поддерживает ли терминал imgcat из iTerm2 или icat из Kitty. | Переключитесь на терминал, поддерживающий протоколы изображений. |
| Отображение изображений отключено в конфигурации. | Проверьте, имеет лиterminal.showImagesзначение true. | Измените его на true и выполните/reload, чтобы применить конфигурацию. |
Сочетания клавиш не работают
Симптом: нажатие сочетаний клавиш, описанных в документации, не даёт эффекта или запускает собственные функции терминала.
| Возможные причины | Шаги по устранению неполадок | Решения |
|---|---|---|
| Терминал перехватывает сочетание клавиш. | Проверьте список привязок сочетаний клавиш в настройках терминала. | Измените или освободите конфликтующие привязки в терминале. |
| Неправильно запомнены текущие сочетания клавиш. | Запустите/hotkeys, чтобы просмотреть все текущие привязки сочетаний клавиш. | Работайте в соответствии с фактическими привязками в списке. |
| Нужно настроить под личные привычки. | Проверьте, существует ли файл конфигурации~/.pi/agent/keybindings.json. | Отредактируйте этот файл, чтобы настроить сочетания клавиш |
Проблемы с сессиями
В этом разделе рассматриваются два типа проблем: раздувание файла сессии и невозможность найти исторические сессии.
Файл сессии слишком большой
Симптом: использование контекста продолжает расти, ответы замедляются или сжатие запускается раньше времени.
| Возможные причины | Методы устранения неполадок | Решения |
|---|---|---|
| История диалога слишком длинная | Запустите/sessionПроверьте количество сообщений и использование токенов | Запустите/compactСожмите историю диалога |
| Автосжатие не включено | Проверьтеcompaction.enabled, равно ли оно true | После установки значения true перезапустите pi, чтобы это вступило в силу |
| Одна сессия накапливалась слишком долго | используйте/sessionСледите за ростом размера файла сессии | Регулярно используйте/newНачинайте новую сессию, разделяйте сессии по задачам |
Не удается найти предыдущую сессию
Симптом: в списке pi -r не видны записи о предыдущей работе.
| Возможные причины | Методы устранения неполадок | Решения |
|---|---|---|
| Не использовалась точка входа resume | Запуститеpi -rИли введите /resume в интерактивном режиме для просмотра списка сессий | Выберите целевую сессию в списке для возобновления |
| sessionDirНастройки были изменены | Проверьте в settings.jsonsessionDirтекущее значение | Вернитесь в исходный каталог или перенесите файлы из исходного каталога в новый каталог |
| Аномалия прав доступа к каталогу сессий | Выполнитеls ~/.pi/agent/sessions/Убедитесь, что он доступен для чтения и записи | Выполнитеchmod -R u+rw ~/.pi/agent/sessionsИсправьте права доступа |
Проблемы с производительностью
В этом разделе рассматриваются два типа проблем с производительностью: медленные ответы и снижение производительности при длинном контексте.
Ответы ИИ медленные
Симптом: после отправки запроса долго нет вывода первого слова, или общее время значительно выше обычного.
| Возможные причины | Методы устранения неполадок | Решения |
|---|---|---|
| Высокая сетевая задержка или обрыв соединения | Запуститеping api.anthropic.comПроверьте задержку и потери пакетов | Смените сеть или настройте прокси, как описано в настройках прокси ниже |
| Уровень рассуждений слишком высок, время обдумывания увеличено | Проверьте текущий уровень рассуждений в строке состояния | Нажмите Shift+Tab, чтобы понизить уровень рассуждений |
| Системный промпт или содержимое файла контекста слишком велико | Проверьте размер файлов контекста, таких как AGENTS.md | Сократите системный промпт, оптимизируйте содержимое AGENTS.md |
| Потребление токенов на запрос слишком велико | Запустите/sessionПросмотрите распределение использования токенов и затрат времени | Запустите/compactили/newСократите контекст и попробуйте снова |
Если вы используете прокси-среду, переключитесь наcurl -x $HTTP_PROXY https://api.anthropic.comдля проверки.
В среде с прокси сбой ping не означает, что API недоступен.
ping использует ICMP, а API использует HTTPS; в этом случае переключитесь на curl, чтобы проверить фактическое соединение.
Производительность ИИ снижается после большого контекста
Симптом: после увеличения числа ходов диалога ИИ начинает забывать предыдущие договорённости или даёт повторяющиеся ответы.
| Возможные причины | Методы устранения неполадок | Решения |
|---|---|---|
| Контекст близок к лимиту окна, и раннее содержимое сжимается | Запустите/sessionПроверьте текущее использование токенов | Вручную запустите/compactСожмите контекст |
| В исторические сообщения подмешано большое количество недействительных попыток | используйте/treeПроверьте ветки и недействительные диалоги | используйте/newНачните новый сеанс, запишите выводы в AGENTS.md |
| Содержимое указанного файла не связано с текущей задачей | Проверьте, содержат ли @-ссылки и файлы контекста нерелевантное содержимое | Сократите ненужное содержимое файла контекста, оставьте только то, что нужно текущей задаче |
Настройки прокси
В этом разделе объясняется, как обеспечить Pi Agent нормальный доступ к API в среде с ограниченным сетевым доступом.
Доступ к API из Китая
Настройте HTTP-прокси в settings.json:
{
"httpProxy": "http://127.0.0.1:7890"
}
Или запустите после настройки переменных среды:
$ export HTTP_PROXY=http://127.0.0.1:7890 $ export HTTPS_PROXY=http://127.0.0.1:7890 $ piДругие расширения