Agent框架探秘：拆解 OpenHands（9）--- AgentController 与 TaoToken 配置实战

1. 从一次 AgentController 初始化失败说起如果你正在折腾 OpenHands大概率会遇到这样一个场景容器起来了Web UI 也能打开但一发消息就卡住日志里反复出现AgentController初始化相关的报错或者 LLM 调用直接 401。我试过在本地和云主机上各部署一遍发现十次里有七次问题不在 Agent 本身而在配置加载链路——也就是config.toml里 LLM 那段没写对或者环境变量没被 AgentController 正确读到。OpenHands 的 AgentController 是整个 Agent 运行时的“指挥中枢”它负责订阅事件流、维护状态机、驱动step()迭代并在需要时创建委托子控制器。而它驱动 LLM 调用的依据全部来自初始化时注入的LLMConfig。换句话说AgentController 本身不关心你用哪家模型它只认配置。配置对了Agent 就能跑配置错了再强的模型也调不通。这篇就聚焦一件事把 TaoToken 的统一 Key/API 通道写进 OpenHands 的config.toml让 AgentController 在初始化时正确加载并验证它确实能驱动 LLM 调用。适合已经跑通 OpenHands 基础环境、想换成统一 API 通道的开发者也适合想理解 AgentController 配置加载链路的同学。下面给的config.toml骨架可以直接复制改两个值就能用。2. TaoToken 前置为什么 AgentController 需要一个统一通道先说清楚 TaoToken 在这里扮演什么角色。OpenHands 的 AgentController 在初始化时会读取LLMConfig里面包含model、base_url、api_key三个关键字段。默认情况下你需要为每个模型厂商单独配一套 Key 和地址。而 TaoToken 提供的是 OpenAI 兼容的统一 API 通道一个 Key 就能访问多种模型base_url固定指向https://taotoken.net/api。这对 AgentController 的意义在于它的agent_to_llm_config是一个dict[str, LLMConfig]映射用于委托代理场景。当你用统一通道时这个映射里所有条目可以共享同一个base_url和api_key只改model字段即可。配置复杂度从“N 个厂商 N 套凭证”降到“一套凭证 N 个模型名”。需要提前准备的东西只有两样一个 TaoToken 的 API Key以及你想用的模型名。Key 在控制台的 API Keys 页面创建地址是https://taotoken.net/console/api-keys。模型名按 OpenAI 兼容格式填比如claude-sonnet-4-20250514这类。如果你还不确定用哪个模型可以先到模型对话页面试一下确认通道通了再写进配置。注意base_url填https://taotoken.net/api不要带末尾斜杠也不要带/v1OpenHands 内部会自己拼接路径。这一点和很多教程里写的习惯不同填错会直接 404。3. 可复制配置config.toml 骨架与 AgentController 加载链路OpenHands 的配置加载顺序大致是先读config.toml再用环境变量覆盖最后注入 AgentController 的__init__。所以最稳的做法是把 TaoToken 参数写进config.toml的[llm]段同时用环境变量兜底。下面是我实测可用的config.toml骨架[core] workspace_base ./workspace max_iterations 100 cache_dir ./cache [llm] # TaoToken 统一通道 model claude-sonnet-4-20250514 base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 # 采样参数按需调整 temperature 0.0 top_p 1.0 max_input_tokens 128000 max_output_tokens 8192 # 重试与超时长任务建议保留 num_retries 3 retry_min_wait 5 retry_max_wait 30 timeout 300 [agent] # 默认使用 CodeActAgentAgentController 会据此创建 agent 实例 name CodeActAgent enable_prompt_extensions true [sandbox] # 本地开发可用 local生产建议 docker runtime local timeout 120这份配置里AgentController 真正关心的是[llm]段。它在__init__里接收agent、event_stream、agent_to_llm_config等参数而agent实例在创建时已经持有了从[llm]解析出来的LLMConfig。所以链路是config.toml→ 配置解析器 →LLMConfig→Agent实例 →AgentController。如果你要用委托代理agent_to_llm_config可以这样写[llm] model claude-sonnet-4-20250514 base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 # 委托代理的模型映射共享同一通道 [llm.agent_to_llm_config] CodeActAgent { model claude-sonnet-4-20250514 } BrowsingAgent { model gpt-4o }这样start_delegate创建子控制器时会从agent_configs里取对应配置而base_url和api_key依然走 TaoToken 统一通道。子控制器标记is_delegateTrue不会重复订阅事件流但共享同一个event_stream和llm_registry。环境变量兜底可以这样设防止配置文件被覆盖或漏读export LLM_MODELclaude-sonnet-4-20250514 export LLM_BASE_URLhttps://taotoken.net/api export LLM_API_KEYsk-你的TaoToken密钥提示环境变量优先级通常高于config.toml如果你改了配置不生效先检查 shell 里有没有残留的旧环境变量。4. 验证请求确认 AgentController 真的驱动了 LLM配置写完怎么确认 AgentController 初始化成功并且真的调用了 LLM分三步验证。第一步启动 OpenHands 后看日志里有没有AgentController初始化相关的输出。正常情况会看到类似Creating agent CodeActAgent和AgentController initialized with sid...的记录。如果看到LLMConfig解析失败或base_url为空的警告说明配置没读到。第二步发一条最简单的消息比如“列出当前工作目录的文件”。观察日志里是否出现对https://taotoken.net/api的请求。你可以临时把日志级别调高export LOG_ALL_EVENTStrue export LOG_LEVELdebug然后在日志里搜taotoken.net能看到请求发出和响应返回就说明 AgentController 的step()已经通过 Agent 触发了 LLM 调用。第三步用 curl 单独验证通道本身排除 OpenHands 配置问题curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: reply with ok}], max_tokens: 16 }如果 curl 返回正常但 OpenHands 里报错那问题一定在配置加载链路而不是通道本身。反过来如果 curl 就失败先解决 Key 或模型名的问题。成功的结果长这样Agent 在 UI 里正常回复日志里能看到Action和Observation交替出现state.iteration_flag.current_value逐步递增。这说明 AgentController 的状态机在正常流转LLM 调用被正确驱动。5. 本篇常见错排查配置这条链路上报错集中在几个固定位置。下面按出现频率排一下。401 Unauthorized九成是api_key没读到。检查config.toml里 Key 有没有引号包裹、有没有多余空格以及环境变量是否覆盖成了空值。另外确认 Key 是在https://taotoken.net/console/api-keys创建的没有过期。404 Not Foundbase_url写错了。常见错误是写成https://taotoken.net/api/v1或带末尾斜杠。正确写法就是https://taotoken.net/api。OpenHands 内部会拼/chat/completions你多写一层就 404。model not found模型名拼错或者该模型不在当前通道支持列表里。建议先用模型对话页面确认模型名可用再写进配置。模型名大小写敏感别自己造名字。AgentController 初始化卡住如果日志停在StateTracker初始化或_add_system_message附近多半是event_stream订阅出了问题。检查是不是在委托场景里重复订阅了——子控制器应该is_delegateTrue不订阅事件流。如果你手动改了代码确认EventStreamSubscriber.AGENT_CONTROLLER只注册一次。配置改了不生效OpenHands 可能读了缓存目录里的旧状态。清掉cache_dir和workspace_base下的会话文件再重启。另外确认没有多个config.toml被同时加载比如项目根目录和用户目录各有一份。长任务中途断掉检查timeout和num_retries。TaoToken 通道本身稳定但长任务里单次请求超时设太短会触发重试风暴。建议timeout300、num_retries3配合retry_min_wait做退避。注意如果你在容器里跑环境变量要在docker run或 compose 文件里传进去容器内的 shell export 不会影响已经启动的进程。6. 接下来怎么走配置跑通之后AgentController 的加载链路就算打通了。你可以继续做两件事一是把agent_to_llm_config用起来试试委托代理场景下不同子任务走不同模型二是把max_iterations和budget_per_task_delta调成适合你任务的数值观察 AgentController 的卡死检测和预算管理怎么生效。如果你还没创建 Key去https://taotoken.net/console/api-keys建一个然后回到config.toml把api_key填上。接入文档在https://taotoken.net/doc里面有各语言 SDK 的调用示例对照着调通道参数会更快。想先验证模型通不通直接用模型对话页面发一条消息最省事。长期跑编码任务或 Agent 工作流的话Coding Plan 那条通道在配额和稳定性上更适合持续调用可以在控制台里看一下具体方案。配置这件事一次写对后面就只剩调参了。AgentController 的初始化日志里出现第一行成功的 LLM 响应时这套链路就算真正跑起来了。