拆解 OpenHands（1）--- 核心理念与 TaoToken 统一 Key 接入骨架

1. 为什么我要从 OpenHands 开始拆 AgentOpenHands 是一个开源的 AI 软件开发代理框架前身叫 OpenDevin它能用自然语言驱动一个 Agent 去读写文件、跑命令、浏览网页最终把一个小需求变成可运行的代码改动。它适合谁适合想搞明白 Agent 到底怎么运转、又不想从零造轮子的开发者。我选它做拆解对象不是因为它功能最全而是因为它的架构足够“透明”事件流、AgentController、Runtime、Memory 这些模块职责清晰源码翻起来不费劲跑起来也快。但很多人卡在第一步Agent 跑不起来或者跑起来了却连不上模型。原因往往不是 OpenHands 本身而是模型接入这一层没配好——Key 散落在环境变量、配置文件、命令行参数里换一个模型就要改三处。这篇是系列第一篇先把核心理念讲清楚再给出一套可复制的 config.toml 与 settings.json 骨架用 TaoToken 统一 Key/API 通道接入最后用一条最小验证动作确认 Agent 真的能发起请求。你跟着做十分钟内能看到 Agent 回话。2. OpenHands 的核心理念事件驱动 状态机2.1 Agent 不是“更聪明的模型”而是“能闭环的系统”很多人以为 Agent 就是给 LLM 加几个工具函数。实际跑起来你会发现真正难的不是让模型生成一段代码而是让它在“感知 → 规划 → 行动 → 反馈”这个循环里不跑偏。OpenHands 的做法是把整个循环拆成事件Agent 产生一个 Action比如“编辑文件”Runtime 执行后返回一个 Observation比如“文件已写入”这两个东西都作为 Event 进入 EventStreamAgentController 再根据最新状态决定下一步。这个设计的好处是Agent、Runtime、UI 三者解耦。你可以换一个 Agent 实现也可以换一个 RuntimeDocker 或本地只要它们都说“事件”这门语言就能拼在一起。2.2 核心组件各管什么LLM 负责与模型交互底层走 LiteLLM所以理论上任何兼容 OpenAI 接口的模型都能接。Agent 负责看当前状态、产生下一个 Action。AgentController 是驱动循环的引擎它初始化 Agent、管理 State、一步步推进任务。State 是 Agent 的“记忆大脑”记录当前步骤、历史事件、长期计划还支持断点恢复。EventStream 是事件中枢任何组件都能发布或订阅事件。Runtime 提供隔离的执行环境Sandbox 是其中跑命令的那部分。把这些串起来的一句话是ReAct 范式定下“先想再做再收反馈”的行为准则事件驱动模型搭起系统骨架State 保证长任务不丢进度。2.3 为什么接入层值得单独拎出来讲OpenHands 支持多种 LLM 后端配置入口有好几个环境变量、config.toml、settings.json、启动参数。如果你同时用几个模型做对比或者团队里几个人共用一台开发机Key 管理很快就会乱。更麻烦的是有些模型走的是 OpenAI 兼容接口有些走 Anthropic 风格接口base_url 和鉴权头都不一样。统一 Key/API 通道的价值就在这里你只维护一份凭证和一个入口地址OpenHands 那边只认这一套配置换模型时改的是模型名不是接入方式。3. TaoToken 前置把 Key 和入口先准备好TaoToken 在这里扮演的是统一接入层它提供一个兼容 OpenAI 风格的 API 入口你拿一个 Key 就能调用多种模型。对 OpenHands 来说它只需要知道“base_url 指向哪里、api_key 是什么、模型名写什么”剩下的路由由接入层处理。你需要先做两件事。第一在 TaoToken 控制台创建一个 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建时给它起个能认出来的名字比如 openhands-dev方便后面轮换。第二确认你要用的模型名。如果你不确定哪个模型适合 OpenHands 这种需要长上下文和工具调用的场景可以先去模型对话页试一下 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。在对话页里发一条带工具调用意图的消息看它能不能正确返回结构化结果再决定写进配置。注意API Key 只显示一次创建后立刻复制到安全的地方。不要把它写进会提交到 Git 的配置文件里后面我会用环境变量引用的方式处理。如果你打算长期用 OpenHands 做编码任务建议顺手看一下 Coding Plan 页面了解配额和模型选择策略 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定时以文档为准。4. 可复制配置config.toml 与 settings.json 骨架4.1 先理解 OpenHands 的配置优先级OpenHands 读取配置的顺序大致是命令行参数 环境变量 config.toml 默认值。settings.json 主要用于前端和部分运行时偏好。为了避免“改了文件但不生效”我的做法是敏感信息全部走环境变量config.toml 只写非敏感的模型参数和运行时选项settings.json 保持最小化。4.2 config.toml 骨架在 OpenHands 的工作目录下创建或编辑 config.toml。下面这份是可直接复制的骨架关键行我都加了注释[core] # 工作区路径按你的实际目录改 workspace_base ./workspace # 缓存目录避免每次重跑都重新拉依赖 cache_dir ./cache [llm] # 模型名按 TaoToken 文档里支持的写法填 model gpt-4o # 统一入口注意这里不带 UTMAPI 地址就是纯入口 base_url https://taotoken.net/api # 从环境变量读取不把 Key 写死在文件里 api_key ${TAOTOKEN_API_KEY} # 长任务建议调大OpenHands 的上下文消耗不低 max_input_tokens 32768 max_output_tokens 8192 # 工具调用场景下温度别太高 temperature 0.2 [agent] # 用默认的 CodeActAgent 即可后续拆解再换 name CodeActAgent # 最大迭代次数防止无限循环烧配额 max_iterations 30 [runtime] # 本地跑用 local要隔离就换 docker runtime local # 命令超时单位秒 timeout 120这里有两个点容易踩坑。第一base_url 结尾不要带斜杠也不要带 /v1OpenHands 内部会自己拼路径写多了会 404。第二api_key 用${TAOTOKEN_API_KEY}这种占位符前提是你的启动方式支持环境变量展开如果你直接跑二进制不经过 shell就把这行改成从环境读取的写法或者用启动脚本 export 后再启动。4.3 settings.json 骨架settings.json 放在 OpenHands 的配置目录下通常和 config.toml 同级。它的作用是给前端和部分运行时提供偏好不要在这里重复写 LLM 的 Key{ language: zh-CN, theme: dark, runtime: local, workspace: ./workspace, llm: { provider: openai-compatible, base_url: https://taotoken.net/api, model: gpt-4o }, ui: { show_events: true, auto_scroll: true } }注意 provider 写 openai-compatible因为 TaoToken 的入口是 OpenAI 风格。model 字段和 config.toml 保持一致避免两处不一致导致 Agent 初始化时用了错的模型。4.4 环境变量与启动在 shell 里导出 Key然后启动 OpenHandsexport TAOTOKEN_API_KEY你的Key # 确认变量已生效输出应该是你的 Key 前几位 echo ${TAOTOKEN_API_KEY:0:6} # 启动 OpenHands具体命令按你的安装方式调整 python -m openhands.core.main如果你用的是 Docker 方式把环境变量通过 -e 传进去docker run -it --rm \ -e TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} \ -v $(pwd)/workspace:/workspace \ openhands/openhands:latest5. 验证请求一条最小动作确认 Agent 能发起请求配置写完不代表通了。最稳的验证方式是让 Agent 做一个极小的、可观察的动作而不是直接扔一个复杂需求。我通常用“创建一个文件并写入一行内容”来验证。启动 OpenHands 后在交互界面输入在当前工作区创建一个名为 hello_agent.txt 的文件内容写一行agent is alive如果接入正常你会看到事件流里依次出现Agent 产生一个文件编辑 ActionRuntime 执行后返回 ObservationState 更新最后界面显示文件已创建。然后你在终端确认cat ./workspace/hello_agent.txt # 期望输出agent is alive这一步能同时验证三件事LLM 能收到请求并返回结构化 ActionRuntime 能执行文件操作EventStream 能把结果回传给 Agent。如果文件没出现或者事件流里只有 Action 没有 Observation问题基本出在接入层或 Runtime而不是 Agent 逻辑。想更直接地确认模型通道本身是否通可以单独发一条 curlcurl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer ${TAOTOKEN_API_KEY} \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: reply with ok}], max_tokens: 10 }返回里能看到 choices 字段就说明 Key 和入口都没问题。这一步和 OpenHands 无关但能帮你快速定位是接入层的问题还是框架配置的问题。6. 本篇常见错排查6.1 401 或 invalid api key最常见的原因是环境变量没传进 OpenHands 进程。如果你在 shell 里 export 了但用 systemd 或 IDE 启动环境变量不会自动继承。解决方式是显式在启动脚本里 export或者用 .env 文件配合加载。另一个原因是 Key 复制时带了空格或换行用echo ${TAOTOKEN_API_KEY:0:6}检查前几位再和创建时对比。6.2 404 或 model not found先检查 base_url 是不是写成了https://taotoken.net/api/或https://taotoken.net/api/v1。正确写法是https://taotoken.net/api不带尾斜杠不带版本段。然后检查 model 名是否在 TaoToken 支持的列表里写错一个字符就会 404。如果模型名对但依然报错去接入文档确认该模型是否需要额外的请求头。6.3 Agent 一直循环不结束这通常不是接入问题而是 max_iterations 设太大加上任务描述太模糊。先把 max_iterations 降到 10 做测试任务描述尽量具体比如“在 workspace 下创建 a.txt 并写入 123”而不是“帮我整理一下项目”。如果循环里反复出现同一个 Action说明 Observation 没有被正确回传检查 Runtime 是否真的执行了命令。6.4 文件写到了错误的位置OpenHands 的 workspace_base 和 settings.json 里的 workspace 要指向同一个目录。如果两处不一致Agent 可能把文件写到默认路径你在预期目录里找不到。用pwd和ls确认当前工作目录再对照配置里的相对路径。6.5 长任务中途断掉后无法恢复State 支持断点恢复但前提是 cache_dir 和 workspace 没有被清空。如果你每次启动都挂载一个全新的临时目录历史状态就丢了。做长任务时把 workspace 和 cache 挂到宿主机固定路径重启后 Agent 能从上次的 State 继续。7. 下一步把统一 Key 用在长期编码任务上这一篇的重点是核心理念和接入骨架验证动作只做到“Agent 能发起请求”。如果你打算把 OpenHands 当成日常编码助手下一步要处理的是配额、模型切换和会话管理。统一 Key 的好处在这里会放大你不需要为每个模型维护一套凭证换模型只改 config.toml 里的 model 字段base_url 和 api_key 不动。长期跑编码任务前建议先去 Coding Plan 页面确认配额策略 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。如果你更想先手动试几个模型再决定模型对话页可以直接对比输出质量 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。Key 管理和轮换在控制台 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入参数以文档为准 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。下一篇我会拆 OpenHands 的 EventStream 和 AgentController把“一个 Action 从产生到执行再到 Observation 回传”的完整链路用日志和源码对照讲清楚。你现在要做的是把这篇的配置跑通确认 hello_agent.txt 真的被写出来。