DeerFlow 配置系统实现说明

May 8, 2026

xiwang

全栈开发者

概述

DeerFlow采用双文件、模块化的配置系统设计，将核心应用配置与扩展配置分离，同时支持环境变量注入、自动热重载、版本校验等企业级特性，兼顾灵活性与易用性。

---

核心架构

DeerFlow配置系统由两个独立的配置文件组成：

配置文件	格式	存储内容	位置
config.yaml	YAML	应用核心配置（模型、沙箱、工具、内存、子Agent等）	项目根目录
extensions_config.json	JSON	扩展配置（MCP服务器、技能开关状态）	项目根目录

设计理念

• 核心配置稳定：config.yaml包含系统运行必需的基础配置，变更频率低
• 扩展配置灵活：extensions_config.json包含动态变化的扩展配置，支持运行时修改
• 敏感信息分离：所有敏感信息通过环境变量注入，不硬编码在配置文件中
• 热重载支持：配置文件修改后自动生效，无需重启服务

---

配置加载流程

1. 路径解析优先级

配置文件路径按以下优先级解析：

主配置（config.yaml）

1. 显式传入的config_path参数
2. DEER_FLOW_CONFIG_PATH环境变量
3. 当前工作目录下的config.yaml
4. 当前工作目录父目录下的config.yaml（推荐位置）

扩展配置（extensions_config.json）

1. 显式传入的config_path参数
2. DEER_FLOW_EXTENSIONS_CONFIG_PATH环境变量
3. 当前工作目录下的extensions_config.json
4. 当前工作目录父目录下的extensions_config.json（推荐位置）
5. 兼容旧版：查找mcp_config.json作为备选
6. 不存在则返回空配置（扩展功能可选）

2. 环境变量解析

配置系统支持递归解析以$开头的环境变量引用：

• 示例：api_key: $OPENAI_API_KEY会自动替换为对应环境变量的值
• 作用范围：主配置和扩展配置中的所有字符串值都支持环境变量解析
• 错误处理：环境变量不存在时主配置会抛出异常，扩展配置会替换为空字符串避免运行错误

3. 配置版本检查

加载主配置时会自动对比用户配置与config.example.yaml的版本：

• 配置文件中config_version字段标识版本号
• 缺失config_version视为版本0
• 用户版本低于示例版本时会输出警告，提示运行make config-upgrade升级配置

4. 分类配置加载

主配置加载时会按功能模块分别初始化全局单例配置：

• title：自动标题生成配置
• summarization：上下文摘要配置
• memory：记忆系统配置
• subagents：子Agent配置
• tool_search：工具搜索配置
• guardrails：安全护栏配置
• checkpointer：状态持久化配置
• acp_agents：ACP外部Agent配置
• 扩展配置独立加载后合并到主配置的extensions字段

5. 自动热重载机制

配置系统内置自动热重载能力：

• 首次加载后缓存配置单例和文件修改时间(mtime)
• 每次调用get_app_config()时检查文件修改时间
• 检测到文件变更时自动重新加载配置，无需重启服务
• 扩展配置目前需手动调用reload_extensions_config()重载

---

配置结构

主配置（AppConfig）

基于Pydantic实现的强类型配置结构：

class AppConfig(BaseModel):
    log_level: str                  # 日志级别
    token_usage: TokenUsageConfig   # Token用量跟踪配置
    models: list[ModelConfig]       # 可用LLM模型列表
    sandbox: SandboxConfig          # 沙箱执行环境配置
    tools: list[ToolConfig]         # 自定义工具配置
    tool_groups: list[ToolGroupConfig] # 工具分组配置
    skills: SkillsConfig            # 技能系统配置
    extensions: ExtensionsConfig    # 扩展配置（自动加载）
    tool_search: ToolSearchConfig   # 工具搜索配置
    checkpointer: CheckpointerConfig | None # 状态持久化配置

子配置模块

每个功能领域都有独立的配置类：

配置类	功能
ModelConfig	LLM模型配置（提供商、密钥、参数、能力标识等）
SandboxConfig	沙箱环境配置（提供商、路径映射、资源限制等）
ToolConfig	自定义工具配置（加载路径、参数等）
MemoryConfig	记忆系统配置（开关、存储路径、模型、阈值等）
SubagentsConfig	子Agent配置（开关、超时时间等）
SummarizationConfig	摘要配置（开关、触发条件、模型等）
GuardrailsConfig	安全护栏配置（开关、提供商、规则等）

扩展配置（ExtensionsConfig）

class ExtensionsConfig(BaseModel):
    mcp_servers: dict[str, McpServerConfig] # MCP服务器配置
    skills: dict[str, SkillStateConfig]     # 技能开关状态配置

MCP服务器配置支持三种传输方式：

1. stdio：本地子进程方式启动MCP服务器
2. sse：连接远程SSE协议的MCP服务器
3. http：连接远程HTTP协议的MCP服务器

• 支持OAuth2认证（client_credentials/refresh_token模式）
• 支持自定义环境变量和HTTP头

---

关键特性

1. 自动热重载

• 主配置文件修改后自动生效，无需重启LangGraph或Gateway服务
• 基于文件修改时间检测变更，性能开销可忽略
• 运行中的会话自动使用新配置，无需中断用户交互

2. 环境变量安全注入

• 所有敏感信息（API密钥、令牌等）都可以通过环境变量传递
• 配置文件中仅保留环境变量引用，避免密钥泄露
• 支持递归解析嵌套结构中的环境变量

3. 配置版本管理

• 自动检测过时的配置文件，提示用户升级
• 配套make config-upgrade命令自动合并新配置字段
• 向后兼容旧版本配置，避免升级故障

4. 强类型校验

• 所有配置都基于Pydantic模型定义，加载时自动校验类型
• 格式错误提前发现，避免运行时异常
• 支持IDE自动补全和类型提示

5. 模块化设计

• 按功能领域拆分配置模块，易于扩展和维护
• 新增功能配置无需修改核心配置加载逻辑
• 每个子配置模块有独立的加载和访问API

6. 多环境支持

• 通过环境变量指定配置文件路径，支持开发、测试、生产等多环境部署
• 配置文件可以独立于代码仓库管理，避免敏感信息提交

---

运行时配置

除了静态配置文件，DeerFlow还支持在会话级别动态配置功能开关：

配置参数	作用	默认值
is_plan_mode	开启/关闭Plan Mode任务跟踪功能	False
model_name	指定当前会话使用的LLM模型	配置文件中第一个模型
thinking_enabled	开启/关闭模型思考模式	True
subagent_enabled	开启/关闭子Agent委派功能	False
max_concurrent_subagents	最大并发子Agent数	3
reasoning_effort	推理努力程度（low/medium/high）	None

运行时配置通过config.configurable参数在创建Agent会话时传入，仅对当前会话生效。

---

配置API

核心访问API

# 获取主配置单例（自动热重载）
from deerflow.config import get_app_config
config = get_app_config()

# 获取扩展配置单例
from deerflow.config import get_extensions_config
ext_config = get_extensions_config()

管理API

# 强制重载主配置
from deerflow.config import reload_app_config
new_config = reload_app_config()

# 强制重载扩展配置
from deerflow.config import reload_extensions_config
new_ext_config = reload_extensions_config()

# 重置配置缓存（测试用）
from deerflow.config import reset_app_config, reset_extensions_config
reset_app_config()

# 注入自定义配置（测试用）
from deerflow.config import set_app_config, AppConfig
custom_config = AppConfig(...)
set_app_config(custom_config)

辅助方法

# 获取指定模型配置
model_config = get_app_config().get_model_config("claude-3-opus")

# 获取指定工具配置
tool_config = get_app_config().get_tool_config("bash")

# 获取启用的MCP服务器
enabled_mcp = get_extensions_config().get_enabled_mcp_servers()

# 检查技能是否启用
is_enabled = get_extensions_config().is_skill_enabled("commit", "public")

---

最佳实践

1. 敏感信息管理：所有API密钥、凭证都通过环境变量传递，不要硬编码在配置文件中
2. 配置版本控制：config.example.yaml提交到代码仓库，实际config.yaml加入.gitignore
3. 热重载使用：修改配置文件后等待几秒自动生效，无需重启服务
4. 多环境部署：通过DEER_FLOW_CONFIG_PATH环境变量指定不同环境的配置文件
5. 配置升级：当看到版本过时警告时，运行make config-upgrade自动合并新字段

Tags:

• deer-flow

DeerFlow Harness 架构分析

DeerFlow Backend Sandbox 执行环境分析