docs: fill all TBD documentation pages and add new harness module pages

Agent-Logs-Url: https://github.com/bytedance/deer-flow/sessions/ff389ed8-31c9-430c-85ff-cc1b52b8239c Co-authored-by: foreleven <4785594+foreleven@users.noreply.github.com>
2026-05-24 08:55:59 +00:00 · 2026-04-11 05:01:20 +00:00
parent 814a488bcb
commit 88f822a8b3
18 changed files with 2449 additions and 17 deletions
@@ -1,3 +1,157 @@
+import { Callout, Cards } from "nextra/components";
+
 # Configuration

-TBD
+<Callout type="info" emoji="⚙️">
+  All DeerFlow Harness behaviors are driven by <code>config.yaml</code>. One
+  file controls which models are available, how the sandbox runs, what tools are
+  loaded, and how each subsystem behaves.
+</Callout>
+
+DeerFlow's configuration system is designed around one goal: every meaningful behavior should be expressible in a config file, not hardcoded in the application. This makes deployments reproducible, auditable, and easy to customize per environment.
+
+## Config file location
+
+DeerFlow resolves `config.yaml` using the following priority order:
+
+1. The path passed to `AppConfig.from_file(config_path)` explicitly.
+2. The `DEER_FLOW_CONFIG_PATH` environment variable.
+3. `backend/config.yaml` (relative to the backend directory).
+4. `config.yaml` in the repository root.
+
+If none of these paths exist, the application raises an error at startup.
+
+To use a custom location:
+
+```bash
+export DEER_FLOW_CONFIG_PATH=/path/to/my-config.yaml
+```
+
+## Environment variable interpolation
+
+Any field value can reference an environment variable using `$VAR_NAME` syntax:
+
+```yaml
+models:
+  - name: gpt-4o
+    api_key: $OPENAI_API_KEY
+```
+
+This keeps secrets out of the config file itself. The variable is resolved at runtime from the process environment.
+
+## The `use` field
+
+Many configuration entries use a `use:` field to specify the Python class or object to instantiate. The format is:
+
+```
+package.subpackage.module:ClassName
+```
+
+or for module-level objects:
+
+```
+package.subpackage.module:variable_name
+```
+
+Examples:
+
+```yaml
+sandbox:
+  use: deerflow.sandbox.local:LocalSandboxProvider
+
+tools:
+  - use: deerflow.community.tavily.tools:web_search_tool
+    api_key: $TAVILY_API_KEY
+```
+
+This pattern is how DeerFlow achieves pluggability without hardcoding class references.
+
+## Extra fields are passed through
+
+For model configuration, `ModelConfig` uses `pydantic ConfigDict(extra="allow")`. This means any extra fields you add under a model entry are passed directly to the model constructor. This allows provider-specific options (like `extra_body`, `reasoning`, or custom timeout keys) to work without modifying the harness:
+
+```yaml
+models:
+  - name: my-model
+    use: langchain_openai:ChatOpenAI
+    model: gpt-4o
+    api_key: $OPENAI_API_KEY
+    some_provider_specific_option: value  # passed through to ChatOpenAI constructor
+```
+
+## Configuration version
+
+`config.yaml` includes a `config_version` field that tracks the schema version:
+
+```yaml
+config_version: 6
+```
+
+When the schema changes (new fields, renamed sections), this number is bumped. If your local `config.yaml` is behind the current version, run:
+
+```bash
+make config-upgrade
+```
+
+This merges new fields from `config.example.yaml` into your existing `config.yaml` without overwriting your customizations.
+
+## Module configuration reference
+
+The following table maps each top-level `config.yaml` section to its documentation page:
+
+| Section | Description | Documentation |
+|---|---|---|
+| `log_level` | Logging level (`debug`/`info`/`warning`/`error`) | — |
+| `models` | Available LLM models | [Lead Agent](/docs/harness/lead-agent) |
+| `token_usage` | Token tracking per model call | [Middlewares](/docs/harness/middlewares) |
+| `tools` | Available agent tools | [Tools](/docs/harness/tools) |
+| `tool_groups` | Named groups of tools | [Tools](/docs/harness/tools) |
+| `tool_search` | Deferred/on-demand tool loading | [Tools](/docs/harness/tools) |
+| `sandbox` | Sandbox provider and options | [Sandbox](/docs/harness/sandbox) |
+| `skills` | Skills directory and container path | [Skills](/docs/harness/skills) |
+| `skill_evolution` | Agent-managed skill creation | [Skills](/docs/harness/skills) |
+| `subagents` | Subagent timeouts and max turns | [Subagents](/docs/harness/subagents) |
+| `acp_agents` | External ACP agent integrations | [Subagents](/docs/harness/subagents) |
+| `memory` | Cross-session memory storage | [Memory](/docs/harness/memory) |
+| `summarization` | Conversation summarization | [Middlewares](/docs/harness/middlewares) |
+| `title` | Automatic thread title generation | [Middlewares](/docs/harness/middlewares) |
+| `checkpointer` | Thread state persistence | [Agents & Threads](/docs/application/agents-and-threads) |
+| `guardrails` | Tool call authorization | — |
+| `stream_bridge` | Streaming configuration | — |
+| `uploads` | File upload settings (PDF converter) | — |
+| `channels` | IM channel integrations (Feishu, Slack, etc.) | — |
+
+## Minimal config to get started
+
+The minimum valid `config.yaml` requires at least one model and a sandbox:
+
+```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
+```
+
+Start from `config.example.yaml` in the repository root and uncomment the sections you need.
+
+<Cards num={2}>
+  <Cards.Card title="Deployment Guide" href="/docs/application/deployment-guide" />
+  <Cards.Card title="Application Configuration" href="/docs/application/configuration" />
+</Cards>