1. 为什么要在 Docker 沙箱里给 OpenHands 接一条统一 Key 通道OpenHands 是一个把 LLM 当“执行大脑”的开源编程 Agent它能读你的仓库、改文件、跑命令、看报错再自己修。它和普通补全插件最大的区别是它真的会动手。而它动手的地方是一个隔离的 Docker 沙箱容器不是你的宿主机。这个设计很关键——Agent 跑偏了最多把沙箱搞坏你的系统盘和家目录是安全的。但很多人第一次在 Linux 上把 OpenHands 跑起来后会卡在同一个地方模型接不上。表现是界面能打开、任务能提交但 Agent 一直转圈或者日志里反复出现鉴权失败、连接超时、模型名不识别。原因通常不是 OpenHands 本身而是 LLM 通道没配对要么 Key 填错位置要么 base_url 没指向兼容端点要么 config.toml 和 Docker 环境变量两处配置打架。这篇就聚焦这一件事在 Linux 上用 Docker 启动 OpenHands 之后怎么通过一条统一的 Key/API 通道把 LLM 接进去让第一次代码任务真正跑通。我会给出一份可以直接复制的 config.toml 骨架、一份 Docker 环境变量骨架然后用一个“自动修复小 bug”的真实任务来验证最后把常见的报错路径一条条排掉。适合已经在 Linux 上装好 Docker、想让 OpenHands 真正干活的人。2. TaoToken 前置把 Key 和端点先准备好OpenHands 支持多种 LLM 提供方配置上分两层一层是 OpenHands 应用自己的 config.toml一层是传给沙箱容器的环境变量。两层都要指向同一个可用的 API 端点否则会出现“应用以为配好了、沙箱里请求却发不出去”的割裂。我用的统一通道是 TaoToken它提供 OpenAI 兼容的接口所以 OpenHands 里凡是填 base_url 和 api_key 的地方都能直接对接。你需要先拿到两样东西一是 API Key。登录后在控制台创建格式通常是一串以特定前缀开头的字符串。这个 Key 只显示一次复制好放安全的地方。二是确认端点地址。对话补全走的是兼容 OpenAI 的路径base_url 填https://taotoken.net/api注意这里不要带任何查询参数。模型名按你实际要用的填比如claude-sonnet-4-5这类具体以文档里的模型列表为准。注意Key 不要写进会提交到 Git 的文件里。config.toml 如果放在仓库内用环境变量引用或者把 config.toml 加进 .gitignore。相关入口我放在这里按需取用创建和管理 Key 在 API Keys接入参数和字段说明看 接入文档想先在网页里验证模型通不通用 模型对话。3. 可复制配置config.toml 骨架 Docker 环境变量骨架3.1 config.toml 骨架OpenHands 的 config.toml 一般放在工作目录下或者通过挂载进容器。下面这份骨架把 LLM 段单独拎出来字段名按 OpenHands 的约定来你只需要替换模型名和 Key 来源。[core] # 工作区路径容器内路径和挂载点保持一致 workspace_base /opt/workspace_base # 缓存目录避免每次重建 cache_dir /opt/workspace_base/.cache [llm] # 统一通道的兼容端点不要带查询参数 base_url https://taotoken.net/api # 模型名按实际可用列表填写 model claude-sonnet-4-5 # 从环境变量读取避免明文写死在文件里 api_key ${TAOTOKEN_API_KEY} # 采样温度改代码任务建议低一点稳定优先 temperature 0.2 # 单次最大输出修 bug 场景够用 max_output_tokens 4096 # 请求超时网络抖动时给足余量 timeout 120 [sandbox] # 沙箱类型Docker 环境下用 docker type docker # 沙箱内也注入同一套 Key保证 Agent 执行时能调模型 runtime_extra_env { TAOTOKEN_API_KEY ${TAOTOKEN_API_KEY} }这里有两个容易踩的点。第一api_key用${TAOTOKEN_API_KEY}这种引用写法前提是启动 OpenHands 的进程环境里真的有这个变量否则会解析成空字符串表现为 401。第二runtime_extra_env是给沙箱容器用的很多人只配了应用层忘了沙箱层结果 Agent 在容器里执行到需要调模型的步骤就断。3.2 Docker 环境变量骨架启动命令里把 Key 通过-e注入同时把 config.toml 挂载进去。下面这份可以直接改路径用。# 先导出 Key避免写进命令历史 export TAOTOKEN_API_KEY你的Key # 工作区目录 WORKSPACE_BASE$(pwd)/workspace mkdir -p $WORKSPACE_BASE docker run -it --rm \ --pullalways \ -e SANDBOX_USER_ID$(id -u) \ -e WORKSPACE_MOUNT_PATH$WORKSPACE_BASE \ -e TAOTOKEN_API_KEY$TAOTOKEN_API_KEY \ -v $WORKSPACE_BASE:/opt/workspace_base \ -v $(pwd)/config.toml:/opt/workspace_base/config.toml:ro \ -v /var/run/docker.sock:/var/run/docker.sock \ -p 3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app-$(date %Y%m%d%H%M%S) \ ghcr.io/opendevin/opendevin:0.8几个参数的作用值得说清楚。-e TAOTOKEN_API_KEY把 Key 传进应用容器-v config.toml把配置只读挂载进去容器重建也不丢-v /var/run/docker.sock让 OpenHands 能创建和管理它自己的沙箱容器这个不挂Agent 起不来--add-host host.docker.internal:host-gateway让容器内能访问宿主机网络某些本地服务场景会用到。提示如果你不想把 Key 放进环境变量也可以写进一个.env文件用--env-file .env加载效果一样但记得把.env加进 .gitignore。4. 验证请求用一次真实的小 bug 修复跑通全链路配置写完不算通得让 Agent 真的改一次代码。我准备了一个最小可复现的 bug一个 Python 函数在列表为空时抛异常。4.1 准备待修复的代码在$WORKSPACE_BASE下建一个buggy.pydef average(nums): # 当 nums 为空时这里会 ZeroDivisionError return sum(nums) / len(nums) if __name__ __main__: print(average([1, 2, 3])) print(average([]))4.2 提交任务给 OpenHands浏览器打开http://localhost:3000在任务框里输入修复 buggy.py 中的 average 函数使其在输入为空列表时返回 0 而不是抛异常。 修改后运行该文件确认两个调用都不报错。提交后观察 Agent 的动作序列。正常情况下它会读取buggy.py、定位到len(nums)为 0 的分支、写入修复、在沙箱里执行python buggy.py、看到输出2.0和0、给出完成总结。4.3 期望的成功结果修复后的函数大致长这样def average(nums): if not nums: return 0 return sum(nums) / len(nums)终端输出应该是2.0 0如果你在 OpenHands 界面里看到 Agent 完成了文件修改并贴出了执行输出说明从应用层到沙箱层、再到 LLM 通道整条链路是通的。这一步跑通后面接更复杂的任务才有意义。5. 本篇常见错排查从 401 到沙箱起不来5.1 鉴权失败401 / invalid api key最常见。先确认三件事Key 是否复制完整、有没有多余空格base_url是否写成了带路径或查询参数的地址环境变量是否真的传进了容器。进容器里验证一下docker exec -it 容器名 env | grep TAOTOKEN如果输出为空说明-e没生效检查启动命令。如果变量在但请求仍 401用 curl 直接打一次兼容端点排除 Key 本身的问题curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-5,messages:[{role:user,content:ping}]}返回正常内容说明 Key 和端点没问题问题在 OpenHands 配置层。5.2 模型名不识别model not foundOpenHands 里填的model必须和通道支持的模型名完全一致大小写、连字符都不能错。不确定时先去模型列表里核对别凭记忆填。填错的表现是请求发出去了但立刻返回错误Agent 会反复重试同一个名字。5.3 沙箱起不来Cannot connect to the Docker daemon这个报错说明 OpenHands 应用容器里访问不到宿主机的 Docker。检查启动命令里有没有挂/var/run/docker.sock以及当前用户有没有权限操作 Docker。用docker ps在宿主机确认守护进程正常再确认挂载路径没写错。5.4 请求超时timeout / connection reset改代码任务里 Agent 会连续发多次请求网络抖动时容易超时。把 config.toml 里的timeout调大比如 180。如果频繁 reset检查是不是有本地网络策略拦了出站或者容器 DNS 解析有问题可以在启动命令里加--dns 8.8.8.8试一次。5.5 配置不生效改了 config.toml 没反应OpenHands 可能读的是容器内另一份配置或者你挂载的路径和它默认查找的路径不一致。确认挂载目标路径和workspace_base对得上改完配置后重启容器别指望热加载。用docker exec进容器cat一下挂载进去的 config.toml确认内容是你改后的版本。6. 接下来怎么用按场景选入口链路跑通之后OpenHands 能做的事就多了批量重构、补测试、按 issue 描述改代码。如果你主要是长期跑编码任务、想让 Agent 持续在项目里干活建议用 Coding Plan 这类面向编码场景的通道配额和稳定性更适合长时间会话。如果你还在调模型参数、想先确认某个模型在改代码任务上的表现去 模型对话 里手动试几轮比在 Agent 里反复试错快得多。Key 的创建和轮换在 API Keys字段含义和兼容细节以 接入文档 为准。最后留一个我自己的习惯每次改完 config.toml先用第 5.1 节那条 curl 打一次确认 Key 和端点活着再启动 OpenHands。这样能把“通道问题”和“Agent 问题”分开排障时少绕很多路。