Skip to main content

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

Основной файл конфигурации Велеса обычно находится в ~/.veles/config.json. При запуске с --config можно использовать другой файл. В исполняемой поставке для Windows программа первого запуска копирует соседний config.json в workspace/config.json без изменения байтов. Служебная переменная VELES_PORTABLE_ROOT задаёт каталог установки: рабочая область всегда находится в его подпапке workspace, а шлюз слушает только 127.0.0.1. Эти переопределения применяются при выполнении, не переписывая исходный образец. При обновлении исполняемого файла действующая конфигурация сохраняется. Ключи принимаются в camelCase и snake_case, но в пользовательском JSON лучше держаться camelCase.

Оформление Nerve

Название и подпись рядом с логотипом Nerve задаются переменными окружения самого процесса Nerve и не входят в config.json Велеса:
Заданные значения используются при любом выбранном языке интерфейса. Если пользовательская подпись отсутствует, интерфейс сохраняет встроенную подпись на выбранном языке. Пробельные символы сворачиваются в одиночные пробелы; название ограничено 60 символами, подпись — 120 символами. Пути к изображениям должны начинаться с / и вести к файлам того же сервера. Перед сборкой положите пользовательские файлы в nerve/public, а в переменной укажите путь вида /имя-файла.png. Для верхней панели лучше подходит PNG с прозрачностью. Необязательные изображения оформления высокого разрешения загружаются по запросу и намеренно не входят в предварительный кеш оболочки приложения. Значок устанавливаемого веб-приложения должен быть квадратным изображением 512×512 в формате PNG, JPEG или WebP либо квадратным SVG и иметь достаточные поля для обрезки системной маской. После изменения переменных перезапустите Nerve и обновите страницу. Для обновления значка уже установленного приложения может потребоваться повторная установка. В репозитории уже есть необязательные подготовленные файлы /brand-logo.png с прозрачностью и /brand-logo.jpg. Они не используются по умолчанию. Чтобы включить особый логотип, задайте NERVE_BRAND_LOGO_URL=/brand-logo.png; без этой переменной Nerve сохраняет прежний /favicon-256.png. NERVE_DEFAULT_THEME принимает идентификатор из списка тем Nerve, включая новую коричневую тему brown. Сохранённый пользователем выбор oc-theme всегда имеет приоритет над переменной окружения. После выбора другой темы в настройках браузер сохраняет её при обновлении страницы и перезапуске Nerve. Поэтому переменная задаёт тему для новых профилей браузера и профилей без допустимого сохранённого выбора; неизвестное значение приводит к встроенной теме ayu-dark. Допустимые идентификаторы: midnight, brown, light, porcelain, phosphor, dracula, nord, solarized-dark, catppuccin-mocha, tokyo-night, gruvbox-dark, one-dark, monokai, ayu-dark, rose-pine и monochrome.

Встроенные модули

Раздел modules включает и выключает крупные встроенные возможности продукта. Доступны tasks, calendar и mail; у каждой записи есть только поле enabled. Если раздел или отдельная запись отсутствуют, модуль считается включённым для обратной совместимости.
Изменение применяется после перезапуска шлюза. Выключение не удаляет задачи, источники календаря, почтовые настройки или результаты анализа. Оно не создаёт профиль продукта и не загружает внешний код: набор модулей заранее собран вместе с Велесом. modules.mail.enabled управляет интерактивным разделом «Почта». Отдельный почтовый канал агента по-прежнему включается через channels.email.enabled, поэтому один переключатель не изменяет другой. При выключенном модуле его служба, маршруты, обработчики и фоновые операции не запускаются, а Nerve скрывает соответствующие пункты навигации.

Почтовый клиент

Для почтового клиента Nerve раздел channels.email должен содержать настройки IMAP/SMTP и consentGranted=true. Поле enabled включает отдельный агентский почтовый канал и не требуется разделу «Почта». clientAutoAnalyze управляет фоновой обработкой писем моделью и по умолчанию имеет значение true; pollIntervalSeconds задаёт общий период проверки почты и по умолчанию равен 1800 секундам; clientRemoteImagePolicy выбирает режим внешних изображений block, ask или allow, по умолчанию — ask. Автоматическое чтение для анализа и агентского канала всегда выполняется в режиме просмотра и не меняет отметку прочтения на почтовом сервере. Устаревшее поле markSeen больше не поддерживается и игнорируется. clientMaxBodyChars отдельно ограничивает показываемый текст письма и не меняет более узкий предел maxBodyChars агентского канала. Пароли остаются локальными зашифрованными секретами channels.email.imapPassword и channels.email.smtpPassword.
clientAnalysisModel выбирает модель только для анализа писем и подготовки черновиков. Пустая строка, используемая по умолчанию, означает модель agents.defaults.model. Пробелы по краям удаляются, длина ограничена 500 символами, а сам идентификатор сохраняется без изменения; при agents.defaults.provider=auto префиксы openrouter/..., custom/... и другие поддерживаемые префиксы направляют этот запрос к соответствующему поставщику. Для выбранного маршрута должен быть настроен собственный ключ или выполнен вход, например через veles provider login openai-codex. Результаты анализа сохраняются в workspace/.veles/mail/analysis.db; тела писем и вложения в эту базу не попадают. Это обычный незашифрованный файл SQLite, защищённый правами доступа к рабочей области. Внешние изображения при режиме ask загружаются только после подтверждения пользователя и могут сообщить отправителю об открытии письма.

Редактирование через интерфейс

В настройках Nerve есть раздел «Конфиг». Он читает текущий config.json через шлюз Велеса и строит поля по серверной схеме, включая схемы встроенных каналов. Разделы agents, providers, gateway, modules, interface, channels, tasks, tools, secrets и skills выбираются через выпадающий список. Если внутри раздела есть вложенные объекты, например modules.mail, channels.telegram, tasks.youtrack или tasks.bitrix, рядом появляется второй список подразделов. Такие объекты редактируются обычными полями формы, а не как сырой JSON. Кнопка «Сохранить и перезапустить» записывает файл и сразу планирует перезапуск шлюза, чтобы изменения применились без отдельного ручного действия. Названия полей в форме показываются как обычный текст: например, blockPrivateNetworks отображается как «Block private networks». Если строковое значение в JSON содержит управляющую escape-последовательность вроде \b, поле показывает её явно, чтобы путь или логин не выглядели обрезанными. gateway.token в этом разделе не показывается и не редактируется. При сохранении Велес сохраняет прежнее значение из исходной конфигурации. Значения, которые вынесены в зашифрованные секреты или представлены объектом-ссылкой на секрет, показываются как заглушки; сам секрет через этот раздел не раскрывается. Кнопка «Править JSON» открывает полный физический config.json в обычной вкладке файлового редактора Nerve. Этот режим показывает gateway.token и секреты, если они записаны в файле открытым текстом. Сохранение проверяет JSON и схему Велеса, но не планирует перезапуск шлюза; после такой правки перезапустите шлюз вручную, когда захотите применить изменения.

Общая структура

interface

Раздел interface хранит небольшие несекретные настройки интерфейса, которые должны переживать перезапуск Nerve и быть одинаковыми в разных браузерах. Сейчас в нём есть usageBadgeMetric — ключ показателя для компактного значка расхода в виде <поставщик>:<показатель>, например openai_codex:weekly. Обычно это поле не нужно править вручную: выбор в разделе внешнего вида Nerve сохраняется через Велес без перезапуска шлюза. Значение из хранилища браузера используется только до подключения к шлюзу и для однократного переноса прежней настройки.

agents

Раздел agents.defaults задаёт поведение Велеса по умолчанию. agents.defaults остаётся глобальной конфигурацией по умолчанию. Конкретная личность может иметь собственные model и thinkingLevel в personality.json; это не создаёт отдельную рабочую область, память или набор сессий.
Важные поля:

compression — сжатие контекста

Блок agents.defaults.compression управляет сжатием контекста: когда беседа разрастается, Велес заменяет старые ходы одним структурированным резюме, а свежие сообщения и системный промпт сохраняет дословно. Те же настройки ограничивают контекст внутри одного длинного ответа: старые завершённые вызовы средств сворачиваются в контрольный снимок, полный журнал остаётся неизменным, а модель продолжает исходную задачу со свежим хвостом работы. Это распространяется и на исполнителей режима «Проект». Подробное описание — на странице Сжатие контекста. Если provider равен auto, префиксы в models работают как маршруты к поставщикам. Например, openrouter/... использует OpenRouter, а custom/... использует собственный совместимый адрес и передает ему имя модели без префикса. Если запись модели не содержит modalities или модель не перечислена в списке, Велес считает её текстовой. Вложения-изображения передаются как данные только в модели, где явно указана поддержка image или vision; для остальных моделей Велес убирает данные изображения из запроса и оставляет текстовое описание вложения. reasoningEfforts задаёт точный набор значений в переключателе уровня рассуждения для одной модели. Допустимы off, minimal, low, medium, high, xhigh и max; устаревшее имя uhigh приводится к xhigh. Для моделей с обязательным рассуждением не добавляйте off. Если поле не задано, Nerve получает доступные уровни из каталога OpenRouter. Идентификаторы openrouter/openai/<модель> и openai-codex/<модель> сопоставляются с одной записью openai/<модель> в этом каталоге. Явно заданное поле всегда имеет приоритет и позволяет сохранить нужный набор при недоступности внешнего каталога. Если каталог возвращает supported_efforts: null, модель принимает все уровни шлюза. Если поле supported_efforts отсутствует, модель не предоставляет ручной выбор уровня: Nerve показывает фиксированное значение auto и не передаёт уровень поставщику. При смене модели Nerve одновременно сохраняет новую модель и совместимый с ней уровень, поэтому, например, max от предыдущей модели не переносится в модель без такого уровня.

providers

Каждый провайдер обычно имеет apiKey, apiBase и иногда extraHeaders. Отсутствующий apiKey поставщика не мешает запуску шлюза и открытию Nerve. Велес проверяет выбранный маршрут при первом обращении к модели: явный префикс вроде openrouter/... или custom/... по-прежнему не заимствует ключ другого поставщика. Пока ключ не настроен, запрос к такой модели завершится понятной ошибкой; после сохранения значения в разделе «Секреты» новые запросы используют его без обязательного перезапуска.
OAuth-провайдеры вроде openaiCodex и githubCopilot не требуют обычного apiKey в config.json. Для openaiCodex используется пустой блок-маркер, а токены доступа и обновления остаются только в зашифрованном хранилище:
Сам блок не означает, что вход уже выполнен. Велес считает поставщика подключённым только после успешной проверки его учётных данных. Если поставщик реализует получение баланса или ограничений, его показатели автоматически появляются в панели «Баланс» Nerve и в выборе показателя компактного значка. Интерактивный мастер может показать рекомендуемый адрес apiBase для выбранного провайдера. Это только черновое значение внутри открытого раздела: если выйти назад или отменить раздел, конфигурация не считается изменённой и адрес не сохраняется. Подробнее: Провайдеры и модели.

gateway

Раздел gateway настраивает сервер Велеса: интерфейс, внутренние вызовы, каналы, расписания и периодические проверки.
gateway.token обязателен для запуска сервера. Не публикуйте его и не вставляйте в чат. Если токен удобнее передавать через окружение, используйте VELES_GATEWAY_TOKEN: это значение переопределяет gateway.token из config.json. Второе обязательное условие запуска — корректный VELES_SECRETS_MASTER_KEY в окружении процесса Велеса. Все остальные секреты могут отсутствовать при запуске: шлюз и Nerve останутся доступны, чтобы пользователь заполнил их в разделе «Секреты». Команда veles gateway, включая запуск через uv run veles gateway, перед чтением конфигурации загружает эти переменные из .env текущего рабочего каталога. Значения, которые уже переданы процессу, не заменяются содержимым .env. Велес не ищет такой файл в родительских каталогах. Nerve может запускаться без собственного GATEWAY_TOKEN: после входа пользователя он вызывает auth.login у Велеса, получает текущий токен только в серверный процесс и использует его для внутренних запросов. Пароль Nerve хранится в зашифрованном хранилище Велеса, а не в окружении Nerve.

channels

channels содержит настройки встроенных каналов и каналов-расширений. Общие поля:
allowFrom — белый список отправителей. Пустой список означает запрет всем. Чтобы разрешить всех, укажите ["*"]. Подробнее: Каналы и интеграции.

tasks

Раздел tasks подключает внешние задачи к общей доске Велеса. Локальные задачи по-прежнему хранятся в workspace/tasks, а записи YouTrack и Bitrix24 не копируются в рабочую область: Велес получает их при чтении, объединяет по устойчивому идентификатору источника и недолго хранит последний удачный снимок. Поэтому повторное обновление не создаёт дубликаты.
Ключ сопоставления сравнивается без учёта регистра и окружающих пробелов. Для YouTrack используйте исходное название состояния или приоритета, для Bitrix24 — числовой код; для состояния Bitrix24 также можно указать его отображаемое название. Значение statusMapping должно быть одним из backlog, todo, in-progress, review, done, cancelled. Сопоставление выбирает только колонку и значок: решение о том, является ли задача открытой, можно ли её завершить и можно ли поручить её Велесу, всегда принимается по исходному состоянию системы. Поэтому открытая задача, показанная в колонке done, сохраняет разрешённые действия, а завершённая задача, показанная в todo, их не получает. Токен YouTrack задаётся через цель tasks.youtrack.api_token в панели секретов. Для Bitrix24 повторно вводить значения не нужно: поля задач ссылаются на те же зашифрованные значения, которые использует навык alor-bitrix24. Когда навык обнаружен, в каталоге видны только его две канонические цели; технические псевдонимы задач скрыты. Если навык ещё не установлен, псевдонимы временно показываются как способ первоначальной настройки, но всё равно записывают значения по каноническим идентификаторам навыка. Значения не попадают в config.json открытым текстом и не передаются в Nerve. Перед завершением внешней задачи Велес принудительно перечитывает источник и проверяет, что запись по-прежнему входит в настроенную выборку и допускает это действие. Nerve отдельно просит подтвердить источник, идентификатор и ожидаемый результат, после чего Велес вызывает команду, записывает аудит и ещё раз перечитывает источник. Успех возвращается только после подтверждения, что задача исчезла из открытой выборки или больше не допускает завершение; при включённом контроле Bitrix24 она может перейти в колонку проверки. Неопределённый исход временно блокирует повторное действие до безопасной сверки. Один вызов завершения поэтому может включать три этапа ожидания: предварительное чтение, запись и контрольное чтение; прокси Nerve отводит на весь вызов 120 секунд. Завершение по устаревшим данным запрещено. Обычное редактирование, удаление, перетаскивание и запуск агентом для таких записей также запрещены. Сбой одного источника не блокирует локальные задачи и второй источник; если есть предыдущий удачный снимок, он возвращается только для чтения с признаком устаревания. Действие «Поручить Велесу» не является изменением внешней задачи. После подтверждения Велес создаёт обычную локальную задачу со ссылкой delegatedFrom на исходную запись и сразу запускает её. Для одной внешней задачи создаётся только одна локальная: повторное поручение открывает существующую запись и не запускает параллельного исполнителя. Заголовок и описание из внешней системы считаются недоверенными данными и не дают агенту права автоматически завершать или иначе менять исходную задачу. Оба адреса закреплены за корпоративными службами АЛОР и используют HTTPS. Проверка сертификата не отключается, перенаправления не используются. Для внутреннего YouTrack не нужно выключать tools.blockPrivateNetworks: это ограничение относится к пользовательским веб-инструментам, а не к явно настроенному системному источнику задач. Источник задач не запускает командный клиент навыка alor-bitrix24: тот предназначен для интерактивных действий агента с планом и отдельным подтверждением. Постоянный системный адаптер доски ограничен только чтением списка и завершением после подтверждения в Nerve, но использует те же секреты навыка. Для любых других действий в Bitrix24 используйте сам навык.

tools

Раздел tools управляет встроенными инструментами, веб-поиском, MCP, памятью, распознаванием текста, аудио и глубоким исследованием.
blockPrivateNetworks управляет сетевой защитой инструментов. По умолчанию значение true: Велес блокирует адреса, которые указывают на частные сети, loopback и служебные локальные диапазоны. Если поставить false, exec и загрузка страниц смогут обращаться к внутренним доменам и частным адресам, если среда Велеса видит эту сеть. Для постоянной установки включайте restrictToWorkspace, особенно если включён exec или внешние MCP-серверы. Подробнее: Инструменты, веб-поиск и MCP. Для поиска через Exa укажите tools.web.search.provider="exa". Структура раздела не меняется: apiKey остаётся общей ссылкой на зашифрованный ключ выбранного сервиса, а maxResults задаёт число результатов. Пустое apiKey включает доступ без ключа с ограничениями Exa. При переключении замените прежний ключ или явно очистите поле: смена названия сервиса не меняет сохранённый ключ автоматически. Exa подключается непосредственно через MCP и не требует установки Agent-Reach. Адрес фиксирован, baseUrl не используется; общий tools.web.proxy учитывается. Автоматического перехода на другой поисковик при ошибке Exa нет.

sessionMemory и memoryFlush

sessionMemory управляет сохранением итогов завершённых сессий в память.
deleteBehavior: "hide" скрывает сессии из списков интерфейса Велеса, но оставляет точный поиск и возможность повторной активации. delete физически удаляет файлы через обычные пути удаления.

vectorMemory

Векторная память индексирует проектные файлы внутри workspace/docs/<project>, а также файлы долговременной памяти. Документация самого Велеса при старте копируется в workspace/docs/agent рекурсивно, включая .md и .mdx, поэтому её можно искать как проект agent. Пустые файлы и фрагменты, состоящие только из пробелов, пропускаются и не отправляются в модель эмбеддингов.
В индекс попадают поддерживаемые текстовые файлы из docs/<project>/, MEMORY.md в корне рабочей области, если он есть, и заметки memory/**/*.md, включая memory/MEMORY.md. Сырые аварийные архивы memory/*-raw-archive.md сохраняются для восстановления, но не индексируются. Файлы крупнее maxFileBytes также остаются на диске, однако исключаются из смыслового и ключевого поиска. Значение по умолчанию — 8 МиБ, допустимый верхний предел — 64 МиБ. До первого запроса к поставщику Велес полностью подсчитывает фрагменты во временной дисковой базе, проверяет предел в 8192 фрагмента и нижнюю оценку объёма текстовой записи. Когда первый ответ определяет размерность вектора, полная оценка поколения с векторами проверяется до их упаковки и публикации. Поколение с расчётной записью более 64 МиБ не индексируется — такой файл нужно разделить. Если превышено именно число фрагментов, можно также увеличить chunkTokens или уменьшить chunkOverlap. Велес обрабатывает один файл ограниченными порциями, временно складывает подготовленные данные отдельно и только затем целиком заменяет прежнее поколение индекса. Перечень найденных и уже индексированных путей тоже не накапливается в памяти: потоки имён записываются порциями во временную дисковую базу, которая задаёт порядок и позволяет точно находить исчезнувшие файлы. Если каталог временно не удалось обойти полностью, прежние записи на этом проходе не скрываются. chunkTokens принимает значения от 1 до 8192, чтобы ограничивать размер одного элемента запроса; chunkOverlap должен быть меньше chunkTokens, а syncIntervalSeconds — не меньше 1 секунды. За один проход полное чтение, первичное хеширование или переиндексация выполняются не более чем для 20 файлов. Кроме того, суммарная расчётная запись поколений ограничена 64 МиБ, а обращения к поставщику получают отдельный общий бюджет. Если одному допустимому файлу требуется больше обычного бюджета обращений, он не делит этот бюджет с другим файлом: так предел остаётся жёстко связан с 8192 фрагментами и обработка не застревает в середине файла. Поэтому смена модели и постепенное заполнение признаков старой схемы не запускают неограниченную массовую работу. Неудачный запрос к поставщику открывает общую паузу с постепенным увеличением, поэтому остальные файлы не создают сотни одинаковых сбоев. Изменение файла во время обработки не оставляет частичный результат; та же повторная проверка защищает удаление прежнего поколения при отклонении нового. При временной недоступности поставщика сохраняется полный ключевой индекс, а смысловая часть повторяется после паузы. Для неизменившихся файлов Велес сравнивает сохранённые признаки файловой системы и не перечитывает всё содержимое каждые 60 секунд. Для новых и обновлённых фрагментов двоичный вектор в chunks_vec является единственным рабочим представлением; устаревшее текстовое представление в chunks.embedding больше не дублируется. Старые строки остаются совместимыми и автоматически не переписываются, поэтому размер уже существующего memory/vector.db сам по себе не уменьшится. До добавления в прежнюю таблицу files столбцов, которые скрыли бы смысл старого формата, Велес отдельно сохраняет сведения о нём и о неизвестном профиле. Затем формат хранилища определяется по компактному списку файлов, без полного чтения крупных таблиц при каждом запуске. Число оставшихся старых поколений уменьшается в той же транзакции, которая скрывает или заменяет их; после последнего такого поколения новые файлы снова могут получать смысловой индекс. При смешанном старом хранилище доступные двоичные строки продолжают участвовать в смысловом поиске, но Велес не пытается доказывать полноту и не дописывает отсутствующие строки массово во время запуска. Не удаляйте, не уплотняйте и не заменяйте эту базу во время работы Велеса.

Ручное уплотнение

Обычная фоновая очистка делает освобождённые страницы базы доступными для повторного использования, но не сокращает сам vector.db. Для физического уплотнения остановите шлюз и все процессы агента, затем сначала проверьте план, а после примените его:
Это не новая настройка config.json: команда использует выбранную конфигурацию и рабочую область. Она переносит только живые строки в проверенную теневую базу, заново строит полнотекстовый индекс и переносит достоверные старые JSON-векторы в двоичное хранилище. Исторические нулевые заглушки считаются отсутствующими смысловыми данными, но соответствующие фрагменты остаются в полнотекстовом поиске; к поставщику модели команда не обращается. Исходные файлы и записи памяти не изменяются. Байт-в-байт резервная копия с отметкой времени всегда остаётся в memory. Поэтому уплотнение сокращает активный vector.db, но не общий объём занятого места. Перемещайте или удаляйте эту копию вручную только после проверки новой базы. Подробный порядок описан в разделе командной строки и эксплуатации.

secrets

secrets описывает источники SecretRef: окружение, файл или команду.
Для локального зашифрованного хранилища нужен VELES_SECRETS_MASTER_KEY. Он обязателен уже при запуске шлюза; через Nerve его задать нельзя. Подробнее: Секреты и токены.

skills

skills.entries включает настройки отдельных навыков.
Секреты окружения, объявленные навыком, могут появляться автоматически из метаданных SKILL.md, даже если вы не добавляли их вручную в config.json. requires.env делает секрет обязательным для доступности навыка, а secrets.env создаёт опциональную цель в панели секретов. Обычные параметры навыка помещайте в config, а секреты — в env через ссылку на зашифрованное хранилище. Например, Teamly ALOR хранит логин и выбор домена как настройки, а пароль отдельно:
Такая же запись есть в scripts/config.template.json. Значения username, adDomainId и accountSlug не маскируются, а пароль настраивается только через панель секретов.

skillMarketplaces

Массив skillMarketplaces описывает источники, из которых интерфейс Nerve может устанавливать навыки. Файлы источников загружает и хранит только шлюз Велеса. Поддерживаются репозитории GitHub и GitLab.
Общие поля записи: Пользователь не задаёт id, path, removable и editable: для добавленной им записи шлюз создаёт идентификатор UUID версии 4, а в пути использует его полную компактную запись без дефисов. Для пользовательской записи шлюз всегда сохраняет оба флага со значением true. В начальном scripts/config.template.json уже заданы каталоги «Alor Public skills» и «Alor Internal skills». У них removable=false и editable=false: их можно синхронизировать и использовать, но нельзя изменять или удалять. Для GitHub поле repositoryUrl обязательно и принимает только публичный адрес HTTPS. Для GitLab разрешён адрес HTTP или HTTPS на любом узле; адрес не должен содержать учётные данные, строку запроса или фрагмент. Поле branch можно оставить пустым, тогда используется ветка репозитория по умолчанию. Для указанной ветки шлюз выполняет отдельное неглубокое клонирование без подмодулей. На Windows загрузка, сканирование, копирование и удаление используют поддержку длинных путей, поэтому глубина дерева репозитория не зависит от обычного ограничения пути Windows. После успешного добавления, изменения или синхронизации служебная папка маркетплейса содержит только каталог source и файл skills.json. Временные каталоги загрузки и резервные копии удаляются до успешного ответа, в том числе если Git создал файлы с атрибутом «только чтение». При запуске следующей операции шлюз также восстанавливает прерванную замену и очищает оставшиеся служебные каталоги.