AI Agent

2026 OpenHands 沙箱怎么部署,才能隔离 AI 编码任务与 macOS 主机?

OpenHands 沙箱部署的首选是官方支持的 Docker 沙箱,并且只挂载当前任务必需的项目目录;若任务必须调用 Xcode 等 macOS 原生工具链,则应把构建环境与 Agent 的文件权限分开规划。容器能降低 Agent 命令直接触及主机的风险,但不是绝对安全边界,Docker socket 和主机凭据也不应默认交给沙箱。

准备首次在 Mac 上运行 OpenHands 的开发者,可按下文核对安装与目录边界。
需要隔离多个代码库的工程团队,可据此拆分工作区、凭据和服务入口。
负责 macOS 原生应用构建的技术负责人,可参考文末的容器与原生构建分工。

第一步:先选执行后端,别把本机进程误当沙箱

OpenHands 的 V1 文档把执行任务的环境称为 sandbox,并列出 Docker、Process 和 Remote 等提供方:Docker 是本地推荐选项;Process 会把 Agent 作为普通进程运行在本机,不具备容器隔离;Remote 则把执行环境放在远端。官方沙箱模式说明执行改代码、跑测试,尤其要运行不可信仓库脚本时,应先选 Docker 沙箱,而不是让 Agent 直接在 macOS 主机进程中操作。官方 Docker 沙箱说明

OpenHands 文档中仍可能同时出现新旧术语与路径:V1 使用“sandbox”概念,部分配置仍沿用 RUNTIME;旧版 Docker Runtime 步骤则被标记为 V0。不要因为旧教程中出现了 SANDBOX_VOLUMES、旧镜像变量或 Docker 命令,就认定它们是所有当前部署的通用配置。先看对应版本的官方安装说明,再采用该版本支持的启动方式。当前本地安装说明;标注为 V0 的 Docker Runtime 文档

怎么选后端?

  • 若任务要修改代码、运行测试或处理不完全可信的仓库脚本,选官方支持的 Docker 沙箱。
  • 若任务确实需要直接操作 macOS 工具链或系统能力,不要因此改用没有容器隔离的本机 Process 后端;应把 Agent 执行与原生构建拆成独立环境。
  • 若任务不需要访问本机项目文件,优先考虑远端执行,避免为方便而把主机目录挂进去。

第二步:建立专用工作区,只开放任务所需路径

先把要处理的代码放进单独的项目工作目录,并确认里面没有与任务无关的文件,例如其他项目、个人文档、SSH 私钥或包含长期访问令牌的配置。需要让 Agent 修改代码时,只把这个目录作为可写工作区;参考文档、样例或只供读取的数据,另设路径并使用只读挂载。Docker 的绑定挂载默认允许写入,目录一旦挂入,容器内进程就可能创建、修改或删除其中的文件;ro / readonly 才会把对应挂载设为只读。Docker 绑定挂载与只读选项

OpenHands 沙箱能访问 Mac 上哪些文件?它能访问哪些主机文件,首先取决于部署实际授予了什么目录挂载,以及其他被明确开放的能力;“在容器里运行”并不等于能随意读取 Mac 全盘,也不等于挂入的目录不可触及。OpenHands 的 Docker 沙箱文档明确提醒:以读写方式挂到 /workspace 的内容可以被 Agent 修改。

需要限制为当前项目时,最稳妥的操作不是挂载整个用户目录后再要求 Agent 不要碰,而是从挂载源头缩小范围:先进入专用项目目录,再使用当前版本官方支持的工作区挂载方式;如果该版本提供 --mount-cwd,先确认当前工作目录确实是目标项目,再启动。检查挂载结果时,可用 docker inspect 核对容器的 Mounts 信息,确认源路径、容器内目标路径以及是否为只读。不要直接照搬不匹配版本的固定命令或镜像标签。

⚠️ 只读挂载也不是“不可见”:Agent 仍可能读取其中的内容,并将其带入任务输出或可访问的网络请求。敏感文件应从挂载范围中移除,而不是只依赖只读权限。

第三步:收紧 Docker socket 与 Web 服务入口

OpenHands 的控制端需要与 Docker 通信,才能按其部署方式创建或管理执行容器;官方安装示例包含 Docker socket。这里要区分控制端与Agent 沙箱容器:执行项目代码的容器不应仅因“沙箱需要 Docker”就直接获得管理宿主机 Docker 的 socket。Docker 官方文档提醒,能控制 Docker daemon 的用户具有很强的主机管理能力;将 socket 交给不可信进程,会显著扩大权限风险。Docker daemon socket 访问保护

OpenHands 容器为什么会用到 Docker socket?在 Docker 沙箱部署中,OpenHands 的控制端可能需要通过它调用 Docker 服务来管理运行容器;这是编排能力,不等于每个 Agent 任务都需要在沙箱内再运行 Docker。若任务不涉及容器构建或嵌套容器,不要把 socket 额外挂给 Agent 沙箱。若当前官方支持路径要求控制端使用 socket,应确认 socket 只交给受信任的控制组件,并评估控制端本身被攻破时的影响范围。

本地管理界面也要核对监听范围。Docker 未指定主机 IP 发布端口时,默认可能监听所有网络接口;只在本机访问时,应按所用部署方式将入口限制在回环地址,或通过受控的反向代理开放给授权网络,而不是把开发配置直接暴露到公网。Docker 端口发布与主机地址绑定说明

需要反向代理时,还要留意 OpenHands 沙箱自身服务端口的处理:官方 Docker 沙箱说明了随机主机端口、container_url_pattern 与 host-network 配置之间的关系;固定端口方案也有并发限制。不要为了让代理“先通起来”,就未经评估启用 host-network 或开放动态端口。

第四步:分开管理模型凭据、仓库凭据与目录权限

模型服务 API Key、代码仓库访问令牌和工作区写权限是不同的授权面,容器不会自动替你做好这三者的最小权限配置。部署文档要求在 OpenHands 设置中选择模型提供方并配置 API Key;团队应避免把个人长期凭据复制进仓库、项目 .env 文件或所有任务共用的启动配置。

处理私有仓库时,为具体任务准备独立凭据,限定到所需仓库和操作权限,并设置适当的过期时间;任务结束后撤销不再需要的令牌。GitHub 官方建议只授予任务所需的最小权限并设置有效期,也说明了令牌撤销方式。GitHub API 凭据安全建议;GitHub 令牌过期与撤销说明

还需单独判断 Agent 是否需要访问外部网络或 API:容器隔离主机文件系统,不会自动阻止任务向外发起请求,也不能消除用户主动提供的凭据被误用的可能。若任务只需本地改代码,应避免附带无关密钥;若确需调用外部服务,则把访问范围限定在任务需要的服务和资源。

第五步:用低风险任务验证部署链路

首次启动后,不要立刻把主力项目和长期凭据交给 Agent。先准备一个没有敏感数据的小型仓库,完成一次可回滚的简单任务,确认服务入口、执行后端、挂载路径和退出清理都符合预期。

逐项勾选:

  • ✅ OpenHands 管理界面只从计划中的本机或授权网络访问。
  • ✅ 当前执行后端确认为 Docker 沙箱,而不是本机 Process。
  • ✅ 容器只挂载本次任务所需的项目目录;参考资料如无写入需要,使用只读挂载。
  • ✅ 用 docker inspect 检查实际挂载源、目标路径和读写模式,与预期一致。
  • ✅ 任务输出及文件变更仅出现在计划中的工作区;检查容器列表,确认没有未计划创建的容器或额外 Docker 能力。
  • ✅ 停止或移除任务容器后,需要保留的改动已提交、备份或以其他方式保存。

这一步的目的在于验证部署路径和权限边界,而不是证明容器“绝对安全”。如果发现额外挂载、接口暴露范围不明或 socket 授权超出预期,应暂停使用真实项目和凭据,先修正启动配置。

第六步:任务结束后回收权限,并拆分原生构建

临时任务结束时,先保存经过审查的代码变更,再停止或清理不再使用的任务容器;之后撤销临时仓库令牌与外部 API 凭据,并检查是否有意外写入工作区以外的位置。不要把一次性测试环境留成默认信任环境,也不要因下次启动方便就长期保留不必要的目录挂载或访问权限。

如果 OpenHands 任务需要 Xcode,是否应直接在容器中构建?Docker 沙箱提供的是容器执行环境,并不等于提供 macOS 原生构建能力。需要 Xcode 或其他 macOS 原生工具链时,应把 Agent 的 Linux 容器执行与专用 macOS 构建环境分开:Agent 在限定工作区内生成并检查变更,再将变更交给授权的 macOS 执行环境完成构建和测试。Apple 的 App Sandbox 则是面向 macOS 应用及其授权能力的机制,不能与 Docker 容器边界混为一谈。Apple App Sandbox 官方说明

如果当前方案是在日常主力 Mac 上直接跑 Agent,主要代价是项目目录、日常凭据和开发环境容易共享权限边界;若改用容器,它又不能代替 Xcode 所需的 macOS 原生环境。需要临时进行原生构建或测试时,可评估租用 KuzCloud 的 Mac 环境,把构建任务与本地 Agent 工作区分开;这是一种环境分工,不是对 OpenHands 容器安全性的额外保证。选择前先核对适用地区与费用信息,并通过 KuzCloud 价格页面了解可选方案;若需要确认使用方式,可查看 KuzCloud 帮助说明。

把 AI 编码任务放到独立远程 Mac 上运行

KuzCloud 提供专属 Mac mini M4 物理节点,让你在远程主机上运行编码与构建任务,减少对本地 macOS 环境的影响。

SSH 与 VNC 远程接入,完整 root 权限,按需安装工具链并灵活配置工作环境。