1. OpenHands 到底是个什么东西为什么值得拆OpenHands 是一个开源的 AI Agent 框架前身叫 OpenDevin目前在 GitHub 上已经拿到超过 6.5 万星标。它能做什么简单说你给它一句自然语言指令比如“帮我写一个 Flask 接口读取 CSV 并返回 JSON”它就能自己规划步骤、写代码、跑命令、看报错、改代码直到任务完成。适合谁刚接触 Agent 的开发者、想理解 Agent 内部运转逻辑的后端工程师、以及需要快速验证 AI 编程想法的小团队。我试过把它跑在本地 Docker 里整个流程从拉镜像到第一个任务执行成功大概花了二十分钟。但中间踩了一个坑默认配置下它要连 OpenAI 的 API国内网络环境直接请求会超时。后来换成 TaoToken 的统一 Key 接入才把链路跑通。这篇文章就按“先理解架构再动手接入最后验证任务链路”的顺序来写你跟着做就能跑通第一个 Agent 任务。OpenHands 的核心价值不在于它“能写代码”——能写代码的工具太多了——而在于它把 Agent 的完整闭环做成了可观测、可干预、可扩展的系统。你能看到它每一步在干什么能中途叫停能换模型能加工具。这对学习者来说非常关键因为黑盒式的 Agent 你只能看结果而 OpenHands 让你看过程。它的架构设计围绕一个核心概念展开事件驱动。所有组件之间的通信都通过 EventStream 来传递 Action 和 Observation。Agent 发出一个 Action比如“运行这条 shell 命令”Runtime 执行后返回一个 Observation比如“命令输出Hello World”Agent 再根据 Observation 决定下一步。这个循环就是 ReAct 范式的工程化实现。理解这一点之后你再看它的目录结构就清晰了agenthub/放 Agent 实现events/定义事件类型runtime/管执行环境memory/管上下文llm/管模型调用。每个目录对应一个明确的职责互不越界。这种模块化设计让你可以只替换其中一层——比如把 LLM 层从 OpenAI 换成 TaoToken 代理的其他模型——而不影响其他部分。对于刚入门的开发者我建议先不要急着读源码。先把系统跑起来发一个任务看它怎么一步步执行再回头对照架构图去理解每个组件的作用。这样学习曲线会平缓很多。2. 接入前的准备TaoToken 统一 Key 与环境配置在动手改配置之前你需要先拿到一个能用的 API Key。OpenHands 默认走的是 OpenAI 的接口格式所以任何兼容 OpenAI 接口的服务都可以接。TaoToken 提供的就是这种统一接入方式——一个 Key 可以调用多个模型Base URL 指向https://taotoken.net/api模型 ID 按需选择。先注册并创建 Key。打开 TaoToken 的 API Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite登录后点“创建新 Key”复制生成的字符串。这个 Key 只显示一次建议先存到密码管理器里。接下来确认本地环境。OpenHands 推荐用 Docker 运行所以你需要Docker Engine 24 以上Docker Compose v2至少 8GB 可用内存跑 Agent 任务时容器会吃资源Python 3.11如果你打算用 CLI 模式检查 Docker 是否就绪docker --version docker compose version如果这两条命令都能正常输出版本号说明环境没问题。然后拉取 OpenHands 的代码git clone https://github.com/OpenHands/OpenHands.git cd OpenHands目录里有一个config.toml模板位于openhands/config/下。你需要复制一份到工作目录然后填入自己的配置。下面是一个最小可用的骨架[core] workspace_base ./workspace max_iterations 50 [llm] model gpt-4o api_key sk-你的TaoTokenKey base_url https://taotoken.net/api temperature 0.2 max_output_tokens 4096 [sandbox] timeout 120 use_host_network false [agent] name CodeActAgent这里有几个参数需要解释。model填你想用的模型 IDTaoToken 支持的模型列表可以在模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite查看。base_url固定填https://taotoken.net/api注意不要加尾部斜杠。max_iterations控制 Agent 最多执行多少步设太小任务可能跑不完设太大可能浪费 token50 是一个比较安全的起点。如果你用的是 Claude Code 或者 Cline 这类工具配置方式略有不同。Claude Code 需要在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Cline 的 MCP 配置则在 VS Code 的settings.json里加{ cline.mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_API_KEY: sk-你的TaoTokenKey, TAOTOKEN_BASE_URL: https://taotoken.net/api } } } }不管用哪种方式核心三件套是一样的Base URL 指向 TaoToken、Key 填你创建的、Model ID 选你要用的。这三项配对了链路就通了一半。注意不要把 Key 硬编码到会提交到 Git 的文件里。用环境变量或者.env文件并在.gitignore里排除。3. 可复制的 config.toml 与启动命令上一节给了骨架这一节把完整的config.toml写出来并说明每个字段的实际作用。你可以直接复制到OpenHands/config.toml改掉 Key 就能用。[core] workspace_base ./workspace cache_dir ./cache max_iterations 50 max_budget_per_task 2.0 enable_auto_lint true [llm] model gpt-4o api_key sk-你的TaoTokenKey base_url https://taotoken.net/api temperature 0.2 top_p 0.95 max_input_tokens 32768 max_output_tokens 8192 num_retries 3 retry_min_wait 2 retry_max_wait 10 [llm.draft] model gpt-4o-mini api_key sk-你的TaoTokenKey base_url https://taotoken.net/api temperature 0.1 [sandbox] timeout 120 use_host_network false runtime_container_image docker.all-hands.dev/all-hands-ai/runtime:0.9-nikolaik [agent] name CodeActAgent enable_prompt_extensions true enable_browsing false enable_jupyter true enable_llm_editor false [security] confirmation_mode false security_analyzer [logging] level INFO file ./logs/openhands.log逐段说明。[core]里的max_budget_per_task是成本上限单位是美元防止 Agent 无限循环烧钱。enable_auto_lint打开后Agent 写完代码会自动跑 lint有问题会自己修。[llm]是核心配置。num_retries和retry_min_wait控制重试策略网络抖动时很有用。[llm.draft]是可选的草稿模型用于快速生成初步方案主模型再精修能省不少 token。[sandbox]里的runtime_container_image指定沙箱镜像。如果你在国内拉 Docker Hub 慢可以换成 TaoToken 文档里推荐的镜像源或者提前docker pull好。[agent]的name目前支持CodeActAgent和BrowsingAgent。前者专注代码任务后者能操作浏览器。新手先用CodeActAgent。配置写好后启动命令有两种。Docker 方式docker run -it --rm \ --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.9-nikolaik \ -e LOG_ALL_EVENTStrue \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.openhands:/.openhands \ -p 3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:0.9这条命令会把 OpenHands 的 Web UI 暴露在localhost:3000。浏览器打开后在设置里填入 TaoToken 的 Base URL 和 Key模型选gpt-4o保存。CLI 方式cd OpenHands python -m openhands.cli \ --config config.toml \ --task 创建一个 Python 脚本读取 data.csv 并输出每列的平均值CLI 模式适合快速测试不用开浏览器。任务执行过程中终端会实时打印每一步的 Action 和 Observation。如果你用 Coding Plan 的额度来跑可以在 TaoToken 控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里查看用量和余额。长期跑 Agent 任务的话Coding Plan 比按量计费划算不少具体可以看 Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite的说明。4. 验证 Agent 任务执行链路是否走通配置写好了启动也成功了但你怎么知道 Agent 真的在按预期工作这一节给出具体的验证动作。第一步发一个最简单的任务。在 Web UI 的输入框里打在当前目录创建一个 hello.py内容为 print(Hello from OpenHands)然后运行它。点发送。观察右侧的事件流面板。你应该看到类似这样的序列[Action] AgentThinkAction: 我需要创建一个 Python 文件并运行它。 [Action] FileWriteAction: 写入 hello.py [Observation] FileWriteObservation: 文件写入成功 [Action] CmdRunAction: python hello.py [Observation] CmdRunObservation: Hello from OpenHands [Action] AgentFinishAction: 任务完成如果这个序列完整出现说明 Agent 的“思考-行动-观察”闭环走通了。如果卡在某一步比如FileWriteAction之后没有Observation那可能是沙箱没启动或者权限问题。第二步检查 LLM 调用是否真的走了 TaoToken。在日志文件./logs/openhands.log里搜索base_url应该能看到https://taotoken.net/api。或者直接在 TaoToken 控制台的请求日志里看每一条 LLM 调用都会记录模型、token 数、耗时。第三步故意制造一个错误看 Agent 能不能自己修。发任务创建一个 Flask 应用监听 5000 端口返回 JSON {status: ok}然后启动它并用 curl 测试。这个任务会涉及写代码、装依赖、启动服务、发请求。中间很可能因为缺少 Flask 包而报错。观察 Agent 是否会自动执行pip install flask然后重试。如果它能自己修说明错误恢复机制在工作。第四步验证多步任务的状态保持。发一个需要多轮交互的任务创建一个名为 users 的 SQLite 数据库建一张 user 表id, name, email插入三条测试数据然后查询并打印所有记录。这个任务需要 Agent 记住前面的步骤数据库路径、表结构不能每一步都从头开始。如果它能连续完成说明 Memory 模块正常。提示验证阶段建议把max_iterations设小一点比如 20避免任务跑飞了浪费额度。确认链路没问题后再调大。如果以上四步都通过恭喜你OpenHands 的 Agent 任务执行链路已经完整走通了。接下来可以尝试更复杂的任务比如“读取当前 Git 仓库的最近 5 次提交生成一份变更摘要 Markdown 文件”。5. 常见报错与排查手册这一节整理我在接入过程中实际遇到的报错以及对应的排查思路。你大概率也会碰到其中几个。报错一401 Unauthorized或Invalid API Key这是最常见的。原因通常是 Key 填错了、Key 过期了、或者 Base URL 写成了https://taotoken.net/api/多了尾部斜杠。检查config.toml里的api_key和base_url确保 Key 是完整的sk-开头字符串Base URL 没有多余字符。如果用的是环境变量确认变量名拼写正确比如OPENAI_API_KEY和LLM_API_KEY在不同版本里可能不一样。报错二local proxy failed或Connection refused这个报错说明 OpenHands 尝试连接 LLM 接口时被拒了。可能原因本地网络无法直连taotoken.net或者 Docker 容器内的 DNS 解析有问题。先在宿主机上curl https://taotoken.net/api看能不能通。如果宿主机通、容器不通在 Docker 启动命令里加--add-host host.docker.internal:host-gateway并把 Base URL 改成http://host.docker.internal:端口的形式如果 TaoToken 有本地代理的话。但更常见的情况是容器内没配 DNS加--dns 8.8.8.8试试。报错三Error reading choices或Response format unexpected这个报错通常出现在流式响应解析时。OpenHands 期望的响应格式和实际返回的不一致。检查你选的模型 ID 是否在 TaoToken 的支持列表里。有些模型不支持streamtrue需要在config.toml里加stream false。另外max_output_tokens设得太大也可能导致响应被截断试着降到 4096。报错四OAuth error或Authentication failed如果你用的是 Claude Code 或 Cline 的 OAuth 流程这个报错说明 token 刷新失败了。Claude Code 的settings.json里需要同时配ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY缺一不可。如果之前配过官方 Anthropic 的 OAuth先清掉~/.claude/下的缓存文件再重试。报错五Sandbox timeout或Runtime container exited沙箱容器启动失败或执行超时。先检查 Docker 是否在运行docker ps看有没有残留的 runtime 容器。如果有docker rm -f清掉。然后确认runtime_container_image的版本和 OpenHands 主程序版本匹配。0.9 版本的 OpenHands 要配 0.9 的 runtime 镜像版本错配会直接崩。报错六Agent stuck in loop或Max iterations reachedAgent 陷入死循环反复执行同一个动作。这通常是因为任务描述太模糊或者工具返回的结果不符合预期。解决办法把max_iterations调小强制中断然后在任务描述里加更明确的约束比如“只修改 app.py 文件不要创建新文件”。另外temperature设得太高比如 0.8 以上也容易导致 Agent 行为发散降到 0.2 左右会稳定很多。排查通用思路先看日志文件./logs/openhands.log的最后 50 行找到第一个 ERROR 级别的记录。然后对照上面的分类定位。如果日志里没有明显错误把logging.level改成DEBUG再跑一次能看到更详细的请求和响应内容。6. 从跑通到用好下一步可以做什么链路跑通之后你可以开始探索 OpenHands 更高级的用法。比如自定义 Agent在agenthub/下新建一个目录继承Agent基类实现自己的step()方法。这样你可以针对特定场景比如只做代码审查、只写测试用例定制 Agent 的行为。另一个方向是接入更多工具。OpenHands 的 Tool-use 模块支持通过 MCP 协议扩展。你可以在config.toml里加[mcp]段配置外部工具服务器。比如接一个数据库查询工具、一个 API 文档检索工具让 Agent 的能力边界从“写代码”扩展到“查数据”。如果你打算长期用 OpenHands 跑任务建议关注成本控制。max_budget_per_task设一个合理值[llm.draft]用便宜模型做草稿主模型只做精修。TaoToken 的 Coding Plan 适合高频使用场景具体额度可以在控制台里看。最后提醒一点Agent 跑出来的代码不要直接上生产。OpenHands 的沙箱环境是隔离的但生成的代码逻辑需要人工 review。把它当成一个高效的“初级程序员”而不是“技术负责人”。