Справочник по конфигурации
В этом документе перечислены все настраиваемые параметры Elftia, сгруппированные по функциональным областям.
Переменные окружения
Frontend (Vite / VITE_*)
Переменные окружения frontend открываются с префиксом VITE_ и доступны в коде React через import.meta.env.
| Переменная | Тип | По умолчанию | Описание |
|---|
VITE_APP_TITLE | string | 'Elftia' | Название приложения |
VITE_DEV_PORT | number | 5375 | Порт Vite Dev Server |
Backend (Main Process)
| Переменная | Тип | По умолчанию | Описание |
|---|
LOG_LEVEL | string | 'info' | Уровень логирования (debug / info / warn / error) |
NODE_ENV | string | 'development' | Среда выполнения |
ELECTRON_IS_DEV | string | '1' | Запущено ли приложение в режиме разработки |
Предпочтения приложения (AppPreferences)
Чтение/запись через window.api.appPreferences. Хранится в базе данных SQLite.
| Поле | Тип | По умолчанию | Описание |
|---|
sendByCtrlEnter | boolean | false | Отправлять сообщения с помощью Ctrl+Enter |
autoScrollToBottom | boolean | true | Автоматически прокручивать вниз при новых сообщениях |
showThinking | boolean | true | Показывать процесс мышления модели |
autoExpandTools | boolean | false | Автоматически раскрывать детали вызовов инструментов |
showRawParameters | boolean | false | Показывать необработанные параметры вызовов инструментов |
Конфигурация темы (Theme)
Чтение/запись через window.api.theme. Полная структура состояния:
Режим
| Поле | Тип | По умолчанию | Описание |
|---|
mode | 'light' | 'dark' | 'system' | 'system' | Режим темы |
Пользовательская тема (UserTheme)
| Поле | Тип | Описание |
|---|
colors | Record<string, string> | Переопределения пользовательских цветовых токенов |
fonts | { ui?: string; code?: string; display?: string } | Пользовательские шрифты |
Пользовательский CSS
| Поле | Тип | По умолчанию | Описание |
|---|
customCss | string | '' | Пользовательский CSS, внедряемый пользователем |
Обои
Все поля, связанные с обоями, находятся в ThemePreferencesSchema (packages/desktop/app/main/services/platform/config/store/configSchema.ts), хранятся в config.theme и частично обновляются через IPC theme:setWallpaperPreferences. Исходное определение см. в packages/desktop/app/shared/contracts/settings-types.ts → ThemePreferences.
Источник обоев (изображение / градиент)
| Поле | Тип | По умолчанию | Описание |
|---|
wallpaper | { light?: string; dark?: string } | {} | Источник изображения для обоев; поддерживает протоколы file://, wallpaper://, data: URLs или разрешенные https:// URLs |
wallpaperGradient | { stops: string[1..4]; angle?: number 0..360 } | null | Линейный градиент из 1–4 цветов; имеет приоритет над wallpaper; при включении временно скрывает изображение |
disableWallpaperInCompactWindows | boolean | false | Отключать обои в компактных окнах (Mini/Selection) |
wallpaperOverlayEnabled | boolean | false | Включить полупрозрачные поверхности (лучше подходит для режима обоев) |
Матовое стекло и наложение
| Поле | Тип | Диапазон | По умолчанию | Описание |
|---|
wallpaperBlurIntensity | number | 0–30 | 6 | Размытие матового стекла в px |
wallpaperDimming | number | 0–100 | 70 | Общая непрозрачность наложения, % |
wallpaperDimmingHue | number | 0–360 | 0 | Оттенок HSL наложения (декодируется из hex-пикера цвета) |
wallpaperDimmingSaturation | number | 0–100 | 0 | Насыщенность HSL наложения, % |
wallpaperDimmingLightness | number | -1–100 | -1 | Светлота HSL наложения, %; -1 = auto (белый в светлом режиме, черный в темном режиме); 0–100 = вручную |
wallpaperDimmingGradient | WallpaperGradient | null | — | null | Градиентное наложение; при включении переопределяет HSL выше, но wallpaperDimming по-прежнему управляет общей непрозрачностью |
| Поле | Тип | По умолчанию | Описание |
|---|
wallpaperElementTint | string (#RRGGBB or '') | '' | Оттенок поверхности элементов; пустая строка = использовать значение темы по умолчанию (теплый кремовый / теплый угольный) |
wallpaperElementGradient | WallpaperGradient | null | null | Градиент элементов; переопределяет сплошной оттенок; каждый уровень сохраняет собственную alpha |
Пузырьки сообщений (User / Assistant независимо)
| Поле | Тип | По умолчанию | Описание |
|---|
wallpaperBubbleOverride | boolean | false | Главный переключатель: true = пузырьки используют независимые поля ниже; false = пузырьки следуют настройкам фона элементов (цвет + непрозрачность по умолчанию) |
wallpaperBubbleTintUser | string (#RRGGBB or '') | '' | Сплошной цвет пузырька User; активен при включенном переопределении |
wallpaperBubbleTintAssistant | string (#RRGGBB or '') | '' | Сплошной цвет пузырька Assistant; активен при включенном переопределении |
wallpaperBubbleGradientUser | WallpaperGradient | null | null | Градиент пузырька User; переопределяет сплошной цвет на этой стороне |
wallpaperBubbleGradientAssistant | WallpaperGradient | null | null | Градиент пузырька Assistant; переопределяет сплошной цвет на этой стороне |
wallpaperBubbleOpacity | number 0–100 | 35 | Alpha заливки пузырька; активна только при включенном переопределении |
Общая непрозрачность элементов
| Поле | Тип | Диапазон | По умолчанию | Описание |
|---|
wallpaperElementOpacity | number | 0–100 | 0 | Экспериментально: сдвигает полупрозрачный UI в целом в сторону непрозрачности |
wallpaperTransparency | number | 0–100 | 100 | Коэффициент интенсивности оттенка поверхности (0 = полностью прозрачная поверхность; 100 = alpha по умолчанию) |
Проверка Hex / градиента
- Hex-поля (
wallpaperElementTint / wallpaperBubbleTint*) Zod regex: /^(#[0-9a-fA-F]{6})?$/ (пустая строка или #RRGGBB).
WallpaperGradient.stops требует 1–4 строки; backend ThemeService.setWallpaperPreferences также отбрасывает пустые строки stops и обрезает массив до 4 элементов.- В IPC payload для полей градиента
null = очистить; отсутствие ключа = сохранить текущее значение. Backend различает это через 'wallpaperDimmingGradient' in patch.
Приоритет (порядок переопределения при рендеринге)
wallpaperGradient > wallpaper.{light,dark} // main wallpaper source
wallpaperDimmingGradient > wallpaperDimming{Hue,Saturation,Lightness} // overlay color
wallpaperElementGradient > wallpaperElementTint // element tint
wallpaperBubbleGradient{User,Assistant} > wallpaperBubbleTint{User,Assistant} // bubble color (only when override is on)
Когда wallpaperBubbleOverride=false, нижестоящий атрибут data-wp-bubble-override не записывается в body, а CSS возвращается к правилу «пузырьки наследуют оттенок элементов».
Конфигурация LLM
Провайдер (ProviderConfig)
Структура конфигурации для каждого провайдера LLM:
| Поле | Тип | Описание |
|---|
id | string | Уникальный идентификатор |
name | string | Отображаемое имя |
type | string | Тип провайдера (openai / anthropic / google / deepseek и т. д.) |
apiKey | string | API-ключ (хранится на backend, не передается через IPC) |
baseUrl | string? | Пользовательская API-точка доступа |
models | Model[] | Список доступных моделей |
enabled | boolean | Включен ли провайдер |
Глобальные параметры модели (GlobalModelParameters)
| Поле | Тип | Диапазон | По умолчанию | Описание |
|---|
temperature | number | 0 - 2 | По умолчанию провайдера | Температура генерации |
maxTokens | number | 1 - лимит модели | По умолчанию провайдера | Максимальное количество выходных токенов |
topP | number | 0 - 1 | По умолчанию провайдера | Top-P sampling |
topK | number | 1 - 100 | По умолчанию провайдера | Top-K sampling (некоторые провайдеры) |
frequencyPenalty | number | -2 - 2 | 0 | Штраф за частоту |
presencePenalty | number | -2 - 2 | 0 | Штраф за присутствие |
Пул API-ключей (ApiKeyEntry)
Конфигурация для каждой записи ключа:
| Поле | Тип | По умолчанию | Описание |
|---|
id | string | Автоматически генерируется | Уникальный идентификатор ключа |
providerId | string | - | ID провайдера-владельца |
label | string? | - | Метка ключа |
apiKey | string | - | Значение ключа (зашифрованное хранение) |
weight | number | 1 | Вес (1–100); влияет на вероятность распределения round-robin |
enabled | boolean | true | Включен ли ключ |
Поведение пула ключей:
- Использует Weighted Round-Robin для распределения ключей
- Привязка к сессии: одна и та же сессия предпочтительно использует один и тот же ключ
- Ответы 429/529 автоматически переключают на следующий ключ
- Экспоненциальная задержка cooldown: 60s → 2min → 5min → 15min
Конфигурация Agent
Значения по умолчанию для TinyElf Engine
| Поле | Тип | По умолчанию | Описание |
|---|
maxIterations | number | 40 | Максимальное количество итераций |
temperature | number | 0.1 | Температура генерации |
maxTokens | number | 8192 | Максимальное количество выходных токенов |
toolResultMaxChars | number | 50000 | Максимальное количество символов в результатах инструментов |
Claude SDK Engine
| Поле | Тип | Описание |
|---|
permissionMode | string | Режим разрешений (ask / auto-approve / deny) |
maxTurns | number | Максимальное количество ходов диалога |
systemPromptAppend | string? | Содержимое, добавляемое к системному промпту |
Конфигурация безопасности
GuardianAgent
| Поле | Тип | Описание |
|---|
mode | 'off' | 'monitor' | 'enforce' | Режим работы |
allowedCommands | string[] | Allowlist команд, которые можно выполнять |
blockedPaths | string[] | Шаблоны путей, доступ к которым заблокирован |
PromptGuardian
| Поле | Тип | Описание |
|---|
mode | 'off' | 'warn' | 'block' | Режим работы |
RateLimiter
| Поле | Тип | По умолчанию | Описание |
|---|
maxRequestsPerMinute | number | 60 | Максимальное количество запросов в минуту |
maxTokensPerMinute | number | 100000 | Максимальное количество токенов в минуту |
Конфигурация MCP (McpServerConfig)
Структура конфигурации для каждого MCP-сервера:
| Поле | Тип | Описание |
|---|
id | string | Уникальный идентификатор |
name | string | Отображаемое имя |
transport | 'stdio' | 'sse' | 'streamable-http' | Транспортный протокол |
command | string? | Команда запуска (режим stdio) |
args | string[]? | Аргументы команды (режим stdio) |
env | Record<string, string>? | Переменные окружения (режим stdio) |
url | string? | URL сервера (режим sse / streamable-http) |
enabled | boolean | Включен ли сервер |
autoConnect | boolean | Автоподключение при запуске приложения |
Запланированные задачи Cron
Конфигурация расписания
| Поле | Тип | Описание |
|---|
schedule | string | Cron-выражение (формат из 5/6 полей) |
timezone | string? | Идентификатор часового пояса (например, Asia/Tokyo) |
enabled | boolean | Включено ли расписание |
Типы действий
| Тип | Описание |
|---|
agent-run | Запустить указанный Agent |
channel-check | Проверить сообщения Channel |
custom-script | Запустить пользовательский скрипт |
Конфигурация Channel
Режимы триггера
| Режим | Описание |
|---|
mention | Отвечать только при @-упоминании |
keyword | Отвечать при наличии ключевого слова |
all | Отвечать на все сообщения |
Ограничения длины сообщений платформ
| Платформа | Макс. символов |
|---|
| Discord | 2000 |
| Telegram | 4096 |
| Slack | 40000 |
| Custom Webhook | Без ограничений |
CSS-переменные (Tailwind-токены)
Определены в packages/renderer/src/app/index.css и сопоставляются с utility-классами через конфигурацию Tailwind.
Цветовые токены
| CSS-переменная | Класс Tailwind | Описание |
|---|
--background | bg-background | Основной фон страницы |
--foreground | text-foreground | Основной цвет текста |
--surface-0 | bg-surface-0 | Фон слоя L0 |
--surface-1 | bg-surface-1 | Фон слоя L1 (карточки/sidebar) |
--surface-2 | bg-surface-2 | Фон слоя L2 (поля ввода/вторичные контейнеры) |
--surface-3 | bg-surface-3 | Фон слоя L3 (popovers) |
--text-strong | text-foreground | Основные заголовки, текст body (яркость 93%) |
--text-muted | text-muted-foreground | Вторичный текст (яркость 65%) |
--text-subtle | text-text-subtle | Вспомогательные подсказки (яркость 50%) |
--primary | bg-primary / text-primary | Цвет темы |
--secondary | bg-secondary | Вторичный цвет |
--destructive | text-destructive | Цвет ошибки/деструктивного действия |
--success | text-success | Цвет успеха |
--warning | text-warning | Цвет предупреждения |
--border | border-border | Цвет границы |
--ring | ring-ring | Цвет кольца фокуса |
--muted | bg-muted | Приглушенный фон |
--accent | bg-accent | Акцентный фон |
--popover | bg-popover | Фон popover |
--card | bg-card | Фон карточки |
Шрифты
| CSS-переменная | Класс Tailwind | Шрифт |
|---|
--font-sans | font-sans | Inter, system-ui |
--font-mono | font-mono | JetBrains Mono, monospace |
--font-display | font-display | Noto Serif, Georgia, serif |
--font-ui | font-ui | Пользовательский UI-шрифт |
--font-code | font-code | Пользовательский шрифт кода |
Радиус границы
| CSS-переменная | Класс Tailwind | Значение |
|---|
--radius | rounded-lg | 0.5rem (8px) |
| - | rounded-md | 0.375rem (6px) |
| - | rounded-sm | 0.25rem (4px) |
| - | rounded-xl | 0.75rem (12px) |
Файловая конфигурация (ConfigStore)
Чтение/запись через window.api.config. Хранится в JSON-файле с поддержкой hot-reload.
При изменении конфигурации main process уведомляет frontend через канал config:changed.
Общие ключи конфигурации
| Ключ | Тип | Описание |
|---|
magi | MagiConfig | Конфигурация Magi/Claw Agent |
magi.promptVersion | 'v1' | 'v2' | 'v3' | 'v4' | Версия сборки промпта |
cron | CronConfig | Конфигурация запланированных задач Cron |
channel | ChannelConfig | Конфигурация сообщений Channel |
security | SecurityConfig | Конфигурация управления безопасностью |
Полный путь к файлу конфигурации можно получить через window.api.config.getPath().