Settings Reference
This page is a complete reference for all user-configurable settings in Elftia. Settings are organized by tab and correspond to the Settings page in the application.
General Settings
Located under Settings → General.
Language
| Setting | Options | Default | Description |
|---|---|---|---|
| Interface Language | Simplified Chinese / English / 日本語 | Follow System | The display language of the application interface |
Language changes take effect immediately without requiring a restart.
Proxy
| Setting | Options | Default | Description |
|---|---|---|---|
| Proxy Mode | System Proxy / Custom Proxy / No Proxy | System Proxy | The proxy method used for network requests |
| Custom Proxy URL | Text Input | Empty | Only takes effect in "Custom Proxy" mode |
For more details, see Using Proxy.
Startup
| Setting | Type | Default | Description |
|---|---|---|---|
| Autostart | Toggle | Off | Automatically run Elftia when the operating system starts |
| Minimize on Startup | Toggle | Off | Minimize to tray instead of showing the window after autostart |
Tray
| Setting | Type | Default | Description |
|---|---|---|---|
| Minimize to Tray | Toggle | Off | Minimize to system tray when closing the window instead of exiting the application |
Notifications
| Setting | Type | Default | Description |
|---|---|---|---|
| Desktop Notifications | Toggle | On | Show system notifications when new messages arrive |
| Notification Sound | Toggle | On | Play a notification sound when alerts arrive |
Environment Tools
Displays the status of development tools installed on the system, located at the bottom of the General Settings page.
| Tool | Purpose | Auto-Installable |
|---|---|---|
| Node.js | MCP server runtime | No |
| Git | Version control | No |
| ripgrep (rg) | Fast file search | Yes |
| uv | Python package manager | Yes |
| uvx | Python tool runner | Yes |
Tools marked as "Auto-Installable" can be installed automatically by clicking the "Install" button.
Appearance Settings
Located under Settings → Appearance. For detailed explanations, see Themes and Appearance.
| Setting | Type | Default | Description |
|---|---|---|---|
| Theme Mode | Light / Dark / Follow System | Follow System | Interface color scheme |
| Accent Color | Color Picker | Preset Blue | Theme color for buttons, links, and other elements |
| UI Font | Text Input | Inter | Font for interface text |
| Code Font | Text Input | JetBrains Mono | Monospace font for code blocks |
| Wallpaper (Light Mode) | Image Upload / URL | None | Background wallpaper for light mode |
| Wallpaper (Dark Mode) | Image Upload / URL | None | Background wallpaper for dark mode |
| Blur Strength | Slider 0-30 | 6 | Gaussian blur amount for the wallpaper |
| Mask Opacity | Slider 0-100 | 70 | Opacity of the wallpaper mask layer |
| Disable Wallpaper in Compact Window | Toggle | On | Automatically disable wallpaper when the window is small |
| Custom CSS | CSS Editor | Empty | Inject custom styles |
| Allow Remote Resources | Toggle | Off | Allow loading remote images and fonts |
| Remote Domain Whitelist | List | Default List | Domains allowed to load resources |
Provider Settings
Located under Settings → Provider Settings. For detailed explanations, see LLM Provider Configuration.
Each provider can be configured with the following options:
| Setting | Type | Description |
|---|---|---|
| API Key | Password Input | The API key for the provider |
| Base URL | Text Input | API endpoint address (supports custom endpoints) |
| Enabled | Toggle | Whether to activate this provider |
| API Key Pool | Multi-Key Management | Configure multiple API Keys for load balancing |
API Key Pool
Each provider supports configuring multiple API Keys, and the system automatically selects among them using weighted round-robin:
| Setting | Type | Description |
|---|---|---|
| Key List | List | Multiple API Key entries |
| Weight | Number | Selection weight for each key |
| Enabled/Disabled | Toggle | Enabled status for individual keys |
When a key encounters 429 (rate limit) or 529 (overload) errors, the system automatically switches to another available key and sets a cooldown period for the failed key (exponential backoff from 60 seconds to 15 minutes).
Default Models
Located under Settings → Default Models.
| Setting | Purpose | Description |
|---|---|---|
| General Chat | Default model for daily conversations | Automatically selected when creating a new conversation |
| Long Context | Model for processing long documents | Automatically switched when context exceeds threshold |
| Web Search | Model for search summarization | Used when enabling web search |
| Image Generation | Image generation model | Used when creating images |
| Background Tasks | Model for background processing | Used for conversation title generation, summaries, etc. |
Each category can be selected from available models of all enabled providers.
Agent Settings (Clawia)
Located under Settings → Clawia (Agent Configuration tab).
Agent Engine
| Setting | Options | Default | Description |
|---|---|---|---|
| Agent Backend | Claude SDK / TinyElf / CLI | Claude SDK | Agent execution engine |
- Claude SDK: Uses Anthropic's Agent SDK with the most complete functionality.
- TinyElf: Built-in lightweight agent engine that supports any LLM provider.
- CLI: Call external agent tools via command line (Claude Code CLI, Codex CLI, etc.).
CLI Backend Settings (CLI Mode Only)
| Setting | Type | Default | Description |
|---|---|---|---|
| CLI Tool | Selection | Claude Code | The CLI backend to use |
| Timeout | Number (seconds) | 300 | Maximum duration for a single execution |
| PTY Mode | Toggle | Off | Use pseudo-terminal for execution |
| PTY Columns | Number | 120 | PTY terminal width |
| PTY Rows | Number | 40 | PTY terminal height |
Prompt Version
| Setting | Options | Default | Description |
|---|---|---|---|
| Prompt Version | V1 / V2 / V3 / V4 | V4 | The construction method for system prompts |
- V1: SDK preset + simple appending (time, workspace, memory, channels)
- V2: Fully customized system prompts (PromptBuilder)
- V3: V2 + 5-layer structure (bootstrap, onboarding, memory, channels, dynamic)
- V4: SDK preset + bootstrap file + soul/memory/onboarding/channels/scheduling
V4 is the recommended default version, combining SDK optimizations with project-specific customization. Most users do not need to change this setting.
Security Settings
| Setting | Options | Default | Description |
|---|---|---|---|
| GuardianAgent Mode | Off / Monitor / Guard / Strict | Off | AI safety review level |
See Security Settings for details.
Session Mode
| Setting | Options | Default | Description |
|---|---|---|---|
| Default Session Mode | Continue / New | Continue | Default behavior when opening the application |
- Continue: Restore the previous conversation session when opening the application.
- New: Create a new conversation session each time the application opens.
Developer Mode
| Setting | Type | Default | Description |
|---|---|---|---|
| Developer Mode | Toggle | Off | When enabled, access DevTools and additional debugging information |
Developer Mode needs to be activated in Settings → About through a specific action (continuously click the version number). Once activated, the Developer Mode toggle appears in the Clawia tab.
Web Search Settings
Located under Settings → Web Search. For detailed explanations, see Web Search Feature.
| Setting | Type | Description |
|---|---|---|
| Search Provider | Selection | Choose the web search engine provider |
| Organization Strategy | Selection | The organization method for search results |
| Compression Settings | Options | Compression level for search result content |
| Domain Blacklist | List | Do not fetch search results from these domains |
System Settings
Located under Settings → System.
Diagnostic Tools
| Action | Description |
|---|---|
| Export Diagnostics | Export diagnostic information (logs, configuration, runtime environment) |
| Clear Caches | Clear local cache data |
| Copy diagnostics log | Copy diagnostic logs to clipboard |
| Prune attachments | Clean up unassociated attachment files |
Database Maintenance
| Action | Description |
|---|---|
| Database Size | Display current SQLite database file size |
| VACUUM | Execute database compression optimization and reclaim space used by deleted data |
Resource Cleanup
| Action | Description |
|---|---|
| Cleanable Items | Display the quantity and size of orphaned resources that can be safely deleted |
| Clean Resources | Execute resource cleanup |
Data Import and Migration
| Action | Description |
|---|---|
| Legacy JSONL Import | Sync ~/.claude/projects/*.jsonl to the database for fast paginated queries |
| Thumbnail Generation | Batch generate thumbnails for existing images to improve list and gallery loading speed |
| Attachment Storage Migration | Migrate old media:// attachments to resource:// content-addressable storage, dedup, and save space |
Experimental Features
Some new features being tested can be toggled in this section. Experimental features may be unstable and are only recommended for advanced users:
| Feature | Description |
|---|---|
| New File System | Stream search, ripgrep integration, and auto-fallback mechanism |
| Optimized File Tree | Enhanced tree rendering and incremental updates |
If you encounter issues, you can toggle them off at any time to revert to the stable version.
:::info Design Studio is Enabled by Default
Design Studio is enabled by default as of version 0.1.7 and is no longer in Experimental Features. The navigation bar now shows the 🎨 Design Studio entry directly. The only remaining requirement is that the current LLM provider engine supports the Design adapter (the api engine does not support it). See Design Studio for details.
:::
About
Located under Settings → About.
| Information | Description |
|---|---|
| Version | Current Elftia version |
| Check for Updates | Manually check if a new version is available |
| Developer Mode | Enabled by continuously clicking the version number |
| DevTools | Open/close Electron DevTools in developer mode |
| Account Status | Login status and membership information |
For detailed explanations of security-related settings, continue reading Security Settings.