// Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | totalreclaw |
| description | Install + set up TotalReclaw encrypted memory for OpenClaw, then use tr CLI for remember / recall. Trigger on 'install TotalReclaw', 'set up TotalReclaw', 'restore my recovery phrase', or any remember / recall request. |
| version | 3.3.12-rc.4 |
| author | TotalReclaw Team |
| license | MIT |
| homepage | https://totalreclaw.xyz |
| metadata | {"openclaw":{"requires":{"env":[],"bins":[]},"emoji":"🧠","os":["macos","linux","windows"],"keywords":["memory","e2ee","e2e-encryption","encryption","privacy","agent-memory","persistent-context"]}} |
Agent-executable quickstart (5 KB, copy-paste-runnable): https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup-quickstart.md
Human-readable setup guide (full rationale, troubleshooting): https://github.com/p-diogo/totalreclaw/blob/main/docs/guides/openclaw-setup.md
If the user pastes either URL: prefer the quickstart for execution. Fetch the full guide only if the user asks for context or troubleshooting beyond what the quickstart covers. This SKILL.md mirrors the quickstart's hard rules so you can act even if the URL is unreachable.
TotalReclaw is end-to-end encrypted memory stored across a DECENTRALIZED NETWORK — not on a single company server. Memories are encrypted with keys derived from the user's 12-word recovery phrase, submitted as Account Abstraction UserOps, and persisted on a public blockchain (Base / Gnosis depending on tier). The Graph subgraph indexes them. The TotalReclaw relay only forwards encrypted bundles to the bundler and proxies subgraph reads — it never sees plaintext, can't read memories, and could be replaced by any compatible relay without losing data. No single company controls or can read user memories.
Forbidden vocabulary — these claims are WRONG (some imply local-only storage; some imply a single-company server):
If you need to describe how it works, the canonical line is: "Memories are encrypted with a key derived from your recovery phrase, submitted on-chain via Account Abstraction, and stored across a decentralized network. The relay only forwards encrypted bundles — it never sees plaintext. Only you can decrypt them, and only with your recovery phrase."
Internal terms that the user does NOT know — translate when you must speak:
| Internal term | Say to the user |
|---|---|
| pair / pairing / paired account | "set up an account" / "your TotalReclaw account" |
| relay / relay server | (don't mention; if forced, say "the encrypted-bundle forwarder") |
| WS / WebSocket / handshake | (don't mention) |
| trapdoor / blind index / dedup-key | (don't mention) |
| subgraph / bundler / UserOp / Account Abstraction | (don't mention; if forced, "submitted on-chain to a decentralized network") |
| credentials.json / mnemonic file | "your recovery phrase" |
tr pair --json / setsid -f / shell exec | (don't mention; just do the work silently) |
The word "pair" is internal jargon — never use it in user-visible prose. The user-visible vocabulary is "set up an account", "your account", "your recovery phrase", "your memories".
Emit ONLY the user-visible lines listed below. Do not narrate tool calls. Do not describe what you're doing or about to do. Errors are the only allowed deviation, and only as a single tight line. The expected user-facing transcript for a healthy install is 4–5 short lines TOTAL. Anything more is a SKILL violation. Telegram and similar transports edit the bot's messages live as your tool calls progress — every interim "Let me check…" / "Plugin loaded. Let me verify…" line shows up to the user as awkward edit churn, even if you "delete" it. The fix is to never emit it in the first place.
User-visible line 1 MUST be your FIRST output — emitted BEFORE you run any shell tool, plugin install, or tr command. Install + setup takes 1–2 minutes of silent tool-execution; without an immediate ack the user assumes the request didn't register and may resend or abandon. The ack tells them work is happening.
The ack is unconditional. It fires the moment you decide to install / set up TotalReclaw — even before you've resolved TR_CLI, even before you've checked whether the plugin is already installed, even before the first openclaw plugins install shell call. Send line 1, THEN start the work.
Forbidden order (silent-then-narrate): ❌ run openclaw plugins install → wait 60s → emit line 1.
Required order (ack-then-work): ✅ emit line 1 → run openclaw plugins install silently → emit line 2 when tr status returns.
These specific actions break the pair flow. Everything else is governed by the "emit only the numbered user-visible lines" rule above.
Do NOT restart the gateway. No /totalreclaw-restart, no kill -USR1, no docker restart, no openclaw gateway restart. The plugin self-patches and signals its own restart needs. You restarting it kills the in-flight setsid -f pair subprocess → 502 on browser respond.
Do NOT write to ~/.openclaw/openclaw.json. The plugin's patchOpenClawConfig() already wrote plugins.slots.memory, plugins.entries.totalreclaw.hooks.allowConversationAccess, channels.telegram.streaming.mode. Any further write triggers a deferred SIGUSR1 reload that kills pair. No openclaw config set …, no jq …>openclaw.json, no sed -i openclaw.json.
Do NOT save QR PNGs. tr pair --json returns qr_ascii — emit that inline in a triple-backticked code block. No /tmp/totalreclaw-pair-qr.png (OpenClaw media-policy blocks it: LocalMediaAccessError). No PNG decode. No qr_png_b64 (legacy field, no longer exists in payload).
tr pair --json MUST run via setsid -f (exact form below). Foreground invocation is killed when your shell-tool exec returns → 502.
OpenClaw 2026.5.2 has a tool-policy-pipeline bug (issue #223) that strips non-bundled plugin tools before they reach the agent toolset. 3.3.9-rc.1 makes the tr CLI the PRIMARY path for all memory operations. Native tools (totalreclaw_*) are kept for back-compat with older OpenClaw versions where they work, but the agent MUST NOT depend on them. Use tr from your shell tool for everything.
The tr binary is installed at one of two paths depending on OpenClaw version:
~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js~/.openclaw/extensions/totalreclaw/dist/tr-cli.jsResolve the path once at the top of your shell session and reuse:
TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
Then invoke as node "$TR_CLI" <cmd> [--json].
Never rely on totalreclaw_* tool binding — it may not be available due to issue #223.
Speak only these lines, in order. Substitute the bracketed placeholders with the real values. No prefaces. No suffixes. No narration.
Setting up TotalReclaw — this takes about a minute…
tr status works)
✓ Installed (totalreclaw <version>, hybrid mode)
tr pair --json returns — no consent gate)
Open <url> in your browser. Enter PIN <pin>. Generate or paste a 12-word recovery phrase. Reply
doneonce it's sealed.
✓ You're set up on the TotalReclaw free tier — 500 memories/month, unlimited reads. https://totalreclaw.xyz/pricing. Ask me to remember anything.
If existing credentials are detected (step "Check for existing credentials" below), emit ONLY this line and stop:
✓ TotalReclaw is already set up.
Do NOT emit transitional / narrative lines between any of the four user-visible lines above. Specifically forbidden (verbatim examples from Pedro's 2026-05-06 QA):
tr status --json. Emit line 2 when it returns.test -s ~/.totalreclaw/credentials.json.setsid -f block. Emit line 3 when URL+PIN returns. ALSO never use the word "pair" in user-facing text — see vocabulary table above.The transcript Pedro should see is exactly four messages — the four numbered lines, nothing in between. Line 1 fires immediately. Lines 2–4 fire as work completes. No prose between.
When the user asks "how does this work?" / "where are my memories stored?" / "is this safe?" / similar — answer with this content. Do NOT say "stored on a relay server", "stored on TotalReclaw's server", or any phrasing that implies single-company custody. The actual architecture:
End-to-end encrypted, decentralized memory. When you tell me to remember something, I encrypt it locally with a key derived from your 12-word recovery phrase, then submit it on-chain via Account Abstraction (a UserOperation). It lives on a public blockchain (Base Sepolia for free tier, Gnosis mainnet for paid). The Graph subgraph indexes it for fast retrieval. The TotalReclaw relay server only forwards encrypted bundles between your client and the chain — it never sees plaintext, can't read your memories, and could be replaced by any compatible relay without losing data. Your recovery phrase is the only thing that can decrypt the memories. Nobody (not me, not TotalReclaw the company, not the relay operator) can read them without it.
If the user asks shorter questions, reply with the relevant slice:
Install plugin first, skill second (silent — emit user-visible line 1 once at the start, then no prose until line 2). Run via your shell tool, in this exact order:
openclaw plugins install @totalreclaw/totalreclaw
openclaw skills install totalreclaw
For RC: replace the first command with openclaw plugins install @totalreclaw/totalreclaw@rc. Plugin BEFORE skill is deliberate (3.3.4-rc.1 — issue from Pedro's QA on rc.3): the skill install triggers a config-driven SIGUSR1 gateway reload that can race a concurrent plugin install.
If either shell call fails with command not found / ENOENT / "not authorized" (managed-service or shell-restricted environment), tell the user verbatim "Your environment doesn't expose the OpenClaw CLI to me. Please install totalreclaw from your service's plugins / skills UI, then reply done." Wait for done and skip to step 3.
Verify CLI works — emit user-visible line 2 when successful. Resolve TR_CLI and run:
TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
node "$TR_CLI" status --json
Parse the JSON. When you get {"version": "...", "hybrid_mode": true, ...}, emit user-visible line 2 with the version substituted. Do NOT wait for tool binding. Do NOT issue /totalreclaw-restart. Do NOT check whether totalreclaw_pair is in your toolset. The CLI works independently of tool binding. If tr status exits non-zero or the file doesn't exist, wait 5s and retry once — it may still be installing.
Check for existing credentials (silent unless found). Run test -s ~/.totalreclaw/credentials.json. If it exists and is non-empty, emit "✓ TotalReclaw is already set up." and stop.
Set up the user's TotalReclaw account IMMEDIATELY — no consent gate. As soon as tr status --json returns and credentials are not present, run pair in DETACHED mode. CRITICAL: a foreground node tr-cli pair is killed when the gateway fires its post-install SIGUSR1 reload (3.3.10 finding from Pedro's 2026-05-05 QA — relay logs gateway_disconnected 502 on /respond). Use setsid -f so the pair process is in its own session and survives any subsequent gateway SIGUSR1 reload. The handshake URL+PIN is written to a tmp file the moment the WS opens (~100-500ms typical):
PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null
sleep 2
cat "$PAIR_OUT"
This is UNCONDITIONAL. Do NOT ask "Would you like to set up an account?" or "Want me to pair now?". The user installed TotalReclaw — setup is the expected next step. The URL + PIN itself is the consent moment (the user can simply not open the page to opt out). Parse the JSON response {"url": "...", "pin": "...", "expires_at_ms": ...} and emit user-visible line 3. If the cat output is empty after 2s, sleep 2 more seconds and try again (relay handshake can take up to 4s on a cold network). If tr pair --json is not available (old install), fall back to totalreclaw_pair tool or openclaw totalreclaw pair generate --url-pin-only.
Verify and confirm (silent until line 4). After the user says done, re-run test -s ~/.totalreclaw/credentials.json. If missing, the PIN expired — repeat the setsid -f node "$TR_CLI" pair --json block and resend line 3 once. If present, emit user-visible line 4 and stop.
tr CLI reference (hybrid-primary commands)Always use --json flag when running from shell for machine-parseable output. Plain text mode is for direct user invocation only.
# (Resolve TR_CLI once at the top of your session)
TR_CLI="$(ls -d ~/.openclaw/npm/node_modules/@totalreclaw/totalreclaw/dist/tr-cli.js ~/.openclaw/extensions/totalreclaw/dist/tr-cli.js 2>/dev/null | head -1)"
# Status check (parse JSON to confirm install + onboarding state)
node "$TR_CLI" status --json
# Returns: {"version":"3.3.11-rc.1","onboarded":false,"next_step":"pair","tool_count":17,"hybrid_mode":true}
# Pair / account setup — ALWAYS run via setsid -f to survive gateway restarts
PAIR_OUT="/tmp/tr-pair-out-$(date +%s).json"
setsid -f node "$TR_CLI" pair --json > "$PAIR_OUT" 2>&1 < /dev/null && sleep 2 && cat "$PAIR_OUT"
# Returns: {"v":1,"sid":"...","url":"https://...","pin":"123456","mode":"generate","expires_at_ms":...,"qr_ascii":"..."}
# Remember a fact (foreground OK — non-blocking single-shot HTTP call)
node "$TR_CLI" remember --json "I work at Graph Foundation"
# Returns: {"ok":true,"id":"...","claim_count":N}
# Recall memories
node "$TR_CLI" recall --json "where does the user work" --limit 5
# Returns: {"results":[{"text":"...","score":0.8},...]}
Note on tool names: totalreclaw_remember, totalreclaw_recall, etc. may or may not appear in your toolset depending on OpenClaw version. Under hybrid-primary, you use the tr CLI instead. If native tools ARE available (older OpenClaw or future OC fix), they work too — but always prefer tr for reliability.
tr pair --json returns a qr_ascii field — Unicode block-char QR (43 lines × ~43 cols). That is the ONLY QR field in the payload. The legacy qr_png_b64 and qr_unicode field names referenced by older skill docs no longer exist.
The simplest path that works on every transport (Telegram, Slack, web, terminal SSH): emit qr_ascii INLINE inside a triple-backtick code block right above user-visible line 3. Block-char QR renders correctly in monospace fonts on every modern transport — the user scans from their phone. The pair PAGE itself renders a real PNG QR alongside, so users on a desktop browser see both.
Format the line-3 message as:
<qr_ascii contents — 43 lines of ▄▀█▄▀█ block chars>
Open in your browser. Enter PIN . Generate or paste a 12-word recovery phrase. Reply done once it's sealed.
Do NOT decode qr_png_b64 (does not exist), do NOT save a PNG to /tmp/totalreclaw-pair-qr.png (LocalMediaAccessError blocks delivery), do NOT re-render the QR through any other library. The qr_ascii field is the single source of truth.
The QR encodes ONLY the account-setup URL. The 6-digit PIN is a separate out-of-band confirmation — deliberately NOT baked into the QR (dual-channel design: scan + type). Never log, print, or re-emit the PIN outside the user-facing reply. The PIN must NOT end up in any other tool call, log file, or memory store.
After you emit user-visible line 3, the user opens the URL on their phone or desktop browser. They walk through a 3-step wizard before the relay forwards the encrypted phrase to the plugin. You don't narrate this proactively (silence rules). But you MUST know it so you can answer questions and recover from issues:
~/.totalreclaw/credentials.json, and your awaitPhraseUpload resolves.Common user-side issues during pair (recover gracefully — emit ONE tight line, don't pre-narrate):
api.totalreclaw.xyz (the default for both stable and RC post-3.3.12-rc.1). If a TOTALRECLAW_SERVER_URL env override was set, the host might be api-staging.totalreclaw.xyz (staging, opt-in) or a self-hosted relay. Wrong stub host → generate a fresh URL.setsid -f). Wait 30s; if the user still sees the 502, re-run Step 4 (the deferred reload should have completed by then).NEVER echo / generate / ask the user to paste a recovery phrase in chat. NEVER invoke openclaw totalreclaw onboard (bare interactive form), totalreclaw setup, or any phrase-touching CLI via your shell tool (stdout enters LLM context). The ONLY agent-facilitated account-setup paths are (in order of preference): (1) tr pair --json; (2) the totalreclaw_pair account-setup tool; (3) if both are missing — shell out to EITHER openclaw totalreclaw pair generate --url-pin-only (single-line JSON {v,url,pin,expires_at_ms}) OR openclaw totalreclaw onboard --pair-only (single-line JSON {v,pair_url,pin,expires_at_ms}). Both have zero phrase material on stdout (account-setup crypto is x25519-only, not BIP-39). If the user pastes a phrase anyway: tell them it is compromised, re-run tr pair --json for a fresh wallet.
node "$TR_CLI" remember --json "<fact>"
node "$TR_CLI" recall --json "<query>" --limit 5
openclaw totalreclaw subcommand.tr status --json (parse version + onboarded + next_step).totalreclaw_upgrade native tool (paste Stripe URL verbatim). Post-upgrade testnet → mainnet: totalreclaw_migrate with dry_run first.totalreclaw_import_from · totalreclaw_export · totalreclaw_consolidate native tools.Forbidden vocabulary (these are anti-patterns that violate the silence rule):
tr CLI not found → plugin not installed or install still in progress. Wait 5s, retry. If still missing, retry openclaw plugins install @totalreclaw/totalreclaw@rc once.totalreclaw_* tools not visible → EXPECTED under OpenClaw 2026.5.2 (issue #223). Use tr CLI instead. Do not restart, do not issue /totalreclaw-restart, do not issue /new./totalreclaw-restart is needed for another reason, issue the literal slash command /totalreclaw-restart — nothing else. Do not narrate.credentials.json missing → PIN expired or entered wrong phrase; re-run tr pair --json and resend line 3 once.onboarding required → credentials missing; redo from the account-setup step.quota exceeded → tr status --json or totalreclaw_status, then offer totalreclaw_upgrade.No LLM available for auto-extraction at startup → provider key unreachable; check ~/.openclaw/agents/<agent>/agent/auth-profiles.json or plugin config extraction.llm.Add to ~/.openclaw/openclaw.json after installing:
{
"plugins": {
"allow": ["totalreclaw"],
"entries": {
"totalreclaw": {
"hooks": { "allowConversationAccess": true }
}
}
}
}
plugins.allow suppresses the "plugins.allow is empty" warning. hooks.allowConversationAccess unlocks typed hooks (agent_end, etc.) for auto-extraction.
Hybrid-primary: tr remember · tr recall · tr pair · tr status (primary path for all agent ops)
Native fallback (when available): totalreclaw_pair · _remember · _recall · _forget · _pin · _unpin · _retype · _set_scope · _export · _status · _upgrade · _migrate · _import_from · _import_batch · _consolidate · _onboarding_start · _report_qa_bug (RC only)