配置系统

相关源文件

• config.template.toml
• openhands/core/config/README.md
• openhands/core/config/__init__.py
• openhands/core/config/agent_config.py
• openhands/core/config/config_utils.py
• openhands/core/config/extended_config.py
• openhands/core/config/security_config.py
• openhands/core/config/utils.py
• openhands/core/main.py
• tests/unit/test_arg_parser.py
• tests/unit/test_config.py
• tests/unit/test_config_extended.py

本文档描述了OpenHands中的分层配置管理系统，该系统提供了从TOML文件、环境变量和命令行参数灵活加载配置的功能。该系统使用Pydantic模型进行类型验证，并支持不同组件的命名配置。

有关特定运行时配置的信息，请参阅运行时系统。

配置概述

OpenHands使用以OpenHandsConfig类为中心的层级配置系统。配置从多个来源按定义的优先级加载，从而在保持合理的默认值的同时实现灵活的自定义。

配置系统遵循此加载顺序，后续来源能够覆盖先前来源的值

1. Pydantic模型中定义的默认值
2. 来自TOML配置文件（默认：config.toml）的值
3. 环境变量（具有特定的命名约定）
4. 命令行参数

这种优先级顺序确保了最大的灵活性，同时保持了稳健的默认值。

来源：openhands/core/config/utils.py785-803 openhands/core/main.py11-15 openhands/core/config/utils.py124-293

配置类层级结构

配置系统围绕OpenHandsConfig类组织，该类包含所有配置选项，并为不同的组件提供专门的配置类。每个类都使用Pydantic进行验证，并支持从TOML节加载。

架构展示了配置类之间的关系。 OpenHandsConfig类包含LLMConfig和AgentConfig实例的字典，以支持命名配置，并包含其他专用配置的单个实例。

来源：openhands/core/config/openhands_config.py openhands/core/config/agent_config.py10-47 openhands/core/config/security_config.py4-15 openhands/core/config/extended_config.py6-42

配置加载过程

配置通过一系列函数加载，这些函数以特定顺序组合多个来源

加载配置的典型模式是使用load_openhands_config函数

此函数内部执行完整的加载序列，并在代码库中普遍使用。

来源：openhands/core/config/utils.py785-803 openhands/core/main.py279 openhands/core/config/utils.py805-838

配置源

TOML 配置

主要配置源是一个TOML文件（默认：config.toml）。该文件分为几个部分。

• [core]：OpenHands通用配置
• [llm]：默认LLM配置
• [llm.<name>]：命名LLM配置
• [agent]：默认Agent配置
• [agent.<name>]：命名Agent配置
• [sandbox]：沙盒环境配置
• [security]：安全功能配置
• [condenser]：对话历史管理配置

基本的TOML配置示例

来源：config.template.toml1-382 openhands/core/config/utils.py114-135

环境变量

环境变量可以使用特定的命名约定覆盖TOML配置。load_from_env函数使用反射自动将环境变量映射到配置字段。

命名约定

• 大写字母加下划线
• 节前缀：LLM_，AGENT_，SANDBOX_，SECURITY_，MCP_
• 字段名：Pydantic字段名的大写版本

类型转换：系统自动处理类型的转换

• 布尔值：'true'，'1' → True；'false'，'0' → False
• 列表和字典：使用literal_eval解析
• 可选类型：从Union类型中提取非None类型

环境变量使用示例

来源：openhands/core/config/utils.py41-122 openhands/core/config/utils.py67-111

命令行参数

命令行参数提供最高优先级的配置。关键参数包括：

• --config-file：TOML配置文件的路径
• --llm-config：要使用的LLM配置的名称
• --agent-config：要使用的Agent配置的名称
• --agent-cls：要使用的Agent类的名称
• --max-iterations：最大迭代次数
• --max-budget-per-task：每个任务的最大预算

命令行用法示例

来源：openhands/core/config/utils.py440-557 openhands/core/main.py264-297

命名配置

OpenHands配置系统最强大的功能之一是能够为不同组件定义命名配置。

命名LLM配置

命名LLM配置允许定义具有不同模型、参数或API端点的多个LLM设置。它们在TOML文件中的[llm.<name>]节下定义，并由LLMConfig.from_toml_section()处理。

在代码中访问这些配置

来源：openhands/core/config/utils.py176-184 openhands/core/config/utils.py454-508 tests/unit/test_config.py174-213

命名Agent配置

命名Agent配置允许自定义不同Agent类型的行为。它们在TOML文件中的[agent.<name>]节下定义，并由AgentConfig.from_toml_section()处理。

在代码中访问这些配置

来源：openhands/core/config/agent_config.py49-108 openhands/core/config/utils.py164-173 tests/unit/test_config.py145-156

配置继承

命名配置会继承其父节的值。例如，[llm.gpt3]会继承[llm]的所有值，除非它们被明确覆盖。

此表总结了继承的工作原理

章节	继承自	示例
[llm.<name>]	[llm]	[llm.gpt3] 继承自 [llm]
[agent.<name>]	[agent]	[agent.RepoExplorerAgent] 继承自 [agent]

来源： openhands/core/config/llm_config.py90-152 tests/unit/test_llm_config.py50-216

压缩器配置

压缩器控制着当上下文过大时如何管理和压缩对话历史。配置系统支持多种类型的压缩器。

TOML 格式的压缩器配置示例

来源： config.template.toml320-382 tests/unit/test_config.py585-646

配置最终化

加载完所有来源的配置后，配置将通过 finalize_config 函数进行最终化，该函数执行必要的后处理步骤。

主要的最终化步骤

1. 工作空间路径解析：处理 sandbox.volumes 以设置工作空间挂载路径
2. 路径绝对化：将缓存目录和日志路径的相对路径转换为绝对路径
3. JWT 密钥管理：使用 get_or_create_jwt_secret 生成或检索 JWT 密钥
4. 运行时兼容性：自动禁用 CLI 运行时的 Jupyter/浏览功能
5. 目录创建：创建必要的目录（缓存、日志文件夹）
6. 默认压缩器设置：如果 enable_default_condenser 为 true，则设置默认压缩器

卷处理示例

CLI 运行时调整

这确保配置完整、经过验证，并可在整个系统中随时使用。

来源： openhands/core/config/utils.py305-399 openhands/core/config/utils.py295-303 openhands/core/config/utils.py376-399

安全考量

配置系统包含多项安全相关功能

1. 敏感值保护：API 密钥和其他敏感值存储为 SecretStr 对象
2. 日志保护：日志系统自动屏蔽敏感值
3. JWT 密钥管理：JWT 密钥自动生成和管理

来源： openhands/core/config/llm_config.py48-54 openhands/core/logger.py234-279

配置 API 用法示例

基本配置加载

使用命名配置

命令行配置加载

手动配置步骤

来源： openhands/core/config/utils.py785-803 openhands/core/config/utils.py805-838 openhands/core/main.py277-279 openhands/core/config/utils.py805-838 tests/unit/test_arg_parser.py26-76

命令行配置界面

OpenHands 通过 get_parser() 函数提供了一个全面的命令行界面来配置应用程序。

主要的命令行参数

参数	描述	默认	环境变量
--config-file	配置文件路径	config.toml	-
--llm-config	使用的命名 LLM 配置	默认 LLM	-
--agent-cls	使用的代理类	CodeActAgent	-
--agent-config	使用的命名代理配置	默认代理	-
--max-iterations	最大迭代次数	250	-
--max-budget-per-task	最大预算	无	-
--directory	工作目录	当前目录	-
--selected-repo	GitHub 存储库（所有者/存储库）	无	-

CLI 覆盖流程

来源： openhands/core/config/utils.py624-747 openhands/core/config/utils.py805-838 tests/unit/test_arg_parser.py26-76

与 OpenHands 系统的集成

配置系统通过 OpenHandsConfig 对象与 OpenHands 集成，该对象在系统初始化期间传递给各种组件。配置通过关键的设置函数流转，这些函数创建主要的系统组件。

关键集成点

1. 代理创建：create_agent() 使用 config.get_agent_config() 和 config.get_llm_config_from_agent()
2. 运行时设置：create_runtime() 使用 config.sandbox 进行 Docker/远程运行时配置
3. 控制器初始化：create_controller() 使用完整的配置进行编排
4. 内存设置：create_memory() 使用配置加载对话和微代理

主应用程序中的配置流程

来源： openhands/core/main.py99-156 openhands/core/setup.py openhands/core/main.py277-279

配置调试

配置系统包含调试功能，以帮助诊断问题

1. 结构化日志：记录配置加载事件
2. 环境变量追踪：追踪环境变量加载
3. TOML 解析错误：报告 TOML 解析错误

要启用调试模式，请设置 DEBUG 环境变量

来源： openhands/core/logger.py16-17 openhands/core/logger.py42-44

最佳实践

1. 使用 TOML 进行持久化配置：将稳定的配置存储在 config.toml 中
2. 使用环境变量存储敏感信息：将 API 密钥和敏感数据存储在环境变量中
3. 使用命令行参数进行临时更改：为一次性运行使用命令行参数
4. 定义命名配置：为不同的用例定义不同的配置
5. 覆盖特定设置：只覆盖您需要更改的设置，其余的保持默认

来源： config.template.toml1-382 openhands/core/config/README.md1-101