Open Harness：基于Docker沙箱为AI编码代理打造安全自动化平台

1. 项目概述为AI编码代理打造一个隔离的“游乐场”如果你和我一样经常让Claude Code、Codex这类AI编码助手帮你写代码、调试项目那你肯定遇到过这样的烦恼这些AI工具虽然聪明但它们在执行命令、安装依赖、甚至修改系统文件时常常显得“肆无忌惮”。你永远不知道它下一次sudo rm -rf会删掉什么或者它安装的某个全局包会不会污染你的开发环境。更别提让它们自主运行定时任务了——那简直是把你的主机系统变成了一个充满未知变量的实验场。Open Harness项目就是为了解决这个核心痛点而生的。简单来说它是一个基于Docker的、预配置好的沙箱容器环境。你可以把它想象成一个专门为AI编码代理准备的、拥有完整权限的“游乐场”。在这个沙箱里AI可以自由地执行任何命令、运行后台进程、安装软件甚至操作Docker本身而所有这些操作都被严格限制在容器内部完全不会影响到你的宿主机系统。它不是一个简单的Docker容器而是一套完整的编排系统支持多工作树Git Worktree架构让多个AI代理可以并行工作各自拥有独立的工作空间、记忆和心跳任务同时共享底层的工具链和认证信息。这个项目特别适合那些希望将AI深度集成到日常开发、自动化运维或CI/CD流程中的开发者。无论是想搭建一个能自动巡检代码库健康状况的“AI哨兵”还是创建一个能自主处理GitHub Issue的“AI项目经理”Open Harness都提供了一个安全、可控且功能强大的基础平台。接下来我将带你深入拆解它的设计哲学、手把手完成部署并分享我在实际使用中积累的一系列实战技巧和避坑指南。2. 核心架构与设计哲学解析Open Harness的架构设计非常巧妙它没有采用为每个AI代理启动一个独立容器的“笨重”方式而是巧妙地利用了Git的工作树Worktree机制和单容器多进程模型在隔离性与资源效率之间找到了一个绝佳的平衡点。2.1 核心拓扑一容器多工作树一心跳守护进程整个系统的核心可以概括为“一个沙箱容器N个Git工作树一个心跳守护进程”。让我们来拆解这个设计沙箱容器这是唯一的运行时环境。它基于Debian bookworm-slim构建预装了从Node.js、Python到Docker CLI、GitHub CLI等一整套开发工具链以及Claude、Codex、Pi等AI代理的客户端。更重要的是它将宿主机的项目根目录通过bind mount的方式挂载到了容器内。这意味着容器内的所有操作包括AI写代码都直接作用于你主机上的文件修改是即时同步的你无需在容器和主机之间来回拷贝文件。Git工作树这是实现AI代理隔离与身份独立性的关键。每个AI代理比如一个专门处理前端Bug的Claude或一个负责后端API的Codex并不运行在独立的容器里而是“生活”在同一个容器内的不同Git工作树下。工作树是Git的一个功能它允许你在同一个仓库的不同分支上拥有独立的、互不干扰的工作目录。在Open Harness中每个工作树对应一个AI代理它拥有自己的workspace/目录里面存放着该代理的“灵魂”文件SOUL.md定义其性格、技能定义、记忆日志和具体的项目代码。这样每个代理都有了自己稳定的“家”和独立的活动范围。心跳守护进程这是一个运行在沙箱容器内的Node.js后台进程。它的职责是“监听”所有工作树下workspace/heartbeats/目录中的Markdown文件。这些文件定义了定时任务比如“每30分钟检查一次构建状态”。守护进程会解析这些文件的YAML前置元数据定义执行周期和使用的AI代理然后像系统的cron一样在指定的时间点以对应工作树为当前目录cwd启动相应的AI代理来执行任务。这样多个代理的定时任务可以由一个中心化的、轻量的守护进程来调度避免了为每个任务启动独立容器的开销。这种设计的精妙之处在于它实现了运行时环境与代理身份的分离。所有代理共享同一套昂贵的工具链和认证信息比如GitHub OAuth token、Claude的登录状态这避免了重复安装和配置。同时通过工作树机制每个代理又拥有完全独立的代码上下文、任务历史和“记忆”它们之间不会相互干扰。心跳守护进程则让这些代理具备了“自主运行”的能力实现了真正的自动化。2.2 身份文件系统赋予AI代理“人格”与“记忆”Open Harness为每个代理工作树预定义了一套核心的Markdown身份文件这是AI代理能进行有上下文、持续性工作的基石。理解这些文件的作用至关重要SOUL.md: 这是代理的“灵魂”或“性格设定”。它定义了代理的沟通语调、核心价值观、行为准则和防护栏。例如你可以设定它“以简洁、务实的方式沟通”、“优先考虑代码的可读性和性能”、“绝不修改package-lock.json以外的锁定文件”。Claude Code启动时会自动读取这个文件以此来塑造其行为模式。IDENTITY.md: 定义了代理的“社会身份”。包括它的名称如“前端守护者”、核心职责如“负责React组件库的维护与Issue处理”、技术栈偏好以及相关项目的URL链接。USER.md: 代表“你”即项目所有者。在这里你可以明确你的偏好、约束条件和最终目标。例如“我希望所有API响应时间优化到200ms以内”、“预算有限优先使用开源方案”。这是AI代理理解并服务于你个人需求的窗口。AGENTS.md/CLAUDE.md: 这是代理的“操作手册”。它包含了具体的决策规则、可调用的技能Skills列表、以及如何处理特定场景如遇到构建失败时是先回滚还是先查日志。CLAUDE.md通常是AGENTS.md的符号链接确保Claude能直接读到这些规则。MEMORY.md与memory/目录这是代理的“长期记忆”。MEMORY.md可能记录一些重要的经验教训或关键决策逻辑而memory/目录下按日期YYYY-MM-DD.md存放着日常的活动日志。AI代理在分析问题时可以回顾这些记忆实现有连续性的学习与改进。这套文件系统共同作用将一个通用的AI模型“塑造”成了一个专属于你、理解你项目、并拥有持续“记忆”和“个性”的专属编码伙伴。3. 从零开始完整部署与初始化实战理论讲完了我们动手把它跑起来。整个过程只需要Docker对宿主机的侵入性极低。3.1 环境准备与快速启动首先确保你的机器上已经安装了Docker和Docker Compose。这是唯一的前提依赖。# 1. 克隆项目仓库 git clone https://github.com/ryaneggz/open-harness.git cd open-harness # 2. 复制并配置环境变量文件 cp .devcontainer/.example.env .devcontainer/.env接下来编辑刚刚复制的.devcontainer/.env文件。虽然大部分配置可以先用默认值但我强烈建议你至少修改以下两项# 给你的沙箱起个独特的名字方便管理多个实例 SANDBOX_NAMEmy-ai-workshop # 如果启用SSH访问这是登录密码务必修改 SANDBOX_PASSWORDyour_secure_password_here注意SANDBOX_NAME会直接作为Docker容器的名称和Compose的项目名。如果你计划在同一台主机上运行多个Open Harness实例比如一个用于工作项目一个用于个人实验给它们起不同的名字是必须的否则会发生冲突。配置好后一键启动沙箱# 3. 构建并启动沙箱容器-d 表示后台运行 docker compose --env-file .devcontainer/.env -f .devcontainer/docker-compose.yml up -d --build这个命令会基于.devcontainer/Dockerfile构建一个包含了所有工具和AI客户端的镜像然后启动容器。第一次运行可能会花费几分钟时间下载基础镜像和安装软件包。3.2 多种方式连接沙箱容器启动后你有多种方式进入这个“游乐场”。方式A通过Docker命令进入最通用docker exec -it -u sandbox my-ai-workshop bash使用-u sandbox指定以sandbox用户身份进入这是容器内的主用户拥有sudo权限。方式B使用VS Code远程连接本地开发最佳体验这是我个人最推荐的方式它能获得近乎原生的开发体验。在VS Code中安装“Dev Containers”扩展。按下CmdShiftP(Mac) 或CtrlShiftP(Windows/Linux)打开命令面板。输入并选择“Remote-Containers: Attach to Running Container...”。从列表中选择你的沙箱容器如my-ai-workshop。 VS Code会打开一个新窗口并自动加载容器内的环境。你可以在里面直接使用集成终端、文件管理器和所有VS Code功能就像在本地一样。方式C通过SSH直连适用于远程服务器或多沙箱管理如果你将Open Harness部署在远程服务器上或者启用了sshd覆盖层可以通过SSH直接连接。首先确保在.env中设置了SANDBOX_PASSWORD并在.openharness/config.json中启用了docker-compose.sshd.yml覆盖层。在本地~/.ssh/config中添加配置Host my-remote-sandbox HostName your.server.ip.address Port 2222 # 默认映射的SSH端口 User sandbox连接ssh my-remote-sandbox然后输入密码。3.3 一次性初始化授权与认证首次进入沙箱后需要完成几个关键服务的认证这样AI代理才能代表你执行操作。# 1. 认证GitHub CLI这是很多操作如克隆私有库、创建PR的基础 gh auth login # 跟随提示选择浏览器登录或令牌方式。完成后运行 gh auth setup-git # 这会将Git认证配置为使用GitHub CLI的令牌无需管理SSH密钥。 # 2. 可选认证Pi Agent # Pi Agent是一个功能强大的自动化代理可用于Slack机器人、扩展等。 pi # 首次运行会引导你完成OAuth流程。实操心得gh auth setup-git这一步非常关键。它配置Git使用gh作为凭证助手意味着所有Git操作git push,git clone都会自动使用你通过gh auth login获得的令牌。这比配置SSH密钥更简单尤其是在容器环境中避免了密钥管理的问题。确保在完成gh auth login后立即运行它。完成这些步骤后你的沙箱就完全就绪了。可以尝试运行claude命令启动一个Claude Code交互会话或者运行pi来管理自动化任务。4. 核心功能深度配置与使用指南Open Harness的强大之处在于其高度的可配置性和丰富的功能模块。我们来深入几个核心部分。4.1 心跳任务让AI代理自主运行心跳是Open Harness自动化能力的核心。它允许你定义周期性的任务由AI代理自动执行。创建与管理心跳心跳任务以Markdown文件的形式存在于workspace/heartbeats/目录下。每个文件都需要一个YAML前置元数据块来定义调度规则。例如创建一个每小时检查依赖更新的任务# 在沙箱内使用内置技能需要AI代理会话 /heartbeat check for outdated npm dependencies every hour或者手动创建文件workspace/heartbeats/dependency-check.md--- schedule: 0 * * * * # 每小时的0分执行 agent: claude # 使用Claude执行 active: 9-18 # 只在工作日9点到18点执行 --- # 依赖健康检查 请检查当前项目package.json中的依赖使用npm outdated或pnpm outdated命令。 如果发现有可用的主要版本更新请在MEMORY.md中记录。 如果发现有安全漏洞可通过npm audit或第三方工具创建一个新的Issue并标记为security。文件保存后心跳守护进程会在几秒内自动检测到并开始按照计划执行。你可以在workspace/heartbeats/heartbeat.log中查看执行日志。高级调度技巧随机延迟为了避免所有任务在整点同时触发可以在cron表达式上增加随机延迟或者在前置元数据中注释说明让AI代理在任务开始时先sleep一个随机时间。依赖任务可以通过在心跳任务的提示词中让AI代理去读取另一个心跳任务的输出文件如memory/下的日志来模拟任务间的依赖关系。禁用与调试临时禁用某个心跳只需在其YAML块中用#注释掉schedule行。使用heartbeat-daemon status命令查看所有活跃的心跳任务及其下次执行时间。4.2 组合覆盖层按需扩展沙箱能力Open Harness通过Docker Compose覆盖层机制来提供模块化功能。你不需要修改基础的docker-compose.yml只需在.openharness/config.json中声明需要启用的覆盖层即可。{ composeOverrides: [ .devcontainer/docker-compose.postgres.yml, .devcontainer/docker-compose.sshd.yml, .devcontainer/docker-compose.slack.yml ] }常用覆盖层详解postgres: 为你启动一个PostgreSQL 16数据库容器并自动设置好DATABASE_URL等环境变量。数据持久化在独立的pgdata卷中。非常适合需要数据库的AI代理项目如数据分析、Web应用后端。sshd: 在容器内启动SSH服务器并将宿主机的~/.ssh目录以只读方式挂载。这是实现Git SSH认证最优雅的方式。你无需在容器内生成或复制密钥容器直接使用你宿主机已有的SSH密钥和配置~/.ssh/config,~/.ssh/known_hosts。只需在.env中设置HOST_SSH_DIR/home/yourname/.ssh请替换为你的实际路径该覆盖层会自动启用。slack: 集成Slack机器人。你需要提供SLACK_APP_TOKEN和SLACK_BOT_TOKEN。启动后一个名为“Mom”的Pi Agent机器人会在Slack中运行可以将消息转发给沙箱内的AI代理处理实现通过Slack与AI交互。cloudflared: 自动安装并配置Cloudflare Tunnel客户端和headless浏览器。这为AI代理提供了访问外部网络和服务的能力同时也能通过Tunnel将本地服务安全地暴露到公网。配置要点覆盖层的加载顺序通常不重要因为它们是合并到主配置中的。但是如果多个覆盖层修改了同一个服务如都修改了sandbox服务的volumes后加载的可能会覆盖前面的。这种情况较少见但如果你自定义了覆盖层需要注意一下。4.3 多沙箱管理与SSH网络当你需要在同一台主机比如一台开发服务器上运行多个独立的Open Harness实例时多沙箱SSH功能就派上用场了。场景你有一个“生产沙箱”用于处理正式项目的自动化一个“实验沙箱”用于测试新的AI工作流或技能。设置步骤为每个沙箱创建独立目录和配置# 假设在服务器上 mkdir -p ~/sandboxes/production ~/sandboxes/experiment cd ~/sandboxes/production git clone https://github.com/ryaneggz/open-harness.git . cp .devcontainer/.example.env .devcontainer/.env # 编辑.env设置 SANDBOX_NAMEproduction并为sshd分配端口如 - 2222:22 cd ~/sandboxes/experiment git clone https://github.com/ryaneggz/open-harness.git . cp .devcontainer/.example.env .devcontainer/.env # 编辑.env设置 SANDBOX_NAMEexperiment分配另一个端口如 - 2223:22关键是在每个沙箱的docker-compose.yml或通过覆盖层中为SSH服务映射不同的主机端口。配置本地SSH客户端 在你的笔记本电脑上编辑~/.ssh/configHost production-sandbox HostName your.server.ip Port 2222 User sandbox ForwardAgent yes Host experiment-sandbox HostName your.server.ip Port 2223 User sandbox ForwardAgent yesForwardAgent yes允许你将本地的SSH认证代理转发到沙箱内这样在沙箱里执行git命令时可以直接使用你笔记本电脑上的SSH密钥无需在服务器或容器内存储密钥。连接与互访# 从本地直接SSH进入生产沙箱 ssh production-sandbox # 在生产沙箱内部可以通过Docker网络访问实验沙箱 ssh -p 2223 sandboxhost.docker.internal这种模式开启了有趣的可能性一个沙箱内的AI代理可以SSH到另一个沙箱并指挥其工作实现简单的“AI代理编排”。5. 高级技巧、问题排查与实战心得经过一段时间的深度使用我积累了一些超出官方文档的实战经验和常见问题的解决方法。5.1 性能优化与资源管理镜像构建加速首次docker compose up --build可能会很慢因为要安装很多包。你可以考虑预先构建基础镜像并推送到私有仓库然后在.devcontainer/Dockerfile中FROM你自己的镜像。或者在Dockerfile中合理使用构建缓存将不常变的依赖安装如系统包放在前面将经常变的如项目代码放在后面。磁盘空间清理AI代理在运行中可能会下载很多npm包、Python包或Docker镜像。定期在沙箱内运行docker system prune -f和pnpm store prune或对应包管理器的清理命令可以回收空间。你也可以配置心跳任务让AI代理每周自动执行一次清理。内存与CPU限制如果宿主机资源紧张可以在docker-compose.yml中为sandbox服务添加资源限制services: sandbox: deploy: resources: limits: cpus: 2 memory: 4G5.2 常见问题与解决方案速查表问题现象可能原因解决方案docker compose up失败提示端口冲突端口已被占用如2222检查.env中的SANDBOX_NAME是否唯一或修改docker-compose.yml中ports映射的宿主机端口。进入容器后运行claude命令无反应或报错Claude Code客户端未正确认证或网络问题1. 确认容器能访问外网 (curl -I https://claude.ai)。2. 尝试重新认证rm -rf ~/.claude然后再次运行claude命令跟随引导登录。Git操作提示“Permission denied (publickey)”SSH认证未正确设置1. 确保启用了ssh或ssh-generate覆盖层。2. 如果使用ssh覆盖层检查.env中HOST_SSH_DIR路径是否正确且宿主机密钥权限为600。3. 尝试在容器内运行ssh -T gitgithub.com测试连接。心跳任务没有按计划执行心跳守护进程未运行或配置文件错误1. 进入容器运行heartbeat-daemon status查看状态。2. 检查workspace/heartbeats/下的.md文件YAML前置元数据格式是否正确schedule字段是否被注释。3. 查看日志tail -f workspace/heartbeats/heartbeat.log。VS Code 无法附加到容器Dev Containers 扩展问题或容器未运行1. 运行docker ps确认容器正在运行。2. 在VS Code命令面板执行“Remote-Containers: Rebuild and Reopen in Container”有时能解决元数据问题。AI代理修改了宿主机的文件可能性极低但需确认挂载点Open Harness通过bind mount将主机目录挂载到容器。AI的所有操作都在挂载点内。确保你克隆项目的路径不是系统关键路径。这是一种安全的设计但理解其原理很重要。5.3 安全最佳实践强化认证SANDBOX_PASSWORD是SSH登录密码务必设置为强密码。考虑使用SSH密钥认证替代密码认证需自定义sshd配置。最小权限原则虽然沙箱内用户有sudo权限但在编写AI代理的AGENTS.md规则或技能时应明确限制高风险操作。例如可以规定“禁止使用sudo安装来自未知源的软件包”。隔离网络对于生产环境考虑使用自定义的Docker网络并严格限制容器的外网访问权限。可以在docker-compose.yml中配置networks。定期审计利用心跳任务让AI代理定期检查workspace/下的文件变更或者扫描日志中是否有异常命令并将报告发送给你。备份身份文件SOUL.md,IDENTITY.md等文件是AI代理的“大脑”。定期将这些文件备份到Git仓库或其他安全位置。5.4 扩展思路将Open Harness集成到你的工作流Open Harness本身是一个平台你可以基于它构建更复杂的自动化工作流CI/CD流水线中的AI质检员在GitHub Actions或GitLab CI中在合并请求Merge Request构建成功后自动启动一个临时的Open Harness沙箱让AI代理对代码进行深度审查检查代码风格、潜在Bug、性能问题并将评论自动提交到PR中。自动化运维机器人创建一个专门的心跳任务让AI代理定期检查服务器日志、数据库性能指标、API健康状态发现问题时自动尝试修复如重启服务、清理缓存或至少生成一份清晰的告警报告。个人知识库助手配置一个AI代理其工作树指向你的个人笔记或知识库目录。通过心跳任务让它每天自动整理新笔记、生成摘要、建立索引甚至回答你关于知识库内容的提问通过Slack集成。多代理协作项目利用多工作树特性为项目的前端、后端、数据库分别创建专属的AI代理。通过编写一个“协调者”代理Orchestrator在workspace/根目录运行它可以根据Issue的类型将任务分配给对应技术栈的“专家”代理去处理并汇总结果。Open Harness的魅力在于它提供了一个安全、标准化的“操作界面”给AI。一旦你掌握了这个界面就能将AI的能力像乐高积木一样灵活地嵌入到你开发流程的各个环节中从被动的代码助手转变为主动的、可持续的自动化伙伴。