Справочное руководство по конфигурации Pi Agent
Ниже представлена краткая справочная таблица по элементам конфигурации Pi Agent settings.json.
В этой таблице перечислены общие элементы конфигурации; некоторые расширенные ключи, специфичные для JSON (такие как tuiMode, серия fullscreen, terminal.hyperlinks, markdown.mermaid и т. д.), не перечислены по отдельности.
Расположение файла конфигурации
Конфигурация делится на два уровня: глобальный и проектный. Проектная конфигурация загружается только после подтверждения доверия к проекту.
| Путь к файлу | Область действия | Описание |
|---|---|---|
| ~/.pi/agent/settings.json | Глобальные (все проекты) | Общая конфигурация, действующая для всех проектов |
| .pi/settings.json | Уровень проекта | Загружается только после подтверждения доверия к проекту; переопределяет ключи с тем же именем в глобальной конфигурации. |
Модель и рассуждения
Конфигурация в этом разделе определяет провайдера, модель и уровень рассуждений по умолчанию.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| defaultProvider | string | Optional | Нет (задаётся при первом использовании через /login или /model) | Провайдер по умолчанию, например, "anthropic", "openai" |
| defaultModel | string | Optional | Нет (задаётся при первом использовании через /login или /model) | ID модели по умолчанию, например, "claude-sonnet-4-20250514" |
| defaultThinkingLevel | string | Optional | Нет (не указано в документации) | Уровень рассуждений по умолчанию: off/minimal/low/medium/high/xhigh/max |
| modelThinkingLevels | объект | Optional | Отсутствует | Установите уровень рассуждений при запуске для каждой модели по "provider/modelId" |
| hideThinkingBlock | логическое значение | Optional | false | Скрыть процесс рассуждений |
| showCacheMissNotices | логическое значение | Optional | false | Показывать уведомления о промахах кэша |
| thinkingBudgets | объект | Optional | Нет (пользовательский бюджет не включён) | Настроить бюджет токенов для каждого уровня |
| warnings.anthropicExtraUsage | логическое значение | Optional | истина | Напоминать, когда подписка Anthropic может повлечь платное дополнительное использование |
Интерфейс и отображение
Конфигурация в этом разделе управляет внешним видом интерфейса, внешним редактором и плотностью отображения.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| theme | string | Optional | "dark" | Название темы |
| externalEditor | string | Optional | Использует $VISUAL, затем $EDITOR; в противном случае использует Notepad в Windows и nano в других системах | Команда внешнего редактора (явная конфигурация имеет приоритет над переменными среды) |
| quietStartup | логическое значение | Optional | false | Скрыть заголовок при запуске |
| defaultProjectTrust | string | Optional | "ask" | Поведение по умолчанию для доверия к проекту: "ask" (запрос), "always" (автоматическое доверие), "never" (автоматическое отклонение); действует только в глобальной конфигурации |
| collapseChangelog | логическое значение | Optional | false | Свернуть журнал изменений |
| enableInstallTelemetry | логическое значение | Optional | истина | Анонимная статистика установок |
| enableAnalytics | логическое значение | Optional | false | Аналитика поведения пользователей (требуется согласие) |
| doubleEscapeAction | string | Optional | "tree" | Действие, запускаемое двойным нажатием Escape; по умолчанию открывает браузер дерева сеансов |
| treeFilterMode | string | Optional | "default" | /tree режим фильтра по умолчанию: default/no-tools/user-only/labeled-only/all |
| editorPaddingX | число | Optional | 0 | Горизонтальный отступ редактора (0-3) |
| outputPad | число | Optional | 1 | Отступ сообщения (0 или 1) |
| autocompleteMaxVisible | число | Optional | 5 | Максимум записей автодополнения (3-20) |
Сеть
Конфигурация в этом разделе используется для доступа через прокси в сетях с ограничениями.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| httpProxy | string | Optional | Нет (прокси не используется) | HTTP-прокси (только глобально) |
httpProxyДействует только в глобальной конфигурации; игнорируется, если указан в конфигурации уровня проекта.
Когда требуется прокси, запишите его в глобальную конфигурацию.~/.pi/agent/settings.json。
Сжатие
Конфигурация в этом разделе управляет политикой срабатывания и сохранения автоматического сжатия контекста.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| compaction.enabled | логическое значение | Optional | истина | Автоматическое сжатие |
| compaction.reserveTokens | число | Optional | 16384 | Зарезервированные токены для ответа LLM |
| compaction.keepRecentTokens | число | Optional | 20000 | Недавние токены для сохранения |
Сводка по ветке
Конфигурация в этом разделе управляет тем, создавать ли сводку по заброшенным веткам при переходе между деревьями сессий.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| branchSummary.reserveTokens | число | Optional | 16384 | Зарезервированные токены для сводки |
| branchSummary.skipPrompt | логическое значение | Optional | false | Пропустить запрос сводки |
Повторить
Конфигурация в этом разделе управляет поведением автоматических повторных попыток после сбоев запросов.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| retry.enabled | логическое значение | Optional | истина | Автоматический повтор |
| retry.maxRetries | число | Optional | 3 | Максимальное количество повторных попыток |
| retry.baseDelayMs | число | Optional | 2000 | Базовая задержка (ms) |
| retry.provider.timeoutMs | число | Optional | Значение по умолчанию SDK | Тайм-аут запроса |
| retry.provider.maxRetries | число | Optional | 0 | Количество повторных попыток на уровне провайдера |
| retry.provider.maxRetryDelayMs | число | Optional | 60000 | Максимальная задержка повторной попытки |
Передача сообщений
Конфигурация в этом разделе определяет, как вставляются директивные сообщения и последующие сообщения, а также используемый транспортный протокол.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| steeringMode | string | Optional | "one-at-a-time" | Политика директивных сообщений: "all" (вставлять все директивные сообщения сразу) или "one-at-a-time" (вставлять по одному) |
| followUpMode | string | Optional | "one-at-a-time" | Политика последующих сообщений |
| transport | string | Optional | "auto" | Транспортный протокол: sse / websocket / websocket-cached / auto |
| httpIdleTimeoutMs | число | Optional | 300000 | Тайм-аут простоя HTTP |
| websocketConnectTimeoutMs | число | Optional | 15000 | Тайм-аут подключения WebSocket |
Терминал и изображения
Конфигурация в этом разделе управляет размером отображения и поведением отправки изображений в терминале.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| terminal.showImages | логическое значение | Optional | истина | Отображать изображения в терминале |
| terminal.imageWidthCells | число | Optional | 60 | Ширина изображения (ячейки) |
| terminal.clearOnShrink | логическое значение | Optional | false | Очищать пустые строки при уменьшении содержимого |
| images.autoResize | логическое значение | Optional | истина | Автоматическое масштабирование изображений |
| images.blockImages | логическое значение | Optional | false | Запретить отправку изображений в LLM |
Шелла
Конфигурация в этом разделе используется для настройки оболочки и обёртки npm при выполнении команд.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| shellPath | string | Optional | Нет (использовать системную оболочку по умолчанию) | Пользовательский путь к оболочке |
| shellCommandPrefix | string | Optional | Нет (префикс не добавляется) | Префикс команды |
| npmCommand | string[] | Optional | Нет (вызывать npm напрямую) | Обёртка команды npm |
Встроенные инструменты
Конфигурация в этом разделе управляет набором встроенных инструментов, включённых по умолчанию при запуске.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| defaultTools | string[] | Optional | Нет (использовать встроенный набор инструментов по умолчанию) | Изначально включённые встроенные инструменты, возможные значения: read/bash/powershell/edit/write/grep/find/ls, при этом powershell доступен только в Windows |
Эта конфигурация влияет только на встроенные инструменты; пользовательские инструменты, зарегистрированные расширениями и SDK, не затрагиваются.
Массив defaultTools уровня проекта полностью заменяет глобальный массив.
Цикл моделей и ресурсы
В этом разделе настраивается область действия цикла моделей по Ctrl+P, а также пути загрузки ресурсов, таких как расширения и навыки.
| Элемент конфигурации | Type | Обязательный | Значение по умолчанию | Описание |
|---|---|---|---|---|
| enabledModels | string[] | Optional | Нет (все доступные модели) | Доступные модели по Ctrl+P |
| packages | массив (смешанные строки или объекты) | Optional | [] | Источник пакета; строковая форма загружает все ресурсы, объектная форма фильтрует с использованием таких полей, как {source, skills, extensions} |
| extensions | string[] | Optional | [] | Путь к расширению |
| skills | string[] | Optional | [] | Путь к навыку |
| prompts | string[] | Optional | [] | Путь к шаблону |
| темы | string[] | Optional | [] | Путь к теме |
| enableSkillCommands | логическое значение | Optional | истина | Зарегистрировать команду /skill:name |
| sessionDir | string | Optional | Нет (использует ~/.pi/agent/sessions/) | Каталог хранения сессий |