Настройки

Настройки Veai CLI хранятся в JSON-файлах settings.json на двух уровнях:

Уровень	Файл	Где действует
Глобальный	~/.veai/settings.json	во всех проектах
Проектный	<проект>/.veai/settings.json	только в текущем проекте

Проект — это каталог, из которого запущен veai. Файл .veai/settings.json в родительских каталогах не читается.

Файлы не обязаны существовать, и ошибка в них не ломает сессию. Если файла нет или у значения неверный тип, используется значение по умолчанию. Если файл перестал быть корректным JSON во время сессии, агент продолжает работать с последними успешно прочитанными значениями.

tip

Попросите агента: «Включи уведомления на рабочем столе» или «Отвечай на английском во всех проектах». Он сам выберет файл и уровень и не тронет остальные ключи.

Формат файла

Настройки сгруппированы по разделам. Каждый раздел — объект с ключами внутри:

{
  "rules": {
    "disabledRules": ["project:AGENTS.md"]
  },
  "skills": {
    "disabledSkills": ["pdf-tools"]
  },
  "subagents": {
    "maxConcurrency": 20
  }
}

При ручной правке меняйте только нужный ключ и сохраняйте остальное содержимое файла.

Все параметры

Ключ	Тип	По умолчанию	Назначение
ui.language	"ru" или "en"	"ru"	язык ответов агента, названий чатов, подсказок и описаний команд /
permissions.defaultMode	строка	"default"	режим разрешений, в котором стартует новый чат: default, paranoid или bypassPermissions. Только глобальный уровень
afk.maxContinuations	положительное целое	10	сколько раз режим afk просит модель продолжить работу после последнего сообщения пользователя. Только глобальный уровень
sessionTitle.enabled	логическое	true	генерировать ли короткое название чата после первого ответа. Только глобальный уровень
rules.disabledRules	массив строк	[]	ID отключённых правил, см. «Правила»
skills.disabledSkills	массив строк	[]	имена отключённых скиллов, см. «Скиллы»
subagents.maxConcurrency	положительное целое	20	сколько субагентов может одновременно работать или ждать запуска
subagents.disabledAgents	массив строк	[]	имена отключённых вспомогательных агентов
subagents.disabledProfiles	массив строк	[]	имена отключённых профилей моделей
tui.mascot	строка	"cat"	анимированный маскот в строке статуса: cat, snake, pacman, tetris, fishing, robot, pong, crab или custom
tui.customMascotFrames	массив строк	[]	кадры собственного маскота, по строке на кадр
tui.customMascotText	строка	"Working…"	слово рядом с собственным маскотом
tui.tips	логическое	true	показывать ли подсказки под строкой статуса, пока агент работает
tui.quickSwitchSeconds	число	1.5	сколько секунд панель быстрого переключения Shift+Tab ждёт после последнего нажатия, прежде чем применить выбор
tui.recentModels	массив строк	[]	недавние модели в формате "<provider>/<id>"; заполняется автоматически
notifications.enabled	логическое	false	уведомления на рабочем столе
notifications.onDone	логическое	true	уведомлять, когда запущенная задача завершилась
notifications.onInput	логическое	true	уведомлять, когда агент ждёт ответа в диалоге
notifications.onError	логическое	true	уведомлять, когда задача остановилась из-за ошибки модели
notifications.sound	строка	"off"	звук: off, bell или system
notifications.whenFocusUnknown	строка	"off"	что делать, если терминал не может определить, активно ли его окно: off, idle или always
notifications.idleSeconds	целое	60	для idle: сколько секунд без нажатий ждать перед уведомлением, от 5 до 3600

Списки отключённых правил, скиллов, агентов и профилей сравниваются точно и с учётом регистра. Шаблоны не поддерживаются: "pdf-*" ничего не отключит. Запись, которая ни с чем не совпала, не считается ошибкой.

Как сочетаются уровни

• Списки (disabledRules, disabledSkills, disabledAgents, disabledProfiles) не заменяют друг друга: элемент отключён, если он указан хотя бы на одном уровне. Исключение — правила проекта: их можно отключить только в проектном settings.json.
• subagents.maxConcurrency и ui.language: значение проекта переопределяет глобальное.
• permissions.defaultMode, afk.maxContinuations, sessionTitle.enabled, tui.* и notifications.* читаются только из глобального ~/.veai/settings.json. В проектном файле они игнорируются — так склонированный репозиторий не может, например, выключить подтверждения действий.

Язык

ui.language задаёт язык ответов агента, генерируемых названий чатов, подсказок и описаний в списке команд /. Названия самих команд остаются на английском. Если язык не задан ни на одном уровне, используется русский.

В терминале язык можно переключить командой /language ru или /language en — она записывает значение в ~/.veai/settings.json. Команда /language без аргумента показывает текущий язык и откуда он взят. Изменение действует со следующей сессии.

Режим разрешений при старте

permissions.defaultMode задаёт режим, в котором начинается каждый новый чат. Пригодится, если вы всегда работаете в одном режиме, например без подтверждений:

{ "permissions": { "defaultMode": "bypassPermissions" } }

Допустимые значения — default, paranoid и bypassPermissions. Режим afk здесь задать нельзя: он предназначен для одного запуска без присмотра. Любое другое значение запускает чат в режиме default.

Режим, выбранный в чате через /mode, Shift+Tab или флаг --permission-mode, имеет приоритет. Изменение настройки действует для следующего нового чата.

Субагенты отдельной настройки режима не имеют: они стартуют в режиме родительской сессии.

Режим afk

afk — режим для работы без присмотра. Агент ничего не спрашивает, а после каждого ответа просит модель продолжить, пока она не завершит работу или пока не исчерпается лимит продолжений:

{ "afk": { "maxContinuations": 25 } }

Чат, сохранённый в режиме afk, при повторном открытии переходит в bypassPermissions.

Уведомления на рабочем столе

Уведомления выключены, пока notifications.enabled не равно true. Пока окно терминала активно, уведомления не отправляются. Команда /notify в терминале открывает меню, которое меняет те же ключи и отправляет тестовое уведомление.

{
  "notifications": {
    "enabled": true,
    "sound": "bell",
    "whenFocusUnknown": "idle",
    "idleSeconds": 120
  }
}

Определить активное окно терминал может только в Linux с X11. В tmux и screen, по SSH, в Wayland, macOS и Windows это неизвестно, и поведение задаёт notifications.whenFocusUnknown:

• off — не отправлять уведомления;
• idle — отправлять, если в сессии не нажимали клавиш notifications.idleSeconds секунд;
• always — отправлять всегда.

Если уведомления не приходят, попробуйте "whenFocusUnknown": "idle". Если не слышен звук при sound: "system", проверьте системные настройки уведомлений (режим «Не беспокоить», звук для приложения) или используйте sound: "bell".

Внешний вид терминала

Маскот

Команда /mascot переключает маскота сразу. Можно нарисовать своего — укажите кадры, подпись и "mascot": "custom":

{
  "tui": {
    "mascot": "custom",
    "customMascotText": "Quacking…",
    "customMascotFrames": ["🦆      ", " 🦆     ", "  🦆    ", "   🦆   "]
  }
}

Каждый кадр показывается 120 мс, затем список повторяется. Делайте кадры одинаковой ширины; эмодзи занимает две колонки. Кадр или подпись шире 40 колонок обрезается.

Подсказки и быстрое переключение

• "tips": false скрывает строку подсказок под строкой статуса.
• quickSwitchSeconds задаёт, сколько ждёт панель Shift+Tab перед тем, как применить выбранные режим, модель и уровень размышлений. Enter применяет выбор сразу, Esc отменяет.
• recentModels агент заполняет сам при каждой смене модели и хранит до 5 моделей. Чтобы очистить список, запишите [].

Настройки агента: veai config

Часть настроек относится к самому агенту, а не к проектам. Они хранятся в отдельном settings.json в каталоге установки (по умолчанию ~/.local/share/veai-ai-agent/agent/settings.json, в Windows — %USERPROFILE%\.local\share\veai-ai-agent\agent\settings.json), а не в .veai/. Меняйте их командой veai config:

veai config set autoUpdate false
veai config set updateChannel stable
veai config set cacheWarming streaming
veai config get cacheWarming

Ключ	Значения	По умолчанию	Назначение
updateChannel	stable, dogfood	stable	канал обновлений; dogfood получает предварительные версии раньше
autoUpdate	true, false	true	false отключает фоновую проверку обновлений; veai update продолжает работать
cacheWarming	off, streaming, idle	off	прогрев кэша модели

Прогрев кэша поддерживает кэш промпта у провайдера: незадолго до его истечения агент повторяет последний запрос с ограничением ответа в один токен, чтобы следующий настоящий запрос стоил дешевле. Каждый такой запрос оплачивается. В режиме streaming прогрев идёт, пока агент работает над задачей. В режиме idle прогрев продолжается ещё до 30 минут после последнего запроса — это самый затратный вариант. Прогрев работает только с моделями, для которых известно время жизни кэша: во встроенном каталоге это модели Anthropic (Claude).

Режим отображения терминала меняется командой /settings:

Пункт /settings	Значения	По умолчанию
TUI mode	fullscreen, regular	fullscreen
Fullscreen copy on select	true, false	false

В полноэкранном режиме разговор прокручивается внутри окна (колесо мыши, PgUp/PgDn, Ctrl+Home/Ctrl+End), а выделенный мышью текст копируется сочетанием Ctrl+X. Режим regular выводит разговор в обычную историю терминала. Чтобы один раз запустить сессию в этом режиме без изменения настроек, используйте veai --tui-mode regular.

Переменная окружения VEAI_OFFLINE=1 отключает проверку обновлений и обновление каталога моделей. Запросы к моделям, веб-поиску, MCP-серверам и Telegram при этом продолжают отправляться.