78 · luoyuctl · May 10, 2026 · May 10, 2026 · May 10, 2026 · May 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -88,6 +88,13 @@ Win/macOS: tenbox-manager ──IPC v1──► tenbox-vm-runtime (WHVP / HVF)
 - **LLM proxy** exists in two places: `src/daemon/llm_proxy.cpp` (Linux) and `src/manager/llm_proxy.cpp` (Windows); change both when the protocol changes.
 - **RemoteSession** is single-instance per VM. Read `remote_webrtc.cpp`'s `force` takeover path before adding DataChannels.
 - **macOS Caps Lock forwarding**: send Caps Lock as a tap (`down` then `up`) on each `flagsChanged` event; AppKit exposes it as a toggle state, but the guest input stack needs a full key press for every switch.
+- **Agent toolbox**: macOS and Windows desktop managers expose Agent急救箱 without image/rootfs changes. Prefer qemu-guest-agent `guest-exec` plus runtime-only shared folders; keep any console-marker path as fallback only, throttle bulk console input, and never persist temporary Agent share tags into VM manifests.
+- **Agent profile and backups**: keep the gzip package format in `docs/agent-profile.md`, include `export_scope`, reject cross-Agent imports, merge imports into the existing Agent home, and exclude reinstallable binaries plus volatile logs/caches/runtime locks. Host backups live under the platform TenBox data dir in `AgentBackups/<vm-id>/<agent>`, use time-based filenames, tolerate live-file tar churn, and rotate by the configured retention count.
+- **Agent scheduled backups**: store per-VM/per-Agent schedules in `settings.json` under `agent_backups.schedules`; only run them when the VM is running and guest execution is connected, and surface the last automatic backup attempt in the UI.
+- **Agent health and repair**: health, restart, reset, and diagnostics run through guest-exec as user `tenbox`; fail instead of falling back to root if user switching fails, and enforce guest-side timeouts for long commands. Destructive or repair actions must create a host-managed backup first, patch only the necessary config, confirm with the user, and avoid full guest `/tmp` extraction that can exhaust small images.
+- **OpenClaw to Hermes migration**: use official `hermes claw migrate` with a separate dry run; pass `--migrate-secrets`, `--workspace-target`, Hermes global `--overwrite`, and map UI conflict choices only to `--skill-conflict`. Treat `Refusing to apply` as failure, save dry-run/final reports beside Hermes backups, restore TenBox model proxy settings after migration, and only copy compatible Feishu/WeCom env settings best-effort.
+- **Agent UI responsiveness**: keep Agent tool UI copy in Chinese, put destructive/low-frequency actions behind confirmation, run guest-exec and shared-folder IPC off the UI thread, and show compact progress/results while writing full logs/reports to files.
+- **macOS app signing**: the app entitlement includes `com.apple.security.cs.disable-library-validation` so the hardened-runtime app can load the bundled Sparkle framework.
 - **Static build** (`TENBOX_STATIC_FFMPEG=ON`) requires `/opt/tenbox-deps` (only present inside the CI/packaging container). Dev builds use system shared libs — keep `ON` off by default.
 - **Release**: `docs/release.md` — VERSION bump → commit → push → tag → push tag. Always push commit before tag.
 

diff --git a/docs/agent-profile.md b/docs/agent-profile.md
@@ -0,0 +1,131 @@
+# Agent Data Tools
+
+TenBox.app on macOS and `tenbox-manager.exe` on Windows provide Agent data
+export/import, backup/restore, migration, and health actions without requiring
+Hermes/OpenClaw images to preinstall TenBox-specific scripts.
+
+The desktop manager creates a temporary shared folder, then sends a short shell
+command through qemu-guest-agent `guest-exec`. The command uses standard guest
+tools such as `tar`, `gzip`, `systemctl`, `curl`, and `journalctl`. On Windows,
+the same flow is exposed through the Agent急救箱 dialog and host files are stored
+under `%LOCALAPPDATA%\TenBox`.
+
+## Profile package
+
+The exported package is a gzip tar archive:
+
+```text
+<vm>-<agent>-profile.tar.gz
+├── manifest.json
+└── files.tar.gz
+```
+
+`manifest.json` contains:
+
+- `format`: `tenbox-agent-profile`
+- `format_version`: `2`
+- `agent_type`: `hermes` or `openclaw`
+- `export_scope`: `migration` or `backup`
+- `archive`: `files.tar.gz`
+
+`files.tar.gz` contains the Agent data directory relative to the guest home:
+
+- Hermes: `.hermes`
+- OpenClaw: `.openclaw`
+
+Always excluded paths:
+
+- Hermes: `.hermes/logs`, `.hermes/image_cache`, `.hermes/audio_cache`,
+  `.hermes/cache`, `.hermes/hermes-agent`, `.hermes/bin`, `.hermes/gateway.pid`,
+  `.hermes/gateway.lock`
+- OpenClaw: `.openclaw/cache`, `.openclaw/.cache`, `.openclaw/workspace/.cache`,
+  `.openclaw/logs`
+
+Migration exports keep secrets, identity, session state, and config files so a
+profile can move with the user's full Agent state. Only volatile logs, caches,
+runtime lock files, and reinstallable binaries are skipped.
+
+Import rejects packages whose `agent_type` does not match the selected Agent.
+Before replacing existing data, it renames the current directory to
+`*.pre-import-YYYYMMDDHHMMSS`.
+
+## Backups
+
+Manual backups are created by TenBox.app in:
+
+```text
+~/Library/Application Support/TenBox/AgentBackups/<vm-id>/<agent>/
+```
+
+On Windows the equivalent directory is:
+
+```text
+%LOCALAPPDATA%\TenBox\AgentBackups\<vm-id>\<agent>\
+```
+
+Backups use the same profile package format. Retention is configurable per VM
+and Agent; the default keeps the newest seven packages. Restore uses the package
+selected in the backup list for the selected VM and Agent.
+
+Host-managed backups use `export_scope: backup` and keep restorable user state
+except volatile logs, caches, runtime lock files, and reinstallable binaries.
+They are intended for recovery on the same host, not for sharing.
+
+## Health actions
+
+TenBox.app can run these actions while the VM is running:
+
+- health status
+- restart Agent
+- reset Agent config
+- export diagnostics
+
+Restart and reset create a backup first, using the same host-managed backup
+directory. Diagnostics are exported to the host backup directory through the
+temporary shared folder. Both desktop managers also support per-VM/per-Agent
+scheduled backups persisted in `settings.json` as `agent_backups.schedules`.
+
+## OpenClaw to Hermes migration
+
+When both source and target VMs are running, TenBox.app can migrate OpenClaw
+data into a Hermes VM without image-specific helper scripts:
+
+1. Create a host-managed Hermes backup for the target VM.
+2. Mount one runtime-only host shared folder into both VMs.
+3. Export the source VM's `~/.openclaw` into that shared folder with full user
+   state, including secrets, identity, browser profile, and OpenClaw config.
+4. Extract it inside the Hermes VM and run the official Hermes CLI:
+
+   ```sh
+   hermes claw migrate --dry-run --source <shared>/.openclaw --preset full --migrate-secrets --overwrite
+   hermes claw migrate --source <shared>/.openclaw --preset full --migrate-secrets --overwrite --skill-conflict skip --yes
+   ```
+
+The migration deliberately uses the `full` preset with `--migrate-secrets` so
+Hermes can import every compatible secret and file category its official
+OpenClaw migration flow supports.
+
+TenBox always passes Hermes CLI's global `--overwrite` flag for migration. This
+is required for target-level conflicts such as the existing Hermes soul or model
+config; the UI conflict strategy controls only imported skills via
+`--skill-conflict`.
+
+After the Hermes CLI succeeds, TenBox reads `.openclaw/openclaw.json` and maps
+compatible channel settings into the Hermes environment file:
+
+- Feishu: `appId`, `appSecret`, `domain`, `connectionMode`, `groupPolicy`, and
+  optional allowed users become `FEISHU_*` values.
+- WeCom: `botId`, `secret`, `dmPolicy`, `groupPolicy`, and optional allowed
+  users become `WECOM_*` values.
+
+TenBox also best-effort enables `platforms.feishu` and `platforms.wecom` through
+the Hermes CLI. It does not copy plugin install state, pairing/device runtime
+state, request de-duplication state, or channel adapter internals; users may
+still need to check adapter compatibility after migration.
+
+After the Hermes CLI imports OpenClaw model metadata, TenBox restores the
+running VM's local model proxy settings (`http://10.0.2.3/v1`, API key
+`tenbox`) for the primary model and auxiliary compression, vision, and session
+search models. Imported provider definitions remain available in
+`custom_providers`, but TenBox-managed images should keep routing runtime model
+traffic through the host proxy.