Claude Code: **CRITICAL: Fix Data Persistence - Add HF_TOKEN and AUTO_CREATE_DATASET*

SETUP.md

@@ -0,0 +1,168 @@
+# Cain Data Persistence Setup
+
+**CRITICAL:** Without completing this setup, all conversations, settings, and credentials will be **LOST** when the HuggingFace Space restarts.
+
+---
+
+## The Problem
+
+Cain's data persistence is currently **DISABLED**. The `sync_hf.py` script requires:
+
+1. **HF_TOKEN** environment variable (Repository Secret) - Missing
+2. **AUTO_CREATE_DATASET=true** environment variable - Missing
+
+Without these, Cain cannot persist data to the HuggingFace Dataset.
+
+---
+
+## Quick Setup (5 minutes)
+
+### Step 1: Create an HF Token with Write Access
+
+1. Go to: https://huggingface.co/settings/tokens
+2. Click **"New token"**
+3. Set **Type** to: **Write** (NOT "Read" - this is critical!)
+4. Name it something like: `Cain-Data-Persistence`
+5. Click **"Generate token"**
+6. **Copy the token immediately** - you won't see it again!
+
+### Step 2: Add Environment Variables in Space Settings
+
+1. Go to your Space settings: https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain/settings
+2. Scroll to **"Repository Secrets"** section
+3. Click **"New Secret"**
+
+Add these two secrets:
+
+| Name | Value | Type |
+|------|-------|------|
+| `HF_TOKEN` | *[Paste your token from Step 1]* | Repository Secret |
+| `AUTO_CREATE_DATASET` | `true` | Repository Secret |
+
+4. Click **"Save"** for each secret
+
+### Step 3: Restart the Space
+
+1. Go to: https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain
+2. Click the **"Settings"** tab (top right gear icon)
+3. Scroll down and click **"Factory reset"** or **"Restart"**
+4. Wait 2-3 minutes for the Space to restart
+
+---
+
+## What Happens After Setup
+
+### Automatic Dataset Creation
+
+When the Space restarts with `HF_TOKEN` and `AUTO_CREATE_DATASET=true`:
+
+1. The script auto-creates the dataset: `tao-shen/HuggingClaw-Cain-data`
+2. The dataset will be **private** (only you can access it)
+3. You can verify it at: https://huggingface.co/datasets/tao-shen/HuggingClaw-Cain-data
+
+### What Data Gets Synced
+
+The `sync_hf.py` script syncs the entire `~/.openclaw` directory, including:
+
+- **Conversations** - All chat history
+- **Settings** - `openclaw.json` configuration
+- **Credentials** - API keys (stored in config)
+- **Workspace files** - All user-created files
+- **Agent memory** - Persistent agent state
+- **Devices** - Paired Telegram/WhatsApp connections
+
+### Sync Schedule
+
+- **On startup:** Downloads latest data from dataset
+- **Every 60 seconds:** Uploads changes (only if files changed)
+- **On shutdown:** Final upload before Space stops
+
+### Logs to Monitor
+
+After restart, check these logs for confirmation:
+
+```
+[SYNC] Dataset repo found: tao-shen/HuggingClaw-Cain-data
+[SYNC] ✓ Dataset repo created: tao-shen/HuggingClaw-Cain-data
+[SYNC] ✓ Restore completed.
+[SYNC] ✓ Upload completed at 2026-03-14T...
+```
+
+Look for the sync log in the Space's "Logs" tab or in the running Space output.
+
+---
+
+## Troubleshooting
+
+### "Persistence disabled" message
+
+**Cause:** `HF_TOKEN` is not set or invalid
+
+**Solution:**
+1. Verify the token exists in Repository Secrets
+2. Ensure token type is "Write" (not "Read")
+3. Restart the Space after adding the token
+
+### "Dataset repo NOT found" (dataset not created)
+
+**Cause:** `AUTO_CREATE_DATASET` is not set to `true`
+
+**Solution:**
+1. Add `AUTO_CREATE_DATASET=true` as a Repository Secret
+2. Restart the Space
+
+### Data still not persisting after restart
+
+**Check the Space logs for:**
+```
+[SYNC] WARNING: HF_TOKEN not set. Persistence disabled.
+```
+
+**Solution:** Re-add the HF_TOKEN secret (it may not have saved properly)
+
+---
+
+## Advanced Configuration
+
+### Change Sync Interval
+
+Default sync interval is 60 seconds. To change it:
+
+| Name | Value | Type |
+|------|-------|------|
+| `SYNC_INTERVAL` | `120` (for 2 minutes) | Repository Secret |
+
+### Custom Dataset Name
+
+To use a different dataset (not auto-derived):
+
+| Name | Value | Type |
+|------|-------|------|
+| `OPENCLAW_DATASET_REPO` | `your-name/custom-dataset-name` | Repository Secret |
+
+---
+
+## Summary
+
+| Setting | Value Required | Default if Missing |
+|---------|----------------|-------------------|
+| `HF_TOKEN` | Write token from HF settings | **Persistence DISABLED** |
+| `AUTO_CREATE_DATASET` | `true` | Dataset NOT auto-created |
+| Dataset ID | Auto: `tao-shen/HuggingClaw-Cain-data` | N/A |
+| Sync Interval | 60 seconds | N/A |
+
+---
+
+## Verification Checklist
+
+After completing setup:
+
+- [ ] HF Token created with "Write" type
+- [ ] `HF_TOKEN` secret added to Space settings
+- [ ] `AUTO_CREATE_DATASET=true` secret added
+- [ ] Space restarted
+- [ ] Dataset created at `tao-shen/HuggingClaw-Cain-data`
+- [ ] Logs show "Dataset repo found" or "Dataset repo created"
+- [ ] Logs show "Restore completed" or "Upload completed"
+
+**Once all items are checked, data persistence is enabled!**