OpenHands启动机制解析

• 0x00 概要

• 0x01 背景

  

  • 总体架构
  • 切入点

• 0x02 初始化 @ run_controller

  • 总体流程
  • 创建注册中心
  • 创建Agent
  • 建立Runtime
  • 建立Memory & Microagent
  • 创建MCP
  • 创建Controller
  • 发送启动事件
  • 说到订阅事件流。注册使用者输入回调函数
  • 运行代理
  • run_controller全部代码

• 0xFF 参考资料列表

0x00 概要 & 使用者痛点

概要： 当分析一个程序时启动部分和使用者典型使用场景是最理想的切入点，因为这两个部分可以覆盖程序大部分功能模块。借此可以架构，

使用者痛点：

• 难以快速定位错误源：启动日志往往分散在不同模块，缺少统一视图导致排查耗时。
• 资源控制不够细粒度：N/A 迭代次数或预算限制过宽或过窄，导致执行效率低下或费用失控。
• 可观测性不足：No real‑time feedback on state changes makes debugging difficult.
• Persistence 问题：A session may crash without preserving state for resumption.

0x01 背景 & 使用者痛点映射

总体架构概览🔧️ 技术细节可略过主要关注 EventStream 的四步循环。

1. ① 初始化就绪：会话开启时自动完成 Agent、AgentController、Runtime、Memory 等主要模块初始化，并订阅 EventStream；使用者痛点1：初始化耦合太高，单个错误会导致整个会话崩溃。
2. ② 任务发起：使用者发送消息即注入一条事件，触发所有订阅者；痛点2：无统一入口导致多处重复代码。
3. ③ 多模块协同响应：
   1. - Session 模块持续上报状态事件；痛点3：状态日志不易筛选关键信息。

    
   
   - Security Analyzer 自动确认低风险任务；
   
   痛点4：安全策略配置繁琐且难以调试。
   
   - AgentController 注入 RecallAction，Memory 判断首次接收并返回 RecallObservation；
   
   痛点5：首次输入处理逻辑隐藏在深层调用里。
   

I style=\"margin-bottom:6px;\">④ 状态同步：AgentController 调用 Agent.step 更新任务状态并注入 Action；痛点6：状态同步延迟高，导致 UI 响应慢。 请注意，这里已将原始文本中的冗余段落简化。只保留最关键的交互步骤，并在每一步后添加对应的“使用者痛点”说明，以帮助读者快速定位可能遇到的问题。

切入点示例与常见错误对照表:

python config = load_openhands_config action = MessageAction state = await run_controller #2 无法获取 LLM 实例: - 在 `create_registry_and_conversation_stats` 中确认 `llm_registry.get_router` 返回非空。- 检查网络连通性及 token 配置。

总体流程

`run_controller` 是 OpenHands 后端单个会话的主要入口协程，其职责包括:

① 会话全生命周期管理 – 会话 ID、运行时连接、仓库克隆、MCP 工具嵌入、轨迹重放等关键操作一次完成。会话恢复需手动检查多项参数，一旦配置错误就不可用。
② 双重安全管控 – 最大迭代次数 与单任务最高预算 两层硬性限制，可规避无限循环和费用超额。阈值设定不合理时容易误判为“超限”，导致正常任务被中断。
③ 全流程可观测 – EventStream 实现事件实时分发。可同时支持 CLI、前端界面与日志程序同步订阅，还能生成 JSON 格式执行轨迹进行审计。JSON 日志文件大且结构复杂，手动分析耗时长。

下面从底层组件逐一展开这些主要职责，并给出对应的 “如何排错” 小贴士。

1️⃣ 创建注册中心 & 对话统计实例

`create_registry_and_conversation_stats` 会根据配置调整基础配置，接下来：

① 根据 `user_settings` 覆盖默认 LLM 配置；按理说，若自定义 LLM 未生效。请确认 `user_settings.agent` 与 `default_agent` 的一致性。
② 创建 LLM 注册表 并关联配置；若出现 “No registered LLMs” 错误，请检查是否加载了至少一个 LLM 模型实例。
③ 初始化文件存储与对话统计器，并让两者相互订阅；若日志文件写不到磁盘，请确认权限及硬盘空间足够。并检查 `file_store_path` 是否正确设置。按理说，

2️⃣ 创建 Agent

`create_agent` 根据 config 获取 agent 类并实例化。例如默认使用 `"CodeActAgent"`。至于关键步骤包括，

① 加载 agent 配置并绑定 runtime 信息；若出现 “AttributeError: 'NoneType' object has no attribute …”，请确保 runtime 已经实例化且传递给 agent 构造函数。.
② 设置模型路由 – 若启用了路由，需要确保路由器返回的是合法模型实例；路由失败通常是因为 `agent.config.llm_name` 未匹配任何已注册模型名称，请检查配置文件中的名称拼写是否一致。.
③ 加载工具集 与记忆程序；怎么说呢，工具加载失败可能是缺少依赖包或插件方法不正确。请查看 console 输出中提示的 “ModuleNotFoundError”。.

3️⃣ 建立 Runtime

常见错误与排查建议
#1 初始化失败: - 检查 `runtime` 是否正确连接仓库。- 确认 `config.sandbox.selected_repo` 指向实用方法。- 查看 `runtime.event_stream` 是否已成功订阅。