配置项参考
本文档列出 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> | 自定义颜色 Token 覆盖 |
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:// |
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 | 元素渐变；优先于纯色 tint，每层保留独立 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 | 气泡 fill 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 payload 中
null= 清空；省略 key = 保持原值。后端通过'wallpaperDimmingGradient' in patch区分两者。
优先级（实际渲染时的覆盖关系）
wallpaperGradient > wallpaper.{light,dark} // 主壁纸图源
wallpaperDimmingGradient > wallpaperDimming{Hue,Saturation,Lightness} // 遮罩颜色
wallpaperElementGradient > wallpaperElementTint // 元素着色
wallpaperBubbleGradient{User,Assistant} > wallpaperBubbleTint{User,Assistant} // 气泡颜色（仅 override 开启时）
wallpaperBubbleOverride=false 时，下游 data-wp-bubble-override 属性不写入 body，CSS 走"气泡继承元素 tint"的 fallback 规则。
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 - 模型上限 | 提供商默认 | 最大输出 Token 数 |
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 | 最大输出 Token 数 |
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 | 每分钟最大 Token 数 |
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 Token)
定义在 packages/renderer/src/app/index.css 中，通过 Tailwind 配置映射为实用类。
颜色 Token
| 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' | Prompt 构建版本 |
cron | CronConfig | Cron 定时任务配置 |
channel | ChannelConfig | Channel 消息渠道配置 |
security | SecurityConfig | 安全管控配置 |
提示
完整的配置文件路径可通过 window.api.config.getPath() 获取。