从入门到精通：OpenHands自定义LLM模型与API密钥安全管理指南

【免费下载链接】OpenHands 🙌 OpenHands: Code Less, Make More 项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands

作为一款强大的AI辅助开发工具，OpenHands允许用户根据自身需求灵活配置大语言模型(LLM)和管理API密钥。本文将详细介绍如何通过配置文件自定义LLM参数、设置API密钥以及实现多模型切换，帮助您充分发挥OpenHands的潜能。

配置文件基础

OpenHands的所有配置都集中在项目根目录下的config.toml文件中。如果您是首次使用，可以通过复制模板文件创建配置：

cp config.template.toml config.toml

配置文件采用TOML（Tom's Obvious, Minimal Language）格式，结构清晰且易于编辑。核心配置模块包括：

• [core] - 应用核心设置
• [llm] - LLM模型配置
• [agent] - 智能体行为配置
• [sandbox] - 沙箱环境设置

配置系统的实现代码位于openhands/core/config/utils.py，该模块负责从文件和环境变量加载配置并应用默认值。

LLM模型配置详解

默认LLM配置

[llm]部分用于设置默认语言模型参数。以下是一个基本配置示例：

[llm]
model = "gpt-4o"
api_key = "your_api_key_here"
temperature = 0.7
top_p = 0.9
max_output_tokens = 2048

关键参数说明：

• model - 模型名称，如"gpt-4o"、"claude-3-5-sonnet"等
• api_key - API访问密钥（敏感信息，建议通过环境变量设置）
• temperature - 控制输出随机性，0.0表示确定性输出，1.0表示高度随机
• top_p - 控制采样多样性，较小值使输出更集中
• max_output_tokens - 限制模型输出长度

模型配置的核心定义在openhands/core/config/llm_config.py文件中的LLMConfig类，包含了所有支持的参数及其默认值。

多模型配置

OpenHands支持配置多个LLM模型，并在不同场景中灵活切换。例如，您可以同时配置GPT-4o和Claude模型：

[llm]
# 默认模型配置
model = "gpt-4o"
api_key = "your_openai_key"
temperature = 0.5

[llm.claude]
model = "claude-3-5-sonnet-20241022"
api_key = "your_anthropic_key"
temperature = 0.7
max_output_tokens = 4096

这种配置方式允许您在不同智能体或任务中使用不同模型。如config.template.toml中所示，您可以为特定智能体指定模型：

[agent.RepoExplorerAgent]
# 为代码库探索智能体使用更经济的模型
llm_config = 'gpt3'

API密钥安全管理

配置文件中的密钥存储

虽然可以直接在config.toml中设置api_key，但出于安全考虑，更推荐使用环境变量或专用密钥管理工具。配置文件中的密钥设置方式如下：

[llm]
# 直接设置（不推荐用于生产环境）
api_key = "sk-..."

[llm.claude]
# 留空将从环境变量读取
api_key = ""

当api_key留空时，系统会尝试从环境变量加载对应的值。环境变量的命名规则为LLM_<模型名>_API_KEY，例如：

• LLM_API_KEY - 默认模型密钥
• LLM_CLAUDE_API_KEY - Claude模型密钥

环境变量加载机制

OpenHands的配置系统会自动从环境变量加载配置参数。相关实现代码在openhands/core/config/utils.py的load_from_env函数中：

def load_from_env(cfg: AppConfig, env_or_toml_dict: dict | MutableMapping[str, str]) -> None:
    # 从环境变量设置配置属性
    # ...
    def set_attr_from_env(sub_config: BaseModel, prefix='') -> None:
        for field_name, field_info in sub_config.model_fields.items():
            # 环境变量名格式如LLM_BASE_URL、AGENT_MEMORY_ENABLED等
            env_var_name = (prefix + field_name).upper()
            if env_var_name in env_or_toml_dict:
                # 转换并设置属性值
                # ...

在Linux/macOS系统中，您可以在终端中设置环境变量：

export LLM_API_KEY="your_openai_api_key"
export LLM_CLAUDE_API_KEY="your_anthropic_api_key"

在Windows系统中，使用：

set LLM_API_KEY="your_openai_api_key"

密钥优先级机制

OpenHands采用以下优先级顺序加载配置（从高到低）：

1. 命令行参数
2. 环境变量
3. config.toml文件
4. 默认值

这种机制允许您在不修改配置文件的情况下临时覆盖设置，例如：

LLM_MODEL="gpt-4o-mini" openhands run --task "分析这个代码库"

本地LLM配置

对于本地部署的模型（如通过Ollama运行的开源模型），需要配置base_url参数指向本地服务：

[llm.ollama]
model = "llama3:8b"
base_url = "http://localhost:11434"
api_key = "none"  # Ollama不需要API密钥
temperature = 0.8

本地模型的支持在openhands/llm/llm.py中实现，通过检查base_url中是否包含"localhost"或"127.0.0.1"来判断是否为本地模型：

def _is_local(self) -> bool:
    """判断是否使用本地运行的LLM"""
    if self.config.base_url is not None:
        for substring in ['localhost', '127.0.0.1', '0.0.0.0']:
            if substring in self.config.base_url:
                return True
    elif self.config.model is not None:
        if self.config.model.startswith('ollama'):
            return True
    return False

配置验证与调试

配置验证

配置系统使用Pydantic模型进行参数验证，确保配置值的类型和范围正确。例如，在openhands/core/config/llm_config.py中定义的LLMConfig类：

class LLMConfig(BaseModel):
    model: str = Field(default='claude-3-7-sonnet-20250219')
    api_key: SecretStr | None = Field(default=None)
    temperature: float = Field(default=0.0)
    # ...其他字段...
    
    model_config = {'extra': 'forbid'}  # 禁止未知字段

如果配置文件中包含无效值或未知字段，系统会记录警告并使用默认值：

WARNING: Cannot parse [llm] config from toml. Continuing with defaults.

调试配置问题

如果您遇到配置不生效的问题，可以通过以下方式调试：

1. 启用调试日志：

[core]
debug = true

2. 检查配置加载顺序：确认环境变量没有意外覆盖配置文件设置

3. 验证配置加载结果：查看应用启动时输出的配置摘要

4. 检查日志文件：配置相关日志会输出到应用日志中，可帮助追踪加载过程

配置加载的完整流程在openhands/core/config/utils.py的load_app_config函数中实现：

def load_app_config(set_logging_levels: bool = True, config_file: str = 'config.toml') -> AppConfig:
    """从指定配置文件和环境变量加载配置"""
    config = AppConfig()
    load_from_toml(config, config_file)
    load_from_env(config, os.environ)
    finalize_config(config)
    # ...
    return config

高级应用：模型切换与性能优化

按任务类型自动切换模型

通过智能体配置，您可以为不同任务类型自动选择最适合的模型。例如，代码生成任务使用GPT-4o，而简单问答使用更经济的模型：

[agent.CodeActAgent]
llm_config = 'llm'  # 使用默认的GPT-4o模型

[agent.QuestionAnswerAgent]
llm_config = 'gpt4o-mini'  # 使用轻量模型

[llm.gpt4o-mini]
model = "gpt-4o-mini"
temperature = 0.3
max_output_tokens = 1024

性能优化配置

根据openhands/llm/llm.py中的实现，您可以调整以下参数优化LLM性能：

[llm]
# 重试策略
num_retries = 4
retry_min_wait = 5  # 初始重试等待时间(秒)
retry_max_wait = 30  # 最大重试等待时间(秒)
retry_multiplier = 2  # 重试等待时间乘数

# 缓存设置
caching_prompt = true  # 启用提示缓存(支持的模型)

# 输出控制
max_message_chars = 30000  # 输入消息最大字符数

这些参数控制LLM调用的重试行为、缓存策略和输入处理，帮助平衡性能和成本。

总结与最佳实践

配置最佳实践

1. 敏感信息管理：

   • 避免在配置文件中硬编码API密钥
   • 使用环境变量或密钥管理服务
   • 将config.toml添加到.gitignore，避免版本控制中泄露密钥

2. 多环境配置：

   • 为不同环境创建专用配置文件，如config.development.toml、config.production.toml
   • 使用符号链接在不同环境间切换：ln -s config.development.toml config.toml

3. 模型选择策略：

   • 复杂任务(代码生成、推理)：使用功能强大的模型如GPT-4o、Claude-3-5-Sonnet
   • 简单任务(格式化、摘要)：使用轻量级模型如GPT-4o-mini、Claude-3-Haiku
   • 本地部署：使用Ollama运行开源模型如Llama 3、Mistral

常见问题解决

Q: 配置修改后没有生效怎么办？
A: 检查配置文件路径是否正确，确保没有同名环境变量覆盖配置值，尝试重启应用。

Q: 如何确认当前使用的是哪个LLM模型？
A: 启用调试日志后，应用启动时会输出当前配置摘要，包含使用的模型信息。

Q: 本地模型无法连接怎么办？
A: 确认本地LLM服务已启动，检查base_url配置是否正确，验证网络连接和端口访问权限。

通过合理配置LLM模型和API密钥，您可以充分发挥OpenHands的能力，同时优化性能和成本。如需了解更多配置选项，请参考项目中的config.template.toml文件和配置系统源代码。

后续学习路径

1. 探索openhands/agenthub/中的智能体类型，了解不同智能体如何使用LLM配置
2. 研究openhands/core/config/agent_config.py，自定义智能体行为
3. 了解openhands/llm/metrics.py中的成本和性能监控功能，优化API使用成本

掌握OpenHands的配置系统将帮助您充分利用AI能力，提高开发效率，同时保持对成本和性能的控制。随着项目的发展，配置选项将不断丰富，建议定期查看配置模板和文档更新。

【免费下载链接】OpenHands 🙌 OpenHands: Code Less, Make More 项目地址: https://gitcode.com/GitHub_Trending/ope/OpenHands