布局和名称
每个工作树位于：[a-z0-9][a-z0-9-]{0,63}。如果未提供名称，OpenClaw 会生成一个易读的、以甲壳类动物为主题的名称，例如 brisk-lobster。如果推断出的名称已被任何已注册的 worktree（包括调用方自己已移除的检出）、本地分支或非受管路径占用，则会添加数字后缀，例如 brisk-lobster-2；只有提供的名称才会复用或恢复调用方已有的记录。
OpenClaw 会在请求的基础引用处创建分支 openclaw/<name>。如果没有基础引用，它会 fetch origin，在可用时使用远程默认分支；如果仓库离线或没有可用的远程，则回退到本地 HEAD。
提供被忽略的文件
在源仓库根目录添加.worktreeinclude，以将选定的被忽略、未跟踪文件复制到新的 worktree 中。该文件使用 gitignore 模式语法，每行一个模式，并支持 # 注释：
运行仓库设置
如果.openclaw/worktree-setup.sh 在源仓库中存在并且可执行，OpenClaw 会以新的工作树作为当前目录来运行它。该脚本接收：
会话工作树
从一个由 Git 支持的文件夹开始一个隔离的聊天，并使用工作树会话：在 Control UI 的 New session 页面中，使用 Place 选择器选择一个 Gateway 源文件夹，然后选择 Worktree（可选地指定基础分支和工作树名称）。当名称被省略时，OpenClaw 会根据显式会话标签或从第一条消息生成的简短标题来推导名称，然后再回退到一个以甲壳类动物为主题的名称。只有在 Gateway 确认所选文件夹是一个 Git 检出目录之后，该选项才会出现；普通文件夹会直接运行，并且不会显示 Git 隔离控制。iOS 会从 Chat actions 中暴露相同的选项，而 Android 会在 New Chat 旁边暴露它，当活动代理工作区由 Git 支持时。 Place 选择器的 Projects 部分可以从已注册的项目 ID 启动相同的工作树流程。Gateway 会解析记录的检出路径，因此该路径在operator.write 处仍然可用；选择任意主机文件夹仍需要 operator.admin。
Coding agents 还可以在发现当前任务之外已确认的后续工作时调用 suggest_task。Control UI 会显示一个建议标签，但不会启动任何操作，而由 Gateway 支持的 TUI 会显示一个包含相同操作的交互式提示。选择 Start in worktree 会从建议的项目创建一个全新的、归会话所有的工作树，并将自包含的提示作为其第一轮消息发送；忽略该建议会使仓库保持不变。建议及其 ID 是临时的，不会在 Gateway 重启后保留。
OpenClaw 仅向具有可操作 Gateway UI 的 operator 会话暴露这些工具。Channel 会话和本地/嵌入式 TUI 会话在这些界面具备可移植的类型化任务操作契约之前不会收到它们。
生成的受管工作树归该会话所有，且该会话中的每次代理运行都会使用它的检出版本。当工作区是仓库的子目录时，工作树会锚定在仓库根目录，且会话会从其中对应的子目录运行。会话工作树的创建使用该方法的 operator.write 范围，但仓库检出钩子和 .openclaw/worktree-setup.sh 步骤仅对 operator.admin 调用者运行，因为它们会执行仓库代码；.worktreeinclude 的预配仍适用于所有调用者。删除会话时，只有在无损的情况下才会移除工作树。脏工作树或包含未推送提交的分支会继续保留；每小时清理会在 7 天无活动后对会话工作树创建快照，并将最近的会话活动视为工作树活动。已移除的工作树可按下文所述从其快照中恢复。
sessions.create 可以包含绝对 cwd，以便直接在另一个 Gateway 文件夹中运行，选择源检出目录并同时使用 worktree: true，或设置配对节点的工作目录。具有 operator.write 的连接可以使用包含在任何已配置代理工作区中的 Gateway cwd；realpath 包含约束可以防止符号链接逃逸出该边界。位于这些工作区之外的 Gateway 路径，以及每个配对节点的工作目录，都需要 operator.admin。普通工作树聊天创建仍然使用 operator.write，并继续锚定在已配置的工作区中。
sessions.create 还接受与 worktree: true 一起使用的 worktreeBaseRef 和 worktreeName，以选择基础引用和工作树名称（分支将变为 openclaw/<name>）；两者仍保持在 operator.write。如果省略 worktreeName，会话标签或生成的首条消息标题会提供可读的分支名称，并带有一个以甲壳类动物为主题的回退名称。创建出的工作树会在创建结果中返回，并以 worktree: { id, branch, repoRoot } 的形式持久化到会话行中，因此会话列表可以显示检出信息和分支。删除会话时，如果保留了脏检出，会报告为 worktreePreserved，而不是默默地将其留在原处。
快照、清理和恢复
移除操作首先会创建一个合成提交，其中包含已跟踪文件和未被忽略的未跟踪文件，然后将其固定到refs/openclaw/snapshots/<id>。被忽略的文件绝不会进入仓库对象数据库。OpenClaw 仅在分块共享状态数据库行中存储其实际提供过的被忽略文件；即使 .worktreeinclude 之后发生更改或消失，记录的路径集合仍然具有权威性。恢复时会从不可变快照中读取这些字节，并重新应用其完整模式。如果快照创建失败，移除操作将停止。显式强制删除可以在没有快照的情况下继续。
OpenClaw 应用以下清理规则：
- 在运行结束时，只有当
git status --porcelain为空且git log HEAD --not --remotes --oneline没有找到未推送提交时，才会移除 worktree。否则只会释放活动锁。 - 每小时清理会为处于解锁状态、由 Workboard 和会话拥有、且空闲超过 7 天的 worktree 创建快照并将其移除，即使其内容有变更也是如此。手动 worktree 永远不会被自动移除。
- 快照记录在 30 天内仍可恢复。之后清理会删除快照引用和注册表行。
- 运行中的 OpenClaw 进程锁，以及任何外部或无法识别的 git worktree 锁，都会阻止 worktree 被垃圾回收。
openclaw worktrees list --json 或 worktrees.list 查看记录的结果。
恢复操作会在原始快照提交之前的提交上重新创建 openclaw/<name>，然后将快照差异重新构建为未暂存的修改和未跟踪文件。这样可以将合成快照提交排除在分支历史之外。快照引用仍会作为来源记录保留。
CLI
网关方法
worktrees.list 需要 operator.read，而修改状态的方法需要 operator.admin。对于已配置的 agent 工作区，worktrees.branches 需要 operator.write；而任何其他主机路径都需要 operator.admin（与 sessions.create 的 cwd 限制一致）。它只读取现有引用，绝不会 fetch，并且仅存在于远端的分支会以远端限定形式返回（origin/feature-a），因此每个返回的名称都可解析为 base ref。New Session 也可以通过此方法请求一个类型化的仓库状态；普通目录或不可用的 checkout 不会返回分支，而不是让 UI 通过错误字符串来推断 Git 能力。
Workboard 工作区
捆绑的 Workboard 插件 可以将卡片工作区实例化为受管理的工作树：path 标识源 git 检出目录。branch 是可选的，并会成为基础引用。对于完整主机调用方，Workboard 会创建或复用 wb-<card-id>，以受管理的检出目录作为其工作目录运行子代理，并将解析后的路径和分支写回卡片。网关客户端需要 operator.admin 才能进行完整主机实例化。运行结束时，只有在可证明无损的情况下，Workboard 才会移除该检出目录；有未清理的工作内容或未推送的提交则会继续保留可用。
对于绑定工作区的调用方，path 和仓库根目录必须与目标代理工作区完全匹配。此时，Workboard 会直接在该目录中运行，并记录目录工作区，而不是在主机上实例化受管理的工作树。目标必须对同一工作区使用可写、非共享的 Docker 沙箱，其实时容器哈希必须与请求的挂载和策略一致，并且不得暴露提升的执行权限、主机控制、主机范围会话、持久化的主机／节点执行，或未分类的插件和 MCP 工具。如果目标策略或实时容器范围更宽，分发会使卡片保持未认领状态，并报告不兼容的状态。