本页内容
本页内容
代理工作区
受管 worktree
托管工作树为代理任务提供了自己的 git 分支和签出,而无需在源存储库中放置临时目录。 OpenClaw 将它们记录在共享状态数据库中,并在普通删除之前对其跟踪和非忽略的未跟踪内容进行快照。 容量驱逐可以在无法制作快照时清除未保存的数据。
当新的聊天启动托管工作树时,OpenClaw 可以在结帐完成时开始第一个模型轮转。它首先从最终工作树目录中选定的 Git 提交中准备项目说明、工作区技能和其他提示文件。因此,初始提示使用与已完成结帐相同的路径和内容。工作区工具(包括 PDF 分析、本地消息附件和读取本地引用的生成工具)等待签出和会话的初始差异基线。不使用工作区的工具可以立即运行,包括使用内联或远程引用进行生成。完成也会等待准备,准备失败会导致回合结束并出现可重试错误。
具有安装脚本、包含文件、不受支持的签出转换或需要其他文件的项目配置的存储库在第一轮开始之前完成准备。主动引导挂钩(包括 bootstrap-extra-files)也保留完整的准备工作,因此配置的指令仍然可用。沙盒投影在启动前需要完整发布的工作树,所需的远程工作人员放置也是如此。没有本机工具挂钩准入的 Codex 配置以及在构建工具时读取工作区文件的插件在开始模型转换之前等待准备工作。明确请求的工作树名称或现有会话标题可以命名结帐。否则,分配会选择一个简短的生成名称,同时显示标题生成在后台运行。
拉取请求统计信息可能会刷新托管结账中 Git 的缓存文件时间戳;他们不暂存内容或更改提交。用户管理的结帐统计数据保持其索引不变。
设备上的现有文件夹
设备上的现有文件夹 与托管工作树分开。兼容的配对会话主机可以直接在该特定设备上的绝对文件夹中运行会话。 OpenClaw 不会将该文件夹作为托管工作树进行克隆、快照、传输、协调或删除。当您需要独立的 OpenClaw- 托管工作区时,请选择 新工作区 或存储库源。请参阅 会话托管 。
沙盒会话
沙盒项目会话使用私有 Git 签出来执行,而托管工作树仍然是已接受更改的事实来源。 Docker 和 Podman 支持此本地投影。主机存储库的共享 Git 元数据和忽略文件配置不会安装或复制到其中。在 Btrfs、APFS 和 ReFS 上,具有已提交 pnpm-lock.yaml 的新私有签出可以重用已安装的依赖项。 OpenClaw 在一次性沙箱中准备一次依赖项,然后为每个会话克隆准备好的签出。网关准备就绪后,它会在后台使用沙箱模式 all 或 non-main 为代理存储库准备默认会话库。沙箱模式代理off跳过后台依赖准备;创建者角色所需的沙箱仍会在首次使用时准备依赖项。准备期间到达的会话等待相同的构建;稍后结账时会显示 node_modules。其他选定的提交仍在首次使用时准备其依赖项。关闭会取消准备并等待一次性安装程序被删除。私有结帐存储必须支持文件系统加速,并且 worktreeAcceleration: false 也禁用此准备。
依赖项准备使用选定的沙箱映像、网络限制和来宾工作目录,无需配置凭据、自定义绑定挂载或设置命令。 Git 元数据在安装期间保持只读状态。无论 Git 忽略拼写如何,仅保留 node_modules 目录作为附加输出;生成的本机协议文件和其他设置工件不共享。作为此准备工作的一部分,存储库代码永远不会在主机上运行。非沙盒存储库设置的现有权限要求保持不变。对于 network: "none",pnpm 使用离线模式,因此丢失的包或元数据缓存会立即回退,而不是通过网络重试等待。
可重用生成绑定源提交、冻结锁定文件、不可变映像(包括其 Node 和 pnpm 版本)、来宾路径和沙箱策略。改变的一代准备了新的模板;现有的 7 天模板清理也会让中断的构建器退出。安装失败或更改的跟踪源会记录警告并保留该代的仅源模板。缺少锁定文件、不受支持的文件系统和不可用的映像使用仅源签出。该代理可以在该私人结账处正常安装。当锁定文件更改时,依赖项准备不会更新已使用的会话。 pnpm 虚拟商店位于 node_modules 之外的布局也使用仅源后备,保留其普通安装合同。
有关写入策略、协调和冲突恢复的信息,请参阅 工作空间访问。
投影绑定和挂起的调节日记帐处于附加 SQLite 状态。他们不会更改数据库版本。在降级之前,先解决待处理的工作区操作。旧版本不符合这些预测;他们完好无损地保留了附加的国家和私人文件。返回支持版本以恢复挂起的更改,而不是删除投影目录。
选择工作树的存储位置
默认情况下,OpenClaw 将托管结账存储在 <openclaw-state-dir>/worktrees 下。在 openclaw.json 中设置全局 worktreeRoot 选项以使用其他文件夹或磁盘:
使用网关主机上的绝对路径,~ 作为网关用户的主目录,或以 ~/ 开头的路径作为其中的文件夹。相对路径被拒绝。网关用户必须能够创建和写入该目录。
此设置适用于所有托管工作树,包括会话、手动和工作板工作树;没有每个代理的覆盖。它仅更改结帐存储。共享状态数据库、已配置的忽略文件的快照、分配限制和清理生命周期仍与同一 OpenClaw 状态目录关联。
更改 worktreeRoot 会影响新的分配。现有注册的工作树保留其记录的路径以供重用和清理,而删除的工作树则恢复到其原始路径。当此设置更改时,OpenClaw 不会移动现有结账或快照。保持其原始存储可用,直到不再需要这些工作树为止。
在默认的国有工作树目录之外,清理仅作用于已注册的工作树和加速模板。它将不相关的、未注册的文件夹单独留在您的自定义位置。
有关该选项的默认值和范围,请参阅 配置参考。
容量和驱逐
worktreeMaxCount 为共享状态目录的所有代理、存储库和所有者之间的实时管理工作树和挂起创建设置了一项限制。默认为 4096。没有单独的每个代理或每个存储库的计数上限。要允许在更大的磁盘上进行更多签出,请在 openclaw.json 中增加它:
策略是:首先是 squashed/merged,然后按年龄(包括未保存的数据)。清理更喜欢将分支合并到存储库的默认分支中,然后检测为挤压着陆的分支,然后按上次使用从最旧到最新的顺序检出空闲检出。手动工作树、移动的分支、嵌套存储库和不可读的内容并不免除托管签出的上限。如果可能,OpenClaw 在清除结帐之前对脏内容进行快照,但快照失败不会阻止上限驱逐。提交或以其他方式备份您需要保留的工作。
创建在准备文件之前保留一个持久槽。姓名和所有者检查在该预订时进行;然后实现、忽略文件配置和设置独立于其他创建运行。发布以原子方式用实时记录替换挂起的槽。对同一所有者的并发请求等待并重用其已完成的结账。当容量接纳的槽阻止接纳时,容量接纳会等待正在进行的创建;等待结账的人永远不会被驱逐。
存储库支持的创建在等待容量接纳之前发现非托管的 Git 分支和签出路径。预留仍会检查分配租约下当前的托管名称、所有者和待处理插槽。 Git 在创建签出时强制执行分支和路径冲突,包括发现后的外部更改。每次准入重试都会刷新其 Git 库存。
源托管在每次操作时检查一次托管结帐和 Git 存储所有权。目标保护在保留插槽的同时重用该清单,因此普通存储库创建不会重新扫描分配租约下的每个托管存储库。库存随作业结束;在删除签出之前,清理仍然会检查实时依赖关系。
失败的创建在确认清理后会释放其插槽。如果调用者崩溃或本机操作具有不确定的结果,则在证明调用者已死亡后,下一个分配或 openclaw worktrees gc 会回收计数容量。它保留未完成的结帐及其名称并报告其路径。在手动恢复这些文件之前检查 Git 注册和任何幸存的本机进程; cleanup 并不假设父进程死亡停止了本机写入。恢复托管不会将不完整的签出发布为就绪,也不会阻止使用未使用的名称进行新的签出。 Creation 在准入重试和租用等待期间共享一个 30 分钟的争用预算。成功的结帐、配置、设置和发布不会消耗该预算;等待预算用完后,仍然可以获得可用的租约。进一步的争用会报告检查和清理命令,而不是开始另一次等待。现有记录不需要架构迁移。在降级到不理解这些保留的版本之前,先解决挂起的操作。
有效的业主租赁可以保护活跃的运行。如果创建需要驱逐活动运行,则 OpenClaw 会拒绝它并指定上限和活动所有者。让这些运行完成或提高 worktreeMaxCount,然后重试。后台清理和创建准入共享相同的容量所有者,包括并发创建和快照恢复。删除的签出及其保留的快照不再占用实时工作树槽。
驱逐会保留其他托管签出所需的源存储库和 Git 存储,包括通过 git clone --shared 借用的对象。创建和快照恢复也保留源托管,因此释放它们的槽不能清除它们需要的对象捐赠者。
降低设置会将逐出策略应用于现有结账。磁盘空间检查仍然独立应用:增加计数不会绕过测量的分配和快照保留。参见 worktreeMaxCount。
文件系统加速
OpenClaw 在受支持时自动对新的托管工作树使用文件系统加速。 Linux 使用本机 Btrfs 快照,无需 btrfs 命令。 macOS 使用本机 APFS 目录克隆,保留独立的文件内容、可执行模式和符号链接。 Windows 使用 ReFS 块克隆,包括在开发驱动器卷上。 OpenClaw 将模板保留在与新签出相同的可写文件系统上;源存储库可以位于另一个文件系统上。目标或模板中的有效签出过滤器、稀疏签出或外部属性使用正常的 Git 签出。启用 Git 的 extensions.worktreeConfig 或在另一个工作树中配置稀疏签出不会禁用完整签出的加速。模板重用包括有效的每个工作树配置,因此更改模板的签出设置会使其失效。
要选择退出,请设置:
省略该选项或将其设置为 true 可启用自动选择。将其设置为 false 对新工作树使用正常的 Git 签出和文件复制。现有工作树保留其内容和生命周期。 NTFS、ext4、HFS+ 和其他不受支持的文件系统使用正常的 Git 路径。不可用的本机绑定或失败的克隆也会回退到 Git; APFS 和 ReFS 文件数据克隆绝不会默默地替换加速路径内的普通文件副本。
APFS 和 Btrfs 操作使用隔离的本机助手,无需更改网关进程的文件系统配置。 APFS 加速也可以在 Rosetta 下使用匹配的 x64 本机帮助程序运行。 ACL 检查在元数据工作器中运行;未知的 ACL 状态或可继承的父 ACL 选择正常的 Git 签出。网关和这些帮助程序保留 fs-safe 的 auto 本机默认值。显式的 FS_SAFE_NATIVE_MODE=off 或 OPENCLAW_FS_SAFE_NATIVE_MODE=off 也会禁用这些帮助程序。只读元数据工作人员可以在取消时停止;恢复在触及其目标之前等待写助手退出。
在 Windows 上,将 worktreeRoot 指向 ReFS 卷上的目录,例如 D:\worktrees。 ReFS 提供文件块克隆而不是可写目录快照:OpenClaw 创建目录树并克隆每个文件的数据。全集群可以共享存储;部分文件尾部和文件系统元数据仍然消耗空间。网关需要普通文件访问权限(而不是管理员访问权限)才能在现有卷上克隆工作树。
OpenClaw 为每个存储库和目标根维护一个可重用的仅源模板。并发创建共享一个冷构建并在独立克隆时保留准备好的模板。虽然准备好的一代有读者,但进一步创建以原子方式获取读者保管权,而无需等待模板突变租用。空闲模板在重用之前会根据该租约进行验证。同一进程中的并发调用者共享挂起的准备等待,然后每个调用者获得自己的读者保管权,而不是排队另一个突变租约。一旦所有读者都安定下来,下一次重用将再次验证空闲模板。模板停用会在接触文件之前阻止新读者,并等待已接受的读者解决。更改的提交或签出策略会重建未使用的模板;虽然读者仍然持有它,但该请求使用正常的 Git 结账。一旦读者安定下来,清理就会废弃 7 天未使用的模板。不确定的本机操作保留模板保管权,而其进程所有者是活着的或未知的。下一次模板获取或清理将回收进程所有者肯定已死亡的读者,而不需要 OS 重新启动。分配和模板突变租约保留其现有的基于到期的恢复。 Git 继续拥有工作树注册、索引和分支;文件系统后端提供共享文件内容。
沙盒纯源会话也重用模板。模板创建、验证和索引刷新使用与普通纯源实现相同的隔离 Git 配置,因此存储库过滤器永远不会在主机上运行。它们的缓存身份包括该签出策略,从而防止重复使用使用主机过滤器准备的模板。
准备日志包括 templateDetails 以及后端、选择或失败原因、克隆字节估计以及错误代码(如果可用)。原因区分禁用加速、空或配置文件签出、本机探测、ACL 拒绝、签出策略、丢失或过时的模板、模板创建和磁盘准入。
用于模板签出的私有 Git 索引副本更喜欢本机写入时复制(包括在 APFS 上),并在克隆不可用时回退到独立字节副本。安全快照使用 Git 的只读状态和缓存的文件元数据来识别更改。干净的签出重用已提交的树,无需构建私有快照索引;更改结帐仅散列选定的路径。隐藏索引标志不排除对快照的编辑。
在 Btrfs 上,OpenClaw 将模板签出与测量的 Git 签出进行比较,并将其选择记录在日志中。如果模板速度慢于 250 毫秒以上,则后续创建将使用 Git 作为该存储库、目标根目录、后端和源策略,直到进程重新启动。提交更改保留此性能提示,而模板内容仍特定于所选提交和签出策略。冷模板构建提供 Git 测量,并将其与该模板的第一个应用程序进行比较,不包括一次性模板构建。重新启动后重用模板时,请求的签出会提供 Git 度量; OpenClaw 不会创建额外的基准检查。重大存储库更改可能会使保留策略变慢,但无法重用其他提交中的内容。
没有文件数据的新签出(包括空会话工作区)使用正常的 Git 签出,无需准备或克隆模板。
如果模板清理无法获取其模板租约或读取其缓存,OpenClaw 会记录警告并继续普通工作树和快照清理。稍后的清理过程会重试模板停用。
共享工作树模板仅包含签出的源。 .worktreeinclude 配置和 .openclaw/worktree-setup.sh 仍然在其现有权限下为每个新工作树单独运行。私有沙箱依赖模板遵循上面单独的准备合同;他们从不从主机存储库复制被忽略的文件。写时复制快照共享存储,直到文件发生更改;它们的实际节省取决于存储库和后续写入。
第一个加速工作树包括通过 Git 准备模板的成本。后来的 APFS 工作树在一次本机操作中克隆整个目录。 OpenClaw 在更新 Git 的缓存文件元数据之前以有限的本机批次读取共享数据流身份,从而避免重新读取已证明未更改的文件的内容。 Git 元数据准备计入时间戳安全延迟,因此在克隆的时间戳边界之后完成它不会增加另一个等待。 Git 仍然会验证生成的索引并检测后续编辑;不支持的索引格式和未经验证的文件会接受普通的 Git 验证。
Apple 不鼓励通过 clonefile 进行一般目录克隆,但未发布其完整原理。一项经过验证的限制是目录克隆不会将目标继承的 ACL 权限应用于后代。当目标父级具有可继承的 ACL 条目、模板根携带 ACL 或 ACL 检查失败时,OpenClaw 使用正常的 Git 签出。它会再次检查克隆以捕获准备期间的策略更改。仅目标父级上的不可继承 ACL 不会禁用加速。 Git拥有权限继承; OpenClaw 克隆后不会重写 ACL。
快速路径仅限于OpenClaw的私有源模板;不要在模板缓存内自定义 ACL。取消会等待已启动的本机克隆完成,然后恢复才能到达其目标。
对于包含许多小文件的存储库,ReFS 克隆可能比本机 Git 签出需要更长的时间,因为每个文件都需要独立的元数据,并且 Git 会刷新其索引。如果结帐延迟比源存储节省更重要,请使用 worktreeAcceleration: false。
存储库源配置文件
完整源仍然是默认值。要在创建 new 工作树时选择存储库拥有的稀疏源配置文件:
跟踪 .openclaw/worktree-profiles/<name> 中的普通 UTF-8 圆锥目录列表。名称使用小写字母、数字和连字符(最多 64 个字符,以字母或数字开头)。每个非空行命名一个跟踪的存储库相对目录;不要使用注释、通配符、绝对路径或父遍历。选定的列表组成一个排序并集。 Git Cone 模式还保留根目录和祖先目录中的文件。 OpenClaw 包括定义目录,因此选择仍然可以检查。
定义是从不可变的签出提交中读取的,而不是从未提交的源文件中读取的。默认远程重试从其后备提交中再次加载定义。选择在忽略文件配置和设置之前完成。它不请求依赖项安装或构建,并且现有存储库设置脚本保留其独立策略。配置文件无法重新缩小重复使用或恢复的工作树;选择一个新名称。
现有的--profile选项仍然选择运行时状态; --source-profile 只选择存储库源:
在本机工作或整个存储库检查之前有意扩展:
如果注册后稀疏物化失败,请保留部分签出和 Git 注册以进行恢复。使用相同名称重试不会缩小该部分状态;在选择新的工作树名称之前检查它。
选定的配置文件当前使用普通的 Git 签出。 Git 在设置稀疏规则时启用每个工作树的共享配置,因此该存储库的后续完整检出也使用 Git 回退,包括在本机完整扩展之后。现有的结账保留自己的来源和索引。
然后运行单独请求的 dependency/build 准备工作。 PR 整个存储库门仍然需要完整源代码。稀疏签出更改源具体化,而不是共享 Git 对象或历史记录;它不是浅克隆。
布局和名称
每个工作树位于:
存储库指纹是已解析的 Git 公共目录和源 URL 上的 SHA-256 哈希值的前 16 个十六进制字符。提供的名称必须与 [a-z0-9][a-z0-9-]{0,63} 匹配。如果没有名称,OpenClaw 会生成可读的甲壳动物主题名称,例如 brisk-lobster。已被任何已注册工作树(包括调用者自己删除的签出)、本地分支或非托管路径占用的推断名称将获得数字后缀,例如 brisk-lobster-2;只有提供的名称才能重用或恢复调用者的现有记录。
OpenClaw 在请求的基本引用处创建分支 openclaw/<name>。如果没有基本引用,它会发现并从 origin 获取远程默认分支,在附近的创建中重复使用成功的准备长达 30 秒。要立即使用新获取的提交,请获取它并选择其显式基本引用。如果提取失败,它将使用上次提取的远程默认值并记录一条包含 Git 失败原因的警告。它从来不会默默地替代本地的HEAD;如果没有可用的远程默认值,请修复 origin 或选择显式基本引用。当本地默认分支是所选远程提交的严格祖先并且干净的主要签出位于该分支上时,它将快进。脏的、分散的、稀疏的、锁定的、单独签出和分离签出都被保留。主要签出中的活跃 Git rebase、am 或 bisect 也会推迟本地进度。链接签出操作仅在保留默认分支(包括以 --update-refs 命名的变基)时才会推迟进度;不相关的操作不会阻止它。创建日志标识工作树和会话所有者、选择的基础 SHA、提交年龄和获取结果;超过 7 天的提交会产生警告。明确请求的基础必须解析为提交; OpenClaw 绝不会用其他碱基替代它。 Git 首先注册分支而不具体化文件,保留其正常的上游跟踪规则。然后,OpenClaw 捕获该分支的提交并将其用于大小估计、源模板和签出。稍后对源引用的更改无法切换正在写入的文件或重用较小的提交限额。
来自同一源签出的并发创建共享远程默认准备和本地默认推进决策,包括等待分配的创建。现有的呼叫者保留他们准备好的结果,直到他们的小组完成。新呼叫者可重复使用成功的准备长达 30 秒;即使旧组仍处于活动状态,到期后到达的呼叫者也会开始新的刷新。当其组完成时,失败的准备将被丢弃。保留繁忙的本地默认值不会导致 Git 引用突变失败。分支注册使用存储库的共享 Git 突变队列,因此上游跟踪无法与另一个注册竞争;文件具体化保持并发。失去引用锁定竞争的提取会在其原始超时时间内重试一次。创建报告未确认的 Git 清理,而没有启动另一次提取。
Git 工作树注册、普通签出删除以及创建或快照还原期间的源实现均具有五分钟的超时。获取丢失的对象以进行大小估计使用相同的五分钟预算。远程默认发现的预算为 30 秒,其获取的预算为 60 秒。其他托管工作树 Git 命令保留两分钟的超时时间,但自动 Git 维护除外,该命令的超时时间为 30 分钟。显式中断删除恢复加入删除,没有截止日期。单独的 .openclaw/worktree-setup.sh 步骤也保留其自己的两分钟超时。
后台 Git 维护、包索引修复和删除快照仅使用本地可用的对象。他们从不从部分克隆的承诺者远程获取丢失的对象;显式获取仍然负责下载这些对象。如果所需的快照对象丢失,普通删除会保留签出并报告失败。获取或修复源存储库中丢失的对象,然后重试删除。
本地代理 shell(包括网关主机上的 OpenClaw 启动的应用程序服务器进程中的工作线程本地执行和 Codex shell)会禁用 Git 的自动维护和旧版 auto-GC。执行适配器将这些设置附加到有效的 Git 参数中,保留不相关的作者和传输设置。这还涵盖了 Git 子进程,例如 promisor 获取,并适用于更新后现有工作树中的下一次运行。存储库配置和交互式操作员 shell 未更改。网关清理所有者仍然负责托管存储库的维护;显式维护命令仍然可用。沙箱、节点传输和外部启动的应用程序服务器对等体保留自己的策略。
容量和磁盘空间
创建和恢复在分配文件之前强制执行 计数和逐出策略 。磁盘接纳独立测量每个受影响的卷。
在分配签出之前,OpenClaw 检查其目标、Git 元数据、源签出和状态卷。它在每个卷上保留固定的 4 GiB 操作储备,加上估计的 Git 签出和配置文件大小的两倍。经过验证的可重用源模板将完整的 Git 签出限额替换为克隆元数据和 Git 索引写入的估计值。 Btrfs 快照共享目录元数据; APFS 和 ReFS 克隆每个跟踪条目的预算元数据,其中包括 ReFS 卷分配大小。冷模板和每个本机 Git 回退都需要在分配之前再次获得完整的检出限额。提供的文件保留其单独的完整副本限额。可执行设置脚本需要额外的空间,该空间等于 4 GiB 或当前源签出占用空间(不包括 Git 元数据)中的较大者。在 provisioning/setup 之前和设置之后再次检查空间。不可用的容量读数会停止分配并出现可操作的错误。
对于部分克隆,OpenClaw 在估计检出大小之前清点缺失的对象,并批量从克隆的承诺者远程获取它们。在推进本地 main 之前,默认基础创建通过捕获的提交来共享准备工作,同时 Git 工作线程保持活动状态(包括跨后续创建组)。没有共享准备的显式引用重新检查对象可用性。如果选定的引用在工作树注册之前移动,则注册的提交会得到自己的准备。该批处理仅请求丢失的对象,而不将共享提交视为其内容在本地可用的证据。大小库存和结账都不能触发每个对象的延迟获取。预取失败会记录丢失对象计数并停止准备。分配获取跳过Git自动维护;清理过程(在网关中每小时一次,或 openclaw worktrees gc)修复包查找并合并小包,然后使用实时管理的工作树或保留的快照,每个共享存储库每小时最多运行一次阈值门控提交图和松散对象打包任务。存档触发的清理仍然会立即删除符合条件的签出和孤儿;它不会在该小时内重复存储库管理。新注册的存储库在第一次清理过程中得到维护,并且 --retry-deferred 绕过了每小时限制。删除单个签出永远不会重建共享包索引或合并包。这些任务保留独特的对象和工作树引用日志;清理不会运行完整的 Git GC 或使引用日志历史记录过期。如果包修复失败,OpenClaw 会记录一次 Git 错误,并在服务生命周期内暂停对该存储库的维护。稍后的提交图或松散对象任务失败只会挂起这些任务;在随后的每小时维护过程中,有限的包整合将继续进行。修复存储库后,运行 openclaw worktrees gc --retry-deferred 或重新启动网关重试。其他存储库和工作树清理仍在继续。支持部分克隆,但建议对注册表拥有的项目使用完整克隆,以保持签出和恢复独立于丢失的远程对象。如果在没有承诺者远程的情况下对象丢失,请在重试之前获取或修复克隆。 Git 超时会报告其预算并建议检查远程可访问性、存储库锁定和部分克隆行为。
包整合将承诺者包和普通包分开。每次传递最多选择每组最小的合格包中的 1,024 个,输入最多 512 个 MiB。 Git 在过期之前验证这些包文件及其索引,而无需遍历引用或获取丢失的部分克隆对象。当一个组至少有 16 个符合条件的包时,维护会合并其经过验证的批次(至少两个包),并且仅使替换涵盖的包过期。较小的组仅废弃已验证批次内的冗余副本。每个组都会运行一次 expiry,因为 Git 在删除包后会重建存储库范围的包索引。验证和重写各有五分钟的子流程预算;索引写入和到期使用30分钟维护预算。保留的包装、废品包装和批次外的包装保持不变,包括超大的重复包装。小包装的积压会随着连续的传递而耗尽;整合并不能保证任意存储库增长的固定包数。整合流通过低优先级的 Git 子进程,每个包进程使用一个线程,并且还选择 ionice 可用的空闲 I/O 优先级。它与获取和包索引修复共享存储库突变所有权。
在 Linux 上,维护还会每次删除最多 256 个废弃的 tmp_pack_* 文件(一旦这些文件超过 24 小时)。隔离的本机助手必须获得独占的 Linux 文件租约,该租约可以跨用户 ID 检测打开的用户,并通过删除阻止新的打开。在取消链接之前,它会重新检查每个文件的身份、大小和时间戳。实时用户、不受支持的文件系统租用或更改的文件会保留该临时文件。其他平台保留临时包。安装更新不需要迁移或立即重新打包;下一个普通维护通行证将应用这些界限。
瞬时提取失败,包括不完整的对象传输,在原始提取超时内一秒后重试一次。取消和过期的工作区权限停止恢复;第二次失败会导致 Git 错误。请参见重试策略。
如果提取在提交图中但在对象存储中未找到引用提示,则 OpenClaw 在重试之前会尝试一次有界修复。它仅修剪确认已删除的上游原始跟踪分支(除非获取显式使用 --no-prune),保留本地符号引用或工作树 HEAD 所需的跟踪引用,然后通过 ID 获取丢失的引用和工作树-HEAD 对象,并禁用提交图查找和自动维护。本地分支、标签和工作树 HEAD 永远不会被删除。修复仅限于 50,000 条参考,4,096 条缺失提示,时间为 5 分钟;健康提取不会扫描存储库健康状况。托管项目刷新在恢复期间保留其隔离的 URL- 固定传输。
修复可能会清除支持的本地上的空源跟踪引用锁Linux当文件系统未更改的 inode 时间戳证明它们比当前启动早至少一小时时。仅凭年龄无法确定本机 Git 锁没有实时所有者,因此相同启动、非空、符号链接和其他不确定的锁保持不变。如果丢失对象或锁仍然阻止获取,恢复会记录其结果和可操作的警告。无需配置或状态迁移。
Git 工作线程在保持活动状态时重用一组有界的成功提交大小估计。当工作线程保持活动状态时,默认基础对象水合作用由不可变提交共享;没有共享准备的显式引用重新检查对象可用性。每次分配时都会检查可用磁盘空间。 Git 替换参考禁止重用受影响的大小估计,并且工作进程关闭会丢弃它们。
创建、恢复、孤立清理和快照过期在使用相同状态目录的存储库和进程之间共享分配所有者。已注册的工作树删除保留其自己的签出的保管权,因此在后台删除运行时可以继续进行不相关的创建。每个分配都会在每个卷上保留其估计的挂起写入量。如果另一个操作的预留空间不足,则创建会等待该操作解决后再重试。保留字节将一直保留,直到本机工作解决为止,包括取消或租约丢失之后。当创建的内容复制托管源时,它们会受到保护。时隙准入和孤儿清理共享分配托管。模板准备按模板进行序列化,同时独立检出同时实现。专用的心跳线程更新操作租约,并且争用等待时间限制为 30 分钟,从而允许依赖项安装的 15 分钟预算加上签出和清理。呼叫者取消和总体请求限制可以更早地停止等待。上述单独的 Git 和设置超时仍然适用。相同体积的成本相加。这些检查是保守估计,而不是磁盘配额:其他 OpenClaw 状态目录、shell 命令、部署工具和任意 setup/build 输出仍然会消耗空间。重用现有的有效结帐不会分配另一个结帐。直接通过 Git 创建的工作树位于托管清理生命周期之外。
Git 库存和目录大小计算在有限的后台工作人员上运行。分支和签出上下文读取使用专用工作器,与差异和快照处理分开。会话差异、基线捕获、拉取请求统计、删除快照、签出删除和 Git 维护共享两个 Git 子进程的限制,并在 POSIX 系统上以较低的 CPU 优先级运行。在创建快照之前,删除会从当前包文件重建存储库的多包索引,即使更广泛的自动维护已暂停或旧索引引用已删除的包也是如此。这可以修复包查找,而无需等待完整的维护过程或重新打包对象。
网关保留 Git 子进程、取消、操作租赁和注册表写入的所有权。取消操作会等待其子进程和临时索引清理完成,然后再释放该所有权。仍在等待另一个 writer 的 ref 突变可以取消,而无需等待该 writer;已经运行的突变在取消返回之前完成清理工作。准备工作可以取消。一旦破坏性签出删除开始,它要么完成并记录删除的签出,要么耗尽其五分钟预算,加入其子进程,并保留已完成的快照以供恢复。即使维护停止或其配置发生变化,运营租赁和拆除索赔仍保留最终确定权。引用清理失败会保留已删除的记录和快照以供恢复。
快照重用其操作的路径清单,并在构建其临时索引时固定源 HEAD。等待其他引用突变后,发布以原子方式验证 HEAD。如果 HEAD 在准备过程中发生更改,清理会保留结帐并要求您重试。由于忽略规则和源索引可以独立更改,因此在捕获时会再次检查预配置文件成员资格。并发操作保留独立的签出保管和共享磁盘准入,而不会削弱快照保护。
快照删除使用 128 MiB 的较小保留加上估计的快照写入,因此在低于操作保留的情况下仍可以进行安全清理。如果所需的快照无法容纳,普通删除会保留签出并要求您首先释放空间;上限驱逐允许快照丢失。
提供被忽略的文件
在源仓库根目录添加 .worktreeinclude,以将选定的被忽略、未跟踪文件复制到新的 worktree 中。该文件使用 gitignore 模式语法,每行一个模式,并支持 # 注释:
只有同时被 git 报告为已忽略且未跟踪的文件才符合条件。已跟踪文件已经通过 git 存在,因此永远不会通过此步骤复制。OpenClaw 不会覆盖或更改已存在的目标文件,不会跟随符号链接目录,并会保留已复制文件的模式。它只记录实际创建的路径,因此后续对清单的编辑不会使这些文件从清理保护中消失。
运行仓库设置
即使启用了 submodule.recurse,Git 源实现也会使子模块保持未填充状态,从而与本机工作树创建相匹配。存储库设置脚本可以初始化它需要的子模块。
如果 .openclaw/worktree-setup.sh 在源仓库中存在并且可执行,OpenClaw 会以新的工作树作为当前目录来运行它。该脚本接收:
非零退出码会中止创建,并移除新的工作树和分支。这是一个仓库本地约定;没有用于此的 OpenClaw 配置键。
设置失败报告退出代码或终止信号,或 120 秒后的实际超时,并带有最近输出的有限摘录,而不是完整的设置日志。如果安装超时,请检查 .openclaw/worktree-setup.sh 及其依赖项是否下载缓慢、服务不可用或等待交互式输入的命令。
会话工作树
本机 sessions_spawn 子级可以使用托管工作树,同时保持隐藏状态:
隐藏的子级使用与可见会话相同的会话工作树准备和持久绑定。验收不等待结帐和设置;第一个代理轮流等待,直到托管工作区准备就绪。子代理仍然是本机子代理,保留其完成路由、沙箱策略、运行超时和清理选择。 cleanup: "delete" 在删除之前使用会话删除来快照结账; "keep" 在正常空闲和归档生命周期下保留它。会话列表和工作树页面可以检查记录的工作树,而无需将子项设置为侧边栏会话。
对于隐藏子项,projectId 需要 worktree: true。工作树名称和基本引用也需要 worktree: true。 projectId 和 cwd 是互斥的。 group、projectGitUrl 和云放置配置文件保持仅可见状态; ACP 不接受托管工作树参数。参见子代理工具参数。
对于没有源存储库的全新隔离会话,请使用 worktree: true 和 worktreeSource: "empty" 调用 sessions.create。这不会复制代理工作区或任何选定的文件夹。它不能与 cwd、项目或存储库选择、外部目录、execNode 或 worktreeBaseRef 结合使用。 Control UI 将此模式用于配对设备和云目标上的 New 工作区。
每个新会话在 <openclaw-state-dir>/worktree-sources/empty 下都有自己的 OpenClaw- 拥有的后备存储库,因此 Git 远程和历史记录在会话之间保持隔离。现有的托管工作树注册表拥有分配、快照、恢复和清理功能;无需数据库迁移。当实时工作树或保留的快照引用它时,后备源仍然可用,并在收集其最终过期快照后被删除。内部仍然需要 Git。现有安装仅针对新的显式空工作空间请求才采用此模式;现有会话及其快照保留其原始来源。
如果工作树准备在第一个模型回复之前失败,会话会记录失败原因。 Control UI 在聊天中显示失败的会话,并且记录中保留了失败通知。命令失败可识别命令及其退出或超时原因,因此 Git 设置超时与模型提供程序超时是有区别的。
使用工作树会话从 Git 支持的文件夹启动隔离聊天:在 Control UI 的新会话页面上,使用 Place 选择器选择网关源文件夹,然后选择 Worktree(带有可选的基本分支和工作树名称)。选择已选择网关文件夹的配对设备或云配置文件会使用此托管工作树路径;远程放置从不浏览或绑定任意节点工作目录。当省略名称时,OpenClaw 从显式会话标签或第一条消息生成的简洁标题中派生出该名称,然后回退到以甲壳类动物为主题的名称。当活动代理工作区由 Git 支持时,iOS 会在聊天操作中公开相同的选择,而 Android 会在新聊天旁边公开它。
从网关文件夹启动的远程会话保留持久的托管工作树镜像,用于工作区协调、恢复和发布。相同的磁盘空间检查也适用于该镜像。要在没有网关签出的情况下开始,请选择 GitHub 存储库和远程目标: 存储库云会话 在节点上获取并保留网关上接受的检查点。它们的检查点具有与托管工作树快照不同的生命周期。
仅在通过至少一次提交确认可用的 Git 签出后,或者当选定的远程 Git 存储库正在等待克隆时,Control UI 才会提供 Worktree。没有提交的普通文件夹和新初始化的存储库可以直接在网关上运行。如果文件夹可访问,则失败的 Git 检查也可以直接执行;仅 .git 条目或保存的项目无法启用隔离。如果您已选择 Worktree 并且稍后的检查失败,则该选择保持可见并且启动被阻止。清除Worktree直接运行,或者重新选择文件夹再次检查。
base-ref 字段建议最多 100 个本地引用和 100 个远程引用,以及默认分支和当前分支。当前分支来自选定的结帐,包括链接的工作树;分离结帐没有当前分支。分支发现直接读取结帐,无需清点同级工作树。重复查找重复使用已完成的分支列表(包括来自大型存储库的有限建议)长达 30 秒,而无需检查 ref 或 HEAD 元数据或启动另一个 Git 进程。存储库更改可能会使建议和存储库状态保持陈旧,直到刷新为止;它们在创建过程中绝不会绕过所选引用的验证。即使没有建议,您也可以输入任何分支或提交。如果无法加载分支建议,Control UI 会说明您可以手动输入引用;经过验证的 Git 签出仍然可用于工作树。在创建会话之前,所选引用仍必须解析为提交。
组 新会话默认值 以与自定义文件夹相同的方式检查代理工作区。如果验证失败,请在保存组默认值之前重试。记住的云目标无法阻止普通文件夹中的新本地草稿;短暂的 Git 检查失败会使保存的目标完好无损地供下次访问。
地点选取器的 Projects 部分可以从注册项目 ID 启动相同的工作树流程。网关解析记录的结帐路径,因此该路径在 operator.write 处仍然可用;选择任意主机文件夹仍然需要 operator.admin。
当代理发现当前任务之外有确认的后续工作时,也可以致电 suggest_task。 Control UI 和网关支持的 TUI 在新会话中提供 Start。这将直接在建议的文件夹中启动任务,而无需创建工作树或需要 Git。新会话被指示解释需求并在稍后创建或切换到工作树之前询问用户。拒绝建议不会带来任何后果。建议及其 ID 是短暂的,并且不会在网关重新启动后继续存在。
在 Control UI 中,Start in a new session 旁边的箭头提供了两个附加操作:Start in a new worktree 根据建议的 Git 签出创建一个隔离会话,并且 Start 在此会话中发送将任务转移到当前对话。如果当前会话正在运行,则任务将遵循其正常的引导行为。工作树创建需要可用的 Git 签出;启动失败会显示错误并保留建议以供重试。
关闭建议任务卡会立即将其删除,同时 Control UI 将取消发送到网关。其他卡和作曲家仍然可用。如果请求失败,卡会返回错误,以便您重试;切换聊天不会将旧卡片带入新对话。
主要操作和网关支持的 TUI 发送 taskSuggestions.accept 和 mode: "local"。 Control UI 菜单发送这些选择的显式 worktree 或 session 模式。 RPC 客户端还保留 cloud 模式。对于使用原始工作树操作的调用者来说,省略模式仍然意味着 worktree; Control UI和TUI从不省略它。
OpenClaw 仅向具有可操作网关 UI 的操作员会话公开这些工具。通道会话和 local/embedded TUI 会话不会接收它们,因为这些表面没有可移植类型的任务操作契约。
生成的托管工作树由会话拥有,并且在该会话中运行的每个代理都使用其签出。当工作区是存储库子目录时,工作树锚定在存储库根目录,并且会话从其中的匹配子目录运行。会话工作树创建使用该方法的 operator.write 范围。存储库 checkout/ref 挂钩和文件系统监视器始终处于禁用状态。 .openclaw/worktree-setup.sh 步骤仅针对 operator.admin 调用者运行;重试评估当前调用者的范围,而不是保留原始调用者的权限。 .worktreeinclude 配置仍然适用于每个呼叫者。删除会话尝试快照并删除其托管工作树,包括脏工作树和具有未推送提交的分支。每小时清理还会在 7 个空闲天后对会话工作树进行快照,将最近的会话活动视为工作树活动。已删除的工作树仍然可以从其快照中恢复,如下所述。
回复命令 /new 和 /reset 以及自动空闲重置,启动新的对话上下文,同时保留会话的托管工作树、项目和工作目录。 Control UI 中的普通 New Chat 故意通过正常的清理流程离开先前的工作树。
归档会话在其归档状态和发布提交后返回,保留对话和工作树绑定。发送响应后,网关唤醒后台维护进行快照并删除结账。响应不会等待 Git 或工作树分配租约。失败的元数据写入不会影响结账。如果清理无法安全完成,会话将保持存档状态,并且其文件仍可用于以后的清理过程。每小时垃圾收集还会拾取自动存档的会话。清理仅在承认其注册表声明并发布已删除的签出时保留会话生命周期突变。 Git 运行在该突变之外。在清理开始之前取消存档会保留现有的签出;在清理过程中,取消归档会报告删除正在进行中,并要求您在解决后重试。不完全删除需要在取消归档之前恢复其保留的快照。
慢归档请求记录请求拥有的阶段持续时间,包括快照读取、投影、运行时选择、归档放置检查、提交、cron 效果和响应准备。这些时间安排将前台元数据工作与后台 Git 清理分开;嵌套阶段可以重叠。
存档准备会读取选定的会话,而不保留其数据库的写入器,因此不相关的排队写入不会延迟停止该会话。承诺的策略更改会使准备好的源失效。存档突变仍然会加入写入队列并在提交之前重新检查当前会话和权限。
取消存档或重新打开存档会话的授权人工消息会在承认工作之前恢复原始分支 HEAD 以及保存的脏文件和未跟踪文件。恢复失败会使会话存档。如果原始存储库或其快照丢失,或者30天快照保留已过期,请恢复原始repository/snapshot或启动新任务; OpenClaw 不会用空结帐替换已保存的工作。
sessions.create 可能包含一个绝对值 cwd,以便直接在另一个网关文件夹中运行或与 worktree: true 一起选择源签出。与 operator.write 的连接可以使用任何配置的代理工作区中包含的网关 cwd;真实路径包含可防止符号链接逃离该边界。这些工作区之外的网关路径需要 operator.admin。普通工作树聊天创建仍然是 operator.write 并保持锚定到配置的工作区。对于网关源,新会话将完成的工作树会话分派到配对设备或云配置文件,而不是将配对节点工作目录传递给创建。单独的 repository: { url, ref? } 创建输入启动远程拥有的存储库会话,而无需网关路径或 worktree: true。
sessions.create 还接受 worktreeBaseRef 和 worktreeName 以及 worktree: true 来选择基本引用和工作树名称(分支变为 openclaw/<name>);两人都住在operator.write。如果省略 worktreeName,则会话标签或生成的第一条消息标题将提供可读的分支名称,如果命名失败或超过 30 秒的等待时间,则会提供以甲壳动物为主题的两个单词的后备名称。原始的第一条消息文本绝不是分支名称的后备。稍后到达的标题会更新会话,而不重命名其现有分支。对于具有初始消息或任务的新会话,创建会返回已承认的会话并在工作树准备完成之前运行。聊天显示提交的消息以及命名、结帐和设置进度;失败在同一会话中仍然可见并可重试。代理仅在最终工作树绑定后启动。没有初始轮次的创建仍然等待准备并返回创建结果中的工作树。绑定签出以 worktree: { id, branch, repoRoot } 的形式保留在会话行上,因此会话列表可以显示其签出和分支。当会话删除无法完成清理时,worktreePreserved 会识别需要注意的活动工作树记录,并报告一个有限原因:所有者不匹配、主动使用或竞争清理、外部 Git 锁、快照失败或其他清理失败。这些原因描述了清理和所有权,而不是检出是否脏或有未推送的提交。
显式会话库必须解析为提交。在保存会话之前检查本地参考;克隆后检查远程项目引用。丢失的远程引用将从记录的项目 URL 中刷新,并仅在网关管理的克隆中重试,而不会在操作员注册的签出中重试。一旦被接受,提交将在设置失败时保持固定状态并重试,而原始引用仍保留发布元数据。无效的显式引用永远不会默默地切换到存储库默认值。托管克隆刷新使用隔离的 Git 存储库进行网络传输,因此签出本地 URL 重写,并且挂钩在获取期间无法重定向或执行。固定提交存在检查禁用延迟获取;缺失的提交使用显式增量获取,而不是通过承诺者远程再次下载其祖先。刷新保留现有克隆的部分克隆过滤器;结账准备在需要时获取所选提交的缺失内容。
对于具有 worktree: true 的同一代理 sessions_spawn,省略 cwd 将使用父级的实时托管存储库或其直接选择的注册项目。孩子有自己的托管工作树。明确的源选择优先;其他生成点使用目标代理工作区。父工作目录本身并不授权在该工作空间之外进行继承。
父会话及其托管工作树或注册项目绑定必须保持当前状态,直到子会话被接受。接受的子会话在父存档、替换或工作树更改中保留其保存的存储库选择。重试仍必须获得当前子会话的授权,并使用当前调用者的设置权限。
创建疑难解答
如果创建报告 git checkout has no commits,请在源存储库中创建初始提交,然后重试。单独运行 git init 不会为新工作树提供提交。
如果 New session 报告 git worktree add failed,请阅读终止原因和最终的 Git 错误行。 Preparing worktree和Updating files是进步,而不是失败的原因。错误消息折叠回车进度重绘并绑定诊断尾部,使其无法淹没横幅。
timed out after 300 seconds 表示工作树签出已达到五分钟限制。其他 Git 命令在两分钟限制时报告 timed out after 120 seconds。检查网关主机上的存储库访问和可用磁盘空间。单独的信号或非零退出状态不会建立超时;使用任何随附的 fatal: 或 error: 详细信息进行调查。输出限制错误意味着命令超出了其输出捕获限制。
如果分配所有权在创建过程中丢失,则尽最大努力进行清理。没有清理权限,OpenClaw 保留结帐和分支;可能需要手动清理或其他工作树名称。在清理失败后尝试再次创建之前,请检查 git -C <repo-root> worktree list 和 git -C <repo-root> branch --list 'openclaw/*' 的部分状态。失败的创建并不能保证其签出和分支已被删除。在未检查结帐或分支是否包含您需要的工作的情况下,请勿删除它。
如果结帐的 .git 链接指向丢失的管理文件,则 OpenClaw 会保留其文件并拒绝重新使用它。在使用该存储库中的 git worktree repair 之前恢复原始存储库元数据。具有相同远程 URL 的不同克隆不会恢复丢失的索引或未推送的历史记录;在未验证原始元数据的情况下,请勿替换链接或重建索引。
快照、清理和恢复
普通删除首先创建一个包含跟踪文件和非忽略的未跟踪文件的合成提交,然后将其固定在 refs/openclaw/snapshots/<id>。主机配置的忽略文件不会进入 Git 快照或存储库对象数据库。 OpenClaw 仅存储它在分块共享状态数据库行中实际配置的被忽略的文件;即使 .worktreeinclude 后来更改或消失,记录的路径集仍然具有权威性。恢复从不可变快照中读取这些字节并重新应用它们的完整模式。当无法再安全地对记录的路径进行快照时,空闲清理会保留实时工作树。如果快照创建失败,则普通删除将停止,除非 --force 明确允许快照丢失。上限驱逐是尽最大努力,并且可以在没有快照的情况下清除结账。
对于普通的干净签出,快照在使用清除隐藏状态标志的私有索引检查工作文件后重用原始 HEAD 树。它在创建相同的恢复提交和快照引用之前检查一批中的对象可用性。丢失的对象保留签出并出现存储库修复错误,包括部分克隆。精确状态快照继续捕获其完整记录的状态。
沙箱创建的忽略文件(包括符号链接)和协调已接受的空目录仍由现有投影所有者保管。在删除之前,OpenClaw 在其待处理结果收据和私有恢复引用中保留其丢失的快照增量。在另一轮之前恢复重播该收据可以同步工作区。这不会强制将忽略的路径发布或导入不相关的忽略的主机文件。收据遵循相同的快照保留期,并且未接受的私人编辑会延迟清理。旧版配置文件分类帐仍然仅包含常规文件。旧版本可以恢复该账本和 Git 快照,但不应用投影收据;返回支持版本以恢复接受的访客数据。
普通删除是归档:成功快照后,它使用 Git 的强制签出删除功能,以便稍后可以恢复脏文件。 CLI 的 --force 选项允许快照丢失;省略它会 not 选择非强制 Git 删除。当删除必须是非强制时,请使用 openclaw worktrees remove <id> --if-lossless。这使用与运行端清理相同的所有者,保留脏的或未发布的工作,并且从不重试 Git 强制拒绝。它不能与 --force 组合使用。
普通删除需要 HEAD 保留在记录的托管分支上。切换分支或分离 HEAD 会在普通删除和空闲清理期间保留签出和记录分支,但不会免除签出上限驱逐。分支删除针对已完成的快照使用本机 git branch -d,因此超出该快照的高级提示保持不变。如果没有快照,分支将保持保留。删除仅删除其自己的 Git 工作树注册,并且从不运行存储库范围的 git worktree prune。
空闲清理会保留包含嵌套 Git 存储库或链接工作树的外部工作树,即使它共享相同的 Git 公共目录也是如此。 Cap 驱逐可以清除非托管嵌套存储库。嵌套的 OpenClaw- 托管结帐通过自己的声明和快照单独退出;实时嵌套结帐还可以保护其封闭结帐。容量准入实时保管创建或恢复所需的托管源和目标容器。
OpenClaw 应用以下清理规则:
- 在运行结束时,仅当
git status --porcelain为空并且git log HEAD --not --remotes --oneline发现没有未推送的提交时,它才会在没有 Git 强制的情况下删除工作树。它还检查捕获的内容是否有被索引标志隐藏的编辑。否则,它会保留结帐并记录原因。 - 后台清理快照并删除空闲超过 7 天的未锁定工作板和会话拥有的工作树,即使脏了也是如此。所有者已存档或缺席的会话工作树无需等待 7 天即可获得资格。失败的所有者查找会推迟空闲清理。运行
openclaw worktrees gc来请求清理并查看其进度。 - 同一后台所有者强制执行
worktreeMaxCount,默认4096,使用容量驱逐策略。强制执行上限时,手动工作树和未保存的数据符合条件。 - 快照记录在 30 天内仍可恢复。之后清理会删除快照引用和注册表行。
- Live 所有者租约可保护活跃运行免遭驱逐。普通的空闲清理还会保留外部或无法识别的 Git 工作树锁。
维护工作以小批量进行,并有时间预算、批次之间的产量,并从之前的位置恢复,直到扫描完成;批量大小不是每小时的移除限制。文件系统扫描、无损检查和嵌套存储库检查在 Git 工作线程中运行。网关请求启动或观察相同的后台作业,而不是等待整个队列被检查; openclaw worktrees gc 报告所有者的进度。健康摘要包括每个驱逐原因和任何住户拒绝。
清理进度和 JSON 输出报告 eligibleCount(通过初始策略和结账检查的删除候选项)、deferredCount 和 failedCount。这些是当前扫描的运行总计,而不是对下一次扫描的预测:最终权限检查仍然可以推迟符合条件的删除。即使 64 条目的问题详细信息列表已满,延迟和失败的总数也会计算所有清理阶段的处置情况。受保护的结帐会导致延迟总计。 orphansRetired 和 retiredCheckoutPaths 中分别报告了在保留其文件的同时停用孤立记录的情况;它不算是成功的签出删除。
空闲收集在请求 Git 库存之前检查注册表资格、记住的处置、所有者活动和运行租约。它按顺序对候选者进行分类,并为每个存储库共享一个初步锁定和分支库存。已知的配置账本使用文件系统检查而无需设置 Git。普通删除会重新读取当前锁和 HEAD 并验证其分配租约下的工作树活动。 Cap eviction 对 Git Worker 中的分支历史记录进行排名,并在删除之前再次检查实时删除权限。初步清查从未授权拆除。如果清理无法获取租约,它会保留孤立候选者和过期快照以供以后使用。
每个清理过程都会对数据库工作人员中的会话所有者活动和工作人员放置读取进行批处理,而无需加载已保存的提示或完整会话条目。批次之间的所有者分类产量。清理仍然会在突变之前重新检查当前会话身份、活动、存档状态、工作树绑定和工作器放置。不可读或不确定的所有者状态保留结账。
清理会记住受保护结帐的延迟原因和指纹,而不是重复未更改的检查。托管活动、注册表生命周期更改以及观察到的签出或 HEAD 更改会使这些决策无效。修复文件或 Git 元数据后,运行 openclaw worktrees gc --retry-deferred 强制进行另一次检查。记住空闲清理保护永远不会免除结帐上限驱逐。可空派生状态列在数据库准入时添加,无需更改架构版本;旧版本会忽略这些配置并恢复之前的检查行为。快照保留期为 30 天。
Git 超时记录其删除阶段、经过的毫秒数、尝试计数以及现有修订绑定清理配置中的下一次重试时间。自动重试最初会等待两个小时,然后加倍直至 24 小时;在该窗口内通过跳过结帐库存工作。此退避在网关重新启动后仍然存在。显式的 --retry-deferred 会绕过等待,而所有者活动或新的注册表生命周期会使旧的处置无效。现有行不需要迁移;仅了解延迟原因的构建保留其现有的保护行为。慢速删除日志行包括结账路径、阶段持续时间、跟踪和不可忽略的未跟踪计数(如果可用)以及延期决定。删除期间超时会保留挂起的快照,并防止新的运行使用潜在的部分签出;使用下面的恢复过程。
丢失或损坏的 Git 对象也使用此持久退避。一次失败的空闲清理尝试会暂停共享存储库的进一步空闲快照,包括同一扫描中的同级检出。包合并仅独立验证可能废弃的有界批次;丢失的快照对象不会强制进行完整的存储库完整性扫描或阻止健康的包。损坏的选定包会停止该批次,而不删除其源。签出将一直受到保护,直到其快照所需的对象在本地可用为止。清理报告需要修复的存储库并保留签出。恢复丢失的对象或修复克隆,然后运行 openclaw worktrees gc --retry-deferred 立即重试。当工作树的所有者或生命周期发生变化时,现有的清理修订版会使记住的故障失效;无需数据库迁移。显式删除和容量驱逐保留其现有政策。
仅当其记录的路径、活动和存储库标识仍与先前的检查匹配时,列表和清理才会将丢失的签出标记为已删除。在该检查期间完成的恢复或存储库修复会保留较新的实时记录。
空闲清理保留 HEAD 已从其注册分支分离或切换为 branch-moved 的结帐。如果链接签出的 Git 元数据目录已消失,但其源存储库仍然可用,则空闲清理会废弃孤立记录,同时保留签出文件和正常快照保留期。这些配置不会失败 openclaw worktrees gc;真正的检查或清理失败仍然返回非零退出状态。摘要和 JSON 输出包括每个保护原因的孤儿退休计数和总数,即使个别详细信息被截断也是如此。上限驱逐可以清除这些原本受保护的结账。
拒绝权限的空闲检查(EACCES 或 EPERM)将签出保留为 unreadable,在其清理详细信息中包含违规路径,在摘要中包含一个保护计数,而不是每次扫描时发出警告。如果无法解析注册路径,孤立删除也会等待。修复网关用户的访问权限;稍后通过重新检查更改结帐。无论早期的不可读处置如何,Cap 逐出都会尝试清除,但无法绕过操作系统权限。
缺少签出或具有本地工作区投影的 gitdir 仍注册为 local-workspace-projection。仅投影文件可能仍需要恢复;清理会推迟退休,直到投影所有者释放监护权,包括在以后的保留期间。
没有快照的孤儿不再出现在 worktrees list 中,并且无法使用 worktrees restore。 GC 验证记录的存储库身份并报告 retiredCheckoutPaths 中手动恢复的每个保留的签出路径,与有限的问题详细信息无关。这些情况是延迟清理:CLI 退出 0,并且网关现有的延迟清理响应包括所有恢复详细信息,而不更改其成功响应合约。文本摘要也保留了每个恢复路径。保留这些文件和保留的源分支;将工作恢复到单独的签出中,而不是删除或覆盖保留的文件。停用不会重建丢失的 Git 元数据或创建替换快照。
运行结束时,清理操作会在 worktree 记录中记录其结果:无损移除;由于检出内容繁忙、存在未提交更改、存在未推送提交或存在已配置文件漂移而保留;或因错误原因而失败。使用 openclaw worktrees list --json 或 worktrees.list 查看记录的结果。
普通的强制签出删除首先会重命名捕获的文件树,然后让 Git 删除原来的注册。文件删除在后台连续运行,因此清理可以释放签出名称,而无需等待每个文件都被取消链接。删除失败会记录保留的目录以供手动清理;在后台删除开始之前发生崩溃可能会留下同级 .openclaw-removing-* 目录以供检查。非强制无损删除和显式中断删除恢复保留了Git的最终检查和连接文件删除。
在恢复网关用户拥有的目录的所有者写入权限后,孤立清理会重试权限被拒绝的删除一次。它永远不会更改文件权限或遵循符号链接目标。如果删除仍然失败,清理会报告孤立项并警告一次,同时继续处理其他孤立项。自动传递会跳过该目录,直到网关重新启动、该目录被替换或者您在修复访问后运行 openclaw worktrees gc --retry-deferred。
如果检出删除失败或中断,OpenClaw 会将已完成的捕获保留在 refs/openclaw/removals/<id> 处。后来的删除拒绝用可能部分签出的文件替换该捕获。保留剩余文件、记录的分支、快照引用和共享状态数据库以供恢复。在尝试清理之前检查原始删除错误和 Git 工作树注册;不要反复强行删除或删除注册。正常完成的删除、成功的还原或快照到期都会清除此恢复引用。签出删除后发生的故障可能会保留其分支,并且需要操作员进行协调,然后才能重新创建该分支。
快照到期会在一个 Git 事务中停用快照及其关联的恢复引用。如果 Git 无法锁定引用或观察到的快照或恢复收据已更改,则事务会保留所有这些引用,并且清理会报告失败以供稍后重试。现有快照在更新后使用此行为而不进行迁移。
对于中断的 普通干净快照 删除,请使用确切的挂起提交:
恢复保留原始捕获,验证保留的索引和所有剩余文件,仅修复签出丢失的 Git 链接,并仅重新创建丢失的捕获文件而不覆盖现有路径。然后,本机非强制 Git 删除完成签出和分支清理。这可能会暂时需要磁盘空间来存储丢失的文件。快照仍然可用于恢复;此命令不会停用快照或在存储库范围内运行 repair/prune.
在恢复之前停止外部编辑器、终端和其他非托管编写器。在最终确定之前,受管理的消费者将被排除在外;同步 byte/mode 检查允许本机删除,无需干预异步检查。
更改的文件、外部路径、实时使用者、更改的 refs/registry 所有权、丢失原始元数据以及与捕获停止恢复不同的索引。脏捕获、配置的忽略文件、预计工作空间和精确状态停用会保留其现有的恢复所有者。保留这些来源以供检查;此命令不会将它们重新解释为干净的删除。在解决其阻止程序后,可以使用相同的 ID 和快照重复中断恢复。一旦允许签出删除,就会在没有普通 Git 命令截止时间的情况下加入,这样超时就不会再次中断删除。
恢复会在原始快照前提交处重新创建 openclaw/<name>,并在可用时重用其干净的源模板。 Git 将保存的差异应用为未暂存的修改和未跟踪的文件,而不用快照内容替换模板。由于没有可重用的模板,Git 直接实现快照。磁盘准入包括用于更改和添加文件以及克隆元数据的空间,或用于普通结帐的完整快照。如果快照更改 .gitattributes 或其差异超出了有限的库存大小,Git 将使用完整副本空间限额重新实现所有快照文件。这甚至可以将快照的行结尾和过滤器应用于未更改的 blob。合成快照不存在于分支历史记录中;它的参考号仍然被记录为出处。
处于浅历史边界的分支仍然可以被快照和恢复。如果稍后的深度限制获取使快照提交本身变浅,Git 可能不再解析其父级。然后,恢复会保留快照并根据 git fetch --unshallow 指导报告存储库和快照提交。 OpenClaw 不会自动加深:origin 可能不包含本地快照,因此即使成功提取也不能保证恢复。如果提取后快照仍然很浅,请在重试之前从原始存储库恢复其父级。
提前撤销已删除的快照
仅当删除的快照与保留的本地分支或远程跟踪提交冗余时,才使用 openclaw worktrees retire-snapshot。此 CLI 操作需要精确的工作树 ID、快照引用和提交、记录的 removedAt 毫秒以及保留的源引用和提交。在调用之前从已删除的记录和存储库中读取这些身份:
停用仅适用于普通快照,不适用于精确状态恢复快照或其保留的签出。它需要相同的源树和保留的快照父历史记录。它拒绝实时或重新出现的签出、Git 注册、更改的身份、待删除、run/removal 消费者、未知或非空的配置文件库存或任何保留的本地工作区投影。 Git 相等并不能证明接受的忽略投影数据是多余的。它使用现有的分配租约和投影所有者,然后自动验证保留的引用并仅删除预期的快照引用。它不会创建备份、删除保留的源或 PR 结果引用、运行全局垃圾收集或报告回收的磁盘字节。 Git 对象存储在 ref 失效后仍可以保持共享。
成功的 JSON 结果是 { "retired": true, "id": "<id>" };删除的注册表项将不存在且无法恢复。拒绝并不意味着清理成功。如果裁判退役后发生中断,请检查剩余记录和投影保管情况,然后再进行进一步清理;此命令不会从丢失的参考中推断出安全退休。 CLI 在实时同根网关上使用 worktrees.retireSnapshot; Control UI 不公开此操作。
精确状态独立退休
普通拆除、强制拆除、--if-lossless仍拒绝分离的HEAD。要停用故意分离的托管签出而不更改其记录的分支或暂存状态,请使用显式的所有者防护请求:
该请求包含来自 worktrees list --json 的当前注册表所有者和生命周期时间戳、分离的 HEAD 提交、记录的分支的提交以及原始 Git 索引字节的 SHA-256。例如:
使用实际观察到的值,而不是示例。对于没有所有者 ID 的手动记录,省略 ownerId。该选项不能与 --force 或 --if-lossless 组合使用。实时运行租约、外部 Git 锁定、更改的 owner/lifecycle 或更改的 HEAD、分支、索引或捕获的文件会保留签出。它不授权删除另一个会话的活动工作。
版本化快照保留分离的提交和单独记录的分支提示、原始索引字节和拆分索引依赖项,以及仅由暂存、缓存树或解析撤消状态引用的对象。它保存原始跟踪和非忽略的未跟踪字节、符号链接、权限模式位和修改时间。此快照中的忽略文件选择保持不变:只有本机配置文件分类帐和暂存输入合约保留符合条件的忽略文件。仅对象恢复不会重现文件系统标识,例如索引节点号或更改时间。记录的分支保持其原始提交。
Exact 退役是存档,而不是立即磁盘回收。 它将通过本机 Git 的原始签出移动到私有恢复名称,并删除实时托管工作树绑定。原始结帐及其本机注册仍保留与不可变快照相同的 30 天恢复保留期。结果包括 recoveryPath 和 recoveryRetainedUntil。这会保留来自已持有工作目录或打开文件描述符的进程的写入; Git index/ref 锁本身无法确保删除这些字节的安全。恢复路径不是活动工作区。快照过期会删除此保留的签出,因此不要继续在那里工作或将其视为永久存储。
精确状态停用需要使用 Git 文件引用和支持的 Git 索引扩展进行完整、非稀疏的签出。它持有本机 Git 索引和引用锁,同时在归档最终确定之前重新验证其索引、引用、文件和权限。当其原始路径仍然可用时,验证失败会将完整的结帐移回原处。这两种移动都不会覆盖重新创建的源路径。
恢复通常会将保留的原始签出移回原处,保留其索引、元数据、忽略的缓存,甚至在捕获后通过旧句柄进行的工作文件写入。如果其 HEAD 或索引发生更改,则恢复会拒绝并保留两个恢复源。如果保留的签出及其注册均不可用,则恢复直接从 Git 对象具体化不可变快照,无需过滤器、行结束转换或工作树编码。该回退仅恢复快照的合格忽略文件,而不恢复不相关的缓存。两条路由都恢复分离的 HEAD 而不替换记录的分支。如果恢复在其本机移动后被中断,请重试恢复:它仅识别实时路径中捕获的原始目录实体,并且从不采用重新创建的替换目录。
仅对象恢复还为新分配的目录实例保留版本化的本机 Git 恢复收据。它以原子方式发布完整的文件和原始索引,而本机 Git 锁则通过注册表最终确定排除暂存和 HEAD 编写器。中断后重试相同的恢复命令;它仅恢复收据拥有的目录并保留更改或替换的源。发布确切的索引是恢复提交点:该点之后重试将保留后续工作文件编辑,并且仅完成注册表清理。成功完成后,收据将被清除。在中断的快照过期后重试可以完成过期的注册表项,而无需猜测未知保留目录的身份。
快照使用 refs/openclaw/snapshots/exact-v1/<id> 和现有的 30 天保留所有者。将存储库对象、保留恢复签出和共享状态数据库放在一起。使用支持此选项的运行时;旧的恢复实现无法保留额外的索引状态。普通快照保留其现有行为。
如果本机归档移动完成但注册表最终确定被中断,请与原始请求进行协调和恢复:
恢复需要匹配已完成的捕获和未更改的所有者和记录的分支。恢复保留现有的删除声明,同时注册表仍然显示活动行,拒绝活动运行和新的运行准入,直到解决为止。重试识别出捕获的原始目录已经移回;它从不采用未知的占用路径。不一致的 source/registration 会保留所有恢复材料并拒绝覆盖它。列表和垃圾收集不会从丢失的原始路径中推断出已完全退出。保存未完成的来源和回收物以供检查;不要强制再次删除、重置索引、重新附加 HEAD 或删除注册。
CLI
Worktree CLI 突变使用经过身份验证的网关,该网关在运行时拥有选定的本地状态目录。这包括创建、普通、无损和精确状态删除、恢复、垃圾收集、中断删除恢复和快照退役。该路由需要 operator.admin,保留源配置文件和存储库设置,并且从不将本地路径重定向到已配置的远程网关。创建绑定捕获的repository目录;每个突变都会将请求与当前所有者的化身绑定在一起。
当网关拥有本地状态时,worktrees list 通过只读工作程序检查注册表并保持其行不变。缺失的结帐在表中显示为退休候选人,并在 retirementCandidates 和 --json 中显示为 ID;这些意见并不授权删除。离线列表保留了专有的国家所有权,因为它可以消除丢失的结帐。协调会等待每个结帐的突变租约,并在记录退休之前重新读取其注册表记录和路径,因此在列表等待期间恢复的结帐仍保持活动状态。
每个操作都需要其自己支持的参数和结果契约。支持路由创建的网关仍然可能缺少路由删除或恢复。所有者变更、能力缺失、身份验证失败或不确定的回复永远不会触发本地突变。升级较旧的网关或通过其服务所有者停止它并离线重试。收到不确定的答复后,请在重试之前检查 worktrees list --json、源存储库以及任何报告的恢复路径。确切状态 JSON 文件由 CLI 验证并作为请求数据发送,而不是作为客户端本地文件名发送。
离线突变通过 Git 工作、数据库结算和清理(包括中断)拥有唯一的状态目录生命周期所有权。在该操作期间启动的网关等待或报告所有权争用。 SDK 工作区和工作树功能保留其现有的所有权边界;这并不排除任意直接编写者或共享外部文件的不同状态根。更新程序和医生保留其现有所有者,并且不需要此路由功能来升级旧安装。不需要架构或配置迁移。
本地状态所有者合约列出了每个所需的能力、拒绝状态和保留的写入者边界。
设置下的 Control UI Worktrees 页面提供了带有基本分支选择器的创建、普通删除和恢复以及垃圾收集。它显示每个工作树的所有者(手册、工作板或带有聊天链接的拥有会话),并在删除报告失败的快照时提供强制重试。
将 Base 分支 留空以获取并使用远程默认分支。分支建议不选择基数;选择或输入分支或提交使用该确切的引用而不进行提取。清除该字段将恢复自动选择。自动选择还会快进一个干净的、严格较旧的本地默认分支。失败的提取使用缓存的远程默认值并带有警告;不可用的远程默认值需要显式引用。
--if-lossless --json 返回 removed 加上记录的 cleanup 结果。保留结帐返回 removed: false;这不是一个成功的删除。合格的网关移除合同保留了这一结果。
通过正在运行的本地网关,openclaw worktrees gc 将后台清理排队并打印其收据以及检查进度的命令:
--json 打印收据,包括作业状态和当前清理摘要。轮询会观察作业,而无需启动另一遍。当作业排队或运行时发出的入队请求返回同一作业;仅保留最新的作业,并且重新启动网关会丢弃其收据。要强制重新检查未更改的延迟签出,请在任何当前作业完成后使用 --retry-deferred 启动新作业。
对于部分克隆,openclaw worktrees gc --retry-deferred 还会在尝试清理之前检查所有 Git 注册的工作树索引和当前 HEAD 树所需的对象。它以有限的批次从现有的承诺者远程获取丢失的对象,保留暂存文件和工作文件。历史提交仍然被过滤,并且普通的后台维护不会获取。 Repair 的预算为 5 分钟,每次传递的对象限制为 4,096 个;已完成的获取不会受到中断。如果修复无法完成,维护会记录一条警告。恢复远程访问并再次运行该命令以从剩余的丢失对象中恢复。从远程无法获得的本地创建的对象仍然需要从另一个副本进行恢复。
网关 Git 检查也仅使用本地可用的对象。在部分克隆中,丢失的对象可能会使可选的签出、分支或差异事实不可用,而不是在读取期间下载包。显式获取、检出准备和请求的对象修复保留其传输行为。
UI 首选项和其他不相关的配置写入不会中断清理。对清理输入(例如工作树根或容量、代理工作区、会话存储或所有权以及沙箱模式)的更改会在下一次突变之前取消当前作业。开始新作业以使用更新的设置。
如果没有正在运行的本地网关,openclaw worktrees gc 将在独占本地状态所有权下运行清理直至完成,并返回完整的摘要。离线模式无法使用 --job 轮询网关作业。 CLI 在其输出中包含部分结果和恢复位置,并退出非零以进行部分清理。
Gateway 方法
| 方法 | 用途 |
|---|---|
worktrees.list |
列出活动的以及可恢复的 worktree 记录。 |
worktrees.branches |
列出仓库的本地和远程分支,用于 base-ref 选择器。 |
worktrees.create |
创建或复用一个命名的受管 worktree。 |
worktrees.remove |
为 worktree 生成快照并将其移除。强制移除会报告 snapshotError。 |
worktrees.restore |
从快照中恢复已移除的 worktree。 |
worktrees.gc |
排队后台清理或读取作业的进度。 |
worktrees.recoverRemoval |
从确切的挂起快照中完成中断的删除。 |
worktrees.retireSnapshot |
使用精确的保留源防护来淘汰一个冗余快照。 |
worktrees.list 需要 operator.read。 worktrees.create 和 worktrees.branches 需要 operator.write 来配置代理工作区和注册项目;任意主机路径仍然需要 operator.admin。所有创建都会禁用存储库 Git 挂钩;写范围创建也会跳过 .openclaw/worktree-setup.sh。删除、恢复和垃圾收集工作树仍然仅限于管理员。分支列表仅读取现有引用并且从不获取。在检查签出、引用、配置和对象存储元数据(包括具有大型包目录的存储库)后,将重用未更改的库存;更改的元数据会刷新库存。仅远程分支返回远程限定 (origin/feature-a),因此每个返回的名称都会解析为基本引用。 New Session 还可以从此方法请求类型化的存储库状态;普通目录或不可用的签出不返回任何分支,而不是强制 UI 从错误字符串推断 Git 功能。
所有者路由的请求需要 operator.admin 和相应的 capability。他们的线场和结果是:
| 方法 | 请求超出 expectedOwnerId |
结果 |
|---|---|---|
worktrees.create |
repoRoot;可选 name、baseRef、profiles、expectedRepoIdentity |
完整的工作树记录,包括任何 gcProtection。 CLI 在调度前捕获物理存储库身份。 |
worktrees.remove |
id;可选,互斥 force、ifLossless 或 exactState |
removed,可选snapshotRef、snapshotError、recoveryPath、recoveryRetainedUntil和无损cleanup。 |
worktrees.restore |
id;可选recoverExactState |
完整恢复的工作树记录。 |
worktrees.gc |
可选jobId进行轮询;排队新作业时可选 retryDeferred: true |
包含当前清理摘要的作业收据;见下文。 |
worktrees.recoverRemoval |
id、snapshot(预期待处理快照 OID) |
removed: true,可选snapshotRef。 |
worktrees.retireSnapshot |
id, expectedSnapshotRef, expectedSnapshotOid, expectedRemovedAt, retainedSourceRef, expectedRetainedSourceOid |
retired: true, id. |
exactState和recoverExactState携带经过验证的JSON对象,而不是文件路径:ownerKind(manual、session或workboard),可选ownerId, createdAt、lastActiveAt、head、branchHead 和 indexSha256。快照和头 OID 接受 40 或 64 个小写十六进制字符; indexSha256 为 64。快照停用还需要精确的删除时间戳以及 refs/heads/ 或 refs/remotes/ 下的保留引用。
worktrees.gc 立即返回 jobId、state(queued、running、completed 或 failed)、startedAt 和 completedAt(Unix 毫秒)或 null)和 error(失败消息或 null)。同一对象携带清理摘要:removed、orphansDeleted、orphansRetired、retiredCheckoutPaths、snapshotsPruned、outcome、issues、issueCount、protectedCount、 protectionReasons、evictions 和 limitsSatisfied。在排队或运行时,这些字段描述到目前为止的进度;检查 state 以确定作业是否完成。 outcome 描述清理结果(completed、deferred 或 partial),而不描述后台工作是否仍在运行。
在存储库管理期间,gitMaintenance 命名当前或最后一个 repoRoot 和 stage(packs、objects、maintenance、completed、suspended 或throttled)。当库存准备好时,它包括 packsBefore;当存储库的有界传递完成时,它包括 packsAfter。 packsRemoved 累积整个作业中已完成的包装减少量。这些计数与结账资格和移除计数是分开的。维修故障出现在issues,阶段为git-maintenance;正在运行的作业的初始 outcome 并不是完成的证明。
使用 worktrees.gc 和 { jobId: "<id>" } 进行轮询。丢失或替换的作业会返回错误;仅保留最新的职位。省略 jobId 会将新作业排队或返回当前的 queued/running 作业。 retryDeferred: true 开始新工作时要求重新检查;它不会重新启动正在进行的作业。
省略 expectedOwnerId 的旧 RPC 客户端保留没有 gcProtection 的公共记录,即原始删除字段(removed、snapshotRef、snapshotError)。对于这些客户端,快照失败将返回 removed: false 和 snapshotError。所有者路由的删除会将快照失败报告为错误。垃圾收集使用 all 客户端的后台收据,包括省略 expectedOwnerId 的客户端;在清理完成之前,它不再保留请求。依赖于已完成的 GC 响应的客户端必须轮询 jobId 并检查 state。恢复和退休方法始终需要所有者字段。部分或丢失的结果不允许重播突变。
Workboard 工作区
捆绑的 Workboard 插件 可以将卡片工作区实例化为受管理的工作树:
path 标识源 git 检出目录。branch 是可选的,并会成为基础引用。对于完整主机调用方,Workboard 会创建或复用 wb-<card-id>,以受管理的检出目录作为其工作目录运行子代理,并将解析后的路径和分支写回卡片。网关客户端需要 operator.admin 才能进行完整主机实例化。运行结束时,只有在可证明无损的情况下,Workboard 才会移除该检出目录;有未清理的工作内容或未推送的提交则会继续保留可用。
卡在调度中重复使用其保留的结帐,包括其原始基本参考和本地工作。如果您在签出仍然存在的情况下使用不同的显式基本引用重新指定卡,则调度会在启动工作程序之前报告不匹配并保留签出。即使结帐干净,它也不会重置或重新调整现有工作。使用原始的基础参考继续该工作,或创建一张新卡以从不同的基础开始。当分支名称前进时,重复使用或省略相同的引用不会刷新结帐。
对于工作区绑定的调用方,path 和存储库根必须与目标代理工作区完全匹配。然后,Workboard 直接在该目录中运行并记录目录工作区,而不是主机具体化托管工作树。目标必须为同一工作区使用可写、非共享的 Docker 沙箱,其实时容器哈希必须与请求的安装和策略匹配,并且不得公开提升的执行、主机控制、主机范围会话、持久的 host/node 执行或未分类的插件和 MCP 工具。如果目标策略或活动容器更广泛,则调度会使卡无人认领并报告不兼容状态。