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

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

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

​
Подготовка игнорируемых файлов

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

​
Запуск настройки репозитория

Если .openclaw/worktree-setup.sh существует в исходном репозитории и является исполняемым, OpenClaw запускает его, используя новое рабочее дерево как текущий каталог. Скрипт получает:
Ненулевой код завершения прерывает создание и удаляет новое рабочее дерево и ветку. Это локальный контракт репозитория; ключа конфигурации 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 дней, даже при наличии изменений. Рабочие деревья, созданные вручную, никогда не удаляются автоматически.
  • Если настроен worktrees.cleanup.maxCount или worktrees.cleanup.maxTotalSizeGb, очистка также создаёт снимки и удаляет рабочие деревья Workboard и сеансов с самой давней активностью, пока общее количество и размер на диске не будут соответствовать ограничениям. Все управляемые рабочие деревья учитываются в итоговых значениях, но созданные вручную и иным образом защищённые рабочие деревья никогда не удаляются из-за превышения ограничений, поэтому ограничение может оставаться превышенным до появления подходящих для удаления рабочих деревьев. Значение 0 или отсутствие значения отключает ограничение.
  • Записи снимков остаются доступными для восстановления в течение 30 дней. После этого очистка удаляет ссылку снимка и строку реестра.
  • Блокировка активного процесса OpenClaw и любая сторонняя или нераспознанная блокировка рабочего дерева git защищают рабочее дерево от сборки мусора.
Восстановление повторно создаёт openclaw/<name> на исходном коммите до снимка, а затем воссоздаёт различия снимка как неподготовленные изменения и неотслеживаемые файлы. Благодаря этому синтетический коммит снимка не попадает в историю ветки. Ссылка снимка сохраняется как запись о происхождении.

​
CLI

Страница Рабочие деревья в разделе Settings интерфейса Control UI предоставляет те же действия, а также создание с выбором базовой ветки, показывает владельца каждого рабочего дерева (создано вручную, Workboard или владеющий сеанс со ссылкой на его чат) и предлагает принудительную повторную попытку, если при удалении сообщается об ошибке создания снимка. В разделе Очистка можно изменить ограничения хранения worktrees.cleanup, описанные в справочнике по конфигурации.

​
Методы Gateway

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

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

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