Openclaw Vault Interaction Confidence Spec

# OpenClaw Vault Interaction & Confidence UX Spec

Status: Proposed  
Date: 2026-03-10  
Audience: Product, design, engineering  
Related: [openclaw-v2-program-upgrade-spec.md](openclaw-v2-program-upgrade-spec.md), [openclaw-v2-technical-architecture-spec.md](openclaw-v2-technical-architecture-spec.md), [openclaw-current-interface-audit.md](openclaw-current-interface-audit.md), [openclaw-artifact-result-center-spec.md](openclaw-artifact-result-center-spec.md)

## 1. Purpose

This document defines the user-facing Vault interaction model and the confidence-building UX needed to make long-term OpenClaw usage feel safe.

Vault is not only a technical snapshot subsystem.

It is the product answer to a critical user fear:

> “If I finally train this system to work well for me, will I lose everything when I change something?”

The purpose of Vault UX is to make the answer clearly:

> “No. Your system is recoverable, branchable, and safe to evolve.”

## 2. Product Problem

OpenClaw becomes more valuable over time because users accumulate:

- preferences
- prompts
- routing choices
- memory
- artifacts
- automations
- bindings
- workflows

Without strong user-facing protection, this creates fear in four forms:

1. fear of changing the current setup
2. fear of losing accumulated memory and quality
3. fear of experimenting with new models or prompts
4. fear that switching systems or devices will erase progress

Vault UX exists to remove those fears.

## 3. Core Product Promise

Vault should communicate this promise:

- your current state is protected
- important milestones are saved automatically
- you can restore safely
- you can duplicate before experimenting
- you can compare versions before making changes
- you can switch systems without confusion

## 4. Key Terms

### 4.1 Snapshot

A saved system state or restore point.

### 4.2 Baseline

The first trusted restore point created after setup or migration.

### 4.3 Checkpoint

A saved restore point created automatically or manually during use.

### 4.4 Branch

A new line of evolution from an existing snapshot.

### 4.5 Restore

Apply a previous state to the current system or create a clone from it.

### 4.6 Confidence UX

The set of cues, explanations, statuses, and guardrails that help users feel safe while using Vault.

## 5. Design Principles

### 5.1 Safety must be visible

Users should not have to assume the system is safe. The product must show it.

### 5.2 Prefer reversible actions

When major change is about to happen, the default should lean toward snapshot or clone first.

### 5.3 Explain impact before mutation

A restore or major policy change should clearly explain what will change.

### 5.4 Encourage experimentation safely

Users should be nudged to duplicate or branch when trying risky changes.

### 5.5 Use human language, not infrastructure language

Say:

- Save current state
- Return to this version
- Duplicate to try a new setup

Not only:

- write manifest
- restore serialized state
- change active head pointer

## 6. Vault’s User-Facing Jobs

Vault must support these user jobs:

- save my current good state
- go back to my last known good version
- test a new idea without breaking current work
- compare what changed between versions
- restore only part of a system
- understand why I can trust the next operation

## 7. Primary Vault Surfaces

Vault should be a top-level product area, not a hidden advanced setting.

### 7.1 Global Vault center

Shows:

- all systems with snapshot health
- recent checkpoints
- branches
- restore history
- backup health

### 7.2 Per-system Vault panel

Shows:

- baseline
- latest checkpoint
- branch timeline
- safe actions for this system
- upcoming risky changes

### 7.3 Contextual Vault prompts

Shown before:

- model/provider changes
- major prompt changes
- permission policy changes
- memory strategy changes
- publish-critical steps
- branch switching

## 8. Confidence Signals

Vault UX should continuously signal safety.

### 8.1 Passive confidence signals

Show:

- `Protected` badge when a recent checkpoint exists
- `Baseline saved` after initial setup
- `Safe to experiment` when clone-first flow is available
- `Last restore point: 3 minutes ago`

### 8.2 Active confidence prompts

Before a risky change, show prompts like:

- `Create a restore point before changing your main model?`
- `This system has built up memory and workflow history. Duplicate it to test safely.`
- `You are restoring an earlier version. Review affected areas before applying.`

### 8.3 Recovery clarity

After restore, clone, or branch, show:

- what happened
- what changed
- where the previous state still exists
- how to return if needed

## 9. Snapshot Strategy UX

Users must understand that snapshots are not rare or manual-only.

### 9.1 Automatic snapshot moments

Create automatic checkpoints at:

- first successful onboarding completion
- first successful system launch
- before model/provider changes
- before major system edits
- before publish
- after major result generation
- before restore
- before migration

### 9.2 Manual snapshot affordance

Users should always be able to:

- save current state
- save milestone
- name a checkpoint

### 9.3 Snapshot labels

Human-friendly examples:

- `Initial setup`
- `Before changing Claude model`
- `Website copy approved`
- `Before publish`
- `Post-launch stable`

## 10. Restore Modes

The product should expose restore modes clearly.

### 10.1 Return current system to this version

Use when the user wants a direct rollback.

### 10.2 Duplicate from this version

Use when the user wants to experiment safely.

### 10.3 Restore part of the system only

Use when the user wants to recover only:

- memory
- prompts
- team structure
- automations
- bindings
- artifact links

### 10.4 Open as read-only history

Use when the user only wants to inspect old state.

## 11. Restore Planner UX

Every restore should go through a planner step.

The planner should show:

- source snapshot name and time
- current target system
- affected scopes
- what will stay unchanged
- recommendation: restore / clone / cancel
- optional auto-create safety checkpoint before apply

This is where user confidence is won or lost.

## 12. Clone And Branch UX

These should be promoted, not buried.

### 12.1 Clone messaging

Good language:

- `Duplicate this system to try a new setup`
- `Create a safe test version`
- `Experiment without affecting current work`

### 12.2 Branch messaging

Good language:

- `Start a redesign branch`
- `Create a variant for another client`
- `Try a different model strategy`

### 12.3 Suggested defaults

When a system is mature, the default should often be:

- clone first
- then change

not:

- overwrite current configuration immediately

## 13. Compare UX

Compare is essential for confidence.

The compare view should show differences in:

- provider/model policy
- prompt / team structure
- memory summary
- automations
- bindings
- latest artifacts
- timestamp and author

Use plain labels such as:

- `Model changed`
- `3 memory rules removed`
- `Telegram binding disabled`
- `SEO automation added`

## 14. Switch UX

Switching between systems or branches must feel controlled.

### 14.1 System switch

When switching, show:

- target system name
- current system preserved state
- whether the target is synced or local-only
- latest checkpoint health

### 14.2 Branch switch

When switching branches, show:

- current branch
- target branch
- most recent result in each branch
- whether unsaved changes need a checkpoint first

## 15. Error And Failure UX

Vault must feel trustworthy even when something fails.

### 15.1 Failure principles

- never present silent failure
- explain what failed clearly
- tell the user what remained safe
- tell the user the recovery path

### 15.2 Example messages

- `Restore could not complete. Your current system was not overwritten.`
- `Snapshot verification failed. We kept your current version active.`
- `Cloud copy is unavailable, but your local restore point is still intact.`

## 16. Local UX Requirements

In the local product, Vault can begin with lightweight but clear surfaces.

Recommended local capabilities:

- current system protection status in header/footer or side panel
- recent checkpoint summary
- create snapshot command
- restore planner overlay
- clone-before-change prompt

## 17. Web UX Requirements

On web, Vault should become much more visual.

Recommended routes:

- `/app/vault`
- `/app/vault/systems/[systemId]`
- `/app/vault/snapshots/[snapshotId]`
- `/app/vault/compare`

Recommended components:

- system protection cards
- snapshot timeline
- branch graph or simplified lineage list
- compare panel
- restore planner modal

## 18. Confidence Language Guidelines

Use reassuring language throughout.

Preferred phrases:

- `Protected`
- `Restore point saved`
- `Safe to test`
- `Your current version will remain available`
- `Duplicate before changing`
- `You can always return to this version`

Avoid over-technical phrases in core UI:

- `state serialization complete`
- `manifest persisted`
- `active pointer replaced`

## 19. Metrics

Vault success should be measured by:

- checkpoint creation rate
- clone-before-edit rate
- restore success rate
- compare usage rate
- reduced abandonment before risky changes
- user retention for systems with Vault usage

## 20. Delivery Plan

### Phase 1

- visible checkpoint health
- baseline badge
- create restore point action
- restore planner shell

### Phase 2

- compare view
- clone-first prompts
- per-system Vault panel
- branch visibility

### Phase 3

- partial restore flows
- read-only history mode
- richer team/workspace controls
- web timeline visualization

## 21. Acceptance Criteria

This spec is implementation-ready when the team can build:

- a visible Vault center or panel
- confidence-building safety cues
- restore planner with impact explanation
- clone and branch flows with user-friendly defaults
- compare and switch interactions
- local and web surfaces that make long-term system evolution feel safe