Керовані робочі дерева

Керовані робочі дерева надають завданню агента окрему гілку 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> на основі запитаного базового посилання. Якщо базове посилання не вказано, він отримує дані з 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-робочого простору активного агента за допомогою сеансу на основі робочого дерева: увімкніть Worktree на сторінці New session в Control UI (де також доступні вибір базової гілки та необов’язкова назва робочого дерева) або скористайтеся меню дій Chat в iOS чи додатковою дією поруч із New Chat в Android. Цей параметр доступний лише для агента на основі git, якщо клієнт має відповідну можливість; клієнти, які не можуть виконати попередню перевірку, натомість показують помилку Gateway.

Агенти програмування також можуть викликати spawn_task, коли виявляють підтверджену подальшу роботу поза межами поточного завдання. Control UI показує чип пропозиції, нічого не запускаючи, а TUI на основі Gateway показує інтерактивний запит із тими самими діями. Вибір Start in worktree створює нове робоче дерево, що належить сеансу, із запропонованого проєкту та надсилає самодостатній запит як його перший хід; відхилення пропозиції не змінює репозиторій. Пропозиції та їхні ідентифікатори є тимчасовими й не зберігаються після перезапуску 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]

Сторінка Worktrees в розділі Settings у 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 із керованими робочими деревами, доки середовище виконання пісочниці не підтримуватиме додаткове монтування робочої копії.