1. OpenHands 的 Agent 跑在容器里模型得你自己接1.1 Docker 起来了不等于它就能干活先把结论放在前面OpenHands 用 Docker 跑起来只要一条命令卡住多数人的是浏览器打开 http://localhost:3000 之后要填的模型配置。TaoToken 的 Key 到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建Base URL 填 https://taotoken.net/api两分钟就能把这条链路接上。那个 5.5 万 Star 的开源编程 Agent 之所以吸引人是它不像补全工具那样只猜下一行而是你给一个任务它自己开终端、自己改文件、自己跑测试、自己看报错再重试。听起来很唬人但镜像里既没有模型权重也没有随包附赠的额度。容器只是一个调度器加一层 Web 界面真正决定它聪不聪明的是你后面接上来的那条模型通道。所以第一次启动 OpenHands你会遇到一个很典型的场景界面出来了任务框也能打字可是左侧状态栏一直在等你把模型配好。这一步没配好它连第一步规划都出不来更别说动你的仓库。1.2 TaoToken 在这条链路里的位置只给两样东西把需求拆开看就清晰了——OpenHands 要开始思考需要一个能访问的模型接口地址和一把能过认证的 Key就这两样。TaoToken 提供的正是这两样统一的接口地址是 https://taotoken.net/apiKey 从官网控制台创建。它既不是 OpenHands 的内置功能也不是什么需要额外装的插件。你在 OpenHands 的模型设置里完全可以把它当成任意一个 OpenAI 兼容或 Anthropic 兼容的服务来填——选了对应的 Provider然后把地址和 Key 换成 TaoToken 给你的那套。理解这一点之后后面所有步骤都是照着界面填格子没有玄学。2. 把 OpenHands 容器起在 localhost:30002.1 docker run 里三个不能省的参数原文的部署方式就是一条 docker run。参数不多但有几个省掉就会出问题。下面这段可以直接改着用镜像的版本 tag 请去官方仓库对照当前值不要照抄某个写死的旧版本号docker run -it --rm --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:runtime-tag \ -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:app-tag三个地方值得单独说。-v /var/run/docker.sock:/var/run/docker.sock是把宿主机的 Docker 交给 OpenHands 使用它每接一个任务都会另起一个沙箱容器去执行命令这条不挂上任务会在准备阶段直接失败日志里能看到连不上 Docker daemon 一类的报错。-p 3000:3000决定你之后访问的端口。-v ~/.openhands:/.openhands用来把配置持久化不然每次重启容器模型设置都得重填一遍前期调试时会很烦。如果你是 Windows 环境把~/.openhands换成明确的盘符路径例如D:\openhands-state--add-host在 Docker Desktop 上通常用不上留着也不影响。2.2 第一屏就是模型选择别误会成自带额度容器起来之后浏览器打开 http://localhost:3000第一屏基本都会落到模型配置上。界面上常常会推荐 Claude 3.7 Sonnet 这类模型看起来像是开箱即用的默认能力。实际上那只是它给你的建议项Key 要你自己准备接口地址也要你自己指过去。默认推荐写什么和你能不能跑起来是两码事。这里还有个常见误判有人以为「容器能起来 网络是通的」于是直接把官方默认项填上去结果一提交任务就卡住。OpenHands 本身不会替你去申请任何凭证它只负责发请求。2.3 启动前顺手确认的两件事一是端口有没有被占用3000 被别的服务占了就换成-p 3001:3000然后访问 3001。二是磁盘Agent 每接一个任务都会拉一次运行环境长期跑的话留出足够空间。这两件事不解决后面排查模型问题时会白白绕远路——你以为是 Key 不对其实是容器根本没跑顺。3. 模型设置里的 Base URL 填 https://taotoken.net/api3.1 先去控制台建一把 Key打开 TaoToken注册登录后在控制台创建一把 API Key复制出来先放在一边。顺手在模型广场看一眼当前有哪些模型 ID等下要填进 OpenHands。Key 通常只在创建时完整显示一次没存下来就直接再建一把不用在这上面纠结。本文所有示例里Key 一律用占位符YOUR_API_KEY表示别把真实 Key 贴进任何截图或文章里。3.2 Provider、Base URL、Model 三格怎么对应OpenHands 的模型设置可以理解成三格一格都别填错设置项填什么备注Provider选与模型家族匹配的项OpenAI 兼容选 OpenAIAnthropic 系选 AnthropicBase URL / API Basehttps://taotoken.net/api末尾不要加/v1API KeyYOUR_API_KEY从 TaoToken 控制台创建的那把Model模型广场里的 ID以当时列表为准不要手写猜测的 ID有两点特别容易踩。第一Base URL 是给 OpenHands 这个程序去请求接口用的不是给人点开的网页所以不要填官网地址更不要把带查询参数的那串贴进去那串是给人看的落地页程序请求它会拿到一堆 HTML。第二这个地址末尾不带/v1客户端会自己拼路径你多写一层就会变成重复路径请求直接失败。3.3 不想每次在界面里填也可以走环境变量如果你习惯用命令行重开容器可以顺手把默认模型用环境变量带进去省得每次进界面再点一遍docker run -it --rm --pullalways \ -e LLM_MODEL模型广场里的模型 ID \ -e LLM_API_KEYYOUR_API_KEY \ -e LLM_BASE_URLhttps://taotoken.net/api \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.openhands:/.openhands \ -p 3000:3000 \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:app-tag具体变量名以你所用镜像版本的配置说明为准。如果你已经把配置目录挂出来并保存过设置界面里那条记录会优先于环境变量两边不一致时以界面为准这也是很多人「明明改了环境变量却没生效」的原因。4. 让它做个小任务确认通道真的通了4.1 任务一给仓库加一份日文版 README配置保存之后别急着丢一个大型 issue 进去先用小任务跑通。找一个自己 clone 到本地工作目录的小仓库在对话框里写清楚边界和验收标准请在当前仓库根目录新增 README.ja.md。 内容对应 README.md 的日文翻译保持原有标题层级、代码块和链接不变。 完成后列出新增或修改的文件路径。任务描述里把「做什么、在哪做、怎么算完成」写全比写一大堆形容词有用得多。这里要提醒一句边界OpenHands 跑在沙箱容器里它能做的是改代码、跑测试、看报错涉及生产库的诊断 SQL、编译、组件注册这类动作让它生成命令或脚本你自己在本机或 SQL*Plus 里执行完再把结果和报错贴回对话。别让它去连生产机器执行操作。4.2 任务二修一个 issue小任务通了之后可以再试一个带排查的任务。把 issue 的描述或链接贴进对话框要求它先复现、再定位、最后改并跑测试请阅读以下 issue 描述先在本地复现问题 说明复现步骤和观察到的现象再给出最小改动方案 修改完成后运行仓库里的测试命令并贴出结果。这个任务能顺带验证两件事一是模型在多轮规划下是否稳定二是你的通道在连续多次请求时有没有被限流或断开。4.3 从哪里看出来调用真的走了模型判断通道是否生效看两处。一是 Agent 的思考过程有没有正常推进——规划、选工具、执行、观察结果这几步是否成串出现如果模型没接上它在第一步就会停住或者反复重试同一个动作不会真的去动文件。二是任务结束后去看实际结果README.ja.md是不是真的出现在仓库里diff 是不是合理测试有没有跑过。如果结果是「动作流走完了但文件没变」「一直卡在等待模型返回」那就不是 OpenHands 的问题回到上一节检查地址和 Key。5. 认证失败先查 Base URL再查 Key5.1 两个最高频的填错排第一的是把官网地址当接口地址填了。有人在模型设置里直接贴了 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end界面不会立刻拦住你但一发请求就是认证失败或者返回一段 HTML——那是给人看的页面不是接口。记住分工官网落地址用于注册、建 Key、看模型广场和看用量填进 OpenHands 的地址只有https://taotoken.net/api。排第二的是末尾多了/v1。这个错误尤其隐蔽因为它看起来「更规范」但拼接之后路径就重复了返回的往往不是 401 而是 404很多人会顺着认证方向查半天。5.2 报错对照表现象大概率原因处理方式401 / UnauthorizedKey 复制不完整、带空格、或已被删除回控制台重新创建一把404 / Not FoundBase URL 多了/v1或填成了官网地址改成https://taotoken.net/api一直转圈不出结果模型 ID 写错或该模型不在当前可用列表去模型广场核对 ID任务起不来日志报 Docker 相关没有挂载docker.sock检查-v参数排查顺序建议固定下来先看 Base URL 是不是https://taotoken.net/api再看模型 ID 是不是从列表里复制的最后才怀疑 Key。这个顺序能省掉大量无用功因为地址类的错误出现频率远高于 Key 本身失效。5.3 用同一把 Key 换个入口验证如果 OpenHands 里始终认证不过先把 Key 本身摘出去。在 TaoToken 模型对话 里用同一把 Key 发一条测试消息能正常回来说明 Key 没问题问题就在 OpenHands 这边的地址或模型 ID 上如果那边也不通那就是 Key 或账户状态的问题重新建一把最快。这一步的价值在于把问题一分为二避免在界面和 Key 之间来回猜。6. 跑通之后去对一下这次调用6.1 任务跑完回控制台看用量OpenHands 的一个任务往往包含多轮规划和多次工具调用一次跑下来消耗不算小尤其是让它反复读文件、跑测试的时候。回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的用量页面能看到这次调用有没有记上账、落在哪个模型上。如果发现用量比预期高很可能是循环没有被正常终止或者任务描述太模糊导致它反复试错这两点都可以通过收紧验收标准来改善。6.2 接下来可以做的事情如果你打算让 OpenHands 长期在后台跑任务先评估一下用量节奏再决定走哪种计费方式Key 统一在 控制台 API Keys 里创建和管理换机换容器只要换这一把。日常想快速验证某个模型 ID 能不能用直接在 TaoToken 模型对话 里发一条最省事。最后补一个容易被忽略的点容器化 Agent 很强但它终究是个会自己动手的执行者。第一次接入某个仓库时先给它一个干净的分支和可回滚的工作目录等小任务稳定跑通几次再把范围放大。通道接对了剩下的就是任务描述的功夫。