1. 从一次“跑不通”的 OpenHands 任务说起如果你正在折腾 OpenHands大概率遇到过这种场景容器起来了Web 界面能打开输入一句“帮我修复这个仓库里的测试失败”代理转了两圈就卡住日志里反复出现模型调用超时或者 401。问题往往不在 OpenHands 本身而在 LLM 调用层——也就是代理系统架构里最容易被忽略、却最影响端到端体验的那一环。OpenHands 是一个 AI 驱动的软件开发代理平台它的核心能力是让大模型自主完成“读代码、改文件、跑命令、看结果、再决策”的闭环。支撑这个闭环的是一套分层清晰的代理系统架构Agent 抽象负责决策循环LLM 调用层负责把上下文送给模型工具集成链路负责把模型输出的动作翻译成真实操作沙箱执行环境负责隔离风险。这几层任何一层配置不对代理就会“看起来在思考实际上什么都没做”。这篇笔记聚焦两件事第一把 OpenHands 代理系统架构拆开讲清楚让你知道每个模块的职责和数据流第二把 LLM 调用端点统一改到 TaoToken用一套 Key 和 API 通道完成一次可复现的端到端任务验证。适合已经装好 OpenHands、想让代理真正跑起来的人也适合想理解 AI 代理架构但不想只停留在概念层面的开发者。下面所有配置片段都可以直接复制改完就能验证。2. OpenHands 代理系统架构拆解与 LLM 调用层定位先把架构讲透不然改配置就是盲改。OpenHands 的代理系统可以理解成一条流水线用户输入进入对话管理层对话管理层把上下文交给 LLM 决策层LLM 返回“思考 动作”动作被工具集成层解析并分发到执行环境层执行结果再回流到对话管理层形成下一轮循环。整条链路里LLM 调用层是唯一一个“必须连外部服务”的环节也是最容易出问题的地方。2.1 Agent 抽象决策循环的心脏Agent 抽象定义了代理“怎么想、怎么做”。在 OpenHands 里一个 Agent 通常包含几个关键方法接收事件、构造 prompt、调用 LLM、解析响应、执行动作、更新状态。它不关心模型是哪个厂商只关心“给我一个能返回结构化动作的 LLM 客户端”。这就是为什么我们可以把底层端点换掉而不动 Agent 逻辑——只要接口兼容。实际代码里Agent 会维护一个事件流event stream每一步的观察、思考、动作都作为事件追加进去。上下文管理模块会从事件流里裁剪出最近的相关历史避免把整个会话塞给模型导致 token 爆炸。理解这一点很重要你改 LLM 端点时改的是 Agent 依赖的那个客户端实例而不是 Agent 的决策逻辑。2.2 LLM 调用层统一端点为什么关键LLM 调用层负责三件事认证、请求构造、响应解析。认证就是带上 API Key请求构造要把 system prompt、历史消息、工具定义按目标模型的格式拼好响应解析要把模型返回的文本或 tool_calls 转成 Agent 能理解的动作对象。问题在于不同厂商的接口格式有差异。OpenHands 默认走的是 Anthropic 风格的接口很多人在本地想换成别的通道时要么改源码要么在环境变量里硬塞一个不兼容的 Base URL结果就是 401 或者响应解析失败。把端点统一到 TaoToken 的价值在于它提供 OpenAI 兼容和 Anthropic 兼容两种调用方式Base URL 和 Key 一套配置Agent 层几乎不用动。2.3 工具集成链路从模型输出到真实动作工具集成层是代理“能干活”的关键。它把可用工具文件读写、命令执行、浏览器操作等整理成模型能理解的 schema注入到 prompt 里。模型返回工具调用后这一层负责参数校验、权限检查、分发执行。数据流是这样的Agent 把工具列表传给 LLM 调用层 → LLM 返回 tool_call → Agent 解析出工具名和参数 → 工具集成层找到对应 handler → 执行环境层在沙箱里跑 → 结果作为 observation 回流。这条链路里LLM 调用层如果返回格式不对工具集成层就拿不到合法的 tool_call代理就会“空转”。2.4 执行环境与安全边界OpenHands 用容器化设计做隔离代理执行的命令、改的文件都在沙箱里不会直接污染宿主机。安全层负责权限控制和审计。这一层和 LLM 端点没有直接关系但它决定了你验证任务时“敢不敢让代理真的跑命令”。建议第一次验证时用只读任务比如“列出仓库根目录文件并解释项目结构”确认链路通了再放开写操作。3. TaoToken 前置准备与可复制配置片段这一章是动手部分。目标是把 OpenHands 的 LLM 调用端点指向 TaoToken并准备好一套可复制的配置。你需要先拿到 API Key再根据 OpenHands 的启动方式选择配置位置。3.1 获取 Key 与确认端点先到 TaoToken 控制台创建 API Key。地址是 https://taotoken.net/api-keys 登录后新建一个 Key复制保存。注意 Key 只在创建时完整显示一次丢了就重新建。端点方面OpenAI 兼容调用用 https://taotoken.net/api Anthropic 兼容调用也用同一个 Base具体路径由客户端拼接。模型 ID 按你实际要用的填比如 claude-sonnet-4-20250514 这类。不要凭记忆写以控制台模型列表为准。3.2 环境变量方式配置OpenHands 支持通过环境变量注入 LLM 配置。最直接的方式是在启动前 export或者写进 .env 文件。下面是一份可复制的配置注意把 Key 换成你自己的# .env 片段OpenHands LLM 端点指向 TaoToken LLM_API_KEYsk-你的TaoToken密钥 LLM_BASE_URLhttps://taotoken.net/api LLM_MODELclaude-sonnet-4-20250514 # 如果 OpenHands 版本区分 provider按实际字段名调整 LLM_PROVIDERanthropic如果你用的是 docker run 启动把这些通过 -e 传进去docker run -it --rm \ -e LLM_API_KEYsk-你的TaoToken密钥 \ -e LLM_BASE_URLhttps://taotoken.net/api \ -e LLM_MODELclaude-sonnet-4-20250514 \ -v /var/run/docker.sock:/var/run/docker.sock \ -p 3000:3000 \ openhands:latest3.3 config.toml 方式配置部分 OpenHands 版本用 config.toml 管理配置。路径通常在 ~/.openhands/config.toml 或项目根目录。下面是一份 TOML 片段# ~/.openhands/config.toml [llm] api_key sk-你的TaoToken密钥 base_url https://taotoken.net/api model claude-sonnet-4-20250514 provider anthropic注意 TOML 里字符串用双引号路径和字段名以你本地版本为准。改完保存重启 OpenHands 让配置生效。3.4 三件套对照表不管用哪种方式核心就是三件套Base URL、Key、Model ID。下面这张表帮你对照检查配置项值说明Base URLhttps://taotoken.net/api统一入口不加多余路径API Keysk-开头控制台创建只显示一次Model ID以控制台为准不要手写猜测注意Base URL 末尾不要多加 /v1 之类的路径除非客户端明确要求。多写一层路径是 404 的常见原因。4. 验证请求与端到端任务复现配置改完不算完必须验证。这一章分两步先用一个最小请求确认端点通再让 OpenHands 跑一个真实任务确认整条代理链路通。4.1 最小连通性验证在终端里用 curl 直接打 TaoToken 的模型对话接口确认 Key 和端点没问题。这一步能排除掉大部分认证和网络问题curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 只回复两个字通了}], max_tokens: 16 }如果返回里能看到 choices 数组和内容说明端点、Key、模型 ID 三件套都对。如果返回 401检查 Key 有没有复制全如果返回 404检查 Base URL 路径如果返回模型不存在检查 Model ID。4.2 在 OpenHands 里跑一个只读任务连通性没问题后启动 OpenHands在对话界面输入一个只读任务比如列出当前工作区根目录下的所有文件并简要说明这个项目是做什么的。观察日志。正常情况下你会看到Agent 构造 prompt → 调用 LLM → 返回工具调用比如执行 ls→ 沙箱执行 → 结果回流 → LLM 再总结。如果卡在“调用 LLM”不动回到第 3 章检查配置如果工具调用解析失败检查模型是否支持 tool_calls。4.3 跑一个带写操作的端到端任务只读任务通过后可以试一个轻量写操作比如让代理在仓库里新建一个 hello.txt 并写入内容。这一步验证的是工具集成链路里的文件操作是否正常。任务描述可以这样写在当前工作区创建一个 hello.txt内容为 hello openhands然后读取它确认写入成功。成功的话你会在事件流里看到文件创建和读取两个动作以及模型对结果的确认。到这里代理系统架构的端到端链路就算跑通了。4.4 观察数据流的小技巧想更直观地看数据流可以把 OpenHands 日志级别调高或者在代码里给 LLM 调用层加一行打印输出请求的 model 和 base_url。这样每次调用你都能确认走的是 TaoToken 而不是默认端点。实测下来这一步能省掉很多“以为改了其实没生效”的排查时间。5. 本篇常见错误排查配置和验证过程中报错集中在几个地方。下面按真实报错对照排查。5.1 401 Unauthorized最常见。原因通常是 Key 没传进去、Key 复制不完整、或者环境变量名和 OpenHands 实际读取的字段名不一致。排查顺序先确认 .env 或 -e 里的变量名和文档一致再用 4.1 的 curl 单独验证 Key最后检查 OpenHands 启动日志里有没有打印实际使用的 base_url 和 key 前缀。5.2 local proxy failed 或连接被拒这个报错通常出现在你本地配了某个转发端口但转发服务没起来。如果你没有用本地转发检查 Base URL 是不是写成了 localhost 或 127.0.0.1。正确做法是直接写 https://taotoken.net/api 不要经过本地中间层。5.3 reading choices 相关解析错误报错里出现 reading choices 或类似字段读取失败说明客户端按 OpenAI 格式解析响应但实际返回结构不匹配。检查两点一是 Base URL 是否指向了正确的兼容路径二是模型 ID 是否拼写正确。如果 OpenHands 版本默认走 Anthropic 格式而你把 provider 配成了 openai也会出现这种解析错位。5.4 OAuth 或认证方式冲突有些 OpenHands 版本支持 OAuth 登录如果你同时配了 API Key 和 OAuth可能触发认证方式冲突。排查方法是只保留一种认证方式把 OAuth 相关配置清掉只用 LLM_API_KEY。5.5 工具调用不执行模型返回了文本但没有 tool_call代理就只会“说”不会“做”。这通常是模型不支持工具调用或者工具 schema 没正确注入。确认你选的模型支持 function calling并检查 OpenHands 日志里 prompt 是否包含工具定义。提示排查时优先用 curl 隔离问题。curl 通了说明端点和 Key 没问题问题在 OpenHands 配置curl 不通说明问题在 Key 或端点本身。6. 把统一接入用起来从验证到日常编码跑通一次端到端任务后你可以把这套配置固化下来。日常用 OpenHands 做长期编码或 Agent 任务时统一端点带来的好处是配置只维护一份换模型只改 Model ID不用动 Agent 代码。如果你想让代理持续跑多轮任务建议把配置写进项目级的 .env 并纳入版本管理的模板文件Key 用占位符团队里每个人填自己的 Key 即可。模型对话调试可以直接用 https://taotoken.net/api 配合 curl 快速验证需要长期编码或 Agent 场景可以了解 Coding Plan 相关能力地址是 https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 控制台在 https://taotoken.net/console Key 管理在 https://taotoken.net/api-keys 。最后留一个实用习惯每次改完 LLM 配置先跑 4.1 的 curl再跑 4.2 的只读任务两步都过再放开写操作。这个顺序能帮你把问题挡在沙箱之外也让你对代理系统架构里“哪一层出问题”心里有数。