Environment Configuration and API Keys

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• packages/core/src/index.ts
• packages/core/src/services/image-model/defaults.ts
• packages/core/src/services/llm/adapters/modelscope-adapter.ts
• packages/core/src/services/llm/service.ts
• packages/core/src/services/model/defaults.ts
• packages/core/src/services/model/manager.ts
• packages/core/src/services/model/types.ts
• packages/core/src/utils/environment.ts
• packages/core/tests/unit/image/modelscope-adapter.test.ts
• packages/core/tests/unit/llm/modelscope-adapter.test.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/core/tests/unit/model/manager.test.ts
• packages/mcp-server/src/config/models.ts
• vercel.json

This document describes the multi-tier configuration system for API keys and model settings in Prompt Optimizer. The system supports three primary configuration methods: UI-based configuration (recommended for most users), environment variables (for deployment scenarios), and runtime configuration injection (for Docker deployments). This page covers the configuration architecture, built-in model setup, custom model patterns, and configuration precedence rules.

For deployment-specific configuration details, see Docker Deployment and Vercel Deployment. For information about model adapters and provider integration, see Model Configuration Management and LLM Service and Provider Adapters.

Configuration Architecture Overview

The configuration system is designed with multiple tiers to support different deployment scenarios while maintaining consistent behavior across all platforms.

Sources: packages/core/src/utils/environment.ts225-255 packages/core/src/services/model/defaults.ts39-94 packages/core/src/services/model/manager.ts22-193

Configuration Priority System

The getEnvVar() function implements a three-tier priority system that determines which configuration source takes precedence:

Priority	Source	Use Case	Access Method
3 (Highest)	window.runtime_config	Docker runtime injection	window.runtime_config[key] (without VITE_ prefix)
2 (Medium)	process.env	Node.js, Electron main process	process.env[key]
1 (Lowest)	import.meta.env	Vite development, static build	import.meta.env[key]

This priority system ensures that runtime configuration (Docker) can override build-time settings, while development environments have sensible defaults.

Sources: packages/core/src/utils/environment.ts225-255

Built-in Model Configuration

The system recognizes eleven built-in providers, each configurable through environment variables following the pattern VITE_{PROVIDER}_API_KEY.

Provider Environment Variable Mapping

Sources: packages/core/src/services/model/defaults.ts11-20 packages/core/src/services/model/defaults.ts39-94

Built-in Model Initialization

The getDefaultTextModels() function creates TextModelConfig objects for each provider by:

1. Retrieving adapter metadata: Uses TextAdapterRegistry to get TextProvider and TextModel metadata
2. Reading API keys: Calls getEnvVar() for each provider's environment variable
3. Setting enabled state: Models are enabled only if their API key is non-empty
4. Initializing parameters: Applies default parameter values from modelMeta.defaultParameterValues

Sources: packages/core/src/services/model/defaults.ts39-94

Custom Model Configuration

Beyond the built-in providers, the system supports unlimited custom models through a pattern-based environment variable convention: VITE_CUSTOM_API_{TYPE}_{SUFFIX}.

Custom Model Environment Variable Pattern

Each custom model requires three environment variables with matching suffixes:

Variable Pattern	Purpose	Example
VITE_CUSTOM_API_KEY_{suffix}	API key for authentication	VITE_CUSTOM_API_KEY_ollama=dummy_key
VITE_CUSTOM_API_BASE_URL_{suffix}	Base URL for API endpoint	VITE_CUSTOM_API_BASE_URL_ollama=http://localhost:11434/v1
VITE_CUSTOM_API_MODEL_{suffix}	Model identifier	VITE_CUSTOM_API_MODEL_ollama=qwen2.5:7b

Suffix Validation Rules (defined in packages/core/src/utils/environment.ts6-8):

• SUFFIX_PATTERN: Must match /^[a-zA-Z0-9_-]+$/
• MAX_SUFFIX_LENGTH: Maximum 50 characters
• No special characters except underscore and hyphen

Custom Model Scanning Process

Sources: packages/core/src/utils/environment.ts263-394 packages/core/src/utils/environment.ts61-108

Custom Model Generation

The generateDynamicModels() function (in packages/core/src/services/model/model-utils.ts) converts validated custom model environment variables into TextModelConfig objects:

1. Scan environment: Calls scanCustomModelEnvVars() to find all valid custom model configurations
2. Create config ID: Uses pattern custom_{suffix} for the model ID
3. Build model metadata: Creates a custom TextModel using the OpenAI adapter as the base
4. Set connection config: Populates connectionConfig with the custom base URL and API key
5. Enable model: Sets enabled: true for all successfully scanned custom models

Example: Environment variables for a local Ollama instance:

This generates a TextModelConfig with ID custom_ollama, enabling local model access without code changes.

Sources: README.md281-288 README_EN.md277-288

UI-Based Configuration

Users can configure models through the ModelManager UI component, which provides a graphical interface for all configuration options.

Sources: packages/ui/src/components/ModelManager.vue1-198

Model Configuration Fields

The UI exposes the following configuration options for text models:

Field	Type	Description	UI Location
name	string	Display name for the model	Model header
enabled	boolean	Whether model is active	Toggle switch
connectionConfig.apiKey	string	API authentication key	Protected input field
connectionConfig.baseURL	string	API endpoint URL	Text input
modelMeta.id	string	Selected model identifier	Dropdown
paramOverrides	Record<string, unknown>	Model-specific parameters	Advanced settings panel

Advanced Parameter Configuration: The llmParams field (now unified into paramOverrides) allows setting any parameter supported by the provider's SDK, such as:

• OpenAI: {"temperature": 0.7, "max_tokens": 4096, "timeout": 60000}
• Gemini: {"temperature": 0.8, "maxOutputTokens": 2048, "topP": 0.95}
• DeepSeek: {"temperature": 0.5, "top_p": 0.9, "frequency_penalty": 0.1}

Sources: README.md248-269 README_EN.md252-273

Docker Environment Configuration

Docker deployments use environment variables injected at runtime through the container's environment and exposed via window.runtime_config.

Docker Configuration Injection Flow

Sources: docker-compose.yml1-44 docker-compose.dev.yml1-37

Docker Environment Variables

Docker deployments support all configuration variables through the environment section of docker-compose.yml:

Built-in Model Keys:

Custom Model Configuration:

Access Control:

The generate-auth.sh script (docker/generate-auth.sh1-46) processes ACCESS_PASSWORD to create HTTP Basic Authentication if provided.

Sources: docker-compose.yml18-41 docker/generate-auth.sh1-46

Vercel Deployment Configuration

Vercel deployments configure API keys through environment variables in the Vercel project settings. The vercel.json file defines the build configuration:

Environment variables are set through the Vercel dashboard:

1. Navigate to Project Settings → Environment Variables
2. Add variables: VITE_OPENAI_API_KEY, VITE_GEMINI_API_KEY, etc.
3. Set ACCESS_PASSWORD for deployment protection (optional)

During build, Vite inlines these environment variables into the static bundle via import.meta.env.

Sources: vercel.json1-32 README.md89-94 README_EN.md89-94

Electron Configuration Management

Electron desktop applications use a specialized configuration manager that synchronizes environment variables from the main process to the renderer process.

ElectronConfigManager Architecture

Sources: packages/core/src/services/model/manager.ts80-85

The ElectronConfigManager ensures that environment variables from the Electron main process (which has access to Node.js process.env) are available to the renderer process's model initialization logic. This is necessary because Electron's security model prevents direct access to process.env from renderer processes.

Sources: packages/core/src/index.ts66

Configuration Validation and Error Handling

The system validates configuration at multiple stages to ensure correctness before use.

Validation Layers

Layer	Function	Location	Checks
Environment Scanning	validateCustomModelConfig()	packages/core/src/utils/environment.ts61-108	Suffix format, API key presence, URL validity, model name
Model Manager	validateTextModelConfig()	packages/core/src/services/model/manager.ts644-697	Required fields, parameter schema compliance
LLM Service	validateModelConfig()	packages/core/src/services/llm/service.ts57-76	Provider metadata, model metadata, enabled state
Parameter Validation	validateOverrides()	packages/core/src/services/model/parameter-utils.ts	Type checking, enum values, range constraints

Validation Result Structure

The ValidationResult interface (packages/core/src/utils/environment.ts47-54) provides structured feedback:

Errors prevent model usage and must be resolved. Warnings indicate potential issues (e.g., short API key) but don't block functionality.

Sources: packages/core/src/utils/environment.ts47-108 packages/core/src/services/model/manager.ts644-697

Configuration Persistence and Migration

Model configurations are persisted to storage and automatically migrated between format versions.

Storage and Migration Flow

Sources: packages/core/src/services/model/manager.ts75-193 packages/core/src/services/model/manager.ts216-238

Configuration Format Migration

The migrateConfig() method (packages/core/src/services/model/manager.ts216-238) handles backward compatibility by merging deprecated customParamOverrides into the unified paramOverrides field:

This ensures configurations from older versions continue to work while guiding users toward the new unified parameter system.

Sources: packages/core/src/services/model/manager.ts216-238

Auto-Enable Logic for Built-in Models

The shouldAutoEnableBuiltinModel() method (packages/core/src/services/model/manager.ts611-640) implements intelligent model activation:

Conditions for Auto-Enable:

1. Model must be in getBuiltinModelIds() list
2. Stored config has enabled: false
3. Stored connectionConfig.apiKey is empty
4. New default config has non-empty API key

This allows environment variable changes (e.g., adding VITE_OPENAI_API_KEY after initial setup) to automatically activate previously disabled models without manual intervention.

Sources: packages/core/src/services/model/manager.ts611-640

Configuration Export and Import

The ModelManager implements the IImportExportable interface (packages/core/src/interfaces/import-export.ts) for bulk configuration management.

Export Format

The exportData() method (packages/core/src/services/model/manager.ts715-726) returns all models as an array of TextModelConfig objects:

Import Behavior

The importData() method (packages/core/src/services/model/manager.ts731-800) handles both new (TextModelConfig) and legacy (ModelConfig) formats:

1. Validates array format: Ensures data is an array
2. Processes each model individually: Converts legacy formats if needed
3. Updates existing models: Merges with existing configuration
4. Adds new models: Creates configurations for unknown model IDs
5. Collects failures: Continues on error, reports failed imports

This design allows partial import success and provides detailed error reporting for troubleshooting.

Sources: packages/core/src/services/model/manager.ts715-800