如果你也是把 OpenHands 从源码跑起来、而不是光看网页 demo 的那批人那对几个词一定不陌生runtime、sandbox、agent harness。网上搜runtime这个词出来的报错五花八门有 WebView2 runtime 装不上的、有 OCI runtime create failed 的、有 MATLAB runtime installer 直接拒绝安装的。你可能会觉得这些跟 OpenHands 八竿子打不着但它们本质上都指向同一件事程序不是活在源码里的而是活在一个能跑起来的环境里。这个环境在 OpenHands 里被抽象成了一个独立模块就叫 Runtime。这一篇我打算把 OpenHands 的 Runtime 层彻底拆开来讲。它是整个 Agent 系统里最容易被忽略、但一挂就全线崩溃的部分也是你把 OpenHands 从“能跑 hello world”推向“能干活”的关键分水岭。我会从架构设计、核心模块、启动流程、报错排查、部署选型几个角度来讲尽量让看完这篇的人能自己动手搭一个稳定的 Runtime 环境而不是对着日志瞎猜。1. Runtime 到底在 OpenHands 里负责什么1.1 别把 Runtime 理解成“运行环境”四个字就完事很多人第一次接触这类系统会觉得 Runtime 就是“程序运行需要的依赖环境”类似 Python 的 venv、Node 的 node_modules装好就行了。但 OpenHands 里的 Runtime 远不止这层意思它是一个有状态的远程执行单元承载的是 Agent 在真实环境里的一切操作执行 Shell 命令、读写文件、启动服务、安装依赖、甚至打开浏览器操作页面。我举个生活化的例子。你把 ChatGPT 当成一个只会出主意的朋友OpenHands 则是一个不仅出主意、还会亲自动手帮你改稿的助理。但这个助理不能在你电脑里乱来你得给他一个独立的小办公室里面放好工具、锁好门他只能在办公室里干活。这个“办公室”就是 Runtime。所以 Runtime 在 OpenHands 里的职责可以拆成四块命令执行Agent 规划出要跑什么命令Runtime 负责让它真实发生并返回输出。文件读写Agent 要改代码、看日志、创建配置文件这些操作全都要落到真实文件系统。会话管理Runtime 不是一次性的它在整个 Agent 任务周期内保持存活保留工作目录、环境变量、临时状态。安全隔离Agent 是 AI不是编译器它可能执行任何命令必须有边界约束它不能碰宿主机敏感内容。理解了这个再看 OpenHands 的 Runtime 相关代码你的目光就不会只盯着“启动容器”那一段了而是会看它如何把一条命令从 Agent 侧传到隔离环境里、如何把文件从宿主机同步进去、如何保证状态不丢。1.2 一个 Agent 任务里 Runtime 的完整生命周期我在本地跑通 OpenHands 后第一件事就是看日志想搞清楚一次简单任务比如“帮我写一个斐波那契数列的 Python 脚本”背后Runtime 做了什么。整个生命周期大致是这样创建阶段用户提交任务OpenHands 后端会先请求一个 Runtime 实例。此时它会去拉取指定的镜像启动容器/沙箱并初始化连接通道。准备阶段Runtime 准备好后会注册自己的事件流接口告诉 OpenHands“我已经就绪可以接命令了”。同时会把工作目录初始化好通常是一个空目录或预置了项目代码的目录。执行阶段Agent 循环分析任务、生成动作Action比如执行python main.py这个动作经过事件流协议发送给 RuntimeRuntime 在沙箱里执行并把结果Observation传回去。交互阶段如果 Agent 需要读取文件内容或者修改文件同样通过 Runtime 的文件操作接口完成。这个阶段的微妙之处在于Agent 是“看一步走一步”的Runtime 返回得快不快、信息全不全直接决定 Agent 的表现质量。销毁阶段任务结束或超时Runtime 被销毁容器删除临时数据清除避免残留垃圾占用资源。如果你只是跑了一个单轮对话可能感受不到这个生命周期有多重要。但一旦跑一个多步骤的代码任务比如“克隆仓库、装依赖、跑测试、修 bug、再跑测试”你就会发现 Runtime 的稳定性比模型本身的聪明程度还关键。模型再聪明Runtime 半路崩了前面的工作全白费。2. 为什么 Runtime 要“容器化”架构选择的底层逻辑2.1 安全隔离是第一驱动力先讲一个很多人没想明白的问题为什么 OpenHands 不让 Agent 直接在宿主机上执行命令明明那样最简单连 Docker 都不用装。最直接的原因是安全。AI Agent 不是传统程序它的每一步行动都由大模型生成而大模型的输出天然存在不确定性。你让它“删除临时文件”它可能真的去执行rm -rf至于删的是哪个目录模型很可能理解错。如果完全没有隔离一次误操作就能让你电脑里的重要资料灰飞烟灭。容器化 Runtime 提供的隔离是操作系统级别的独立的文件系统、独立的进程空间、独立的网络命名空间。Agent 在容器里执行任何命令最多把容器搞崩宿主机毫发无损。我在实验里故意给过 Agent 一些危险的指令比如格式化磁盘、改系统权限容器隔离都能拦下来宿主机一点事没有。当然如果跑的是恶意代码容器隔离也不是万能的。容器共享宿主机内核存在逃逸的可能。但 OpenHands 这种场景防的是“误操作”和“模型幻觉”不是防黑客所以容器的隔离级别已经足够。真要跑不可信代码那就得用虚拟机级别的隔离了但代价是性能大打折扣。2.2 镜像即“工具链快照”可复现性才是生产力除了安全容器化的第二个好处是可复现性。这一点用一句话总结镜像就是工具链的快照。你想想看如果 Agent 直接跑在宿主机上那么每次任务的执行环境都跟宿主机当前的软件状态绑定。今天你电脑里装了 Python 3.11明天升级到 3.12Agent 跑出来的结果可能就不一样了。这种不确定性在调试 Agent 时非常折磨人你昨天还能跑通的任务今天莫名其妙挂在中途查了半天发现是环境变了。用 Docker 镜像后就不一样了。OpenHands 官方提供了一组预先构建好的镜像里面装好了 Python、Node.js、Jupyter、常用命令行工具等。每次任务启动时用同一个镜像创建 Runtime你就能保证这次运行的起始环境跟上次完全一致。这就像做饭用同一袋米、同一锅水哪怕换个厨师做出来的饭底子也是一样的。可复现性对开发调试的意义极大。我之前调试一个 Agent 任务发现问题只在特定版本的 numpy 下出现。因为用了固定镜像我可以快速复现问题、修好逻辑、再跑一次验证。如果没有镜像快照光是排查“为什么我这边能跑、你那边不能跑”就能耗掉半天。2.3 资源与权限边界别让 Agent 跑飞容器化的第三个作用是资源限制。大模型生成的动作有时候是很离谱的比如它会写一个while True死循环或者启动一个占用内存巨大的进程。如果没有任何资源限制宿主机可能直接被拖垮。OpenHands 的 Runtime 在创建容器时通常会配置资源限制参数包括内存上限、CPU 配额、磁盘大小等。这层限制的意义不只是防恶意代码更多是防“模型失控”。我在测试中遇到过一次 Agent 反复重试同一个失败命令几分钟内生成了几百条 Action如果没有资源限制和任务超时机制容器早就把服务器资源耗尽了。权限边界也是一个容易被忽略的点。容器默认以 root 用户运行但 OpenHands 在内部会尽量以非特权方式执行命令避免容器内操作直接映射到宿主机的特权操作。同时文件挂载也会控制范围宿主机只把需要暴露给 Agent 的目录挂载进去其它路径对 Agent 来说就是不可见的。这是一种“最小暴露”的设计思路防止 Agent 因为误操作读取或修改不该碰的文件。3. Runtime 核心模块拆解从镜像到执行3.1 DockerRuntime最常用的本地沙箱如果你在本地使用 OpenHands多数时候用的是 DockerRuntime。它的核心逻辑可以概括为三个动作拉镜像、起容器、维持连接。先看镜像。OpenHands 的镜像名通常长这样ghcr.io/all-hands-ai/runtime:版本号里面预置了 conda、python、node、jupyter、docker嵌套 docker 用等工具。这里要注意OpenHands 镜像的体积通常不小第一次运行需要拉取如果你的网络环境不好可能卡在镜像拉取这一步很久。我的做法是提前手动docker pull而不是等 OpenHands 运行时才拉省了很多等待时间。再看起容器。OpenHands 创建容器时会指定一系列参数典型参数包括镜像 tag决定底层工具链版本挂载目录把宿主机的项目代码挂载进容器环境变量比如WORKSPACE_MOUNT_PATH指定工作目录位置工作目录设置网络模式通常使用默认 bridge 网络资源限制包括内存、CPU如果你用 Docker 命令手动检查正在运行的容器会发现容器名通常带有随机后缀这说明每个任务有独立的 Runtime 实例。这是合理的任务间相互隔离不会出现“上一个任务的环境变量污染下一个任务”的问题。连接机制上OpenHands 在容器启动后会在容器内启动一个 agent runtime 服务宿主机通过 WebSocket 或 HTTP 与它通信。容器内外通过端口映射或内部网络互通。这个设计的核心思路是Agent 的动作Action和结果Observation都以结构化事件的形式在 Runtime 与后端之间传输而不是简单地开个 shell 往里塞字符串。我在刚开始研究 OpenHands 代码时曾经疑惑过为什么它不直接用 SSH 进容器执行命令。后来明白了SSH 适合人工登录操作但 Agent 需要的是细粒度的动作流控制——每条命令、每次文件读写都要能被记录、回放、追踪并且要支持并发、中断、恢复等复杂场景。用自定义的协议栈更灵活但代价是代码复杂度更高。3.2 SSH 形态的 Runtime远程机器接入当你把 OpenHands 跑在本地DockerRuntime 够用了。但如果你想把 Agent 部署到生产环境或者让 Agent 操作远程服务器就需要考虑 SSH Runtime。SSH Runtime 的本质是不在本地起容器而是连接一台已经配置好的远程机器在这台机器上执行命令、读写文件。它的好处是Agent 可以直接操作系统里的真实环境比如线上服务器、GPU 机器而不需要把所有工具链都塞进容器。但 SSH Runtime 对机器环境有要求远程机器需要装好 Python、以及 OpenHands 对应的 runtime 包还需要开放 SSH 端口、配好密钥。OpenHands 会通过 SSH 在远程机器上启动一个 runtime 服务然后建立通信隧道。这里有一个非常重要的实践经验生产环境不要用默认密码登录一定要配 SSH 密钥。原因很简单Runtime 服务会暴露操作接口如果 SSH 密码太弱被扫到就是灾难。另外远程机器的 Python 版本最好跟 OpenHands 官方要求的一致版本差太远runtime 包装不上或运行时报错排查起来非常痛苦。3.3 文件操作与编辑器不只是命令行Runtime 除了执行命令行还有一个容易被忽略但实际使用频率极高的能力文件操作。Agent 要修代码光靠sed和cat当然也能做但效率太低而且容易出错。OpenHands 的文件操作接口提供了一组更语义化的能力比如读取文件、写入文件、编辑文件片段、查看目录结构等。我实际跟踪过 Agent 修改代码的过程它通常不是一次性写完整个文件而是多次读取 - 定位 - 修改 - 校验的循环。这跟人类写代码的方式很像先看当前内容找到要改的地方做一个小改动再看一下结果是否符合预期。Runtime 需要支持这个循环里每一步的高频调用所以文件操作的响应速度和准确性直接影响 Agent 的最终效果。值得一提的是OpenHands 还支持在 Runtime 环境里启动一个 VS Code Server。启动后你可以用浏览器直接打开一个在线 IDE看到 Agent 正在操作的文件和代码甚至手动接管修改。这个能力在做“人机协同”场景时非常有用Agent 负责机械性的部分你负责审查关键逻辑。我在跑一些比较复杂的重构任务时就会刻意把 VS Code Server 打开边看 Agent 操作边做检查。一旦发现它走偏了我能立刻介入而不是等任务跑完再收拾烂摊子。3.4 事件流Runtime 与 Agent 的通信骨架Runtime 能正常运行背后离不开事件流协议。OpenHands 的事件流可以理解成一个双向通道Agent 产生的决策Action通过它发给 RuntimeRuntime 执行完的结果Observation通过它传回给 Agent。一条典型的 Action 可能包含如下信息动作类型执行命令、写入文件、读取文件、浏览网页等动作参数命令内容、目标路径、操作意图元数据时间戳、对应的事件 ID相应地Observation 会包含结果类型命令输出、文件内容、错误信息等结果状态成功、失败、超时内容分组stdout、stderr 分开返回方便 Agent 区分这个设计的精妙之处在于它把“执行”和“决策”解耦了。Agent 只负责生成动作不关心动作如何执行Runtime 只负责执行动作并返回结果不关心结果如何被理解。两侧各司其职中间的协议把两者稳定地连在一起。如果你要二次开发 OpenHands把自定义的动作类型加进事件流是比较核心的扩展点。比如你想让 Agent 能操作某个内部系统你可以定义一个新的 Action比如CallInternalAPI然后在 Runtime 侧实现对应的处理逻辑再在 Agent 的 prompt 或工具列表里注册这个工具。这样系统就能自动扩展能力而不需要改动底层架构。4. 常见 Runtime 报错与排查速查表这章是本文含金量比较高的一部分。我在折腾 OpenHands 的过程中以及后来给团队部署时遇到过的 Runtime 问题数都数不清。很多问题并不复杂但错误信息特别有迷惑性不熟悉的人容易绕远路。4.1 启动失败类镜像缺失、参数错误、OCI 错误先说你最可能在本地遇到的。第一次启动 OpenHands如果镜像没拉下来就急着跑任务会报类似docker: Error response from daemon: manifest unknown或者image not found的错误。这个很好排查手动执行docker pull ghcr.io/all-hands-ai/runtime:版本看能不能拉下来。比这个更吓人的是 OCI 相关的报错比如OCI runtime create failed: container_linux.go:348: starting container process caused process_linux.go:...这串让人头大的错误绝大多数情况下跟 OpenHands 本身没关系是 Docker 或底层容器的能力问题。常见原因包括宿主机内核版本太老、Docker 版本太低、或者 cgroup 配置有问题。我的排查步骤一般是先看 Docker 能不能正常跑起一个 hello-world 容器排除 Docker 本身的问题。检查内核和 Docker 版本太老就升级。查看 Docker daemon 日志那里往往有更详细的 error 上下文。如果是生产服务器还要检查是否配置了特殊的 security policy 或 SELinux 限制。有个朋友遇到过failed to create shim task: OCI runtime namespace ...类似的报错他花了很久才意识到是 Docker 和 containerd 的版本不匹配升级 containerd 后问题就没了。所以遇到 OCI 错误别急着怀疑 OpenHands先检查 Docker 底座。4.2 连接中断类会话超时、端口占用、状态不同步Runtime 启动后OpenHands 需要通过事件流与它保持长连接。如果长时间没有交互或者网络抖动连接可能断开。典型报错有connection refused、websocket: close 1006等。排查时先确认两件事容器是否还活着端口映射是否还在。如果容器被外部机制杀掉比如 OOM killer那报连接失败是正常的看容器退出状态码就能知道。如果容器活着但连不上很可能是 Runtime 服务进程崩了可以进容器看日志。连接类问题还有一种是“端口占用”。如果你同时跑多个 OpenHands 实例或者宿主机上已经有服务占了相同端口新容器起不来或连不上。我在本地跑多个并发任务时遇到过这种情况解决办法是用不同的端口映射段或者让 OpenHands 自动分配空闲端口。状态不同步也是一个容易踩的坑。比如任务中断后Runtime 容器还在但 OpenHands 后端以为它已经死了。这种情况下你再提交新任务可能会卡在“等待 Runtime 就绪”状态。最简单的处理方式是把残留容器全部清掉再重新启动 OpenHands 服务。# 查看所有 OpenHands 相关容器 docker ps -a | grep all-hands # 按需清理残留容器 docker rm -f container_id4.3 宿主环境类Docker 权限、资源不足、架构不匹配在 Linux 服务器上如果你以普通用户运行 OpenHands经常会遇到 Docker socket 权限不足的问题报错类似docker: permission denied while trying to connect to the Docker daemon socket解决办法是把用户加入 docker 组或者用 root 运行不推荐。加入 docker 组后记得重新登录会话组权限才生效。资源不足的情况更多。容器默认的内存限制如果太小Agent 跑大型编译任务时会直接 OOM。OpenHands 的官方镜像虽然内置了技术栈但保不齐你要装大型依赖比如编译 PyTorch、跑前端构建。我建议在创建 Runtime 时把内存限制调大一些或者干脆不设置内存上限但要在系统层面做好监控。还有架构不匹配的问题比如在 ARM 机器M 系列 Mac、树莓派上跑 x86 镜像。Docker 本身支持模拟执行但严重依赖宿主机是否开启 QEMU 兼容。如果你在 ARM 机器上启动 Runtime报exec format error大概率是镜像架构不匹配或者 host 缺少 binfmt 支持。解决方式是用 Apple Silicon 专用的镜像或者安装docker buildx 的 binfmt 自动注册。为了让你快速排查我把常见问题整理成一张速查表症状可能原因快速排查建议提示镜像不存在或 manifest unknown镜像 tag 写错或本地没有拉取手动docker pull 检查镜像 tag 是否正确OCI runtime create failedDocker/内核版本过老、cgroup 问题先跑 hello-world再升级 Docker 和相关驱动连接被拒 / WebSocket 断连容器挂掉 / Runtime 服务崩了 / 端口映射丢失检查容器状态和日志必要时重建容器Agent 任务执行到一半失联连接超时、后端与 Runtime 状态不一致清理残留容器重启 OpenHands 服务Docker permission denied用户不在 docker 组usermod -aG docker 用户名后重登容器启动后进程被杀内存不足触发 OOM调大容器资源限制检查宿主机内存占用exec format error / 架构不兼容ARM 与 x86 镜像混用换匹配的镜像或开启 QEMU 模拟4.4 对标网上常见 runtime 报错的一个提醒搜 runtime 相关热词时能看到大量跟 OpenHands 无关的报错比如webview2 runtime not found、MATLAB runtime installer、DirectX runtime之类。这些虽然跟 OpenHands 没有直接关系但它们指向一个共性认知runtime 缺失或版本不匹配是几乎所有软件项目最容易翻车的一环。你在用 OpenHands 时也一样别以为官方镜像“自带运行时”就啥都不管。如果你自己往镜像里装依赖、换基础镜像或者把 Runtime 安装在 HPC、K8s 这类复杂环境里你会遇到比本地 Docker 多得多的 runtime 问题。我遇到过一种情况在 Kubernetes 集群上跑 OpenHands Runtime因为底层 runtimeClass比如 gVisor、Kata Containers跟普通容器不同有些官方镜像里的二进制在 gVisor 下行为异常导致 Agent 执行命令时报奇奇怪怪的错。这种情况没有万能解法需要你理解 runtime 分层会看日志会对比宿主机环境差异。5. Runtime 部署形态与实践建议5.1 本地开发要快就本机 Docker如果你只是自己研究、写写小工具没有多人协作需求那本地 DockerRuntime 是最舒服的选择。它开箱即用跟 OpenHands 主服务的配合也最顺畅不需要额外配置。本地部署有几个细节值得注意。第一给 Docker 留足资源。OpenHands 跑稍微像样的任务镜像要占几个 GB 磁盘是正常的运行时的临时文件和日志也会占空间。别把/var/lib/docker放在一个几十 GB 的小分区上否则跑一个大项目就满了。第二如果你频繁改 OpenHands 源码或自定义镜像建议用docker compose起服务把镜像构建细节写进配置文件里。我自己维护了一个项目目录里面放着定制的 Dockerfile、环境变量文件和启动脚本这样即使哪天系统重装了也能快速恢复整个调试环境。5.2 团队服务化远程 Runtime 与队列当你要把 OpenHands 做成团队服务时问题就来了多个人同时用每个人的任务都创建一个本地容器宿主机资源很快就会撑爆。这个时候常见的方案是把 Runtime 做成独立的远程执行层跟主服务分开部署。架构上可以这样设计主服务跑在负载均衡后面管理 Agent 的决策逻辑Runtime 层部署在一台或多台高配机器上通过 SSH 或 Docker API 被动态调度。用户启动任务时主服务从 Runtime 池里分配一台机器、创建一个容器任务结束后回收容器并释放资源。这里容易忽略的是任务调度和并发控制。如果多个用户同时提交重型任务比如构建大型前端工程Runtime 层的 CPU、内存、磁盘 IO 都可能成为瓶颈。我在团队实践中的做法是给每个任务设置资源配额并且控制并发任务数量。超出配额的任务排队等待而不是无限创建容器。部署时还要特别注意网络和认证。Runtime 和主服务之间通信必须走加密通道GitHub 登录用户的数据是敏感的不能让 Runtime 接口裸奔在内网之外。我推荐的方案是尽量把 Runtime 层和主服务放在同一个私有网络里不对外暴露 Runtime 的任何端口。5.3 镜像瘦身与缓存策略DockerRuntime 要拉镜像镜像越大冷启动越慢。OpenHands 官方镜像功能齐全但体积也大。如果你只是做一些轻量任务可以自己构建一个精简镜像只装必要工具能显著加快启动速度。我自己的基础镜像大概长这样一个轻量 Linux 基础镜像装 Python 和 Node再装 curl、git、jq 这类常用工具总共不到 500MB。相比官方镜像的几个 GB冷启动快了很多。当然这样做的代价是你得自己维护依赖避免装完缺这个缺那个。缓存策略也值得花钱花时间研究。Docker 的 layer 缓存机制意味着Dockerfile 里写在前面的指令变更越少重建镜像时能复用的层越多。我的习惯是把“稳定的依赖安装”放在 Dockerfile 前几行“项目代码复制”放在最后几行这样每次改代码只需要重建最后几层速度和资源消耗都小很多。如果你用 K8s 或集群环境还可以配置镜像预热让 Runtime 镜像提前在所有节点拉好任务创建时直接秒起。我在一个集群环境里体验过预热和不预热的差别冷拉镜像时节点要等几十秒甚至几分钟预热后几乎无感。5.4 资源限制与监控Runtime 层是易失控的重灾区。大模型生成的代码或命令可能在不经意间耗尽所有资源所以资源限制和监控是一开始就要做的不要等问题爆了再补。资源限制层面至少三个参数要考虑CPU 上限、内存上限、磁盘配额。CPU 和内存可以限制容器磁盘配额则需要通过 Docker 的storage-opt参数控制容器可写的最大数据量。如果不设磁盘配额一个失控的 Agent 可能在短时间内写满磁盘把宿主机搞宕机。监控层面我会关注三组指标容器数量当前活跃的 Runtime 容器数量防止容器泄漏创建了但没被销毁。资源使用率CPU、内存、磁盘的实时占用及时感知有没有容器异常吃资源。启动失败率Runtime 创建失败的次数和原因提前发现镜像问题或宿主机异常。日志集中化也很重要。OpenHands 的容器日志默认散落在各自的 stdout 里容器一删日志就没了。我的做法是把容器日志重定向到统一目录再用一套简单的日志采集工具收集起来。这样排查问题时可以按任务 ID 回溯当时 Runtime 发生了什么而不是面对一堆死无对证的容器。One more thingRuntime 挂了不可怕可怕的是不知道怎么查文章写到这里核心内容基本讲完了。最后分享一点我的个人体会。我最初碰到 OpenHands Runtime 崩溃时习惯性地以为是代码 bug花了很多时间读源码、查 issue。后来发现绝大多数问题都出在“环境”而不是“代码”Docker 版本不匹配、镜像架构不对、磁盘满了、内存不够、权限不足、网络不通。这些问题的排查逻辑其实跟传统运维一模一样只不过包了一层 AI 的外衣。所以我想强调一点当你的 OpenHands 跑不起来先别急着怀疑 AI 能力不够先按传统思路检查 Runtime 层。把容器、网络、磁盘、权限、镜像这五样东西都过一遍大部分问题都水落石出。给自己定一个排查顺序能让你少走很多弯路。另外如果你用的版本比较新偶尔会遇到一些 issue 里还没有答案的问题。这时候我的建议是去看容器内部的 runtime 服务日志而不是只看 OpenHands 主服务的输出。Runtime 服务日志会记录它自己执行动作时遇到的具体错误这些信息往往比主服务日志更接近问题根源。Runtime 这一层说白了就是 Agent 的“手脚”。手脚本不聪明但能不能干活、干得稳不稳全看它。希望这篇拆解能让你对 OpenHands 的 Runtime 建起一个完整的认知地图下次遇到问题至少知道该从哪里下手。