Clawreverse

Inspect, checkpoint, rollback, and branch OpenClaw sessions with the ClawReverse plugin. Use when a user wants to recover from bad tool or file changes, rest...

Security Scan

The skill appears to be a coherent OpenClaw plugin for checkpointing/rollback that asks for the expected binary-level access and performs filesystem and OpenClaw state edits consistent with its purpose, but installing it will run third‑party plugin code on your machine so you should verify the source before installing.

Purpose & Capability

Name, description, and required binary ('openclaw') align with the included files and behavior. The code implements checkpointing, rollback, branching and CLI bindings; none of the requested resources (no unrelated env vars or external services) are disproportionate to the claimed purpose.

Instruction Scope

SKILL.md instructs the agent to run only OpenClaw CLI commands (openclaw reverse, openclaw plugins install -l, openclaw reverse setup) and to edit/patch the OpenClaw config (openclaw.json). Those actions are within the plugin's stated purpose (installing and registering a plugin that manipulates OpenClaw sessions and state). Note: the plugin will read and write OpenClaw state files, session transcripts, workspace paths, and may copy agent/workspace directories as part of fork/continue operations.

Install Mechanism

There is no external download/install spec in the registry metadata—installation is expected to be performed locally via 'openclaw plugins install -l "{baseDir}"' using the skill bundle. The bundle includes source/dist JS files. No network downloads or URL-based installs are specified by the skill metadata.

Credentials

The skill declares no required environment variables, which matches SKILL.md. The plugin code does read environment fallbacks (e.g., OPENCLAW_GATEWAY_TOKEN, OPENCLAW_GATEWAY_PASSWORD, OPENCLAW_STATE_DIR / OPENCLAW_HOME) when attempting to connect to the gateway or resolve state paths — this is expected for an OpenClaw plugin but it does mean the plugin may access environment-held credentials or sensitive config if present. The env access appears proportional to the task (auth to the OpenClaw Gateway, locating state directories) but users should be aware of these implicit reads.

Persistence & Privilege

always: false (normal). The SKILL.md and code instruct enabling the plugin in the OpenClaw config (writing to openclaw.json) and creating plugin-managed directories under the OpenClaw state. That is expected for a native plugin, but it grants the plugin persistent presence inside OpenClaw state and file-system-level access to session/workspace data while installed.

Assessment

This skill is internally consistent with being an OpenClaw native plugin: it installs from the local skill bundle, modifies openclaw.json, and performs filesystem operations on OpenClaw state and workspaces as required for checkpointing/rollback. Before installing: (1) verify you trust the source (check the GitHub repo and author), (2) back up your openclaw.json and important workspace files, (3) inspect the bundle (the dist/*.js files are present) if you have doubts, and (4) be aware that installing the plugin runs third‑party code with access to OpenClaw state and workspace files and may read gateway tokens from environment variables. If you want to limit risk, install and test it in an isolated environment or VM first.

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

• a user wants to undo a bad OpenClaw tool call or recover from unwanted file changes
• a user wants to restore a known-good point without rerunning the whole task
• a user wants to branch from an earlier checkpoint and keep the parent session untouched
• a user wants to inspect checkpoint lineage, rollback status, rollback reports, or branch records
• a user wants to save tokens after a long analysis run by continuing from a checkpoint instead of starting over

Do not use this skill when

• the task is a normal git revert, git checkout, or git branch workflow that should be handled directly with git
• the workspace is not managed by OpenClaw
• there are no OpenClaw sessions or checkpoints to operate on yet

Key behavior you should know first

• ClawReverse creates checkpoints before mutating tool calls. Read-only tools and read-only shell commands do not create checkpoints.
• rollback rewinds the current session to a checkpoint. By default it does not restore the live workspace files unless --restore-workspace is used.
• continue requires a non-empty --prompt and creates a new child agent, new workspace, and new session, leaving the parent untouched.
• checkout creates a new session in the same agent from a checkpoint-backed entry. --continue can immediately start a run in that new session.
• tree is the fastest way to explain lineage and branch points to a user.
• Add --json whenever another tool needs machine-readable output.

Prerequisites

• a working OpenClaw installation
• access to the machine that runs OpenClaw
• a valid openclaw.json
• the ClawReverse plugin files available in this skill bundle

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:

• --new-agent <agent-id> to force the child agent id
• --clone-auth <auto|always|never> for auth-copy behavior
• --log to capture child launch diagnostics and return logFilePath

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

• Prefer continue over rollback when the user wants to preserve the parent line untouched.
• Prefer rollback when the user wants the current line moved back to an earlier checkpoint.
• Ask before using --restore-workspace if the user has not clearly requested live file restoration.
• If no checkpoints appear, explain that ClawReverse only records checkpoints before mutating tools or mutating shell commands. Read-only operations such as read, glob, ls, git status, find, cat, grep, diff, tree, and similar commands are intentionally skipped.
• Use --json for programmatic parsing or when you want to feed results into another tool.
• From {baseDir}, npm test runs the repository test suite.

Troubleshooting

openclaw reverse is missing

• re-run openclaw plugins install -l "{baseDir}"
• run openclaw reverse setup
• restart the Gateway
• check that clawreverse is in plugins.allow
• check that plugins.entries.clawreverse.enabled is true

continue fails

• make sure --prompt is non-empty
• if an agent id conflict occurs, retry with --new-agent <fresh-id>
• if you used --log, inspect the returned logFilePath

rollback did not change files

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

tree or checkpoints shows nothing

• confirm the agent id and session id are correct
• confirm the session has mutating tool calls that could create checkpoints