DeerFlow 环境配置实战config.yaml 定位、运行时路径与沙箱镜像预热【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flowDeerFlow 是一个面向长周期任务的开源 SuperAgent 框架其所有运行时行为模型、工具、沙箱、技能路径都由一份位于项目根目录的config.yaml驱动。本文基于仓库中的 SETUP.md 展开完整覆盖配置创建、API Key 注入、配置定位规则、运行时路径环境变量与沙箱镜像预拉取等操作步骤并结合AppConfig、runtime_paths.py等源码实现说明每个环节在 DeerFlow 内部到底如何解析、何时会热重载、升级失败时如何诊断。一、配置初始化从示例文件到本地 config.yamlDeerFlow 使用一份 YAML 配置文件必须放在项目根目录即deer-flow/目录下。官方示例配置为 config.example.yaml完整初始化步骤如下进入项目根目录cd /path/to/deer-flow复制示例配置cp config.example.yaml config.yaml编辑配置注入模型 API Key两种任选其一# Option A: 设置环境变量推荐 export OPENAI_API_KEYyour-key-here # 可选从其他目录运行 DeerFlow 时显式固定项目根目录 export DEER_FLOW_PROJECT_ROOT/path/to/deer-flow # Option B: 直接编辑 config.yaml vim config.yaml # 或使用你习惯的编辑器验证配置是否被正确加载cd backend python -c from deerflow.config import get_app_config; print(✓ Config loaded:, get_app_config().models[0].name)该验证命令打印models列表第一个模型的name字段能一次性确认“配置文件找到了 → YAML 解析成功 → 模型列表非空”三件事。环境变量引用语法config.example.yaml头部注释明确说明所有字段值都支持环境变量引用例如api_key: $OPENAI_API_KEY。这一点在源码中有对应实现——app_config.py 中的resolve_env_variables会递归遍历整棵配置树字符串以$开头时通过os.getenv解析变量名如果引用了未设置的环境变量加载会直接抛出ValueErrorEnvironment variable XXX not found for config value ...而不是静默置空——这是有意的 fail-fast 设计能帮你尽早发现漏配。因此推荐做法是配置文件中写api_key: $OPENAI_API_KEY这类引用密钥只存在于环境变量中。这与仓库的安全约定一致config.yaml已被 .gitignore 自动忽略其中同时忽略config.yaml与升级备份config.yaml.bak避免含密文件被提交。直接复制示例文件为何不会报错config.example.yaml中models:、memory:等大量顶层区块默认是“键存在但下面全是注释”的状态PyYAML 会把它们解析成None。如果框架直接把这些None交给 Pydantic首跑流程会崩在不明的Input should be a valid list错误上。AppConfig 通过_drop_null_config_sections校验器把所有“存在但为 null”的区块丢弃、回退到各字段的默认值列表区块变为空列表对象区块使用默认配置从而保证cp config.example.yaml config.yaml之后立刻可运行。唯一例外是sandbox这类无默认值、必须显式声明的区块——它在为 null 时仍会报错。二、关键运行时路径环境变量速查SETUP.md 的 Important Notes 部分列出了四个必须理解的约定其底层实现集中在 runtime_paths.py约定默认值控制变量源码依据配置文件位置项目根目录deer-flow/config.yamlDEER_FLOW_CONFIG_PATH直接指定文件resolve_config_path/existing_project_file项目根目录当前工作目录cwdDEER_FLOW_PROJECT_ROOTproject_root()运行时状态目录项目根下.deer-flowDEER_FLOW_HOMEruntime_home()技能目录项目根下skills/DEER_FLOW_SKILLS_PATH或配置项skills.pathskills_config.py几个值得注意的实现细节DEER_FLOW_PROJECT_ROOT有强校验project_root()会 resolve 该路径若目录不存在或不是目录直接抛ValueError。这意味着“指错路径”不会静默退化为当前目录而是启动即失败便于定位问题。DEER_FLOW_HOME优先于项目根推导runtime_home()在设置该变量时返回其 resolve 结果否则回退到project_root() / .deer-flow。数据库默认值sqlite_dir: .deer-flow/data见 app_config.py 的CONFIG_FILE_DATABASE_DEFAULTS也落在该目录下因此移动DEER_FLOW_HOME等价于整体迁移运行时状态。相对路径的解析基准resolve_path将相对路径一律相对项目根解析而不是相对配置文件位置。三、config.yaml 的四级定位顺序当后端需要找到config.yaml时AppConfig.resolve_config_pathapp_config.py按以下优先级依次查找代码显式传入的config_path参数文件不存在时抛FileNotFoundErrorDEER_FLOW_CONFIG_PATH环境变量同样要求文件必须存在不存在即抛错项目根目录下的config.yaml项目根由DEER_FLOW_PROJECT_ROOT决定未设置时取当前工作目录existing_project_file((config.yaml,))遗留的 monorepo 兼容位置_legacy_config_candidates()返回backend/config.yaml与仓库根config.yaml两个候选用于兼容历史目录结构。四级都未命中时抛出FileNotFoundError: config.yaml file not found in the project root or legacy backend/repository root locations官方推荐仍将config.yaml放在项目根deer-flow/config.yaml理由正是上面第 3 级是主路径且make config-upgrade等脚本也优先按该约定解析。配置不是加载一次就结束热重载机制get_app_config()返回的是缓存的单例但它并非“只读缓存”。每次调用都会重新resolve_config_path并比较解析路径、文件 mtime 与内容签名app_config.py一旦config.yaml被修改下一次访问会自动重新加载并在日志中记录Config file content signature changed, reloading AppConfig。部分子系统如 checkpointer在配置变更时还会触发reset_checkpointer()/reset_store()重建单例。需要注意并非所有字段都可热更新——重启才生效的字段清单由reload_boundary模块维护示例配置注释中也提到database属于 restart-required 字段修改这类配置后应重启 Gateway。四、配置版本管理与升级config.example.yaml第 18 行声明config_version: 39它用于检测你的本地配置是否落后。加载流程中的_check_config_versionapp_config.py会从config.yaml所在目录逐级向上找config.example.yaml最多 5 层比较两个文件中的config_version用户版本低于示例版本时打印警告提示运行make config-upgrade。make config-upgrade对应 scripts/config-upgrade.sh其工作过程是依次应用版本化迁移例如 v1 迁移会把src.community./src.sandbox.等旧模块路径批量替换为deerflow.*把config.example.yaml中缺失的新字段递归合并进你的配置只补缺失键不改写已有值修改前自动备份为config.yaml.bak该文件同样被 .gitignore 忽略。此外仓库还提供make config运行 scripts/configure.py若本地已有配置则中止与交互式向导make setupscripts/setup_wizard.py以及用于自检的make doctorscripts/doctor.py可作为配置初始化后的健康检查手段。五、沙箱镜像预热可选但推荐如果你在config.yaml的sandbox.use中启用了容器沙箱deerflow.community.aio_sandbox:AioSandboxProvider强烈建议在首次运行前预拉取镜像# 从项目根目录执行 make setup-sandbox为什么建议预热沙箱镜像体积约 500MB若不在预热首次 Agent 执行时会边拉取边等待造成明显的长等待预热过程有清晰的进度输出避免首次使用 Agent 时被“卡住”误导。跳过此步骤不会导致失败——镜像会在第一次 Agent 执行时自动拉取耗时取决于网络。从 scripts/setup-sandbox.sh 的实现可以看到更多细节脚本会先grep你config.yaml中sandbox:段下未注释的image:字段找到则拉取该镜像未找到时回退到内置默认镜像enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:1.11.0固定版本而非:latest因为镜像源的:latest标签冻结在缺少/v1/bash/*路由的旧 digest 上相关背景见 config.example.yaml 沙箱段注释若拉取的是默认镜像而配置中并无显式sandbox.image脚本会明确警告预热镜像不等于运行时使用它需要在config.yaml中显式写出sandbox.image才会真正生效macOS 上检测到 Apple Container 时会优先走container image pull否则使用docker pull。config.example.yaml的沙箱段同时给出了 Local / AIO 容器 / BoxLite / Provisioner 等多种 provider 的注释示例切换沙箱方案时可直接取消对应注释。六、故障排查1. 找不到配置文件先让后端告诉你它正在查找哪里# 进入 deer-flow/backend 后执行打印后端实际解析出的配置路径 cd deer-flow/backend python -c from deerflow.config.app_config import AppConfig; print(AppConfig.resolve_config_path())如果解析失败按顺序检查确认已执行cp config.example.yaml config.yaml确认你位于项目根目录或已设置DEER_FLOW_PROJECT_ROOTls -la config.yaml确认文件确实存在。对照上文“四级定位顺序”即可判断是走到了哪一级失败参数/环境变量指定了不存在的路径时错误信息会带具体路径走到第 3、4 级仍找不到时则是上述通用FileNotFoundError。2. 权限被拒绝Permission deniedconfig.yaml含密钥建议收紧文件权限chmod 600 ../config.yaml # 保护敏感配置在 backend/ 目录下执行指向项目根的 config.yaml七、进一步阅读配置指南完整配置项详解架构总览系统架构示例配置文件所有模型、工具与沙箱选项的带注释范例配置热重载边界 与backend/packages/harness/deerflow/config/reload_boundary.py哪些字段可热更新、哪些需重启相关测试可参考 test_app_config_reload.py 与 test_config_version.py覆盖热重载与版本检查行为。【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考