--- read_when: - Вам нужна изолированная ветка и рабочая копия для задачи агента - Вы настраиваете карточки Workboard с рабочими пространствами worktree - Вам необходимо восстановить или очистить рабочее дерево, управляемое OpenClaw summary: Запускайте задачи агента в изолированных рабочих копиях Git с автоматическим созданием снимков и очисткой title: Управляемые рабочие деревья x-i18n: generated_at: "2026-07-12T11:21:03Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 12a33dc2d9f1ff30060ddead200196b09cfe9498462f58a7aa8a73fa2273f31f source_path: concepts/managed-worktrees.md workflow: 16 --- Управляемые рабочие деревья предоставляют задаче агента отдельную ветку git и отдельную рабочую копию, не размещая временные каталоги внутри исходного репозитория. OpenClaw создаёт их в своём каталоге состояния, регистрирует в общей базе данных состояния и перед удалением сохраняет снимок отслеживаемого содержимого и неигнорируемых неотслеживаемых файлов. ## Структура и имена Каждое рабочее дерево располагается по адресу: ```text /worktrees// ``` Отпечаток репозитория — первые 16 шестнадцатеричных символов SHA-256-хеша, вычисленного по каноническому общему каталогу git и URL-адресу origin. Заданное имя должно соответствовать шаблону `[a-z0-9][a-z0-9-]{0,63}`. Если имя не задано, OpenClaw генерирует `wt-`, за которым следуют восемь случайных шестнадцатеричных символов. OpenClaw создаёт ветку `openclaw/` на основе указанной базовой ссылки. Если базовая ссылка не задана, OpenClaw извлекает данные из `origin`, использует ветку по умолчанию удалённого репозитория, если она доступна, и возвращается к локальному `HEAD`, если репозиторий находится вне сети или не имеет пригодного удалённого репозитория. ## Добавление игнорируемых файлов Добавьте `.worktreeinclude` в корень исходного репозитория, чтобы копировать выбранные игнорируемые неотслеживаемые файлы в новое рабочее дерево. Файл использует синтаксис шаблонов gitignore: по одному шаблону в строке, с комментариями `#`: ```gitignore .env.local fixtures/generated/** ``` Подходят только файлы, которые git определяет одновременно как игнорируемые и неотслеживаемые. Отслеживаемые файлы уже присутствуют благодаря git и никогда не копируются на этом этапе. OpenClaw не перезаписывает файлы назначения, не переходит по символическим ссылкам на каталоги и сохраняет режимы скопированных файлов. ## Выполнение настройки репозитория Если в исходном репозитории существует исполняемый файл `.openclaw/worktree-setup.sh`, OpenClaw запускает его, используя новое рабочее дерево в качестве текущего каталога. Скрипт получает: ```text 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 дней, даже при наличии изменений. Созданные вручную рабочие деревья никогда не удаляются автоматически. - Записи снимков можно восстанавливать в течение 30 дней. После этого очистка удаляет ссылку снимка и строку реестра. - Блокировка активного процесса OpenClaw и любая сторонняя или нераспознанная блокировка рабочего дерева git защищают рабочее дерево от сборки мусора. При восстановлении заново создаётся `openclaw/` на исходном коммите, предшествующем снимку, после чего различия из снимка воссоздаются как неиндексированные изменения и неотслеживаемые файлы. Благодаря этому синтетический коммит снимка не попадает в историю ветки. Ссылка снимка продолжает храниться как запись о происхождении. ## CLI ```bash openclaw worktrees list [--json] openclaw worktrees create [--name ] [--base-ref ] [--json] openclaw worktrees remove [--force] [--json] openclaw worktrees restore [--json] openclaw worktrees gc [--json] ``` Страница **Рабочие деревья** в разделе настроек Control UI предоставляет те же действия, а также создание с выбором базовой ветки, показывает владельца каждого рабочего дерева — создано вручную, принадлежит Workboard или владеющему сеансу со ссылкой на его чат — и предлагает принудительную повторную попытку, если при удалении не удалось создать снимок. ## Методы 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`, что соответствует требованиям `sessions.create` к `cwd`. Метод только читает существующие ссылки и никогда не извлекает данные из удалённого репозитория, а ветки, существующие только в удалённом репозитории, возвращаются с указанием удалённого репозитория (`origin/feature-a`), чтобы каждое возвращённое имя можно было использовать как базовую ссылку. ## Рабочие пространства Workboard Встроенный [Plugin Workboard](/ru/plugins/workboard) может материализовать рабочее пространство карточки как управляемое рабочее дерево: ```json { "kind": "worktree", "path": "/absolute/path/to/source-checkout", "branch": "main" } ``` `path` указывает исходную рабочую копию git. `branch` является необязательным и становится базовой ссылкой. Когда диспетчеризация запускает обработчик карточки, Workboard создаёт или повторно использует `wb-`, запускает субагента, используя управляемую рабочую копию в качестве рабочего каталога, и записывает разрешённый путь и ветку обратно в карточку. Для материализации, запускаемой через Gateway, требуется `operator.admin`. По завершении запуска Workboard удаляет рабочую копию только тогда, когда доказано, что это не приведёт к потерям; изменённая работа или неотправленные коммиты остаются доступными. Встроенные агенты в песочнице в настоящее время отклоняют рабочий каталог задачи, находящийся за пределами настроенного рабочего пространства агента. Используйте целевого агента без песочницы для карточек Workboard с управляемыми рабочими деревьями, пока среда выполнения песочницы не начнёт поддерживать дополнительное подключение рабочей копии.