OpenHands 安装部署教程：用 Docker 在本地快速跑通开源 AI 编码助手

1. 为什么我建议你用 Docker 跑 OpenHandsOpenHands 是一个开源的 AI 编码助手前身叫 OpenDevin核心卖点不是陪你聊天而是让模型真的去改代码、跑命令、读文件、调接口。你可以把它理解成一个“能动手的编程搭子”你说需求它在沙箱里执行把过程摊开给你看。适合谁想自建 AI 编码助手、又不想被某个闭源 IDE 绑死的开发者想研究软件工程 Agent 执行链的工程师以及想给团队内网搭一套可控编码助手的同学。但这类项目有个通病第一眼像神器第二眼就掉进环境、权限、端口和 API Key 的坑里。我试过用 uv 直接起也试过 Docker最后发现对大多数 CSDN 读者来说Docker 单容器是最稳的复现路线——隔离干净、卸载方便、出错好回滚。这篇就按“能照着敲完”的标准来先起容器再打开 Web 界面然后把模型通道接到 TaoToken 的统一 Key/API 通道上最后用一个最小代码任务验证整条链路真的通了。需要提前说清楚一件事OpenHands 官方明确提醒它默认面向单用户本地工作站不带完整认证、隔离和扩展能力别裸奔到公网。本地体验没问题公网部署必须自己加反向代理和认证。这个边界先记住后面排错会省很多事。2. 前置准备Docker 环境与 TaoToken 通道在拉镜像之前先把地基打平。这一节不涉及 OpenHands 本身但跳过它后面 80% 的报错都会找上门。先确认 Docker 装好了docker --version docker ps如果docker ps报permission denied while trying to connect to the Docker daemon socket别急着重装大概率只是当前用户不在 docker 组sudo usermod -aG docker $USER newgrp docker docker ps接着建持久化目录OpenHands 会把配置和会话状态写进~/.openhandsmkdir -p ~/.openhands再确认 3000 端口没被占ss -lntp | grep 3000有输出就说明被占了要么停掉旧服务要么后面把映射改成 3001。然后是模型通道。OpenHands 启动后要在页面里选 Provider、填 API Key如果你用 OpenAI 兼容接口还得填 Base URL 和 Model ID。这里我建议直接走 TaoToken 的统一通道一个 Key 覆盖多家模型省得在页面里来回切 Provider。你需要准备三样东西Base URLhttps://taotoken.net/apiAPI Key在 TaoToken 控制台的 API Keys 页面生成Model ID按你实际要用的模型填比如claude-sonnet-4-5这类控制台入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite生成 Key 的页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite如果你还没决定用哪个模型可以先在模型对话页面试一下连通性确认 Key 有效再往下走https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite注意Base URL 填https://taotoken.net/api不要带末尾斜杠也不要在后面拼/v1具体以页面字段提示为准。填错这一项后面任务不执行基本就是它。3. 可复制配置docker run 与 compose 两种起法这一节是主线命令可以直接复制。先拉运行时镜像OpenHands 的沙箱执行依赖它docker pull docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik版本标签会随官方更新变化如果拉取失败先去官方 README 确认当前标签别死磕旧版本。3.1 单条 docker run 启动docker run -it --rm --pullalways \ -e SANDBOX_RUNTIME_CONTAINER_IMAGEdocker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik \ -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:0.54几个关键参数拆开说出问题时你就知道该查哪SANDBOX_RUNTIME_CONTAINER_IMAGE指定沙箱运行时镜像Agent 执行命令靠它。LOG_ALL_EVENTStrue打开完整事件日志排错时非常有用。-v /var/run/docker.sock:/var/run/docker.sock让容器内能调用宿主机 Docker这是能力来源也是风险点。-v ~/.openhands:/.openhands持久化配置和会话数据。-p 3000:3000Web GUI 端口映射。--add-host host.docker.internal:host-gateway方便容器访问宿主机网络。3.2 docker compose 版本如果你更习惯 compose把下面内容存成docker-compose.ymlservices: openhands: image: docker.all-hands.dev/all-hands-ai/openhands:0.54 container_name: openhands-app pull_policy: always environment: SANDBOX_RUNTIME_CONTAINER_IMAGE: docker.all-hands.dev/all-hands-ai/runtime:0.54-nikolaik LOG_ALL_EVENTS: true volumes: - /var/run/docker.sock:/var/run/docker.sock - ~/.openhands:/.openhands ports: - 3000:3000 extra_hosts: - host.docker.internal:host-gateway stdin_open: true tty: true然后docker compose up -d docker compose logs -f3.3 模型通道的配置片段OpenHands 的模型配置在首次进入 Web 页面时填写但如果你想把默认配置预置进~/.openhands可以准备一份 settings 片段。路径和字段名以你当前版本页面为准下面这份是 OpenAI 兼容通道的通用结构{ llm: { provider: openai, base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: claude-sonnet-4-5 } }注意三件套必须同时正确——Base URL、Key、Model ID。少一个或者写错一个页面能打开但任务不执行。如果你用的是 Claude Code 类接入Base URL 同样填https://taotoken.net/apiKey 用同一个Model ID 换成对应模型即可。4. 验证请求从页面打开到任务跑通容器起来不等于跑通这一节做三层验证一层比一层深。第一层看容器活着没docker ps正常应该看到openhands-app在运行端口映射是0.0.0.0:3000-3000/tcp。看不到就说明容器压根没起来回去看日志。第二层看日志有没有硬伤docker logs -f openhands-app重点扫这几类信息服务是否正常监听、有没有模型配置报错、有没有 Docker Socket 访问异常。如果日志一直刷错误页面就算能打开也只是个壳子。第三层浏览器访问http://localhost:3000远程服务器部署的话把localhost换成服务器 IP同时确认安全组和防火墙放行了 3000。页面打开后第一次会让你选 Provider、填 Key。走 TaoToken 通道的话Provider 选 OpenAI 兼容Base URL 填https://taotoken.net/apiKey 填你生成的Model ID 填实际模型名。保存后输入一个最小任务验证请帮我创建一个 Python Hello World 示例并说明如何运行。链路正常的话你会看到页面里出现步骤性输出Agent 开始执行、生成文件、可能展示命令执行过程最后返回结果。如果页面能开但任务一动不动基本就是模型通道没打通回去检查三件套。想单独验证 Key 和模型是否可用可以先用模型对话页面发一条消息确认返回正常再回 OpenHands 配置https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite5. 本篇常见报错排查这一节按真实报错来遇到哪个查哪个。报错一permission denied while trying to connect to the Docker daemon socket当前用户没权限访问 Docker 守护进程。执行sudo usermod -aG docker $USER newgrp docker docker ps还不行就确认 Docker 服务本身在跑sudo systemctl status docker sudo systemctl start docker报错二bind: address already in use3000 端口被占。先找占用进程ss -lntp | grep 3000不想停旧服务就把映射改成 3001-p 3001:3000然后访问http://localhost:3001。报错三页面能打开任务不执行这是最高频的一类几乎都出在模型通道Key 填错、Provider 选错、Base URL 写错、Model ID 不存在、或者模型服务本身不可用。按顺序查Provider 和 Key 是否匹配、Key 是否有效、Base URL 是否是https://taotoken.net/api、Model ID 是否存在、页面报错和容器日志有没有线索。别一遇到就重装容器重装治不好错误的 Key。报错四容器反复退出或启动秒退先看日志docker logs openhands-app因为--rm会让退出后的容器消失建议先去掉--rm再重启观察。同时检查~/.openhands目录权限、镜像是否拉全ls -al ~/.openhands docker images | grep openhands docker images | grep runtime报错五拉取镜像失败或超时网络环境问题最常见。切换网络、配置 Docker 镜像加速、稍后重试并确认镜像地址和标签与官方 README 一致。官方版本号更新了就换新标签别死磕旧的。报错六Docker Socket 相关异常确认启动参数里有-v /var/run/docker.sock:/var/run/docker.sock再检查宿主机上文件是否存在ls -l /var/run/docker.sock宿主机 Docker 没启动的话挂进去也没意义。报错七OAuth 或认证相关提示如果你在页面里选了需要 OAuth 的 Provider但走的是统一 Key 通道就会卡在认证环节。这种情况直接切回 OpenAI 兼容模式用 Base URL Key Model ID 三件套不要走 OAuth 流程。6. 跑通之后把通道固定下来到这里你已经完成了 OpenHands 的一条最小闭环Docker 起容器、打开 Web GUI、配置模型通道、跑通第一个代码任务、用容器状态和日志验证部署。接下来最值得做的一件事是把模型通道固定成一套可复用的配置而不是每次重装都重新填。如果你打算长期用 OpenHands 做编码任务建议直接上 Coding Plan把 Key 和额度统一管理省得每次换模型都重新配https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档在这里字段名和路径以文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteAPI Keys 管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite一个实用技巧把~/.openhands目录定期备份换机器时直接拷过去配置和会话都能带走。另一个坑是别把docker.sock挂载到公网可访问的容器里本地玩没问题公网部署一定要加反向代理和认证。最后模型通道的三件套建议写进一个自己的备忘文件下次重装直接复制比在页面里凭记忆填靠谱得多。