ClawReverse

---

name: clawreverse

description: Inspect, checkpoint, rollback, and branch OpenClaw sessions with the ClawReverse plugin. Use when a user wants to recover from bad tool or file changes, restore a known-good checkpoint, inspect session lineage, create a child branch from an earlier point, or avoid re-spending tokens after a long OpenClaw run. Do not use for plain git history operations or non-OpenClaw workspaces.

version: 0.1.0

homepage: https://github.com/OpenKILab/ClawReverse

metadata: {"openclaw":{"emoji":"⏪","homepage":"https://github.com/OpenKILab/ClawReverse","requires":{"bins":["openclaw"]}}}

---

# ClawReverse

Use this skill for OpenClaw session recovery and branching.

ClawReverse is a native OpenClaw plugin that adds the `openclaw reverse` command family for checkpoint listing, rollback, continue, checkout, and lineage inspection.

Use this skill when

Do not use this skill when

Key behavior you should know first

Prerequisites

First step: verify or install the plugin

1. Check whether the plugin is already available:

openclaw reverse --help

2. If the command is missing, install the plugin from this skill bundle:

openclaw plugins install -l "{baseDir}"

3. Then initialize or repair config:

openclaw reverse setup

4. Restart the OpenClaw Gateway after install or config changes, then verify again:

openclaw reverse --help

If the OpenClaw state directory is not the default one, use:

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

Default config created by `setup`

{
  "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
        }
      }
    }
  }
}

Standard workflow

1) Identify the target agent and session

openclaw reverse agents
openclaw reverse sessions --agent <agent-id>

Use the value in the `Agent` column as the `agent id` and the value in the `Session` column as the `session id`. The row marked `latest` is the newest session.

2) List checkpoints

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

If you need details for one checkpoint:

openclaw reverse checkpoint --checkpoint <checkpoint-id>

3) Choose the correct action

#### Roll back the current line

Use this when the user wants to rewind the **current session** to an earlier point.

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

Only add `--restore-workspace` when the user explicitly wants the current on-disk workspace restored too:

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

#### Continue as a safe child branch

Use this when the parent session and workspace must stay untouched and the user wants a fresh attempt from a known-good checkpoint.

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

Optional advanced flags:

#### Checkout into a new session in the same agent

Use this when the user wants a new session from a checkpoint-backed entry without creating a new agent.

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

To start running immediately after checkout:

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

4) Inspect status, reports, and lineage

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` also supports automatic root selection and subtree inspection:

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

Command quick reference

| Command | Purpose |

|---|---|

| `openclaw reverse setup` | Patch `openclaw.json` and create plugin directories |

| `openclaw reverse status` | Show plugin runtime status |

| `openclaw reverse agents` | List configured agents |

| `openclaw reverse sessions --agent ...` | List sessions for one agent |

| `openclaw reverse checkpoints --agent ... --session ...` | List checkpoints for a session |

| `openclaw reverse checkpoint --checkpoint ...` | Inspect one checkpoint by id |

| `openclaw reverse rollback-status --agent ... --session ...` | Show rollback state for a session |

| `openclaw reverse rollback ...` | Rewind a session to a checkpoint |

| `openclaw reverse continue ... --prompt ...` | Create a child agent, workspace, and session from a checkpoint |

| `openclaw reverse nodes --agent ... --session ...` | List checkpoint-backed entries that support checkout |

| `openclaw reverse tree ...` | Display checkpoint lineage as a tree |

| `openclaw reverse checkout ...` | Create a new session from a checkpoint-backed entry |

| `openclaw reverse report --rollback ...` | Inspect a rollback report |

| `openclaw reverse branch --branch ...` | Inspect a saved branch record |

Guardrails

Troubleshooting

`openclaw reverse` is missing

`continue` fails

`rollback` did not change files

That is expected unless `--restore-workspace` was used.

`tree` or `checkpoints` shows nothing