> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Управляемые рабочие деревья Управляемые рабочие деревья предоставляют задаче агента отдельную ветку git и рабочую копию, не размещая временные каталоги внутри исходного репозитория. OpenClaw создаёт их в своём каталоге состояния, регистрирует в общей базе данных состояния и перед удалением создаёт снимки их отслеживаемого и неигнорируемого неотслеживаемого содержимого. ## Структура и имена Каждое рабочее дерево располагается по адресу: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} /worktrees// ``` Отпечаток репозитория — первые 16 шестнадцатеричных символов хеша SHA-256, вычисленного для канонического общего каталога git и URL origin. Указанное имя должно соответствовать `[a-z0-9][a-z0-9-]{0,63}`. Если имя не указано, OpenClaw генерирует `wt-`, за которым следуют восемь случайных шестнадцатеричных символов. OpenClaw создаёт ветку `openclaw/` на запрошенной базовой ссылке. Если базовая ссылка не указана, он получает `origin`, использует удалённую ветку по умолчанию, когда она доступна, и возвращается к локальной `HEAD`, когда репозиторий работает автономно или не имеет пригодного удалённого репозитория. ## Подготовка игнорируемых файлов Добавьте `.worktreeinclude` в корень исходного репозитория, чтобы копировать выбранные игнорируемые неотслеживаемые файлы в новое рабочее дерево. Файл использует синтаксис шаблонов gitignore: по одному шаблону на строку, с комментариями `#`: ```gitignore theme={"theme":{"light":"min-light","dark":"min-dark"}} .env.local fixtures/generated/** ``` Копироваться могут только файлы, которые git определяет одновременно как игнорируемые и неотслеживаемые. Отслеживаемые файлы уже присутствуют благодаря git и на этом этапе никогда не копируются. OpenClaw не перезаписывает файлы назначения, не следует по каталогам, являющимся символическими ссылками, и сохраняет режимы скопированных файлов. ## Запуск настройки репозитория Если `.openclaw/worktree-setup.sh` существует в исходном репозитории и является исполняемым, OpenClaw запускает его, используя новое рабочее дерево как текущий каталог. Скрипт получает: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_SOURCE_TREE_PATH= OPENCLAW_WORKTREE_PATH= ``` Ненулевой код завершения прерывает создание и удаляет новое рабочее дерево и ветку. Это локальный контракт репозитория; ключа конфигурации 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/`); оба остаются на уровне `operator.write`. Созданное рабочее дерево возвращается в результате создания и сохраняется в строке сеанса как `worktree: { id, branch, repoRoot }`, поэтому списки сеансов могут отображать рабочую копию и ветку. При удалении сеанса сохранённая рабочая копия с изменениями указывается как `worktreePreserved`, а не молча оставляется без внимания. ## Снимки, очистка и восстановление Перед удалением создаётся синтетический коммит, содержащий отслеживаемые и неигнорируемые неотслеживаемые файлы, и закрепляется по ссылке `refs/openclaw/snapshots/`. Игнорируемые 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/` на исходном коммите до снимка, а затем воссоздаёт различия снимка как неподготовленные изменения и неотслеживаемые файлы. Благодаря этому синтетический коммит снимка не попадает в историю ветки. Ссылка снимка сохраняется как запись о происхождении. ## CLI ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw worktrees list [--json] openclaw worktrees create [--name ] [--base-ref ] [--json] openclaw worktrees remove [--force] [--json] openclaw worktrees restore [--json] openclaw worktrees gc [--json] ``` Страница **Рабочие деревья** в разделе Settings интерфейса Control UI предоставляет те же действия, а также создание с выбором базовой ветки, показывает владельца каждого рабочего дерева (создано вручную, Workboard или владеющий сеанс со ссылкой на его чат) и предлагает принудительную повторную попытку, если при удалении сообщается об ошибке создания снимка. В разделе **Очистка** можно изменить ограничения хранения `worktrees.cleanup`, описанные в [справочнике по конфигурации](/ru/gateway/configuration-reference#worktrees). ## Методы Gateway | Метод | Назначение | | -------------------- | --------------------------------------------------------------------------------------------------- | | `worktrees.list` | Вывод активных и доступных для восстановления записей рабочих деревьев. | | `worktrees.branches` | Вывод локальных и удалённых веток репозитория для средств выбора базовой ссылки. | | `worktrees.create` | Создание или повторное использование именованного управляемого рабочего дерева. | | `worktrees.remove` | Создание снимка и удаление рабочего дерева. При принудительном удалении сообщается `snapshotError`. | | `worktrees.restore` | Восстановление удалённого рабочего дерева из его снимка. | | `worktrees.gc` | Немедленный запуск очистки по бездействию, потерянным владельцам и правилам хранения. | Для `worktrees.list` требуется `operator.read`, а для методов, изменяющих состояние, требуется `operator.admin`. Для `worktrees.branches` необходим `operator.write` в настроенных рабочих пространствах агента, тогда как для любого другого пути на хосте требуется `operator.admin` (в соответствии с ограничением cwd `sessions.create`). Метод только считывает существующие ссылки и никогда не выполняет получение данных, а ветки, существующие только в удалённом репозитории, возвращаются с указанием удалённого репозитория (`origin/feature-a`), чтобы каждое возвращённое имя разрешалось как базовая ссылка. ## Рабочие пространства Workboard Встроенный [плагин Workboard](/ru/plugins/workboard) может материализовать рабочее пространство карточки как управляемое рабочее дерево: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "kind": "worktree", "path": "/absolute/path/to/source-checkout", "branch": "main" } ``` `path` определяет исходную рабочую копию git. `branch` является необязательным и становится базовой ссылкой. Когда диспетчеризация запускает исполнителя карточки, Workboard создаёт или повторно использует `wb-`, запускает субагента с управляемой рабочей копией в качестве рабочего каталога и записывает разрешённый путь и ветку обратно в карточку. Для материализации, запущенной через Gateway, требуется `operator.admin`. По завершении запуска Workboard удаляет рабочую копию только тогда, когда гарантированно не произойдёт потери данных; изменения или неотправленные коммиты остаются доступными. Встроенные агенты в песочнице сейчас отклоняют рабочий каталог задачи, находящийся за пределами настроенного рабочего пространства агента. Используйте целевого агента без песочницы для карточек Workboard с управляемыми рабочими деревьями, пока среда выполнения песочницы не начнёт поддерживать дополнительное монтирование рабочей копии.