Объяснение конфигурации Pi Agent

Pi Agent использует конфигурационные файлы в формате JSON, поддерживая как глобальную конфигурацию, так и конфигурацию уровня проекта.


Расположение файла конфигурации

Pi Agent читает конфигурацию из двух фиксированных путей, и у них разные приоритеты.

Путь к файлуОбласть действияОписание
~/.pi/agent/settings.jsonГлобальные (все проекты)Общая конфигурация, применимая ко всем проектам
.pi/settings.jsonУровень проектаДействует только для текущего проекта и переопределяет глобальную конфигурацию

Вы можете напрямую редактировать JSON-файл или использовать команду/settingsв интерактивном режиме для изменения общих параметров.


Конфигурация модели и рассуждений

Следующие элементы конфигурации управляют тем, какой провайдер и модель используются по умолчанию, и как распределяется бюджет рассуждений.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
defaultProviderstring-Провайдер по умолчанию, например, "anthropic", "openai"
defaultModelstring-ID модели по умолчанию
defaultThinkingLevelstring-Уровень рассуждений по умолчанию, варианты: off / minimal / low / medium / high / xhigh / max
hideThinkingBlockлогическое значениеfalseСкрывать процесс рассуждений ИИ по умолчанию
showCacheMissNoticesлогическое значениеfalseПоказывать уведомления о промахах кэша
thinkingBudgetsобъект-Настроить бюджет токенов для каждого уровня

Пример настраиваемого бюджета рассуждений:

Пример

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

Следует отметить, что приведённые ниже значения предназначены только для демонстрации и не являются официальными значениями по умолчанию.

Значение каждого уровня и соответствующий ему пример бюджета приведены ниже:

УровеньПрименимый сценарийПример бюджета
минимальныйПочти без рассуждений, цель — максимально быстрый ответ1024
lowПростые вопросы и ответы, а также небольшие изменения4096
среднийВыбор по умолчанию для повседневных задач программирования10240
высокийСложный рефакторинг и диагностика сложных проблем32768

Конфигурация интерфейса и отображения

Следующие параметры конфигурации управляют внешним видом темы, макетом редактора и поведением при запуске.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
themestring"dark"Название темы
externalEditorstringАвтоматически выбирается в зависимости от системыКоманда внешнего редактора, открываемого с помощью Ctrl+G
quietStartupлогическое значениеfalseСкрыть информацию в заголовке при запуске
collapseChangelogлогическое значениеfalseПоказывать ли свёрнутый список изменений после обновлений
editorPaddingXчисло0Горизонтальный отступ редактора (0-3)
outputPadчисло1Горизонтальные отступы области сообщений (0 или 1)
autocompleteMaxVisibleчисло5Максимальное количество отображаемых вариантов автодополнения (3-20)

Рекомендуемая конфигурация внешнего редактора для пользователей VS Code:

Пример

{
  "externalEditor": "code --wait"
}

--waitПараметр гарантирует, что Pi Agent возобновит работу только после того, как VS Code закроет файл; в противном случае Pi Agent продолжит выполнение сразу после открытия редактора.


Конфигурация сети

Следующие параметры конфигурации управляют прокси, который Pi Agent использует при доступе к API моделей.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
httpProxystring-URL HTTP-прокси (только для глобальной конфигурации)

Настройка прокси (для сред, таких как материковый Китай, где требуется прокси для доступа к API):

Пример

{
  "httpProxy": "http://127.0.0.1:7890"
}

Конфигурация сжатия контекста

Когда контекст приближается к своему лимиту, Pi Agent автоматически сжимает исторические сообщения. Эти настройки управляют тем, когда запускается сжатие и что сохраняется.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
compaction.enabledлогическое значениеистинаВключить автоматическое сжатие
compaction.reserveTokensчисло16384Токены, зарезервированные для ответа LLM
compaction.keepRecentTokensчисло20000Количество последних токенов, сохраняемых несжатыми

Конфигурация повторных попыток

Следующие элементы конфигурации определяют поведение автоматических повторных попыток после сбоев запросов, включая количество повторов и интервал отсрочки.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
retry.enabledлогическое значениеистинаВключить автоматические повторные попытки
retry.maxRetriesчисло3Максимальное количество повторных попыток
retry.baseDelayMsчисло2000Базовая задержка повторной попытки (миллисекунды), экспоненциальная задержка: 2s, 4s, 8s
retry.provider.timeoutMsчислоЗначение по умолчанию SDKТайм-аут запроса (миллисекунды)
retry.provider.maxRetriesчисло0Количество повторных попыток на уровне провайдера

Рекомендуется оставлятьretry.provider.maxRetriesего равным 0, если только вам действительно не нужны повторы на уровне провайдера.

Установка значения больше 0 может привести к тому, что повторы на уровне SDK будут блокировать Pi Agent при превышении лимитов использования, вместо того чтобы позволить механизму повторных попыток Pi Agent обработать это.


Конфигурация доставки сообщений

Следующие элементы конфигурации управляют тем, когда и как сообщения, которые вы вставляете в диалог, отправляются модели.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
steeringModestring"one-at-a-time"Стратегия отправки управляющих сообщений: "all" или "one-at-a-time"
followUpModestring"one-at-a-time"Стратегия отправки последующих сообщений
transportstring"auto"Протокол передачи: "sse", "websocket", "websocket-cached", "auto"

Конфигурация терминала и изображений

Следующие элементы конфигурации управляют тем, как изображения отображаются в терминале и как они обрабатываются перед отправкой модели.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
terminal.showImagesлогическое значениеистинаОтображать изображения в терминале
terminal.imageWidthCellsчисло60Ширина встроенного изображения (ячейки терминала)
images.autoResizeлогическое значениеистинаМасштабировать изображения до размеров в пределах 2000x2000
images.blockImagesлогическое значениеfalseБлокировать отправку всех изображений в LLM

Конфигурация оболочки

Следующие элементы конфигурации управляют оболочкой и префиксом команды, используемыми, когда Pi Agent выполняет команды bash.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
shellPathstring-Пользовательский путь к оболочке
shellCommandPrefixstring-Префикс для каждой команды bash
npmCommandstring[]-Пользовательская команда для операций с пакетами npm

Пример использования таких инструментов, как mise или asdf, для управления версией Node.js:

Пример

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

Конфигурация циклического переключения моделей

Следующие элементы конфигурации управляют тем, какие модели можно увидеть при циклическом переключении моделей с помощью Ctrl+P.

Элемент конфигурацииTypeЗначение по умолчаниюОписание
enabledModelsstring[]-Список моделей, доступных при циклическом переключении с Ctrl+P, поддерживает подстановочные знаки

Пример

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Правила слияния конфигурации

Конфигурация проекта (.pi/settings.json) переопределяет глобальную конфигурацию (~/.pi/agent/settings.json).

Вложенные объекты используютслияние, а не замену. Следующий пример иллюстрирует это.

Глобальный файл конфигурации ~/.pi/agent/settings.json:

Пример

{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

Файл конфигурации проекта .pi/settings.json:

Пример

{
  "compaction": { "reserveTokens": 8192 }
}

В эффективной конфигурации после слияния theme принимает глобальное значение dark, compaction.enabled принимает глобальное значение true, а compaction.reserveTokens переопределяется конфигурацией проекта на 8192.

Иными словами, конфигурация проекта переопределяет только те поля, которые она явно объявляет, а все остальные поля продолжают использовать глобальную конфигурацию.


Пример полной конфигурации

Ниже приведён типичный глобальный файл конфигурации:

Пример

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

warnings.anthropicExtraUsage — это логическое значение, по умолчанию равное true.

Оно выдаёт напоминание, когда аутентификация подписки Anthropic может повлечь дополнительное платное использование.

packages — это конфигурация фильтра установленных пакетов, используемая для указания, какие пакеты загружать.

Другие расширения