本地Docker部署OpenHands人工智能软件开发代理平台及远程访问配置指南

1. 本地 Docker 部署 OpenHands 到底解决什么问题OpenHands原名 OpenDevin是一个基于人工智能的软件开发代理平台它能像真人开发者一样修改代码、执行命令行、浏览网页、调用 API。你给它一句自然语言需求它会在隔离的沙箱容器里真正动手写文件、跑脚本、装依赖而不是只吐一段代码让你自己复制。适合谁用三类人最明显一是想体验 AI Agent 自动完成多步开发任务的后端/全栈工程师二是需要把代理跑在隔离环境、不想让它污染本机文件系统的谨慎派三是希望从外部网络随时访问自己这台开发机的远程办公者。问题也很直接。官方推荐的启动方式是一条很长的docker run命令参数多、镜像 tag 容易写错而且默认只监听本机 3000 端口出了局域网就访问不到。更麻烦的是 OpenHands 自己还要在容器里再拉起一个 runtime 沙箱容器所以必须把宿主机的 Docker socket 挂进去这一步配置错了就会报「无法连接 runtime」之类的错。我试过把这套流程整理成可复制的 Compose 配置再配合一个稳定的模型接入点整个链路就顺了。这篇就按「本地部署 → 模型接入 → 远程访问 → 排障」的顺序走一遍命令和配置都能直接抄。模型这一环我用的是 TaoToken 的兼容接口它提供 OpenAI 兼容的 Base URLOpenHands 在设置里填自定义模型时正好用得上省得为每个模型单独折腾 SDK。2. 部署前的前置准备Docker、目录与 TaoToken 接入点先说环境。演示用 Ubuntu 22.04Docker 24 和 Docker Compose v2 是硬性要求因为 OpenHands 依赖 Docker socket 来创建沙箱。检查一下docker --version docker compose version如果 Docker 还没装用官方脚本装完记得把当前用户加进 docker 组否则每次都要 sudosudo usermod -aG docker $USER newgrp docker然后是模型接入。OpenHands 本身不带模型它需要你提供一个 LLM 提供商的 API Key 和 Base URL。TaoToken 的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions协议所以在 OpenHands 里选「Custom」或 OpenAI 兼容模式把 Base URL 填成这个地址即可。先去控制台创建一个 API Key提示API Key 只在创建时完整显示一次复制后立刻存到密码管理器或.env文件里别直接写进会提交到 Git 的配置。创建 Key 的入口在控制台的 API Keys 页面模型对话入口可以用来先验证 Key 是否可用。这两个地址分别是API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenhands_docker模型对话验证https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenhands_docker拿到 Key 之后建议在服务器上建一个独立目录放配置别把 Key 散落在命令行历史里mkdir -p ~/openhands cd ~/openhands touch .env chmod 600 .env.env里先写两行后面 Compose 会引用LLM_API_KEYsk-你的TaoToken密钥 LLM_BASE_URLhttps://taotoken.net/api这样做的意义是命令行里不出现明文 Keydocker compose会自动读取.env容器重启也不用重新输入。3. 可复制的 Docker Compose 配置与启动步骤官方那条docker run命令拆成 Compose 会清晰很多。在~/openhands下新建docker-compose.ymlservices: 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 - LLM_API_KEY${LLM_API_KEY} - LLM_BASE_URL${LLM_BASE_URL} volumes: - /var/run/docker.sock:/var/run/docker.sock - ~/.openhands:/.openhands extra_hosts: - host.docker.internal:host-gateway restart: unless-stopped几个参数值得单独说清楚配错了就是各种玄学报错参数作用常见坑SANDBOX_RUNTIME_CONTAINER_IMAGE指定沙箱 runtime 镜像tag 必须和主镜像版本对齐0.14 配 0.14/var/run/docker.sock挂载让主容器能创建沙箱容器不挂载会报 runtime 连接失败host.docker.internal:host-gateway容器内访问宿主机Linux 上不加这条解析不到宿主机~/.openhands卷持久化设置和会话不挂载重启后模型配置全丢先拉镜像再启动避免启动时卡在拉取docker compose pull docker compose up -d看日志确认没有报错docker compose logs -f openhands日志里出现类似Uvicorn running on http://0.0.0.0:3000就说明服务起来了。这时候浏览器打开http://localhost:3000首次会弹设置窗口让你选 LLM 提供商、模型和 API Key。在设置里这样填提供商选 OpenAI 兼容或 CustomBase URL 填https://taotoken.net/apiAPI Key 填你的 TaoToken 密钥模型名按你实际要用的填。保存后配置会写进~/.openhands下次重启不用重填。如果要用自定义模型展开高级选项手动输入模型名称和 Base URL 即可。4. 验证请求从 hello.sh 到生成一个计算器配置保存后别急着上复杂任务先用最小例子验证整条链路通不通。在对话框输入请编写一个 bash 脚本 hello.sh打印 hello world!正常情况下左侧显示你的提示词右侧 OpenHands 会规划步骤、创建文件、执行脚本最后把输出贴回来。这一步能跑通说明模型接入、沙箱创建、命令执行三个环节都正常。再验证一个多文件任务输入用 HTML JavaScript 创建一个简单的计算器支持加减乘除它会生成index.html等文件然后你让它运行启动这个项目并给我访问链接OpenHands 会在沙箱里起一个静态服务器把链接输出到对话框。你可以用 VSCode 打开生成的文件本地跑一遍确认计算器逻辑正确。不满意就继续在对话框里追加需求它会基于当前工作区迭代修改。这一步如果卡住八成是模型返回格式不对或沙箱没起来。先看docker compose logs里有没有 runtime 相关报错再确认 Base URL 末尾没有多余的/v1TaoToken 的地址填到/api即可具体路径以文档为准。接入文档里有完整的参数说明接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenhands_docker5. 远程访问配置与常见错误排查本地跑通后远程访问是下一个需求。默认 OpenHands 只监听本机外部网络访问不到。这里有两种思路一是把服务绑到0.0.0.0并通过防火墙/安全组放行端口适合有公网 IP 的云主机二是用内网穿透把本地端口映射出去适合家里或公司内网的机器。第一种方式改 Compose 的端口映射即可ports已经是3000:3000容器内监听0.0.0.0所以宿主机层面能访问。云主机上确认安全组放行了 3000 端口然后直接用http://公网IP:3000访问。注意这种方式没有 HTTPS生产环境建议前面挂一层 Nginx 做 TLS 终止。第二种方式用内网穿透工具把本地 3000 端口映射成一个公网地址。配置时协议选 HTTP本地地址填 3000创建后拿到公网 URL在任意设备浏览器打开就能看到 OpenHands 界面重新配置模型即可使用。随机域名会定期变化长期用建议保留一个固定二级子域名把隧道改成固定地址这样远程访问的 URL 就不会变。排障清单按出现频率排序报错一Cannot connect to the Docker daemon容器内访问不到 Docker socket。检查/var/run/docker.sock是否挂载宿主机 Docker 服务是否运行以及当前用户是否有权限。报错二Failed to create sandbox或 runtime 超时多半是SANDBOX_RUNTIME_CONTAINER_IMAGE的 tag 和主镜像不匹配或者宿主机磁盘空间不足拉不下 runtime 镜像。用docker images确认两个镜像都在。报错三模型返回 401 或 404API Key 错了或 Base URL 填错。先用模型对话入口单独验证 Key再回来检查 OpenHands 设置里的地址。注意别把/api和/v1混着拼。报错四重启后模型配置丢失~/.openhands没挂载成卷。补上 volumes 里的那行重建容器。报错五远程访问白屏或连接被拒端口没放行或内网穿透隧道没启动。先在宿主机curl localhost:3000确认服务活着再排查网络层。6. 长期编码与 Agent 场景的接入建议如果你只是偶尔跑几个任务按上面的流程就够了。但如果打算把 OpenHands 当成日常编码代理长期用比如让它持续处理仓库里的 issue、自动重构、跑测试那模型调用的稳定性和成本就变成主要矛盾。这时候建议单独规划一下接入方式Coding Plan 这类面向长期编码和 Agent 场景的方案会更合适额度和调用策略都是按持续使用设计的Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenhands_docker另外几个实操经验把~/.openhands定期备份里面存着会话历史和设置沙箱容器会占磁盘跑久了用docker system prune清理无用镜像和容器如果 OpenHands 要访问私有仓库记得在沙箱里配好凭证别把 token 硬编码进提示词。Claude Code 这类命令行代理和 OpenHands 可以配合用前者适合终端里的快速改动后者适合需要浏览器和沙箱的复杂任务接入方式在文档里有说明。整套流程走下来核心就三件事Compose 把参数固化、TaoToken 提供稳定的模型接入点、远程访问解决随时随地可用。配置一次后面就是提需求等结果了。