企业官网建设流程全解析

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，不要带末尾斜杠，也不要带/v1，OpenHands 内部会自己拼接路径。这一点和很多教程里写的习惯不同，填错会直接 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] # 默认使用 CodeActAgent，AgentController 会据此创建 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_delegate=True，不会重复订阅事件流，但共享同一个event_stream和llm_registry。

环境变量兜底可以这样设，防止配置文件被覆盖或漏读：

export LLM_MODEL="claude-sonnet-4-20250514" export LLM_BASE_URL="https://taotoken.net/api" export LLM_API_KEY="sk-你的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_EVENTS=true export LOG_LEVEL=debug

然后在日志里搜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 Found：base_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_delegate=True，不订阅事件流。如果你手动改了代码，确认EventStreamSubscriber.AGENT_CONTROLLER只注册一次。

配置改了不生效：OpenHands 可能读了缓存目录里的旧状态。清掉cache_dir和workspace_base下的会话文件再重启。另外确认没有多个config.toml被同时加载，比如项目根目录和用户目录各有一份。

长任务中途断掉：检查timeout和num_retries。TaoToken 通道本身稳定，但长任务里单次请求超时设太短会触发重试风暴。建议timeout=300、num_retries=3，配合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 响应时，这套链路就算真正跑起来了。