ClawReverse

Recover from bad OpenClaw tool calls, restore known-good checkpoints, inspect session lineage, branch from earlier points, and save tokens by continuing from a checkpoint instead of rerunning. Use this skill when a user needs to undo mutations, restore a checkpoint, inspect branch structure, or create a child session without touching the parent. Do not use for plain git operations or non-OpenClaw workspaces.

intent

ClawReverse is a native OpenClaw plugin that adds checkpoint, rollback, continue, checkout, and lineage inspection to OpenClaw sessions. Use this skill when a user wants to recover from a bad tool call or unwanted file changes, restore a known-good checkpoint without rerunning, branch from an earlier point, inspect checkpoint lineage and rollback status, or save tokens after a long run by continuing from a checkpoint instead of starting over. Do not use this skill for normal git workflows, non-OpenClaw workspaces, or when no OpenClaw sessions exist yet.

inputs

OpenClaw installation and access:

• a working OpenClaw binary in PATH
• direct access to the machine running OpenClaw
• a valid openclaw.json config file
• read and write access to the OpenClaw state directory (default ~/.openclaw)

ClawReverse plugin files:

• plugin bundle included with this skill (installed via openclaw plugins install -l "{baseDir}")

Session and agent context:

• target agent id (from openclaw reverse agents)
• target session id (from openclaw reverse sessions --agent <agent-id>)
• target checkpoint id (from openclaw reverse checkpoints --agent <agent-id> --session <session-id>)

External dependencies:

• OpenClaw Gateway must be running and accessible
• ClawReverse plugin must be enabled in openclaw.json under plugins.entries.clawreverse.enabled

procedure

Step 1: Verify or install the plugin

Input: OpenClaw binary, skill bundle location

1. Check if ClawReverse is available:

openclaw reverse --help

2. If missing, install from this skill bundle:

openclaw plugins install -l "{baseDir}"

3. Initialize or repair plugin config:

openclaw reverse setup

4. If using non-default state directory:

openclaw reverse setup --base-dir /path/to/openclaw-state

5. Restart OpenClaw Gateway
6. Verify plugin is now available:

openclaw reverse --help

Output: plugin commands available and config created at ~/.openclaw/plugins/clawreverse/ (or custom base-dir).

Step 2: Identify target agent and session

Input: agent id and session id (or discover them)

1. List all agents:

openclaw reverse agents

2. List sessions for the target agent:

openclaw reverse sessions --agent <agent-id>

3. Note the Agent column value as agent-id and Session column value as session-id. The row marked latest is the newest session.

Output: confirmed agent-id and session-id values.

Step 3: List and inspect checkpoints

Input: agent-id and session-id

1. List all checkpoints for the session:

openclaw reverse checkpoints --agent <agent-id> --session <session-id>

2. If checkpoint details are needed, inspect one checkpoint:

openclaw reverse checkpoint --checkpoint <checkpoint-id>

Output: list of checkpoint ids, timestamps, and associated tool calls; or single checkpoint details (timestamp, tool call, workspace state hash).

Step 4: Execute the chosen action

Input: agent-id, session-id, checkpoint-id, and user intent (rollback current line, branch safely, or checkout)

Rollback current session (rewind without branching):

openclaw reverse rollback \
  --agent <agent-id> \
  --session <session-id> \
  --checkpoint <checkpoint-id>

If user explicitly wants on-disk workspace files restored too:

openclaw reverse rollback \
  --agent <agent-id> \
  --session <session-id> \
  --checkpoint <checkpoint-id> \
  --restore-workspace

Output: session history rewound, rollback-id returned. Current session state reset to checkpoint. (Workspace files unchanged unless --restore-workspace used.)

Continue as child branch (safe new attempt from checkpoint):

openclaw reverse continue \
  --agent <agent-id> \
  --session <session-id> \
  --checkpoint <checkpoint-id> \
  --prompt "Continue from here with a different approach."

Optional flags:

• --new-agent <agent-id> to force the child agent id (avoid conflict)
• --clone-auth <auto|always|never> to control auth token copying to child
• --log to capture child launch diagnostics (returns logFilePath)

Output: new agent-id, new session-id, new workspace path, child session ready to run. Parent session and workspace left untouched.

Checkout to new session in same agent (no branching, same agent):

openclaw reverse nodes --agent <agent-id> --session <session-id>

(First, list checkpoint-backed entries.)

openclaw reverse checkout \
  --agent <agent-id> \
  --source-session <session-id> \
  --entry <entry-id>

To start a run immediately after checkout:

openclaw reverse checkout \
  --agent <agent-id> \
  --source-session <session-id> \
  --entry <entry-id> \
  --continue \
  --prompt "Continue from this restored entry."

Output: new session-id in same agent, created from checkpoint-backed entry. If --continue used, session immediately starts running.

Step 5: Inspect status, reports, and lineage

Input: agent-id, session-id, rollback-id, branch-id (as applicable)

openclaw reverse rollback-status --agent <agent-id> --session <session-id>
openclaw reverse tree --agent <agent-id> --session <session-id>
openclaw reverse report --rollback <rollback-id>
openclaw reverse branch --branch <branch-id>

Tree inspection also supports auto-root and subtree modes:

openclaw reverse tree
openclaw reverse tree --node <checkpoint-id>

Output: rollback status (state, timestamp), lineage tree (checkpoint hierarchy, branches, nodes), rollback report (what was wound back, diagnostics), branch record (parent, child, metadata).

decision points

If user wants to undo a tool call but preserve the parent session: Use continue with a new agent, workspace, and session. The parent remains untouched and can be inspected later. Parent stays in the original state; child gets a fresh attempt from the checkpoint.

If user wants to rewind the current session to an earlier point: Use rollback. The current session history is rewound. On-disk workspace files remain unchanged by default. Only add --restore-workspace if user has explicitly requested file restoration; otherwise, ask before applying it.

If no checkpoints appear in the listing: Explain that ClawReverse only records checkpoints before mutating tool calls. Read-only tools (read, glob, ls, git status, find, cat, grep, diff, tree) and read-only shell commands do not create checkpoints. If the user needs checkpoints, they must perform a mutating action (file write, tool that modifies state).

If continue needs a distinct agent ID (conflict with existing agent): Use --new-agent <fresh-id> to force a new agent identifier. If auth tokens must be copied to the child agent, use --clone-auth auto (default) or --clone-auth always.

If output must be machine-readable (fed into another tool or script): Add --json flag to any listing or inspection command (checkpoints, rollback-status, tree, report, branch) to get structured JSON output.

If rollback fails or logs are needed for diagnosis: For continue, use --log to capture launch diagnostics and return the logFilePath for inspection.

If ClawReverse command is not found after install: Re-run openclaw plugins install -l "{baseDir}", then openclaw reverse setup, restart the Gateway, and verify clawreverse is in plugins.allow and plugins.entries.clawreverse.enabled is true.

output contract

Plugin setup success:

• openclaw reverse --help runs without error
• config file created or patched at openclaw.json with structure:

  {
    "plugins": {
      "allow": ["clawreverse"],
      "enabled": true,
      "entries": {
        "clawreverse": {
          "enabled": true,
          "config": {
            "workspaceRoots": ["~/.openclaw/workspace"],
            "checkpointDir": "~/.openclaw/plugins/clawreverse/checkpoints",
            "registryDir": "~/.openclaw/plugins/clawreverse/registry",
            "runtimeDir": "~/.openclaw/plugins/clawreverse/runtime",
            "reportsDir": "~/.openclaw/plugins/clawreverse/reports",
            "maxCheckpointsPerSession": 100,
            "allowContinuePrompt": true,
            "stopRunBeforeRollback": true
          }
        }
      }
    }
  }
  

• directories created under ~/.openclaw/plugins/clawreverse/ (checkpoints, registry, runtime, reports)

Agent and session listing:

• plaintext table with columns: Agent, Session, Timestamp, Status, latest marker
• or --json output as array of objects with agent_id, session_id, timestamp, status

Checkpoint listing:

• plaintext table with columns: CheckpointID, Timestamp, ToolCall, WorkspaceHash, Status
• or --json output as array of checkpoint objects

Rollback execution:

• plaintext confirmation: "Rolled back to checkpoint {checkpoint-id}"
• returned rollback-id (string)
• session state reset in memory
• on-disk workspace files unchanged (unless --restore-workspace)
• or --json output with rollback_id, agent_id, session_id, timestamp, status

Continue execution:

• plaintext confirmation: "Created child agent {new-agent-id}, session {new-session-id}"
• new workspace path (usually under ~/.openclaw/workspace/{new-agent-id}/)
• child session ready to receive --prompt run
• parent session unchanged
• or --json output with new_agent_id, new_session_id, workspace_path, parent_agent_id, parent_session_id, logFilePath (if --log used)

Checkout execution:

• plaintext confirmation: "Created new session {new-session-id} in agent {agent-id} from entry {entry-id}"
• new session-id (same agent)
• session state initialized from checkpoint-backed entry
• if --continue used, session immediately starts running with provided prompt
• or --json output with new_session_id, agent_id, source_entry_id, status

Status, tree, report, and branch inspection:

• rollback-status: plaintext summary of rollback state (completed, pending, failed) with timestamp and checkpoint id
• tree: plaintext tree diagram showing checkpoint hierarchy, branch points, and child sessions; or --json tree structure
• report: plaintext rollback report with what was wound back, diagnostics, and any warnings
• branch: plaintext branch record with parent agent/session, child agent/session, timestamp, and metadata

outcome signal

• User confirms via openclaw reverse checkpoints or openclaw reverse tree that the checkpoint list matches their expectation and the session has the right history.
• After rollback, user verifies that openclaw reverse checkpoints --agent ... --session ... now shows truncated history ending at the target checkpoint.
• After continue, user confirms via openclaw reverse agents and openclaw reverse sessions that a new agent and session exist, distinct from the parent, and the parent remains unchanged.
• After checkout, user verifies that openclaw reverse sessions --agent <same-agent> shows a new session id, restored from the checkpoint-backed entry.
• User runs a new tool call or OpenClaw action in the recovered or branched session and observes that no rollback errors occur and the session proceeds normally.
• If --restore-workspace was used, user inspects the on-disk workspace and confirms that files are now in the state they were at the target checkpoint (not at the later, rolled-back state).
• If a user later inspects the lineage with openclaw reverse tree, they see the branch or rollback point clearly marked, confirming the operation was recorded.

---

credits: original skill by binhuangpjlab (clawhub). enriched per Implexa quality standards.