설정 레퍼런스
이 문서는 Elftia의 모든 설정 가능한 옵션을 기능 도메인별로 분류하여 나열합니다.
환경 변수
프론트엔드 (Vite / VITE_*)
프론트엔드 환경 변수는 VITE_ 접두사를 붙여 노출되며, React 코드에서 import.meta.env를 통해 접근할 수 있습니다.
| 변수 | 타입 | 기본값 | 설명 |
|---|---|---|---|
VITE_APP_TITLE | string | 'Elftia' | 애플리케이션 제목 |
VITE_DEV_PORT | number | 5375 | Vite Dev Server 포트 |
백엔드 (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 |
배경화면 (Wallpaper)
배경화면 관련 필드는 모두 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: URL, 또는 허용 목록의 https:// URL 지원 |
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 = 자동 (라이트 모드에서 흰색, 다크 모드에서 검정); 0–100 = 수동 |
wallpaperDimmingGradient | WallpaperGradient | null | — | null | 그라디언트 오버레이; 활성화 시 위의 HSL을 재정의하지만, wallpaperDimming은 전체 불투명도를 계속 제어 |
요소 배경 색조 (사이드바 / 카드 / 탭 등 반투명 서피스)
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
wallpaperElementTint | string (#RRGGBB 또는 '') | '' | 요소 서피스 색조; 빈 문자열 = 테마 기본값 사용 (따뜻한 크림 / 따뜻한 차콜) |
wallpaperElementGradient | WallpaperGradient | null | null | 요소 그라디언트; 단색 색조보다 우선 적용; 각 계층이 독립적인 알파 값을 유지 |
메시지 버블 (사용자 / 어시스턴트 독립 설정)
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
wallpaperBubbleOverride | boolean | false | 마스터 스위치: true = 버블이 아래 독립 필드 사용; false = 버블이 요소 배경 설정을 따름 (색상 + 기본 불투명도) |
wallpaperBubbleTintUser | string (#RRGGBB 또는 '') | '' | 사용자 버블 단색; override 활성화 시 적용 |
wallpaperBubbleTintAssistant | string (#RRGGBB 또는 '') | '' | 어시스턴트 버블 단색; override 활성화 시 적용 |
wallpaperBubbleGradientUser | WallpaperGradient | null | null | 사용자 버블 그라디언트; 해당 측의 단색을 재정의 |
wallpaperBubbleGradientAssistant | WallpaperGradient | null | null | 어시스턴트 버블 그라디언트; 해당 측의 단색을 재정의 |
wallpaperBubbleOpacity | number 0–100 | 35 | 버블 채우기 알파; override 활성화 시에만 적용 |
전체 요소 불투명도
| 필드 | 타입 | 범위 | 기본값 | 설명 |
|---|---|---|---|---|
wallpaperElementOpacity | number | 0–100 | 0 | 실험적: 반투명 UI 전체를 불투명 방향으로 조정 |
wallpaperTransparency | number | 0–100 | 100 | 서피스 색조 강도 계수 (0 = 서피스 완전 투명; 100 = 기본 알파) |
Hex / 그라디언트 유효성 검사
- Hex 필드 (
wallpaperElementTint/wallpaperBubbleTint*)의 Zod 정규식:/^(#[0-9a-fA-F]{6})?$/(빈 문자열 또는#RRGGBB). WallpaperGradient.stops는 1–4개의 문자열이 필요합니다; 백엔드ThemeService.setWallpaperPreferences는 빈 문자열 stop을 제거하고 배열을 4개 항목으로 자릅니다.- 그라디언트 필드의 IPC 페이로드에서
null= 초기화; 키 생략 = 현재 값 유지. 백엔드는'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 키 (백엔드에 저장, IPC로 전송되지 않음) |
baseUrl | string? | 커스텀 API 엔드포인트 |
models | Model[] | 사용 가능한 모델 목록 |
enabled | boolean | 활성화 여부 |
전역 모델 파라미터 (GlobalModelParameters)
| 필드 | 타입 | 범위 | 기본값 | 설명 |
|---|---|---|---|---|
temperature | number | 0 - 2 | 프로바이더 기본값 | 생성 온도 |
maxTokens | number | 1 - 모델 한도 | 프로바이더 기본값 | 최대 출력 토큰 수 |
topP | number | 0 - 1 | 프로바이더 기본값 | Top-P 샘플링 |
topK | number | 1 - 100 | 프로바이더 기본값 | Top-K 샘플링 (일부 프로바이더) |
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); 라운드로빈 분배 확률에 영향 |
enabled | boolean | true | 활성화 여부 |
키 풀 동작 방식:
- 가중 라운드로빈(Weighted Round-Robin)으로 키를 분배합니다
- 세션 친화성: 동일 세션에서는 동일한 키를 우선 사용합니다
- 429/529 응답 시 자동으로 다음 키로 전환합니다
- 지수 백오프 쿨다운: 60초 → 2분 → 5분 → 15분
Agent 설정
TinyElf 엔진 기본값
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
maxIterations | number | 40 | 최대 반복 횟수 |
temperature | number | 0.1 | 생성 온도 |
maxTokens | number | 8192 | 최대 출력 토큰 수 |
toolResultMaxChars | number | 50000 | 도구 결과의 최대 문자 수 |
Claude SDK 엔진
| 필드 | 타입 | 설명 |
|---|---|---|
permissionMode | string | 권한 모드 (ask / auto-approve / deny) |
maxTurns | number | 최대 대화 턴 수 |
systemPromptAppend | string? | 시스템 프롬프트에 추가할 내용 |
보안 설정
GuardianAgent
| 필드 | 타입 | 설명 |
|---|---|---|
mode | 'off' | 'monitor' | 'enforce' | 동작 모드 |
allowedCommands | string[] | 실행 허용 명령어 허용 목록 |
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 |
| 커스텀 Webhook | 무제한 |
CSS 변수 (Tailwind 토큰)
packages/renderer/src/app/index.css에 정의되어 있으며, Tailwind 설정을 통해 유틸리티 클래스로 매핑됩니다.
색상 토큰
| CSS 변수 | Tailwind 클래스 | 설명 |
|---|---|---|
--background | bg-background | 페이지 메인 배경 |
--foreground | text-foreground | 기본 텍스트 색상 |
--surface-0 | bg-surface-0 | L0 레이어 배경 |
--surface-1 | bg-surface-1 | L1 레이어 배경 (카드/사이드바) |
--surface-2 | bg-surface-2 | L2 레이어 배경 (입력창/보조 컨테이너) |
--surface-3 | bg-surface-3 | L3 레이어 배경 (팝오버) |
--text-strong | text-foreground | 주요 제목, 본문 텍스트 (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 | 팝오버 배경 |
--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 파일로 저장되며 핫 리로드를 지원합니다.
설정이 변경되면 메인 프로세스가 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()로 가져올 수 있습니다.