1. 为什么要在 Linux 上用 Docker 跑 OpenHands AI 开发代理OpenHands 是一个开源的 AI 软件开发代理平台前身叫 OpenDevin。它能做的事情和人类开发者几乎一样读写代码文件、执行 shell 命令、浏览网页、调用 API甚至从技术社区复制代码片段直接改。你可以把它理解成一个「住在容器里的 AI 结对程序员」你给它一句自然语言需求它自己规划步骤、动手改文件、跑命令验证。它适合谁我总结了三类人一是想体验 AI Agent 自动完成多步开发任务的后端/全栈工程师二是需要给团队搭一套可远程访问的 AI 编码环境的技术负责人三是想研究 Agent 架构、自己接大模型 API 的开发者。OpenHands 采用 MIT 许可证社区驱动主语言是 Python但运行强依赖 Docker——因为它的每一次「动手操作」都跑在一个隔离的沙箱运行时容器里这样 AI 执行命令不会污染你的宿主机。为什么强调 Linux Docker因为 OpenHands 的沙箱机制需要挂载宿主机的 Docker socket/var/run/docker.sock让主容器有能力去拉起运行时容器。在 Ubuntu 22.04 这类 Linux 环境里这套机制最顺Windows/Mac 虽然也能跑但路径和权限的坑更多。我实测下来Linux 原生 Docker 的启动成功率和执行速度都明显更好。部署完之后还有一个现实问题服务默认只监听localhost:3000你人在外面比如出差、在家就访问不到。这时候用 cpolar 做内网穿透把本地 3000 端口映射成一个公网地址就能在任意设备的浏览器里远程使用这套 AI 代理环境。整篇文章我会交付可复制的 Docker 命令、环境变量清单、模型接入配置以及 cpolar 隧道从随机域名到固定二级域名的完整验证步骤。需要说明的是OpenHands 本身只是一个「壳」真正干活的是背后的大模型。所以部署完第一件事就是配置 LLM 提供商和 API Key。如果你手头没有现成的模型额度可以先用 TaoToken 这类聚合平台拿一个兼容 OpenAI 协议的 Key 来跑通流程后面我会给出具体的 Base URL 和 Model ID 填法。2. 前置准备Docker 环境、模型 Key 与 TaoToken 接入配置在拉镜像之前先把地基打好。这一节解决三件事Docker 装好没、模型 Key 从哪来、OpenHands 里怎么填。先说 Docker。Ubuntu 22.04 上用官方脚本最省事但生产环境建议用 apt 仓库方式装方便后续升级。装完后执行docker version和docker compose version两个都有输出才算 OK。这里有个容易忽略的点OpenHands 要挂载/var/run/docker.sock所以启动容器的用户必须对 docker 组有权限否则会报permission denied while trying to connect to the Docker daemon socket。解决办法是把当前用户加进 docker 组sudo usermod -aG docker $USER然后重新登录一次 shell 让组权限生效。再说模型 Key。OpenHands 支持多种 LLM 提供商界面上可以选 OpenAI、Anthropic、Azure 等也支持「自定义模型」——只要对方兼容 OpenAI 的/chat/completions协议就行。如果你暂时没有官方额度可以用 TaoToken 拿一个兼容 Key访问 https://taotoken.net/api 注册后在控制台创建 API Key。它的 Base URL 填https://taotoken.net/apiModel ID 按你选的模型填比如gpt-4o、claude-3-5-sonnet这类名称以控制台实际列表为准。这里要提醒一句OpenHands 的模型配置分两层。一层是「主模型」负责理解需求、规划任务另一层是「运行时模型」沙箱里执行具体操作时也会调用。如果只配了主模型没配运行时某些任务会中途卡住。稳妥做法是两层都指向同一个 Key 和 Base URL。关于 TaoToken 的定位它是一个模型 API 聚合与调用平台提供兼容 OpenAI 协议的接口方便你在 OpenHands 这类工具里统一接入不同模型。它不是「中转」意义上的灰色服务而是正规的 API 聚合入口你按文档填 Base URL 和 Key 即可。接入文档在 https://taotoken.net/api 页面有说明遇到 401 先回去核对 Key 有没有复制全。最后确认端口。OpenHands 默认用 3000cpolar 隧道也映射 3000所以启动前用ss -tlnp | grep 3000确认端口没被占用。如果被占了要么停掉占用进程要么改映射端口比如-p 3001:3000但记得 cpolar 的本地地址也要跟着改成 3001。3. 可复制配置Docker Compose 与 settings 片段这一节给你能直接粘贴的配置。我推荐用 Docker Compose 而不是一长串docker run因为环境变量多、以后要改也方便。先建目录并写docker-compose.ymlversion: 3.8 services: openhands: image: docker.all-hands.dev/all-hands-ai/openhands:0.14 container_name: openhands-app pull_policy: always ports: - 3000:3000 environment: - SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.14-nikolaik - LOG_ALL_EVENTStrue - SANDBOX_USER_ID1000 volumes: - /var/run/docker.sock:/var/run/docker.sock - ~/.openhands:/.openhands extra_hosts: - host.docker.internal:host-gateway stdin_open: true tty: true几个参数说明一下。SANDBOX_RUNTIME_CONTAINER_IMAGE指定沙箱运行时镜像必须和主镜像版本对齐否则会出现运行时启动失败。SANDBOX_USER_ID设成你宿主机当前用户的 uid用id -u查避免生成的文件属主变成 root。~/.openhands挂出来是为了持久化配置重启容器后模型设置不丢。extra_hosts那行让容器内能用host.docker.internal访问宿主机某些网络场景会用到。启动命令docker compose up -d docker compose logs -f openhands看到日志里出现Uvicorn running on http://0.0.0.0:3000就说明起来了。接下来是模型配置。OpenHands 首次打开会弹设置窗口也可以点齿轮图标随时改。如果你想像代码一样管理配置可以直接写~/.openhands/settings.json路径与容器内挂载一致{ LLM_MODEL: gpt-4o, LLM_API_KEY: sk-你的TaoToken密钥, LLM_BASE_URL: https://taotoken.net/api, LLM_PROVIDER: openai, AGENT: CodeActAgent, LANGUAGE: zh, SANDBOX_RUNTIME_CONTAINER_IMAGE: docker.all-hands.dev/all-hands-ai/runtime:0.14-nikolaik }这里三件套必须齐全Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 填你实际要用的模型名。少任何一个都会在请求时报错。如果你用的是 Claude 系列模型Provider 可以保持openai兼容模式因为 TaoToken 的接口是 OpenAI 协议兼容的Base URL 不用改。改完配置重启容器生效docker compose restart openhands注意settings.json里的 Key 是明文别把这个文件提交到 Git 仓库。生产环境建议用环境变量注入或者至少给文件设chmod 600。4. 验证请求从 hello.sh 到计算器确认代理真的在干活配置填好后别急着上复杂任务先用最小用例验证链路通不通。这一步能帮你快速区分「是模型没配好」还是「是沙箱没起来」。打开http://localhost:3000在输入框里发第一条指令请编写一个 bash 脚本 hello.sh打印 hello world!正常情况下左侧会显示你的提示词右侧 Agent 会先「思考」再「行动」它会创建一个文件、写入内容、然后执行bash hello.sh验证输出。你会在对话流里看到类似Action: create_file、Observation: hello world!这样的步骤记录。如果这一步就报错八成是模型 Key 或 Base URL 的问题直接跳到第 5 节排障。第一条通过后加一点难度让它生成一个 HTML 计算器用 HTML JavaScript 创建一个简单的计算器支持加减乘除保存为 calculator.htmlAgent 会生成完整文件。生成完后在输入框里让它运行启动一个本地 HTTP 服务运行这个计算器它会在沙箱里执行类似python3 -m http.server 8000的命令并在对话里输出访问链接。因为沙箱端口默认没映射到宿主机你直接在宿主机浏览器打不开那个链接但可以在对话里让它用curl自测返回 200。想真正在浏览器里看效果可以把生成的calculator.html从容器里拷出来docker cp openhands-app:/workspace/calculator.html ./calculator.html然后用本地编辑器打开验证。我试过这套流程从发指令到拿到可运行文件通常一两分钟比手写快不少尤其是模板化的前端页面。验证成功的标志有三个一是 Agent 能连续完成「创建文件→执行→读结果」多步操作二是对话里没有红色的 error 事件三是拷出来的文件内容完整、能正常运行。三个都满足说明 OpenHands 模型 沙箱这条链路是通的可以进入公网访问环节了。5. 本篇常见错排查401、local proxy failed、reading choices 报错对照这一节把我踩过的坑和社区高频报错整理成对照表遇到问题直接查。报错一401 Unauthorized / invalid api key这是最常见的。原因通常是 Key 复制时带了空格、或者 Base URL 末尾多了斜杠。检查两点LLM_BASE_URL必须是https://taotoken.net/api不要写成https://taotoken.net/api/Key 要完整别漏字符。改完settings.json后记得docker compose restart openhands配置不会热加载。报错二local proxy failed / connection refused这个多半是容器内访问不到外部网络或者 Base URL 写成了localhost。注意OpenHands 主容器里的localhost指的是容器自己不是宿主机。如果你把 Base URL 写成http://localhost:xxxx必然连不上。正确做法是填公网可访问的地址比如https://taotoken.net/api。如果是宿主机上跑的服务要用host.docker.internal。报错三Error reading choices / 模型返回格式异常这个报错通常出现在模型返回的 JSON 结构不符合预期时。原因可能是 Model ID 填错了比如填了一个平台不支持的模型名接口返回了错误结构。解决办法是回 TaoToken 控制台核对模型列表把LLM_MODEL改成实际存在的名称。另外某些模型对temperature敏感OpenHands 默认参数下如果模型不支持某些字段也可能触发解析异常换一个稳定模型先跑通。报错四OAuth / 登录态失效如果你在 cpolar 公网地址上访问换了新域名后可能需要重新登录 OpenHands。这是正常的因为浏览器把不同域名当作不同站点本地存储的会话不共享。重新在设置里填一次模型配置即可。如果反复要求登录检查~/.openhands目录有没有正确挂载和写权限。报错五sandbox runtime 启动失败 / docker.sock permission denied回到第 2 节说的权限问题。确认当前用户在 docker 组里且/var/run/docker.sock挂载正确。用docker ps看有没有运行时容器被拉起来。如果主容器日志里报Cannot connect to the Docker daemon就是 socket 挂载或权限没配对。排查顺序建议先看docker compose logs openhands的报错原文再对照上面五类。90% 的问题集中在 Key/Base URL 和 docker.sock 权限这两块。6. 用 cpolar 打通公网访问并固定二级子域名本地跑通后最后一步是让它能被远程访问。cpolar 的作用是把本地 3000 端口映射成一个公网 HTTPS 地址不需要公网 IP也不用买云服务器。先装 cpolarsudo curl https://get.cpolar.sh | sh sudo systemctl status cpolar服务正常启动后浏览器打开http://localhost:9200用 cpolar 账号登录管理界面。接着创建隧道隧道名称填openhands协议选http本地地址填3000域名类型选「随机域名」地区选 China Top。创建成功后在「在线隧道列表」里能看到一个https://xxxx.cpolar.cn的公网地址。拿这个地址在另一台设备比如手机或异地电脑的浏览器里打开应该能看到 OpenHands 界面。第一次访问新域名可能需要重新填一次模型配置这是正常的会话隔离。随机域名有个问题24 小时内会变不利于长期使用。所以要做固定二级子域名。步骤是登录 cpolar 官网左侧「预留」→「保留二级子域名」地区选 China VIP设一个名字比如myopenhands点保留。然后回到localhost:9200的隧道列表编辑刚才那条隧道域名类型改成「二级子域名」Sub Domain 填myopenhands地区选 China VIP点更新。更新完成后在线隧道列表里的地址就变成固定的https://myopenhands.cpolar.cn了不会再随机变化。用这个固定地址访问配置一次模型后就能长期远程使用。到这里一套「Linux 本地 Docker 部署 OpenHands cpolar 公网访问」的环境就完整了。日常使用中我建议把常用的模型配置和docker-compose.yml一起放进一个私有仓库管理换机器时几分钟就能重建。如果后续要接更多模型或做团队协作可以关注 TaoToken 的 Coding Plan 方案统一管理多个模型的调用额度省得每个工具单独配 Key。