The Configuration System provides a centralized, type-safe mechanism for defining and managing all runtime parameters in DeerFlow. It handles loading from YAML files, resolving environment variables, delegating to specialized sub-configurations, and providing access to configuration data throughout the application lifecycle.
For configuration file formats and parameters, see subsections Configuration Loading and Structure through Environment Variables. For how configuration influences agent behavior, see Lead Agent and System Prompt. For multi-channel configuration, see Channel Configuration.
DeerFlow uses three primary configuration files that work together to define system behavior:
| File | Purpose | Format | Default Location |
|---|---|---|---|
config.yaml | Main configuration (models, tools, sandbox, skills, memory) | YAML | Project root |
extensions_config.json | MCP servers and skill enable/disable state | JSON | Project root |
.env | API keys and sensitive credentials | Environment variables | Project root |
Configuration Resolution Priority:
The config.yaml file location is resolved using the following priority backend/packages/harness/deerflow/config/app_config.py32:
config_path parameter to AppConfig.from_file() backend/packages/harness/deerflow/config/app_config.py199DEER_FLOW_CONFIG_PATH environment variable.config.yaml under DEER_FLOW_PROJECT_ROOT or the current working directory.existing_project_file backend/packages/harness/deerflow/config/app_config.py32If no configuration file is found at any of these locations, a FileNotFoundError is raised backend/packages/harness/deerflow/config/app_config.py205
Sources: backend/packages/harness/deerflow/config/app_config.py32 backend/packages/harness/deerflow/config/app_config.py199-205 backend/docs/CONFIGURATION.md22-26
The configuration loading process follows a multi-stage pipeline:
load_dotenv() loads .env file variables into os.environ backend/packages/harness/deerflow/config/app_config.py51config.yaml is parsed into a Python dictionary via yaml.safe_load backend/packages/harness/deerflow/config/app_config.py207-209$ is replaced with its environment variable value via resolve_env_variables backend/packages/harness/deerflow/config/app_config.py368-370AppConfig instantiation backend/packages/harness/deerflow/config/app_config.py10ConfigSignature to trigger reloads when the configuration file changes on disk backend/packages/harness/deerflow/config/app_config.py21-22Sources: backend/packages/harness/deerflow/config/app_config.py10-234 backend/packages/harness/deerflow/config/app_config.py368-370
The AppConfig class backend/packages/harness/deerflow/config/app_config.py127-187 is the root configuration container:
Primary Configuration Fields:
| Field | Type | Description |
|---|---|---|
llm_call | LlmCallConfig | Process-wide cap on concurrent LLM calls and retry strategies backend/packages/harness/deerflow/config/app_config.py69-124 |
circuit_breaker | CircuitBreakerConfig | Failure thresholds and recovery timeouts for LLM providers backend/packages/harness/deerflow/config/app_config.py62-67 |
models | list[ModelConfig] | Available LLM models (OpenAI, Gemini, DeepSeek, etc.) backend/packages/harness/deerflow/config/app_config.py150 |
sandbox | SandboxConfig | Sandbox provider configuration backend/packages/harness/deerflow/config/app_config.py151-156 |
database | DatabaseConfig | Unified database backend (SQLite defaults) backend/packages/harness/deerflow/config/app_config.py56-59 |
Delegated Sub-configurations:
Independent singleton instances are updated during AppConfig.from_file():
load_memory_config_from_dict() backend/packages/harness/deerflow/config/memory_config.py163-180load_summarization_config_from_dict() backend/packages/harness/deerflow/config/app_config.py42load_guardrails_config_from_dict() backend/packages/harness/deerflow/config/app_config.py23Sources: backend/packages/harness/deerflow/config/app_config.py56-187 backend/packages/harness/deerflow/config/memory_config.py163-180
The configuration system feeds into the model factory to instantiate LLM clients. DeerFlow supports standard providers and specialized patched versions for advanced reasoning features.
supports_thinking: true and specific extra_body payloads for thinking modes backend/docs/CONFIGURATION.md151-158PatchedChatOpenAI to preserve thought_signature fields in multi-turn conversations, required by Gemini APIs backend/docs/CONFIGURATION.md162-175CodexChatModel (Codex CLI) and ClaudeChatModel (Claude Code OAuth) backend/docs/CONFIGURATION.md48-49PatchedChatMiMo handles reasoning_content preservation backend/docs/CONFIGURATION.md47Sources: backend/docs/CONFIGURATION.md28-185 backend/packages/harness/deerflow/config/app_config.py69-124
To prevent configuration drift and ensure environment readiness, DeerFlow includes version tracking and a diagnostic tool.
config.yaml tracks a config_version. If the local version is lower than config.example.yaml, a startup warning is emitted backend/docs/CONFIGURATION.md5-12make doctor): The scripts/doctor.py utility checks system requirements, configuration validity, and LLM provider authentication scripts/doctor.py2-10uv, pnpm, and nginx scripts/doctor.py134-204 It also validates that API keys for configured models are set in the environment scripts/doctor.py207-250Sources: backend/docs/CONFIGURATION.md5-17 scripts/doctor.py1-250 backend/tests/test_doctor.py1-120