1. 为什么要在 Linux 上用 Docker 跑 OpenHands还要统一 KeyOpenHands 是一个开源的 AI 软件开发代理平台前身叫 OpenDevin它能像真人开发者一样改代码、跑命令、调 API、翻文档甚至从社区问答里扒代码片段。适合谁适合那些手头有好几台 Linux 服务器、想给团队搭一个私有 AI 开发助手、又不想把 API Key 散落在各个项目里的后端和运维同学。我自己的场景是这样的一台 Ubuntu 22.04 的测试机平时跑 CI、跑爬虫、偶尔做点代码生成实验。之前用 OpenHands 的时候每换一个模型就要改一次环境变量Claude 一个 Key、GPT 一个 Key、国产模型又一个 Key配置文件里塞得乱七八糟。更麻烦的是团队里其他人想用还得把 Key 发来发去安全上很不放心。后来我把 OpenHands 的模型 endpoint 统一指向了 TaoToken 的 API 通道一个 Key 就能切换不同模型配置文件干净了很多。这篇就按我实际踩过的流程从 Docker 部署、docker-compose 配置、环境变量模板到把 endpoint 改到 TaoToken、验证对话和代码生成一步步写清楚。你照着做大概二十分钟能跑起来。核心检索词先明确OpenHands Docker 部署、Linux AI 开发助手、TaoToken 统一 Key 接入。这三个词贯穿全文你搜到这篇基本就是你要找的东西。先说清楚 OpenHands 的架构不然配置容易懵。它本体是一个 Web 应用默认监听 3000 端口但它干活的时候会去启动一个 sandbox runtime 容器也就是真正执行代码的那个隔离环境。所以你的 Docker 必须把宿主机的/var/run/docker.sock挂进去让 OpenHands 有权限去拉 runtime 镜像、起容器。这也是为什么它不能简单塞进一个纯前端静态托管里。模型这块OpenHands 支持自定义 Base URL 和 Model Name这就给了我们接入统一 API 通道的空间。你不需要改它的源码只要在设置界面或者环境变量里把 LLM 的 base_url 指过去就行。下面进入实操。2. TaoToken 前置准备拿到统一 Key 和 Base URL在动 Docker 之前先把 TaoToken 这边的信息准备好不然容器起来了你还得回头找。TaoToken 是一个统一的大模型 API 接入通道你注册后在控制台创建一个 API Key就能用它去调用不同厂商的模型不用每个模型单独申请 Key。对 OpenHands 这种需要频繁切换模型的工具来说省事很多。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。在控制台里找到 API Keys 页面点创建复制生成的 Key形如sk-xxxxxxxx。这个 Key 只显示一次记得存好。第二步确认 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数配置里就写这个。OpenHands 里填 Base URL 的时候通常需要带上/v1后缀也就是https://taotoken.net/api/v1具体以你调用时的实际路径为准后面验证环节我会给出 curl 测试命令帮你确认。第三步想清楚你要用哪个模型。TaoToken 支持多种模型你在控制台的模型列表里能看到可用的 Model ID比如claude-sonnet-4-20250514、gpt-4o这类。OpenHands 的 Model 字段要填的就是这个 ID。建议先选一个你熟悉的验证通了再换。这里有个小坑提前说OpenHands 的模型配置分两部分一部分是 LLM Provider提供商一部分是 Model Name 和 Base URL。如果你用自定义 Base URLProvider 一般选openai兼容模式或者custom因为 TaoToken 的接口是 OpenAI 兼容格式的。选错了 Provider请求会直接 404 或者 401。准备好这三样东西API Key、Base URL、Model ID我们就可以写配置文件了。如果你还没创建 Key现在去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 建一个回来继续。3. 可复制的 docker-compose 配置与环境变量模板这一节是全文最核心的部分配置直接抄改几个值就能用。我不用docker run那种一长串命令因为参数太多容易漏改用 docker-compose配置文件放本地改起来清楚。先建目录结构。在 Linux 服务器上执行mkdir -p /opt/openhands cd /opt/openhands然后创建.env文件把敏感信息和可变参数都放这里docker-compose 会自动读取。文件内容如下# /opt/openhands/.env # TaoToken 统一 API 配置 LLM_API_KEYsk-你的TaoToken密钥 LLM_BASE_URLhttps://taotoken.net/api/v1 LLM_MODELclaude-sonnet-4-20250514 # OpenHands 运行参数 OPENHANDS_PORT3000 LOG_ALL_EVENTStrue SANDBOX_RUNTIME_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.14-nikolaik注意LLM_BASE_URL我写的是带/v1的因为 OpenAI 兼容接口通常在这个路径下。如果你的调用报 404可以试着去掉/v1再测后面排障章节会讲怎么判断。接着创建docker-compose.yml# /opt/openhands/docker-compose.yml version: 3.8 services: openhands: image: docker.all-hands.dev/all-hands-ai/openhands:0.14 container_name: openhands-app pull_policy: always ports: - ${OPENHANDS_PORT}:3000 environment: - SANDBOX_RUNTIME_CONTAINER_IMAGE${SANDBOX_RUNTIME_IMAGE} - LOG_ALL_EVENTS${LOG_ALL_EVENTS} - LLM_API_KEY${LLM_API_KEY} - LLM_BASE_URL${LLM_BASE_URL} - LLM_MODEL${LLM_MODEL} volumes: - /var/run/docker.sock:/var/run/docker.sock - ./data:/.openhands extra_hosts: - host.docker.internal:host-gateway restart: unless-stopped几个关键点解释一下。volumes里挂了/var/run/docker.sock这是 OpenHands 启动 sandbox 容器必须的不挂的话它没法执行代码。./data:/.openhands是把配置和会话数据持久化到本地容器重启不丢。extra_hosts那行是让容器内能通过host.docker.internal访问宿主机某些网络环境下需要。environment里我把 TaoToken 的三个参数通过.env注入进去了。OpenHands 0.14 版本支持从环境变量读取 LLM 配置这样你就不用在 Web 界面里手动填容器一起来就是配好的。如果你用的是更新的版本环境变量名可能略有不同比如有的版本用LLM_API_KEY有的用OPENAI_API_KEY。以你拉下来的镜像文档为准。我实测 0.14 这套是能读到的。配置写好后启动cd /opt/openhands docker compose up -d第一次会拉镜像OpenHands 本体加上 runtime 镜像加起来几个 G网速慢的话等一会儿。拉完后docker compose ps看到openhands-app状态是Up就对了。如果你更习惯用docker run等价命令是这样但我还是推荐 composedocker run -it --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.14-nikolaik \ -e LOG_ALL_EVENTStrue \ -e LLM_API_KEYsk-你的密钥 \ -e LLM_BASE_URLhttps://taotoken.net/api/v1 \ -e LLM_MODELclaude-sonnet-4-20250514 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /opt/openhands/data:/.openhands \ -p 3000:3000 \ --add-host host.docker.internal:host-gateway \ --name openhands-app \ docker.all-hands.dev/all-hands-ai/openhands:0.14两种方式选一种就行别同时跑端口会冲突。配置文件里的 Model ID 记得换成你 TaoToken 控制台里实际可用的写错了请求会返回模型不存在的错误。4. 验证请求从 curl 到 OpenHands 对话与代码生成容器起来不代表模型通了得一步步验证。我习惯先用 curl 直接打 TaoToken 的接口确认 Key 和 Base URL 没问题再去 OpenHands 里测这样出问题好定位。第一步在宿主机上 curl 测试curl 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: 回复两个字通了}] }如果返回 JSON 里有choices字段内容里是「通了」说明 Key、Base URL、Model 三件套都对。如果返回 401是 Key 问题返回 404多半是 Base URL 路径不对返回模型不存在是 Model ID 写错了。这三种情况下一节详细讲。第二步进 OpenHands 界面。浏览器打开http://你的服务器IP:3000。首次进入会弹设置窗口如果你环境变量注入成功这里应该已经填好了 Provider、Model、Base URL。检查一下 Base URL 是不是https://taotoken.net/api/v1Model 是不是你设的那个。没问题就点 Save。第三步测对话。在输入框里发一句请编写一个 bash 脚本 hello.sh打印 hello world!正常情况下左侧显示你的提示词右侧 OpenHands 会开始思考然后给出脚本内容并可能直接在工作区创建文件。这一步验证的是模型对话链路通了。第四步测代码生成和执行。继续输入用 HTML 写一个简单计算器然后启动它OpenHands 会生成 HTML 文件然后尝试在 sandbox 里起一个服务最后在对话里输出访问链接。你点开链接能看到计算器界面说明 sandbox runtime 也正常工作了。这一步很关键因为很多人模型通了但 sandbox 起不来通常是 docker.sock 没挂对。我实测下来从 curl 通到界面出结果整个链路大概十几秒。如果卡在「正在思考」很久多半是模型响应慢或者网络问题可以换个 Model ID 试试。验证通过后你可以在设置里随时切换模型只要改 Model IDBase URL 和 Key 都不用动这就是统一 Key 接入的好处。团队里其他人用你只要给他们 OpenHands 的访问地址不用发 Key。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞的几个报错我按实际遇到的频率排一下每个都给判断方法和解决动作。401 Unauthorized。这个最常见意思是 Key 不对。先检查.env里的LLM_API_KEY有没有多余空格sk-前缀有没有漏。然后确认这个 Key 在 TaoToken 控制台里是启用状态没被删。如果 Key 没问题检查 Base URL 是不是写成了https://taotoken.net/api而漏了/v1有些兼容层对路径敏感。用上一节的 curl 命令单独测能快速区分是 Key 问题还是 OpenHands 配置问题。local proxy failed / connection refused。这个报错通常出现在 OpenHands 容器内访问外部 API 时。原因是容器网络出不去或者 DNS 解析失败。先docker exec -it openhands-app curl https://taotoken.net/api/v1/models看容器内能不能通。如果容器内不通但宿主机通检查 docker 的网络模式别用--network none。另外extra_hosts那行如果写错也可能导致解析异常。Error reading choices / choices 字段为空。这个说明请求发出去了但返回结构不对。常见原因是 Model ID 写错TaoToken 返回了一个错误对象而不是正常的 chat completion。解决办法是拿 curl 单独测这个 Model ID看返回里有没有choices。如果没有去控制台核对模型列表换一个可用的 ID。还有一种可能是 Base URL 少了/v1请求打到了错误的路径返回了 HTML 而不是 JSON。OAuth / 登录相关报错。OpenHands 某些版本会尝试 OAuth 登录或者校验 GitHub token如果你没配它可能报错。这个一般不影响本地使用在设置里跳过或者用匿名模式即可。如果它强制要 OAuth检查你的镜像版本0.14 这套默认是本地设置不需要 OAuth。如果你用的是带登录的版本按它的文档配GITHUB_TOKEN之类的环境变量。容器起来了但 3000 端口打不开。先docker compose ps看状态再docker compose logs -f openhands看日志。常见是端口被占用改.env里的OPENHANDS_PORT换个端口。还有可能是防火墙没放行ufw allow 3000一下。sandbox 起不来代码执行一直转圈。九成是/var/run/docker.sock没挂或者权限不对。确认 compose 文件里那行 volumes 在然后ls -l /var/run/docker.sock看权限当前用户得能读写。如果是 rootless docker路径可能不一样按你的 docker 安装方式调整。排查的核心思路就一条先用 curl 把 TaoToken 这层测通再测 OpenHands 到 TaoToken 这层最后测 sandbox。分层定位比瞎改配置快得多。6. 长期使用建议与接入文档入口跑通之后有几个习惯能让这套东西用得更久。第一.env文件权限设成 600别让其他用户读到 Key。第二./data目录定期备份里面是你的会话和配置。第三模型 ID 别写死在 compose 里放.env换模型只改一行。第四如果团队多人用考虑在前面加一层反向代理做访问控制别直接把 3000 端口暴露到公网。如果你想把 OpenHands 接到更多模型或者想了解 TaoToken 支持哪些 Model ID可以看接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里有各模型的调用示例和参数说明比在界面里一个个试快。想先在线试试模型对话效果不搭环境的话可以用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发几条消息感受一下响应速度和格式再决定用哪个模型接进 OpenHands。如果你打算长期跑编码任务或者做 Agent 实验Coding Plan 会更划算入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合高频调用场景。Key 管理还是去 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。最后说个我踩过的坑OpenHands 的 runtime 镜像版本要和本体版本对上0.14 的本体配 0.14 的 runtime混用会报 sandbox 启动失败。升级的时候两个一起升别只升一个。配置改完记得docker compose down docker compose up -d重启光 restart 有时候读不到新的环境变量。