2026 OpenHands 自托管：本地 Mac 还是云端 Mac？

安装 OpenHands 成功了，但真实仓库既没有完成 Xcode 验收，后台任务还占住了你的开发机。

最快解法：低频个人试用先选本地 Mac；多人并发、持续在线、远程访问或需要隔离生产凭据时，优先选择独立云端 Mac。涉及 iOS、macOS 项目时，必须让 Agent 在可用的 macOS 与 Xcode 工具链中完成最终验证。

谁适合看这篇

如果你只是想低成本体验 OpenHands，并且能接受运行期间本机被 Docker 与后台任务占用，本地部署仍然值得先试。

如果你要为多人提供统一 Agent 环境，或需要让 OpenHands 长时间在线处理任务，这篇文章可以帮你判断何时应该迁移到云端 Mac。Apple 平台团队则需要重点关注 Xcode、模拟器、签名和物理设备验收。

先判断：你的问题是占机，还是验收链路缺失

典型失败不是“程序完全启动不了”，而是第一步看起来顺利，到了真实仓库才暴露问题：Agent 能修改 Swift 文件，却无法在当前环境运行 Xcode 构建；或者本地开发者合上 Mac、切换网络后，长时间任务中断，第二天只能重新确认状态。

OpenHands 官方推荐通过 Docker 沙箱运行 Agent Server，并允许把当前目录挂载到 /workspace。官方文档也明确说明，挂载为可写的目录可以被 Agent 修改，因此“能访问代码”与“安全地处理代码”不是同一个判断。你可以先阅读 OpenHands 官方本地部署说明，确认启动方式与工作区挂载行为。

在 macOS 上，本地安装通常是可行的，但“可以启动”不代表“适合长期运行”。官方本地部署文档给出的环境建议包括现代处理器和至少 4 GB 内存；GUI 服务默认在本机的 3000 端口提供访问，Docker 镜像和相关文件还需要大约 2 GB 磁盘空间。这些数字是启动门槛，不代表同时运行多个 Agent 或大型项目时的实际余量。(OpenHands 本地部署文档)

因此，本地方案适合以下条件：

• 你每次只处理一个项目或一个 Agent；
• 任务是低频交互，例如修改少量代码、生成测试、解释构建错误；
• 运行 OpenHands 时不需要同时使用这台 Mac 进行高强度编译、模拟器测试或视频工作；
• 你可以接受 Docker Desktop、网络和本机电源状态影响任务连续性。

如果任务需要持续在线，或者这台 Mac 同时承担日常开发、Xcode 编译和自动化流水线，本地部署的隐性成本就会快速上升。你付出的不只是计算资源，还包括被打断的开发节奏、端口冲突排查、Docker 状态维护和任务中断后的人工确认。

Docker Runtime 提供的是执行隔离，不是完整安全边界

OpenHands 的 Docker Runtime 主要解决三个问题：让 Agent 在独立运行环境中执行命令、让不同项目使用相对一致的依赖环境，以及减少未知代码直接触碰宿主系统的机会。其运行时采用客户端与容器内执行服务通信的架构，官方还提供运行时镜像标签、挂载卷和插件等配置。(OpenHands Runtime Architecture)

但你不能把 Docker 隔离理解为“Agent 永远碰不到宿主机”。至少要单独检查以下边界：

• 工作区挂载：rw 挂载允许 Agent 修改、删除或重命名宿主机映射目录中的文件；只读资料应使用 ro。
• Docker Socket：官方 Docker 启动示例会挂载 /var/run/docker.sock，这意味着部署者必须把它当作高权限控制面处理，而不是普通数据文件。
• 网络访问：容器中的 Agent 可能访问互联网，也可能使用你提供的 API Key、令牌或其他凭据。
• 监听地址：如果服务绑定到所有网络接口，局域网或公共网络中的其他设备可能看到管理界面；本地试用应优先限制到回环地址。
• 共享凭据：不要把生产 SSH 密钥、云平台令牌、签名证书或完整的钥匙串直接放进 Agent 可读目录。

Docker 官方指出，绑定挂载默认具备写入能力，容器进程可以通过挂载修改宿主机文件；因此 Docker 绑定挂载安全说明 应该和 OpenHands 的运行时架构一起阅读，而不是只看“沙箱”三个字。

在本地 Mac 上，错误配置的影响可能直接落到你的主开发目录、个人凭据和日常工作环境。独立云端 Mac 的价值不只是“远程运行”，更在于可以把 OpenHands、测试仓库和临时凭据放到单独的故障域中。它仍然需要网络、账号和权限管理，但不会因为一次实验性 Agent 任务就拖慢你的主力开发机。

⚠️ 经验提醒：先把仓库复制到临时工作区，再验证 Agent 的修改范围。确认挂载、网络和凭据策略后，才考虑让它接触长期维护的真实目录。

并发一上来，单机问题会从慢变成互相干扰

多个 OpenHands 任务同时运行，需要准备哪些隔离条件？

多个 Agent 并不只是把同一条命令执行多次。每个任务都可能需要独立工作区、依赖安装、临时端口、缓存目录和日志路径。如果多个任务共享同一个目录，最容易出现的是一个 Agent 修改了另一个 Agent 正在测试的文件；如果共享依赖缓存，升级或清理动作还可能改变其他任务的执行结果。

OpenHands 的运行时文档提到，运行时端口、VS Code 端口和应用端口需要分配，并通过锁机制寻找可用端口；这说明并发运行时端口管理本身就是部署变量，而不是可以完全忽略的细节。(OpenHands 运行时端口说明)

可以按下面的方式判断：

• 独立开发者：单个 Agent、低频任务，使用本地 Mac；每个任务用独立 Git 分支或临时副本。
• 共享小团队：两名或多名成员偶尔并行，使用本地专机，而不是占用某个人的日常开发机；统一镜像、统一日志和统一工作区规则。
• 自动化平台：任务持续进入队列，需要远程访问、失败重试或审计时，使用独立云端环境，并按任务分配隔离工作区。
• 涉及生产凭据：即使并发不高，也不建议把多个 Agent 放在个人日常 Mac 上；权限隔离应优先于启动便利性。

本地 Mac 的优势是缓存和调试路径短，依赖安装后再次运行通常更顺手。云端 Mac 的优势是能把任务环境固定下来，成员通过远程方式访问，不必把自己的笔记本变成共享执行节点。

Apple 工具链决定了最终验收地点

面对本地与云端部署，应该优先比较哪些条件？

如果项目只是修改 Swift 源码、生成单元测试或检查 API 调用，本地 Linux 容器或普通 Docker 环境可能足够完成一部分工作。但只要验收要求包括 Xcode 构建、iOS 模拟器、macOS App 打包、代码签名或连接真实设备，通用 Docker Runtime 就不能替代完整的 macOS 工具链。

Apple 文档明确区分了模拟器与物理设备：模拟器运行在 Mac 上，不能完全复现真实设备的性能和功能；签名、运行目标和开发配置也需要在 Xcode 及 Apple 的开发环境中完成。你可以通过 Apple 的 Xcode 系统要求 和 运行模拟器或物理设备的官方说明逐项确认版本与验收路径。

部署前至少做一次真实仓库验收：

1. 确认目标 Mac 的 macOS 版本满足当前 Xcode 要求；
2. 在 Xcode 中打开真实项目，而不是只运行一个最小示例；
3. 执行一次干净构建，记录 SDK、编译器和依赖解析结果；
4. 启动目标模拟器，运行关键流程和自动化测试；
5. 如果项目需要签名，验证证书、Provisioning Profile、Keychain 和权限；
6. 最后再让 OpenHands 执行修改、构建、测试和修复闭环。

对于 iOS 项目，Agent 可以在容器中完成代码分析和部分脚本工作，但最终的 xcodebuild、模拟器启动和签名验收应发生在可用的 macOS 节点上。对于 macOS 项目，也不能仅因为源码是 Swift，就默认所有构建流程都能在 Docker 中完成。

反复重建镜像，往往比首次安装更影响体验

OpenHands 支持使用自定义基础镜像，并通过运行时镜像标签区分版本、锁定依赖和源代码状态。环境变量中也提供了自定义 Agent Server 镜像、额外依赖和沙箱配置入口。(OpenHands 自定义运行时说明)

落地时建议按以下步骤操作：

1. 先固定 OpenHands 版本：试运行阶段可以跟随稳定版本，但团队验收应记录具体版本，避免自动拉取新镜像后行为变化。
2. 建立自定义基础镜像：把 Python、Node.js、系统工具和项目常用依赖写进 Dockerfile，不要每次任务启动后临时安装。
3. 区分代码挂载与依赖缓存：代码目录使用明确的工作区路径，缓存目录单独管理，避免清理代码时连缓存一起删除。
4. 控制挂载权限：默认只挂载任务所需目录；参考资料使用只读挂载，生产密钥不进入工作区。
5. 记录首次启动日志：保存镜像标签、依赖安装过程、端口分配和失败原因，以便判断问题来自 OpenHands、镜像还是项目本身。
6. 重复执行同一验收任务：至少让同一个仓库完成一次修改、构建、测试和回滚，确认环境不是“只成功一次”。
7. 再决定迁移方式：如果本地缓存明显降低重复安装时间，可以保留本地；如果团队更重视一致性和远程可用性，则把镜像与配置迁移到独立云端 Mac。

官方文档建议使用 openhands serve 启动 GUI，并可通过 --mount-cwd 挂载当前目录；CLI 安装要求 Python 3.12 或更高版本。这些是启动路径上的硬条件，但不等同于项目构建条件。(OpenHands 本地启动参数)

用评分和决策表确定部署位置

下面的评分不是性能测试，而是按维护责任、隔离需求和验收路径做出的决策提示。分数越高，越适合对应方案；如果某一项是硬条件，硬条件优先于总分。

具体选择可以直接套用：

• 满足低频、单人、非持续在线、可接受占用本机：选本地 Mac。
• 满足多人并发、远程访问、任务队列或生产凭据隔离中的任意两项：选独立云端 Mac。
• 既要通用代码 Agent，又要稳定完成 Xcode 验收：选择混合方案，让通用任务与 Apple 验收分离。
• 尚未确认云端节点是否满足 Xcode、模拟器和签名要求：先短周期试运行，不要先按理论规格长期采购。
• 长期稳定重负载且任务量可预测：可以评估自购 Mac；租赁更适合临时算力、验证环境和阶段性项目。

如果你要进一步核对远程连接方式，可以先看 SSHMac 的远程连接帮助；如果只是想短期验证 Mac 节点是否能完成真实仓库验收，可先了解 Mac mini 租赁方案，再根据实际任务结果决定是否固定环境。

5 步完成一次不自欺的试运行

为了避免“安装成功”被误判为“适合长期使用”，建议按下面的顺序验收：

1. 准备真实仓库副本：不要使用空项目，保留可以运行测试的分支和回滚点。
2. 限制权限与网络：只挂载必要目录，生产密钥改用临时凭据；确认服务监听范围和外部访问方式。
3. 执行低风险任务：先让 OpenHands 修改文档、补测试或修复一个可回滚的小 Bug。
4. 执行完整任务链：要求它完成代码修改、依赖安装、构建、测试、日志整理和结果说明。
5. 观察连续性：关闭本地终端、切换网络或让任务运行更长时间，检查任务是否仍可追踪；多人场景再增加第二个工作区，验证端口和依赖是否冲突。
6. 完成 Apple 验收：对于 iOS、macOS 项目，必须在目标 macOS 节点执行 Xcode 构建、模拟器测试和必要的签名步骤。
7. 记录人工介入点：统计哪些步骤仍需手工确认，哪些失败来自 Agent，哪些失败来自环境；这比只记录“任务是否成功”更能决定长期方案。

当前方案与 Mac 方案，差距在验收和责任边界

如果你现在把 OpenHands 放在日常开发机上，常见缺点是开发环境与 Agent 环境互相争用、任务离线后难以持续、挂载目录和生产凭据容易混在一起。若使用通用云主机，问题又可能变成没有完整 macOS、Xcode 和模拟器链路，代码能改却无法完成 Apple 平台验收。

因此，临时试用可以留在本地；当任务需要持续在线、多人并发或独立权限域时，租用 SSHMac 的云端 Mac 往往更容易把 Agent 执行、远程访问和 Apple 验收放进同一条可检查的流程。真正适合你的不是“规格看起来更大”的机器，而是能用一个真实仓库稳定跑完 OpenHands 任务、构建和验收的环境。

如果你准备开始验证，建议先用短周期节点跑完上述步骤，再根据并发量、在线要求和 Xcode 结果决定继续本地、固定云端，还是保留混合架构。