Indeling en namen
Elke worktree bevindt zich op:[a-z0-9][a-z0-9-]{0,63}. Zonder naam genereert OpenClaw wt-, gevolgd door acht willekeurige hexadecimale tekens.
OpenClaw maakt branch openclaw/<name> aan op de aangevraagde basisreferentie. Zonder basisreferentie haalt het origin op, gebruikt het indien beschikbaar de standaardbranch van de remote en valt het terug op lokale HEAD wanneer de repository offline is of geen bruikbare remote heeft.
Genegeerde bestanden beschikbaar stellen
Voeg.worktreeinclude toe aan de hoofdmap van de bronrepository om geselecteerde genegeerde, niet-bijgehouden bestanden naar een nieuwe worktree te kopiëren. Het bestand gebruikt syntaxis voor gitignore-patronen, één patroon per regel, met #-opmerkingen:
Repository-installatie uitvoeren
Als.openclaw/worktree-setup.sh in de bronrepository bestaat en uitvoerbaar is, voert OpenClaw het uit met de nieuwe worktree als huidige map. Het script ontvangt:
Sessieworktrees
Start een geïsoleerde chat vanuit een map die door Git wordt beheerd met een worktreesessie: gebruik op de pagina Nieuwe sessie van de Control UI de kiezer Plaats om een bronmap van de Gateway te kiezen en selecteer vervolgens Worktree (met optioneel een basisbranch en worktreenaam). De keuze verschijnt pas nadat de Gateway heeft bevestigd dat de geselecteerde map een Git-checkout is; gewone mappen worden rechtstreeks uitgevoerd en tonen geen besturingselement voor Git-isolatie. iOS biedt dezelfde keuze via Chatacties en Android naast Nieuwe chat, wanneer de actieve agentwerkruimte door Git wordt beheerd. Coderingsagents kunnen ookspawn_task aanroepen wanneer ze bevestigd vervolgwerk buiten de huidige taak ontdekken. De Control UI toont een suggestiechip zonder iets te starten, terwijl een door de Gateway ondersteunde TUI een interactieve prompt met dezelfde acties toont. Als je Starten in worktree selecteert, wordt een nieuwe sessiegebonden worktree vanuit het voorgestelde project aangemaakt en wordt de zelfstandige prompt als eerste beurt verzonden; als je de suggestie afwijst, blijft de repository ongewijzigd. Suggesties en hun ID’s zijn tijdelijk en blijven niet behouden na een herstart van de Gateway.
OpenClaw stelt deze tools alleen beschikbaar aan operatorsessies met een bruikbare Gateway-UI. Kanaalsessies en lokale/ingesloten TUI-sessies ontvangen ze pas wanneer die oppervlakken over een overdraagbaar, getypeerd contract voor taakacties beschikken.
De resulterende beheerde worktree is eigendom van de sessie en elke agentuitvoering in die sessie gebruikt de checkout ervan. Wanneer de werkruimte een submap van een repository is, wordt de worktree verankerd in de hoofdmap van de repository en wordt de sessie uitgevoerd vanuit de overeenkomstige submap daarin. Voor het aanmaken van een sessieworktree wordt het operator.write-bereik van de methode gebruikt, maar repository-checkouthooks en de stap .openclaw/worktree-setup.sh worden alleen uitgevoerd voor operator.admin-aanroepers omdat ze repositorycode uitvoeren; het beschikbaar stellen via .worktreeinclude geldt nog steeds voor elke aanroeper. Als je de sessie verwijdert, wordt de worktree alleen verwijderd wanneer dit zonder verlies kan. Vuile worktrees of branches met niet-gepushte commits blijven beschikbaar; de uurlijkse opschoning maakt na 7 inactieve dagen snapshots van sessieworktrees, waarbij recente sessieactiviteit als worktreeactiviteit telt. Verwijderde worktrees kunnen vanuit hun snapshots worden hersteld zoals hieronder beschreven.
sessions.create kan een absoluut cwd bevatten om rechtstreeks in een andere Gateway-map uit te voeren, om samen met worktree: true de broncheckout te kiezen of om de werkmap van een gekoppelde Node in te stellen. Elk expliciet hostpad vereist operator.admin; het gewone aanmaken van worktreechats blijft operator.write en blijft verankerd in de geconfigureerde werkruimte.
sessions.create accepteert naast worktree: true ook worktreeBaseRef en worktreeName om de basisreferentie en de worktreenaam te kiezen (de branch wordt openclaw/<name>); beide blijven op operator.write. De aangemaakte worktree wordt geretourneerd in het aanmaakresultaat en als worktree: { id, branch, repoRoot } opgeslagen in de sessierij, zodat sessielijsten de checkout en branch kunnen tonen. Bij het verwijderen van een sessie wordt een behouden vuile checkout als worktreePreserved gemeld in plaats van deze stilzwijgend achter te laten.
Snapshots, opschoning en herstel
Bij verwijdering wordt eerst een synthetische commit aangemaakt met bijgehouden en niet-genegeerde, niet-bijgehouden bestanden, waarna deze wordt vastgezet oprefs/openclaw/snapshots/<id>. Genegeerde bestanden komen nooit in de objectdatabase van de repository terecht. OpenClaw slaat alleen de genegeerde bestanden die het daadwerkelijk beschikbaar heeft gesteld op in opgesplitste rijen van de gedeelde statusdatabase; de geregistreerde verzameling paden blijft gezaghebbend, zelfs als .worktreeinclude later verandert of verdwijnt. Bij herstel worden die bytes uit de onveranderlijke snapshot gelezen en worden hun volledige modi opnieuw toegepast. Automatische opschoning behoudt een actieve worktree wanneer van een geregistreerd pad niet langer veilig een snapshot kan worden gemaakt. Als het maken van de snapshot mislukt, stopt de verwijdering. Een expliciete geforceerde verwijdering kan zonder snapshot doorgaan.
OpenClaw past deze opschoningsregels toe:
- Aan het einde van een uitvoering verwijdert het een worktree alleen wanneer
git status --porcelainleeg is engit log HEAD --not --remotes --onelinegeen niet-gepushte commits vindt. Anders geeft het alleen de activiteitsvergrendeling vrij. - De uurlijkse opschoning maakt snapshots van ontgrendelde worktrees die eigendom zijn van Workboard of een sessie en langer dan 7 dagen inactief zijn, en verwijdert ze, zelfs wanneer ze vuil zijn. Handmatige worktrees worden nooit automatisch verwijderd.
- Snapshotrecords blijven 30 dagen herstelbaar. Daarna verwijdert de opschoning de snapshotreferentie en registerrij.
- Een actieve OpenClaw-procesvergrendeling en elke vreemde of niet-herkende git-worktreevergrendeling beschermen een worktree tegen garbagecollection.
openclaw/<name> opnieuw aangemaakt op de oorspronkelijke commit van vóór de snapshot, waarna de verschillen uit de snapshot opnieuw worden opgebouwd als niet-gestagede wijzigingen en niet-bijgehouden bestanden. Hierdoor blijft de synthetische snapshotcommit buiten de branchgeschiedenis. De snapshotreferentie blijft als herkomst geregistreerd.
CLI
Gateway-methoden
worktrees.list vereist operator.read en de wijzigende methoden vereisen operator.admin. worktrees.branches heeft operator.write nodig voor geconfigureerde agentwerkruimten, terwijl elk ander hostpad operator.admin vereist (overeenkomstig de cwd-drempel van sessions.create). Het leest alleen bestaande referenties en haalt nooit iets op, en branches die alleen op een remote bestaan, worden met remote-kwalificatie geretourneerd (origin/feature-a), zodat elke geretourneerde naam als basisreferentie kan worden herleid. Nieuwe sessie kan via deze methode ook een getypeerde repositorystatus aanvragen; een gewone map of niet-beschikbare checkout retourneert geen branches in plaats van de UI te dwingen Git-ondersteuning uit een fouttekst af te leiden.
Workboard-werkruimten
De meegeleverde Workboard-plugin kan een kaartwerkruimte als beheerde worktree materialiseren:path identificeert de Git-broncheckout. branch is optioneel en wordt de basisreferentie. Voor een aanroeper met volledige hosttoegang maakt of hergebruikt Workboard wb-<card-id>, voert het de subagent uit met de beheerde checkout als werkmap en schrijft het opgeloste pad en de branch terug naar de kaart. Gateway-clients hebben operator.admin nodig voor materialisatie met volledige hosttoegang. Aan het einde van een uitvoering verwijdert Workboard de checkout alleen wanneer aantoonbaar geen verlies optreedt; vuil werk of niet-gepushte commits blijven beschikbaar.
Voor een werkruimtegebonden aanroeper moeten path en de hoofdmap van de repository exact overeenkomen met de doelwerkruimte van de agent. Workboard wordt vervolgens rechtstreeks in die map uitgevoerd en registreert een mapwerkruimte in plaats van een beheerde worktree op de host te materialiseren. Het doel moet voor dezelfde werkruimte een beschrijfbare, niet-gedeelde Docker-sandbox gebruiken, de hash van de actieve container moet overeenkomen met de aangevraagde koppelingen en het beleid, en het doel mag geen verhoogde uitvoering, hostbeheer, hostbrede sessies, permanente host-/Node-uitvoering of niet-geclassificeerde Plugin- en MCP-tools beschikbaar stellen. Als het doelbeleid of de actieve container ruimere toegang biedt, laat de verzending de kaart niet-toegewezen en meldt deze de incompatibele status.