配置

⚙️

所有 DeerFlow Harness 行为都由 config.yaml 驱动。一个文件控制哪些模型可用、沙箱如何运行、加载哪些工具，以及每个子系统的行为。

DeerFlow 的配置系统围绕一个目标设计：每一个有意义的行为都应该可以在配置文件中表达，而不是硬编码在应用程序中。这使部署可重现、可审计，并且易于按环境定制。

配置文件位置

DeerFlow 使用以下优先级顺序解析 config.yaml：

显式传递给 AppConfig.from_file(config_path) 的路径。
DEER_FLOW_CONFIG_PATH 环境变量。
backend/config.yaml（相对于后端目录）。
仓库根目录中的 config.yaml。

如果这些路径都不存在，应用程序在启动时会报错。

要使用自定义位置：


export DEER_FLOW_CONFIG_PATH=/path/to/my-config.yaml

环境变量插值

任何字段值都可以使用 $VAR_NAME 语法引用环境变量：


models:
  - name: gpt-4o
    api_key: $OPENAI_API_KEY

这使密钥不出现在配置文件本身中，变量在运行时从进程环境解析。

`use` 字段

许多配置条目使用 use: 字段来指定要实例化的 Python 类或对象，格式为：


package.subpackage.module:ClassName

或对于模块级对象：


package.subpackage.module:variable_name

示例：


sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
 
tools:
  - use: deerflow.community.tavily.tools:web_search_tool
    api_key: $TAVILY_API_KEY

这是 DeerFlow 实现可插拔性而不硬编码类引用的方式。

额外字段透传

对于模型配置，ModelConfig 使用 pydantic ConfigDict(extra="allow")。这意味着你在模型条目下添加的任何额外字段都直接传递给模型构造函数。这允许提供商特定选项（如 extra_body、reasoning 或自定义超时键）无需修改 Harness 即可工作：


models:
  - name: my-model
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    some_provider_specific_option: value # 传递给 ChatOpenAI 构造函数

配置版本

config.yaml 包含追踪 schema 版本的 config_version 字段：


config_version: 6

当 schema 更改（新字段、重命名章节）时，此数字增加。如果你本地的 config.yaml 落后于当前版本，运行：


make config-upgrade

这将 config.example.yaml 中的新字段合并到你现有的 config.yaml 中，而不覆盖你的自定义内容。

模块配置速查表

下表将 config.yaml 中的每个顶层章节映射到其文档页面：

章节	描述	文档
`log_level`	日志级别（`debug`/`info`/`warning`/`error`）	—
`models`	可用的 LLM 模型	Lead Agent
`token_usage`	每次模型调用的 token 追踪	中间件
`tools`	可用的 Agent 工具	工具
`tool_groups`	工具的命名分组	工具
`tool_search`	延迟/按需工具加载	工具
`sandbox`	沙箱提供者和选项	沙箱
`skills`	技能目录和容器路径	技能
`skill_evolution`	Agent 管理的技能创建	技能
`subagents`	子 Agent 超时和最大轮次	子 Agent
`acp_agents`	外部 ACP Agent 集成	子 Agent
`memory`	跨会话记忆存储	记忆系统
`summarization`	对话摘要压缩	中间件
`title`	自动生成线程标题	中间件
`checkpointer`	线程状态持久化	Agent 与线程
`guardrails`	工具调用授权	—
`uploads`	文件上传设置（PDF 转换器）	—
`channels`	IM 频道集成（飞书、Slack 等）	—

最小配置示例

最小有效的 config.yaml 至少需要一个模型和一个沙箱：


config_version: 6
 
models:
  - name: gpt-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    supports_vision: true
 
sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
 
tools:
  - use: deerflow.community.ddg_search.tools:web_search_tool
  - use: deerflow.community.jina_ai.tools:web_fetch_tool
  - use: deerflow.sandbox.tools:ls_tool
  - use: deerflow.sandbox.tools:read_file_tool
  - use: deerflow.sandbox.tools:write_file_tool
  - use: deerflow.sandbox.tools:bash_tool

从仓库根目录的 config.example.yaml 开始，取消注释你需要的章节。

部署指南应用配置

配置