Управляемые рабочие деревья

Управляемые рабочие деревья предоставляют задаче агента отдельную ветку git и отдельную рабочую копию, не размещая временные каталоги внутри исходного репозитория. OpenClaw создаёт их в своём каталоге состояния, регистрирует в общей базе данных состояния и перед удалением сохраняет снимок отслеживаемого содержимого и неигнорируемых неотслеживаемых файлов.

Структура и имена

Каждое рабочее дерево располагается по адресу:

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

Отпечаток репозитория — первые 16 шестнадцатеричных символов SHA-256-хеша, вычисленного по каноническому общему каталогу git и URL-адресу origin. Заданное имя должно соответствовать шаблону [a-z0-9][a-z0-9-]{0,63}. Если имя не задано, OpenClaw генерирует wt-, за которым следуют восемь случайных шестнадцатеричных символов.

OpenClaw создаёт ветку openclaw/<name> на основе указанной базовой ссылки. Если базовая ссылка не задана, OpenClaw извлекает данные из origin, использует ветку по умолчанию удалённого репозитория, если она доступна, и возвращается к локальному HEAD, если репозиторий находится вне сети или не имеет пригодного удалённого репозитория.

Добавление игнорируемых файлов

Добавьте .worktreeinclude в корень исходного репозитория, чтобы копировать выбранные игнорируемые неотслеживаемые файлы в новое рабочее дерево. Файл использует синтаксис шаблонов gitignore: по одному шаблону в строке, с комментариями #:

.env.localfixtures/generated/**

Подходят только файлы, которые git определяет одновременно как игнорируемые и неотслеживаемые. Отслеживаемые файлы уже присутствуют благодаря git и никогда не копируются на этом этапе. OpenClaw не перезаписывает файлы назначения, не переходит по символическим ссылкам на каталоги и сохраняет режимы скопированных файлов.

Выполнение настройки репозитория

Если в исходном репозитории существует исполняемый файл .openclaw/worktree-setup.sh, OpenClaw запускает его, используя новое рабочее дерево в качестве текущего каталога. Скрипт получает:

OPENCLAW_SOURCE_TREE_PATH=<source checkout>OPENCLAW_WORKTREE_PATH=<managed worktree>

Ненулевой код завершения прерывает создание и удаляет новое рабочее дерево и ветку. Это локальный контракт репозитория; ключ конфигурации OpenClaw для него отсутствует.

Рабочие деревья сеансов

Чтобы начать изолированный чат из рабочего пространства git активного агента с сеансом на основе рабочего дерева, включите Рабочее дерево на странице создания сеанса в Control UI, где также доступны выбор базовой ветки и необязательное имя рабочего дерева, либо воспользуйтесь меню действий чата в iOS или дополнительным действием рядом с New Chat в Android. Этот параметр доступен только для агента на основе git, если клиент поддерживает такую возможность; клиенты, которые не могут выполнить предварительную проверку, вместо этого отображают ошибку Gateway.

Агенты программирования также могут вызывать spawn_task, когда обнаруживают подтверждённую последующую работу за пределами текущей задачи. Control UI показывает метку с предложением, ничего не запуская, а TUI на основе Gateway показывает интерактивный запрос с теми же действиями. При выборе Запустить в рабочем дереве создаётся новое рабочее дерево, принадлежащее сеансу, на основе предложенного проекта, а автономное описание задачи отправляется в качестве первого сообщения; отклонение предложения оставляет репозиторий без изменений. Предложения и их идентификаторы эфемерны и не сохраняются после перезапуска Gateway.

OpenClaw предоставляет эти инструменты только операторским сеансам с интерактивным интерфейсом Gateway. Сеансы каналов и локальные или встроенные сеансы TUI не получают их, пока для этих интерфейсов не появится переносимый типизированный контракт действий с задачами.

Полученное управляемое рабочее дерево принадлежит сеансу, и каждый запуск агента в этом сеансе использует его рабочую копию. Если рабочее пространство является подкаталогом репозитория, рабочее дерево привязывается к корню репозитория, а сеанс запускается из соответствующего подкаталога внутри него. Для создания рабочего дерева сеанса используется область действия метода operator.write, но этап .openclaw/worktree-setup.sh выполняется только для вызывающих сторон с operator.admin, поскольку он запускает код репозитория; добавление файлов через .worktreeinclude по-прежнему применяется для каждой вызывающей стороны. При удалении сеанса рабочее дерево удаляется только тогда, когда это можно сделать без потерь. Изменённые рабочие деревья или ветки с неотправленными коммитами остаются доступными; ежечасная очистка создаёт снимки рабочих деревьев сеансов после 7 дней бездействия, считая недавнюю активность сеанса активностью рабочего дерева. Удалённые рабочие деревья можно восстановить из их снимков, как описано ниже.

sessions.create может включать абсолютный cwd вместе с worktree: true, когда задача относится к проекту, отличному от настроенного рабочего пространства агента. Для такого явно указанного пути на узле требуется operator.admin; обычное создание чата с рабочим деревом по-прежнему требует operator.write и остаётся привязанным к настроенному рабочему пространству.

sessions.create также принимает worktreeBaseRef и worktreeName вместе с worktree: true для выбора базовой ссылки и имени рабочего дерева — ветка получает имя openclaw/<name>; для обоих параметров достаточно operator.write. Созданное рабочее дерево возвращается в результате создания и сохраняется в строке сеанса как worktree: { id, branch, repoRoot }, поэтому списки сеансов могут отображать рабочую копию и ветку. При удалении сеанса сохранённая изменённая рабочая копия указывается как worktreePreserved, а не молча оставляется без уведомления.

Снимки, очистка и восстановление

Перед удалением создаётся синтетический коммит, содержащий отслеживаемые файлы и неигнорируемые неотслеживаемые файлы, и закрепляется по ссылке refs/openclaw/snapshots/<id>. Игнорируемые git файлы исключаются из базы объектов репозитория; файлы, выбранные через .worktreeinclude, повторно копируются при восстановлении. Если создать снимок не удаётся, удаление прекращается. Явное принудительное удаление может продолжиться без снимка.

OpenClaw применяет следующие правила очистки:

• По завершении запуска рабочее дерево удаляется только тогда, когда вывод git status --porcelain пуст и команда git log HEAD --not --remotes --oneline не находит неотправленных коммитов. В противном случае снимается только блокировка активности.
• Ежечасная очистка создаёт снимки и удаляет разблокированные рабочие деревья, принадлежащие Workboard и сеансам, если они бездействуют более 7 дней, даже при наличии изменений. Созданные вручную рабочие деревья никогда не удаляются автоматически.
• Записи снимков можно восстанавливать в течение 30 дней. После этого очистка удаляет ссылку снимка и строку реестра.
• Блокировка активного процесса OpenClaw и любая сторонняя или нераспознанная блокировка рабочего дерева git защищают рабочее дерево от сборки мусора.

При восстановлении заново создаётся openclaw/<name> на исходном коммите, предшествующем снимку, после чего различия из снимка воссоздаются как неиндексированные изменения и неотслеживаемые файлы. Благодаря этому синтетический коммит снимка не попадает в историю ветки. Ссылка снимка продолжает храниться как запись о происхождении.

CLI

openclaw worktrees list [--json]openclaw worktrees create <repo-root> [--name <name>] [--base-ref <ref>] [--json]openclaw worktrees remove <id> [--force] [--json]openclaw worktrees restore <id> [--json]openclaw worktrees gc [--json]

Страница Рабочие деревья в разделе настроек Control UI предоставляет те же действия, а также создание с выбором базовой ветки, показывает владельца каждого рабочего дерева — создано вручную, принадлежит Workboard или владеющему сеансу со ссылкой на его чат — и предлагает принудительную повторную попытку, если при удалении не удалось создать снимок.

Методы Gateway

Для worktrees.list требуется operator.read, а для методов, изменяющих состояние, — operator.admin. Для worktrees.branches требуется operator.write при работе с настроенными рабочими пространствами агента, тогда как для любого другого пути на узле требуется operator.admin, что соответствует требованиям sessions.create к cwd. Метод только читает существующие ссылки и никогда не извлекает данные из удалённого репозитория, а ветки, существующие только в удалённом репозитории, возвращаются с указанием удалённого репозитория (origin/feature-a), чтобы каждое возвращённое имя можно было использовать как базовую ссылку.

Рабочие пространства Workboard

Встроенный Plugin Workboard может материализовать рабочее пространство карточки как управляемое рабочее дерево:

{  "kind": "worktree",  "path": "/absolute/path/to/source-checkout",  "branch": "main"}

path указывает исходную рабочую копию git. branch является необязательным и становится базовой ссылкой. Когда диспетчеризация запускает обработчик карточки, Workboard создаёт или повторно использует wb-<card-id>, запускает субагента, используя управляемую рабочую копию в качестве рабочего каталога, и записывает разрешённый путь и ветку обратно в карточку. Для материализации, запускаемой через Gateway, требуется operator.admin. По завершении запуска Workboard удаляет рабочую копию только тогда, когда доказано, что это не приведёт к потерям; изменённая работа или неотправленные коммиты остаются доступными.

Встроенные агенты в песочнице в настоящее время отклоняют рабочий каталог задачи, находящийся за пределами настроенного рабочего пространства агента. Используйте целевого агента без песочницы для карточек Workboard с управляемыми рабочими деревьями, пока среда выполнения песочницы не начнёт поддерживать дополнительное подключение рабочей копии.