1. 为什么我要把 OpenHands 关进 Docker 沙箱里折腾OpenHands原 OpenDevin是一个能自己动手的 AI 程序员它不只是聊天而是能在终端里敲命令、写文件、跑测试、看报错、再改代码直到任务闭环。适合谁适合想跑通“全自主编码 Agent”工作流的运维、后端和平台工程同学尤其是已经受够了“只会说不会做”的对话式助手的人。我这次的目标很明确在一台干净的 Ubuntu 机器上用 Docker 把 OpenHands 拉起来接上统一的模型 Key然后下发一个真实任务看它能不能自己装依赖、写脚本、踩报错、自我纠错最后把结果落盘。整个过程我会把可复制的启动配置、settings.json 骨架、验证请求和常见报错都摊开讲你照着做就能复现。先说清楚它的安全边界这是运维最该关心的OpenHands 的 Agent 循环跑在 Docker 沙盒容器里pip install、npm install、执行脚本、改文件全在沙盒内完成不会直接污染宿主机文件系统。但要注意沙盒防的是本地进程和文件防不住它拿着你给的云端凭证去调外部 API。所以凭证怎么给、给多大权限是后面必须单独设计的一环本文先把链路跑通权限收口放在配置章节讲。2. TaoToken 前置一个 Key 打通模型调用OpenHands 的大脑是 LLM默认要填 OpenAI 兼容的 API Key。我这边用 TaoToken 做统一入口好处是一个 Key 就能切换不同模型不用在多个平台之间来回倒腾配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你需要先拿到 Key再去 OpenHands 的设置里填。拿 Key 的入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。填的时候注意两点Base URL 要带/api模型名要和你账号里可用的模型对齐别照抄别人的模型 ID。如果你只是想先验证模型通不通不想一上来就配 OpenHands可以先用模型对话页面发一条消息试试水https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。确认 Key 有效之后再回到 OpenHands 里配能省掉一半排障时间。注意Key 属于敏感凭证别写进会提交到 Git 的文件里。OpenHands 的配置我建议用环境变量注入或者放在宿主机上不纳入版本管理的 settings 文件里。3. 可复制配置Docker 启动 settings.json 骨架3.1 准备工作空间先在宿主机上建一个和 AI 共享的目录所有它产出的文件都会落在这里方便你事后检查export WORKSPACE_BASE$(pwd)/openhands-workspace mkdir -p $WORKSPACE_BASE这个目录会挂进沙盒Agent 在里面创建、修改的文件你在宿主机上都能看到出问题也好回滚。3.2 拉起 OpenHands 主容器OpenHands 需要在容器里再控制沙盒容器所以要把宿主机的 Docker Socket 挂进去。这条命令是核心参数我逐行标注docker run -it --rm --pullalways \ -e SANDBOX_USER_ID$(id -u) \ -e WORKSPACE_MOUNT_PATH$WORKSPACE_BASE \ -v $WORKSPACE_BASE:/opt/workspace_base \ -v /var/run/docker.sock:/var/run/docker.sock \ -p 3000:3000 \ --name openhands-app \ ghcr.io/all-hands-ai/openhands:mainSANDBOX_USER_ID保证沙盒里生成的文件属主和宿主机当前用户一致不然你会遇到权限报错。WORKSPACE_MOUNT_PATH告诉应用宿主机上的工作目录在哪。-p 3000:3000是 Web 界面端口起来后浏览器访问http://你的机器IP:3000就能进。3.3 settings.json 骨架OpenHands 的模型配置可以走界面填也可以落到 settings 文件里。下面是一个接入 TaoToken 的骨架字段按你实际账号调整{ llm: { model: 你的模型ID, api_key: 你的TaoToken Key, base_url: https://taotoken.net/api, temperature: 0.2 }, agent: { confirmation_mode: true, sandbox: { use_host_network: false } }, workspace: { mount_path: /opt/workspace_base } }confirmation_mode我强烈建议先开着Agent 执行危险命令前会弹窗等你确认等链路跑顺了再考虑关。temperature调低一点写代码和跑命令的场景不需要太发散。3.4 权限收口的思路跑通之后你一定会想给它云凭证去干真活。这里的原则是别把长期高权限 Key 直接塞进沙盒。用临时凭证、按标签限定资源范围、对生产资源显式拒绝让底层 API 在权限层兜底。沙盒防本地IAM 防云端两层缺一不可。具体策略按你所在云平台的权限模型来配核心是“最小权限 显式拒绝生产资源”。4. 验证请求下发一个真实任务看它闭环环境起来后进 Web 界面在对话框里下一个具体任务。我用的测试任务是写一个 Python 脚本把某张表的数据导成 CSV 并上传到对象存储。这个任务有依赖安装、有网络调用、有报错可能正好能看出 Agent 的自我纠错能力。第一幕它没有直接写代码而是先打开沙盒终端装依赖pip install boto3 pymysql第二幕它在工作目录里创建脚本文件写完直接跑python export_db_to_s3.py第三幕是关键。第一次跑必然报连接错误因为脚本里没有真实端点。它会抓到报错分析后回复你连接了 localhost但缺少真实端点和凭证请提供环境变量或让我用os.environ.get()读取。这一步说明它具备排查和推理能力不是无脑重试。第四幕你把测试用的只读凭证以环境变量形式注入它改完配置再跑终端输出上传成功你去对象存储后台确认文件确实在了。整个闭环跑通说明 Agent 循环、沙盒执行、模型调用三部分都正常。如果你在这一步想先单独验证模型返回是否正常可以回到模型对话页面发一条测试消息https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。模型通了但 OpenHands 报错问题就基本锁定在配置或沙盒而不是 Key。5. 本篇常见错排查5.1 容器起来但界面打不开先确认端口映射和防火墙。docker ps看容器状态curl http://localhost:3000在宿主机上试。如果是云主机安全组要放行 3000 端口。别用--network host图省事端口冲突会更难查。5.2 沙盒文件权限报错多半是SANDBOX_USER_ID没设或设错。宿主机上id -u看当前用户 ID确保和启动参数一致。工作目录的属主也要对chown一下再重启容器。5.3 模型调用 401 或 404401 一般是 Key 无效或没带对404 多半是 Base URL 写错。确认base_url是https://taotoken.net/api别漏了/api也别多加路径。模型 ID 要和账号里可用的对齐写错了会返回模型不存在。5.4 Agent 卡在装依赖不动沙盒容器拉取镜像或装包慢先看网络。如果公司网络有限制给 Docker 配好镜像加速。另外确认宿主机磁盘够用沙盒镜像不小。5.5 危险命令没弹确认检查confirmation_mode是否为 true以及你用的 Agent 类型是否支持确认模式。有些配置下确认会被跳过跑生产相关任务前务必确认这个开关生效。排障时如果怀疑是接入配置问题可以对照接入文档再核一遍参数https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里的字段说明比界面提示更全。6. 长期跑编码任务把 Key 和额度管起来如果你只是偶尔试一下上面这套就够了。但如果你打算让 OpenHands 长期跑编码任务比如接进日常开发流、让它处理重复的脚本活那模型调用会变成持续消耗。这时候建议用 Coding Plan 把额度和模型统一管起来避免每次都要临时配 Keyhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。我自己的做法是测试阶段用按量 Key 验证链路确认稳定后切到 Coding Plan 跑长期任务Key 统一在控制台管理换模型不用改 OpenHands 的配置。这样 Agent 的“大脑”和“手脚”解耦后面想换更强的模型或者加新的沙盒都不用动底层。最后留一个我踩过的坑别在沙盒里挂载宿主机的敏感目录尤其是带凭证的配置目录。工作空间只放任务需要的文件凭证走环境变量注入用完即弃。Agent 再聪明也不该看到它不需要看的东西。