設定リファレンス
このドキュメントでは、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 |
壁紙
壁紙関連のすべてのフィールドは 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 | 要素グラデーション。単色ティントを上書きし、各階層は独自の alpha を保持する |
メッセージバブル (ユーザー / アシスタントを個別に設定)
| フィールド | 型 | デフォルト | 説明 |
|---|---|---|---|
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 | バブル塗りつぶしの alpha。override がオンのときのみ有効 |
要素全体の不透明度
| フィールド | 型 | 範囲 | デフォルト | 説明 |
|---|---|---|---|---|
wallpaperElementOpacity | number | 0–100 | 0 | 実験的: 半透明 UI 全体を不透明方向へ近づける |
wallpaperTransparency | number | 0–100 | 100 | サーフェスティント強度係数 (0 = 完全に透明なサーフェス、100 = デフォルト alpha) |
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 Engine
| フィールド | 型 | 説明 |
|---|---|---|
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 | 1 分あたりの最大リクエスト数 |
maxTokensPerMinute | number | 100000 | 1 分あたりの最大トークン数 |
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 で定義され、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% brightness) |
--text-muted | text-muted-foreground | セカンダリテキスト (65% brightness) |
--text-subtle | text-text-subtle | 補助ヒント (50% brightness) |
--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() で取得できます。