1. OpenHands 本地部署为什么总卡在模型接入这一步OpenHands 是一个开源的 AI 编程代理平台能理解任务、读写文件、跑终端命令、调浏览器最后把改动整理成 Pull Request。它适合想自己掌控 Agent 行为、不想被单一模型绑死的开发者也适合团队做二次开发和实验。但很多人第一次跑docker compose up之后Web UI 能打开任务一提交就报错最常见的就是模型通道没配好。我试过在本地把 OpenHands 跑起来前面环境都顺真正耗时间的是让 Agent 稳定拿到模型响应。OpenHands 的 LLM Backend 设计上支持对接任意服务商配置项集中在config.toml和环境变量里。只要 Base URL、API Key、Model ID 三件套对齐Agent 就能正常规划任务。这篇按“项目架构理解 → 统一 Key 接入 → 可复制配置 → 启动验证 → 报错排查”的顺序走每一步都能直接跟做。先说清楚 OpenHands 的架构不然后面配置容易懵。它大致分几层前端 Web UI 负责展示 Chat、Changes、Terminal、Browser 等面板后端核心是 Agent负责解析任务、规划步骤、调 LLM 推理Runtime 是隔离的执行环境通常跑在 Docker 容器里Agent 通过它读写文件、执行命令LLM Backend 是模型交互层把 Agent 的 Prompt 发给模型再解析响应Microagents 是可扩展的小工具单元比如读文件、跑测试、搜网页。模型接入改的就是 LLM Backend 这一层其他层不用动。为什么推荐用统一 Key 通道而不是每个模型单独配因为 OpenHands 支持多模型切换但如果你同时维护 OpenAI、Anthropic、Google 几套 Key配置文件会越来越乱切换模型时容易漏改。统一通道的好处是一个 Base URL 加一个 Key通过改 Model ID 就能切模型配置面收敛到三个变量排障也简单。下面所有配置都围绕这三个变量展开。2. TaoToken 统一 Key 前置准备与 OpenHands 环境变量映射在动 OpenHands 之前先把统一 Key 通道准备好。你需要拿到两样东西一个 API Key一个 Base URL。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数直接填进配置即可。Key 在控制台的 API Keys 页面创建创建后复制保存后面写进环境变量。OpenHands 读取模型配置有两条路径一条是config.toml文件一条是环境变量。环境变量优先级通常更高适合容器化部署config.toml适合本地调试时固定配置。两者不要同时写冲突的值否则会出现“明明改了配置却不生效”的情况。建议容器部署用环境变量本地裸跑用config.toml二选一。先把三个核心变量定下来变量值说明LLM_BASE_URLhttps://taotoken.net/api统一通道地址不带 UTMLLM_API_KEY控制台创建的 Key只存环境变量别写进代码LLM_MODEL例如claude-sonnet-4-20250514按需切换决定实际调用哪个模型OpenHands 的配置字段名在不同版本里略有差异常见的是base_url、api_key、model环境变量侧对应LLM_BASE_URL、LLM_API_KEY、LLM_MODEL。如果你用的是较新版本配置模板里可能叫llm.base_url这种嵌套写法。以你本地config.template.toml的实际字段为准下面给的是通用映射关系。这里要提醒一个坑Base URL 末尾不要多加/v1或斜杠。统一通道的地址就是https://taotoken.net/apiOpenHands 内部会按服务商适配器拼接路径。你多写一层路径请求就会打到不存在的端点报 404 或 401。这个错误很隐蔽因为 UI 上只显示“模型调用失败”不会告诉你路径错了。环境变量准备好后先别急着启动 OpenHands。用一条 curl 验证通道本身是通的能排除掉一半问题。命令如下curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $LLM_API_KEY \ -H Content-Type: application/json \ -d { model: $LLM_MODEL, messages: [{role: user, content: ping}], max_tokens: 16 }如果返回里有choices字段和内容说明 Key、Base URL、Model ID 三件套是对的。如果返回 401检查 Key 是否复制完整、有没有多余空格如果返回 404检查 Base URL 路径如果返回模型不存在检查 Model ID 拼写。这一步过了再进 OpenHands 配置成功率会高很多。3. 可复制配置config.toml 与 docker-compose 环境变量片段这一节给两份可直接复制的配置。第一份是config.toml适合本地直接运行 OpenHands 的场景。第二份是docker-compose.yml的环境变量片段适合容器部署。两份配置的字段名以你本地模板为准核心是三个值对齐。先看config.toml。在 OpenHands 项目根目录下通常有一个config.template.toml复制一份改名为config.toml然后填入以下内容[llm] # 统一通道地址不要加 /v1 或末尾斜杠 base_url https://taotoken.net/api # 从控制台创建的 Key建议用环境变量注入而非硬编码 api_key sk-你的Key # 模型 ID按需切换 model claude-sonnet-4-20250514 # 部分版本需要显式指定服务商类型通用通道填 openai 兼容 provider openai # 超时设置Agent 任务链路长建议放宽 timeout 300 # 最大输出 token按模型能力调整 max_output_tokens 8192如果你不想把 Key 写进文件可以用环境变量占位。OpenHands 支持在config.toml里引用环境变量写法类似${LLM_API_KEY}具体语法看版本。更稳妥的做法是文件里不写 Key靠环境变量覆盖。再看docker-compose.yml的环境变量片段。找到 OpenHands 服务定义在environment下加入services: openhands: environment: - LLM_BASE_URLhttps://taotoken.net/api - LLM_API_KEY${LLM_API_KEY} - LLM_MODELclaude-sonnet-4-20250514 - LLM_PROVIDERopenai - LLM_TIMEOUT300然后在同目录建一个.env文件写入LLM_API_KEYsk-你的Key.env要加进.gitignore别提交到仓库。这样docker compose启动时会自动注入Key 不落盘到 compose 文件里。如果你用的是 Cline 或 Claude Code 这类工具配合 OpenHands 做开发配置逻辑一样都是 Base URL、Key、Model ID 三件套。Cline 的 MCP 配置里baseUrl填https://taotoken.net/apiapiKey填同一个 Keymodel填同一个 Model ID。三处保持一致切换工具时不用重新申请。配置写完后检查一遍三个值Base URL 是不是https://taotoken.net/api没有多余路径Key 是不是完整Model ID 是不是当前通道支持的。这三个对齐后面启动基本不会卡在模型接入上。4. 启动 OpenHands 并验证代理任务执行是否成功配置就绪后启动 OpenHands。容器部署执行docker compose up -d本地裸跑按项目 README 的方式启动后端和前端。启动后打开 Web UI通常是http://localhost:3000。先别急着提复杂任务用一个最小任务验证链路在 Chat 面板输入“在当前目录创建一个 hello.py打印 hello openhands然后运行它”。观察几个关键面板。Chat 面板应该出现 Agent 的规划文本说明它拿到了模型响应并开始推理。Terminal 面板应该出现python hello.py的执行记录和输出hello openhands。Changes 面板应该显示新建了hello.py文件。这三个面板都有动静说明 Agent、Runtime、LLM Backend 三层都通了。如果 Chat 面板一直转圈没有文本输出大概率是模型通道没通。回到上一节的 curl 命令再验一次。如果 Chat 有输出但 Terminal 没动静说明模型通了但 Runtime 有问题检查 Docker 容器是否正常、Runtime 镜像是否拉取成功。如果 Changes 面板没显示文件检查 Runtime 的持久化挂载配置v0.39.0 之后持久化挂载有改进确认工作目录挂载正确。再做一个稍复杂的验证让 Agent 修复一个故意写错的 Python 文件。先手动创建一个bug.py里面写print(1/0)然后让 Agent“运行 bug.py 并修复报错”。成功的表现是Agent 先运行文件捕获到ZeroDivisionError然后修改文件加入异常处理或修正逻辑再次运行通过。这个过程能验证 Agent 的反馈分析和迭代纠错能力也就是它能不能根据 Runtime 返回的错误信息调整行动。验证通过后你可以试着切换 Model ID 再跑一次同样的任务。把LLM_MODEL改成另一个模型重启服务重复上面的最小任务。如果也能跑通说明统一通道的多模型切换是生效的你后续可以根据任务类型选模型比如复杂规划用推理强的简单改动用响应快的。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给排查路径。这些错误在 OpenHands 接入统一通道时出现频率最高按顺序排查能省很多时间。401 Unauthorized。最常见的原因是 Key 不对。检查三处.env里的 Key 有没有多余空格或换行config.toml里的 Key 是不是被环境变量覆盖成了空值Key 是不是在控制台被删除或过期。还有一种情况是 Base URL 写错导致请求打到了别的服务对方返回 401。确认 Base URL 是https://taotoken.net/api不带/v1。local proxy failed。这个报错通常出现在容器网络层。OpenHands 的 Runtime 容器要访问外部模型通道如果容器网络配置有问题请求出不去。检查 Docker 的 DNS 设置确认容器能解析外部域名。在容器内执行curl -sS https://taotoken.net/api看能不能通。如果容器内不通但宿主机通是 Docker 网络问题检查docker-compose.yml的network_mode和 DNS 配置。Error reading choices / reading choices。这个报错说明请求发出去了但响应结构不符合 OpenHands 的解析预期。常见原因是 Base URL 路径不对请求打到了返回非标准 JSON 的端点。确认 Base URL 没有多余路径。另一个原因是 Model ID 不被通道支持通道返回了错误结构。用 curl 单独验证该 Model ID 是否可用。还有一种情况是响应被中间层截断检查max_output_tokens是否设得过大导致超时截断。OAuth / authentication error。如果你在配置里误开了 OAuth 相关选项或者服务商类型provider填错会走到 OAuth 流程。统一通道用 API Key 认证provider填openai兼容模式即可不要选需要 OAuth 的服务商类型。检查config.toml里有没有残留的 OAuth 配置项清掉。排查时建议开日志。OpenHands 后端日志会打印实际请求的 URL 和响应状态码比 UI 上的报错信息详细得多。容器部署用docker compose logs -f openhands看实时日志。看到实际请求 URL 后和你的 Base URL 对比路径错误一眼就能看出来。如果报错信息里出现model not found说明 Model ID 拼写有问题。Model ID 是大小写敏感的claude-sonnet-4-20250514和Claude-Sonnet-4-20250514可能被当成两个模型。从控制台的模型列表里复制别手打。6. 接入后的下一步模型对话验证与长期编码方案配置跑通、最小任务验证成功后建议先做一轮模型对话验证确认通道在不同模型下的稳定性。打开模型对话页面用同一个 Prompt 分别测几个 Model ID观察响应速度和输出质量。这一步能帮你建立“哪个模型适合哪类任务”的直觉后续配 OpenHands 时按任务选模型。如果你打算把 OpenHands 长期用于编码和 Agent 任务建议走 Coding Plan 方案。它适合高频调用场景比按量计费更可控尤其是 Agent 任务链路长、单次任务可能触发几十次模型调用的情况下。接入方式不变还是 Base URL、Key、Model ID 三件套只是 Key 从按量计费换成套餐类型。接入文档里有各工具的详细配置示例包括 OpenHands、Cline、Claude Code 等。遇到配置字段不确定时对照文档里的字段名比猜要快。API Keys 页面管理你的 Key可以创建多个 Key 分别给不同工具用方便排查是哪个工具的问题。最后给一个实用技巧把 OpenHands 的config.toml和.env分开管理config.toml提交到仓库不含 Key.env本地保存并加进.gitignore。团队协作时每个人用自己的 Key配置文件共享。这样既保证配置一致又不会泄露 Key。切换模型时只改.env里的LLM_MODEL重启服务即可不用动其他文件。