Managed worktrees

Managed worktrees 문서는 OpenClaw 공식 문서(concepts/managed-worktrees)를 한국어로 정리한 가이드입니다. Run agent tasks in isolated git checkouts with automatic snapshots and cleanup 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Run agent tasks in isolated git checkouts with automatic snapshots and cleanup

한국어 가이드 범위: concepts/managed-worktrees 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Layout and names
Provision ignored files
Run repository setup
Session worktrees
Snapshots, cleanup, and restore
CLI
Gateway methods
Workboard workspaces

상세 내용

본문

Managed worktrees give an agent task its own git branch and checkout without placing temporary directories inside the source repository. OpenClaw creates them under its state directory, records them in the shared state database, and snapshots their tracked and non-ignored untracked contents before removal.

Layout and names

The repository fingerprint is the first 16 hexadecimal characters of a SHA-256 hash over the canonical git common directory and origin URL. A supplied name must match [a-z0-9][a-z0-9-]{0,63}. Without a name, OpenClaw generates wt- followed by eight random hexadecimal characters.

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

Provision ignored files

Add .worktreeinclude at the source repository root to copy selected ignored, untracked files into a new worktree. The file uses gitignore-pattern syntax, one pattern per line, with # comments:

.env.local
fixtures/generated/**

Run repository setup

If .openclaw/worktree-setup.sh exists in the source repository and is executable, OpenClaw runs it with the new worktree as its current directory. The script receives:

OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>

Session worktrees

Start an isolated chat from a Git-backed folder with a worktree session: on the Control UI's New session page, use the Place picker to choose a Gateway source folder, then select Worktree (with an optional base branch and worktree name). The choice appears only after the Gateway confirms that the selected folder is a Git checkout; ordinary folders run directly and show no Git isolation control. iOS exposes the same choice from Chat actions, and Android exposes it beside New Chat, when the active agent workspace is Git-backed.

Snapshots, cleanup, and restore

Removal first creates a synthetic commit containing tracked and non-ignored untracked files, then pins it at refs/openclaw/snapshots/. Ignored files never enter the repository object database. OpenClaw stores only the ignored files it actually provisioned in chunked shared-state database rows; the recorded path set remains authoritative even if .worktreeinclude later changes or disappears. Restore reads those bytes from the immutable snapshot and reapplies their complete modes. Automatic cleanup preserves a live worktree when a recorded path can no longer be snapshotted safely. If snapshot creation fails, removal stops. An explicit force delete can continue without a snapshot.

주요 항목:

At run end, it removes a worktree only when git status --porcelain is empty and git log HEAD --not --remotes --oneline finds no unpushed commits. Otherwise it only releases the activity lock.
Hourly cleanup snapshots and removes unlocked Workboard- and session-owned worktrees idle for more than 7 days, even when dirty. Manual worktrees are never automatically removed.
Snapshot records remain restorable for 30 days. Cleanup then deletes the snapshot ref and registry row.
A live OpenClaw process lock and any foreign or unrecognized git worktree lock protect a worktree from garbage collection.

CLI

The Control UI Worktrees page under Settings provides the same actions plus creation with a base-branch picker, shows each worktree's owner (manual, Workboard, or the owning session with a link into its chat), and offers a force retry when a removal reports a failed snapshot.

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]

Gateway methods

worktrees.list requires operator.read, and the mutating methods require operator.admin. worktrees.branches needs operator.write for configured agent workspaces, while any other host path requires operator.admin (matching the sessions.create cwd bar). It reads existing refs only and never fetches, and remote-only branches come back remote-qualified (origin/feature-a) so every returned name resolves as a base ref. New Session can also request a typed repository status from this method; a plain directory or unavailable checkout returns no branches instead of forcing the UI to infer Git capability from an error string.

Method	Purpose
`worktrees.list`	List active and restorable worktree records.
`worktrees.branches`	List local and remote branches of a repository for base-ref pickers.
`worktrees.create`	Create or reuse a named managed worktree.
`worktrees.remove`	Snapshot and remove a worktree. Forced removals report `snapshotError`.
`worktrees.restore`	Restore a removed worktree from its snapshot.
`worktrees.gc`	Run idle, orphan, and retention cleanup now.

Workboard workspaces

The bundled Workboard plugin can materialize a card workspace as a managed worktree:

{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/managed-worktrees
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

.env.local
fixtures/generated/**

OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>

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]

{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}

Managed worktrees

핵심 요약

Run agent tasks in isolated git checkouts with automatic snapshots and cleanup

한국어 가이드 범위: concepts/managed-worktrees 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Layout and names
Provision ignored files
Run repository setup
Session worktrees
Snapshots, cleanup, and restore
CLI
Gateway methods
Workboard workspaces

상세 내용

본문

Layout and names

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

Provision ignored files

Add .worktreeinclude at the source repository root to copy selected ignored, untracked files into a new worktree. The file uses gitignore-pattern syntax, one pattern per line, with # comments:

.env.local
fixtures/generated/**

Run repository setup

If .openclaw/worktree-setup.sh exists in the source repository and is executable, OpenClaw runs it with the new worktree as its current directory. The script receives:

OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>

Session worktrees

Snapshots, cleanup, and restore

주요 항목:

At run end, it removes a worktree only when git status --porcelain is empty and git log HEAD --not --remotes --oneline finds no unpushed commits. Otherwise it only releases the activity lock.
Hourly cleanup snapshots and removes unlocked Workboard- and session-owned worktrees idle for more than 7 days, even when dirty. Manual worktrees are never automatically removed.
Snapshot records remain restorable for 30 days. Cleanup then deletes the snapshot ref and registry row.
A live OpenClaw process lock and any foreign or unrecognized git worktree lock protect a worktree from garbage collection.

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]

Gateway methods

Method	Purpose
`worktrees.list`	List active and restorable worktree records.
`worktrees.branches`	List local and remote branches of a repository for base-ref pickers.
`worktrees.create`	Create or reuse a named managed worktree.
`worktrees.remove`	Snapshot and remove a worktree. Forced removals report `snapshotError`.
`worktrees.restore`	Restore a removed worktree from its snapshot.
`worktrees.gc`	Run idle, orphan, and retention cleanup now.

Workboard workspaces

The bundled Workboard plugin can materialize a card workspace as a managed worktree:

{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/managed-worktrees
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

<openclaw-state-dir>/worktrees/<repo-fingerprint>/<name>

.env.local
fixtures/generated/**

OPENCLAW_SOURCE_TREE_PATH=<source checkout>
OPENCLAW_WORKTREE_PATH=<managed worktree>

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]

{
  "kind": "worktree",
  "path": "/absolute/path/to/source-checkout",
  "branch": "main"
}

Managed worktrees

핵심 요약

문서 구성

상세 내용

본문

Layout and names

Provision ignored files

Run repository setup

Session worktrees

Snapshots, cleanup, and restore

CLI

Gateway methods

Workboard workspaces

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Managed worktrees

핵심 요약

문서 구성

상세 내용

본문

Layout and names

Provision ignored files

Run repository setup

Session worktrees

Snapshots, cleanup, and restore

CLI

Gateway methods

Workboard workspaces

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드