feat(backup): include root tool directories in backup and restore (#15)

* feat(backup): include root config in backup and restore

Signed-off-by: tenfyzhong <tenfy@tenfy.cn>

* feat(backup): include codex claude and agents directories

Signed-off-by: tenfyzhong <tenfy@tenfy.cn>

* feat(runtime): preinstall tools and extend backup roots

Signed-off-by: tenfyzhong <tenfy@tenfy.cn>

---------

Signed-off-by: tenfyzhong <tenfy@tenfy.cn>

Dockerfile

@@ -12,16 +12,19 @@ RUN printf 'Acquire::Retries "5";\nAcquire::http::Timeout "30";\nAcquire::https:
     for attempt in 1 2 3 4 5; do \
       if apt-get update && apt-get install -y --no-install-recommends \
           ca-certificates \
+          chromium-headless-shell \
           cmake \
           cron \
           curl \
           g++ \
+          gh \
           git \
           gnupg \
           gosu \
           hostname \
           jq \
           make \
+          neovim \
           openssl \
           procps \
           python3 \
@@ -82,7 +85,14 @@ RUN /bin/bash -lc 'set -euo pipefail; \
       "/usr/local/bin/$cmd" --help >/dev/null; \
     done'
 
-RUN python3 -m pip install --no-cache-dir --break-system-packages "huggingface_hub[cli]>=0.31.1"
+RUN python3 -m pip install --no-cache-dir --break-system-packages "huggingface_hub[cli]>=0.31.1" "uv>=0.6.0" && \
+    hf --help >/dev/null && \
+    uv --version >/dev/null
+
+RUN python3 --version >/dev/null && \
+    gh --version >/dev/null && \
+    nvim --version >/dev/null && \
+    command -v chromium-headless-shell >/dev/null
 
 RUN HOME=/root /bin/bash -lc "curl -sSf https://sshx.io/get | sh" && \
     if [ -x /root/.local/bin/sshx ]; then ln -sf /root/.local/bin/sshx /usr/local/bin/sshx; fi && \
@@ -119,6 +129,12 @@ ENV OPENCLAW_LLM_API=openai-completions
 ENV OPENCLAW_BACKUP_ENABLED=true
 ENV OPENCLAW_BACKUP_CRON="*/30 * * * *"
 ENV OPENCLAW_BACKUP_SOURCE_DIR=/root/.openclaw
+ENV OPENCLAW_BACKUP_ROOT_CONFIG_DIR=/root/.config
+ENV OPENCLAW_BACKUP_ROOT_CODEX_DIR=/root/.codex
+ENV OPENCLAW_BACKUP_ROOT_CLAUDE_DIR=/root/.claude
+ENV OPENCLAW_BACKUP_ROOT_AGENTS_DIR=/root/.agents
+ENV OPENCLAW_BACKUP_ROOT_SSH_DIR=/root/.ssh
+ENV OPENCLAW_BACKUP_ROOT_NPM_DIR=/root/.npm
 ENV OPENCLAW_SSHX_AUTO_START=false
 ENV OPENCLAW_BACKUP_PRIVATE=true
 ENV OPENCLAW_BACKUP_PATH_PREFIX=backups

README.md

@@ -18,7 +18,7 @@ This setup is designed to provide the following:
 - Store OpenClaw config/workspace under `/root/.openclaw`
 - Restore state automatically from a Hugging Face Dataset on startup
 - Run scheduled backups of OpenClaw data to a Hugging Face Dataset via `cron` (as `root` user)
-- Preinstall `vim`, `opencode`, `codex`, `claude` (Claude Code CLI), and `sshx` in the image for interactive terminal use
+- Preinstall `python3`, `uv`, `vim`, `neovim`, `chromium-headless-shell`, `gh`, `hf`, `opencode`, `codex`, `claude` (Claude Code CLI), and `sshx` in the image for interactive terminal use
 
 ## Repository Layout
 
@@ -66,7 +66,13 @@ In that case, you can still configure from inside the container (for example via
 - `OPENCLAW_CONFIG_PATH` (default: `/root/.openclaw/openclaw.json`)
 - `OPENCLAW_WORKSPACE_DIR` (default: `/root/.openclaw/workspace`)
 - `OPENCLAW_BACKUP_CRON` (default: `*/30 * * * *`, backup every 30 minutes)
-- `OPENCLAW_BACKUP_SOURCE_DIR` (default: `/root/.openclaw`, backup/restore base directory)
+- `OPENCLAW_BACKUP_SOURCE_DIR` (default: `/root/.openclaw`, backup/restore base directory for `openclaw-state`)
+- `OPENCLAW_BACKUP_ROOT_CONFIG_DIR` (default: `/root/.config`, additional backup/restore directory for `root-config`)
+- `OPENCLAW_BACKUP_ROOT_CODEX_DIR` (default: `/root/.codex`, additional backup/restore directory for `root-codex`)
+- `OPENCLAW_BACKUP_ROOT_CLAUDE_DIR` (default: `/root/.claude`, additional backup/restore directory for `root-claude`)
+- `OPENCLAW_BACKUP_ROOT_AGENTS_DIR` (default: `/root/.agents`, additional backup/restore directory for `root-agents`)
+- `OPENCLAW_BACKUP_ROOT_SSH_DIR` (default: `/root/.ssh`, additional backup/restore directory for `root-ssh`)
+- `OPENCLAW_BACKUP_ROOT_NPM_DIR` (default: `/root/.npm`, additional backup/restore directory for `root-npm`)
 - `OPENCLAW_BACKUP_PATH_PREFIX` (default: `backups`)
 - `OPENCLAW_BACKUP_LATEST_NAME` (default: `latest-backup.tar.gz`)
 - `OPENCLAW_BACKUP_KEEP_COUNT` (default: `48`, keep newest N timestamped backup archives; older ones are auto-deleted)
@@ -295,11 +301,25 @@ For this project, if you need stable dashboard access without cold starts, use p
 
 ## Backup/Restore Flow
 
-- Startup restore: on container startup, it tries to fetch `latest-backup.tar.gz` from the Dataset and restore it to `OPENCLAW_BACKUP_SOURCE_DIR` (default `/root/.openclaw`)
+- Startup restore: on container startup, it tries to fetch `latest-backup.tar.gz` from the Dataset and restore:
+  - `openclaw-state` -> `OPENCLAW_BACKUP_SOURCE_DIR` (default `/root/.openclaw`)
+  - `root-config` -> `OPENCLAW_BACKUP_ROOT_CONFIG_DIR` (default `/root/.config`, restored only when present in archive)
+  - `root-codex` -> `OPENCLAW_BACKUP_ROOT_CODEX_DIR` (default `/root/.codex`, restored only when present in archive)
+  - `root-claude` -> `OPENCLAW_BACKUP_ROOT_CLAUDE_DIR` (default `/root/.claude`, restored only when present in archive)
+  - `root-agents` -> `OPENCLAW_BACKUP_ROOT_AGENTS_DIR` (default `/root/.agents`, restored only when present in archive)
+  - `root-ssh` -> `OPENCLAW_BACKUP_ROOT_SSH_DIR` (default `/root/.ssh`, restored only when present in archive)
+  - `root-npm` -> `OPENCLAW_BACKUP_ROOT_NPM_DIR` (default `/root/.npm`, restored only when present in archive)
 - Scheduled backup: cron runs based on `OPENCLAW_BACKUP_CRON`
 - Shutdown backup: when the container receives a stop signal, one final backup is uploaded before exit
 - Each backup upload includes:
   - `backups/openclaw-backup-<timestamp>.tar.gz`
+    - archive root `openclaw-state/`
+    - archive root `root-config/` (included when `OPENCLAW_BACKUP_ROOT_CONFIG_DIR` exists)
+    - archive root `root-codex/` (included when `OPENCLAW_BACKUP_ROOT_CODEX_DIR` exists)
+    - archive root `root-claude/` (included when `OPENCLAW_BACKUP_ROOT_CLAUDE_DIR` exists)
+    - archive root `root-agents/` (included when `OPENCLAW_BACKUP_ROOT_AGENTS_DIR` exists)
+    - archive root `root-ssh/` (included when `OPENCLAW_BACKUP_ROOT_SSH_DIR` exists)
+    - archive root `root-npm/` (included when `OPENCLAW_BACKUP_ROOT_NPM_DIR` exists)
   - `latest-backup.tar.gz`
   - `latest-backup.json`
 - Retention: after upload, only the newest `OPENCLAW_BACKUP_KEEP_COUNT` timestamped archives are kept (default `48`); older timestamped archives are deleted automatically

openclaw_hf/backup.py

@@ -48,6 +48,12 @@ class BackupConfig:
     path_prefix: str
     latest_name: str
     private: bool
+    root_config_dir: Path = Path("/root/.config").resolve()
+    root_codex_dir: Path = Path("/root/.codex").resolve()
+    root_claude_dir: Path = Path("/root/.claude").resolve()
+    root_agents_dir: Path = Path("/root/.agents").resolve()
+    root_ssh_dir: Path = Path("/root/.ssh").resolve()
+    root_npm_dir: Path = Path("/root/.npm").resolve()
     keep_count: int = 48
 
     @classmethod
@@ -62,6 +68,20 @@ class BackupConfig:
             backup_source_dir = Path(backup_source_raw).resolve()
         else:
             backup_source_dir = state_dir
+        root_config_dir = Path(
+            (os.getenv("OPENCLAW_BACKUP_ROOT_CONFIG_DIR") or "/root/.config").strip() or "/root/.config"
+        ).resolve()
+        root_codex_dir = Path(
+            (os.getenv("OPENCLAW_BACKUP_ROOT_CODEX_DIR") or "/root/.codex").strip() or "/root/.codex"
+        ).resolve()
+        root_claude_dir = Path(
+            (os.getenv("OPENCLAW_BACKUP_ROOT_CLAUDE_DIR") or "/root/.claude").strip() or "/root/.claude"
+        ).resolve()
+        root_agents_dir = Path(
+            (os.getenv("OPENCLAW_BACKUP_ROOT_AGENTS_DIR") or "/root/.agents").strip() or "/root/.agents"
+        ).resolve()
+        root_ssh_dir = Path((os.getenv("OPENCLAW_BACKUP_ROOT_SSH_DIR") or "/root/.ssh").strip() or "/root/.ssh").resolve()
+        root_npm_dir = Path((os.getenv("OPENCLAW_BACKUP_ROOT_NPM_DIR") or "/root/.npm").strip() or "/root/.npm").resolve()
         work_dir = Path(os.getenv("OPENCLAW_BACKUP_WORK_DIR", "/tmp/openclaw-backup")).resolve()
         repo_type = (os.getenv("OPENCLAW_BACKUP_REPO_TYPE") or "dataset").strip() or "dataset"
         path_prefix = (os.getenv("OPENCLAW_BACKUP_PATH_PREFIX") or "backups").strip("/")
@@ -94,6 +114,12 @@ class BackupConfig:
             path_prefix=path_prefix,
             latest_name=latest_name,
             private=private,
+            root_config_dir=root_config_dir,
+            root_codex_dir=root_codex_dir,
+            root_claude_dir=root_claude_dir,
+            root_agents_dir=root_agents_dir,
+            root_ssh_dir=root_ssh_dir,
+            root_npm_dir=root_npm_dir,
             keep_count=keep_count,
         )
 
@@ -121,6 +147,16 @@ class OpenClawBackup:
             exist_ok=True,
         )
 
+    def _extra_root_dirs(self) -> dict[str, Path]:
+        return {
+            "root-config": self.config.root_config_dir,
+            "root-codex": self.config.root_codex_dir,
+            "root-claude": self.config.root_claude_dir,
+            "root-agents": self.config.root_agents_dir,
+            "root-ssh": self.config.root_ssh_dir,
+            "root-npm": self.config.root_npm_dir,
+        }
+
     def create_archive(self, timestamp: Optional[str] = None) -> Path:
         if not self.config.backup_source_dir.exists():
             raise FileNotFoundError(f"backup source directory does not exist: {self.config.backup_source_dir}")
@@ -131,6 +167,9 @@ class OpenClawBackup:
         archive = self.config.work_dir / f"openclaw-backup-{stamp}.tar.gz"
         with tarfile.open(archive, "w:gz") as tar:
             tar.add(str(self.config.backup_source_dir), arcname="openclaw-state")
+            for archive_root, local_dir in self._extra_root_dirs().items():
+                if local_dir.exists():
+                    tar.add(str(local_dir), arcname=archive_root)
 
         return archive
 
@@ -162,6 +201,7 @@ class OpenClawBackup:
             "latest": self.config.latest_name,
             "created_at_utc": utc_now().isoformat(timespec="seconds"),
             "state_root": "openclaw-state",
+            "extra_roots": sorted(self._extra_root_dirs().keys()),
         }
         self.api.upload_file(
             repo_id=self.config.dataset_repo,
@@ -294,6 +334,13 @@ class OpenClawBackup:
 
             self.replace_dir_contents(extracted_state, self.config.backup_source_dir)
 
+            for archive_root, local_dir in self._extra_root_dirs().items():
+                extracted_extra_dir = tmp_dir / archive_root
+                if extracted_extra_dir.exists():
+                    if not extracted_extra_dir.is_dir():
+                        raise RuntimeError(f"backup archive {archive_root} is not a directory")
+                    self.replace_dir_contents(extracted_extra_dir, local_dir)
+
         print(f"restore completed from {self.config.dataset_repo}/{self.config.latest_name}")
         return True
 

scripts/openclaw-entrypoint.sh

@@ -19,6 +19,12 @@ OPENCLAW_LLM_API_KEY_ENV="${OPENCLAW_LLM_API_KEY_ENV:-OPENCLAW_LLM_API_KEY}"
 OPENCLAW_BACKUP_ENABLED="${OPENCLAW_BACKUP_ENABLED:-true}"
 OPENCLAW_BACKUP_CRON="${OPENCLAW_BACKUP_CRON:-*/30 * * * *}"
 OPENCLAW_BACKUP_SOURCE_DIR="${OPENCLAW_BACKUP_SOURCE_DIR:-${OPENCLAW_STATE_DIR}}"
+OPENCLAW_BACKUP_ROOT_CONFIG_DIR="${OPENCLAW_BACKUP_ROOT_CONFIG_DIR:-/root/.config}"
+OPENCLAW_BACKUP_ROOT_CODEX_DIR="${OPENCLAW_BACKUP_ROOT_CODEX_DIR:-/root/.codex}"
+OPENCLAW_BACKUP_ROOT_CLAUDE_DIR="${OPENCLAW_BACKUP_ROOT_CLAUDE_DIR:-/root/.claude}"
+OPENCLAW_BACKUP_ROOT_AGENTS_DIR="${OPENCLAW_BACKUP_ROOT_AGENTS_DIR:-/root/.agents}"
+OPENCLAW_BACKUP_ROOT_SSH_DIR="${OPENCLAW_BACKUP_ROOT_SSH_DIR:-/root/.ssh}"
+OPENCLAW_BACKUP_ROOT_NPM_DIR="${OPENCLAW_BACKUP_ROOT_NPM_DIR:-/root/.npm}"
 OPENCLAW_BACKUP_ENV_FILE_PATH="${OPENCLAW_BACKUP_ENV_FILE_PATH:-/etc/openclaw-backup.env}"
 OPENCLAW_STDOUT_LOG_PATH="${OPENCLAW_STDOUT_LOG_PATH:-/var/log/openclaw/gateway.stdout.log}"
 OPENCLAW_STDERR_LOG_PATH="${OPENCLAW_STDERR_LOG_PATH:-/var/log/openclaw/gateway.stderr.log}"
@@ -337,6 +343,12 @@ write_backup_env_file() {
     OPENCLAW_BACKUP_PRIVATE
     OPENCLAW_BACKUP_WORK_DIR
     OPENCLAW_BACKUP_SOURCE_DIR
+    OPENCLAW_BACKUP_ROOT_CONFIG_DIR
+    OPENCLAW_BACKUP_ROOT_CODEX_DIR
+    OPENCLAW_BACKUP_ROOT_CLAUDE_DIR
+    OPENCLAW_BACKUP_ROOT_AGENTS_DIR
+    OPENCLAW_BACKUP_ROOT_SSH_DIR
+    OPENCLAW_BACKUP_ROOT_NPM_DIR
     OPENCLAW_STATE_DIR
   )
 

tests/test_backup.py

@@ -39,6 +39,12 @@ class BackupTests(unittest.TestCase):
 
         self.assertEqual(config.state_dir, Path("/root/.openclaw").resolve())
         self.assertEqual(config.backup_source_dir, config.state_dir)
+        self.assertEqual(config.root_config_dir, Path("/root/.config").resolve())
+        self.assertEqual(config.root_codex_dir, Path("/root/.codex").resolve())
+        self.assertEqual(config.root_claude_dir, Path("/root/.claude").resolve())
+        self.assertEqual(config.root_agents_dir, Path("/root/.agents").resolve())
+        self.assertEqual(config.root_ssh_dir, Path("/root/.ssh").resolve())
+        self.assertEqual(config.root_npm_dir, Path("/root/.npm").resolve())
         self.assertEqual(config.keep_count, 48)
 
     def test_from_env_defaults_backup_source_to_explicit_state_dir_when_unset(self):
@@ -73,6 +79,52 @@ class BackupTests(unittest.TestCase):
 
             self.assertEqual(config.backup_source_dir, backup_source.resolve())
 
+    def test_from_env_uses_explicit_root_config_dir(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            root_config = tmp_path / "root-config"
+            root_config.mkdir()
+
+            env = {
+                "OPENCLAW_BACKUP_DATASET_REPO": "user/demo-backup",
+                "OPENCLAW_BACKUP_ROOT_CONFIG_DIR": str(root_config),
+            }
+            with mock.patch.dict("os.environ", env, clear=True):
+                config = BackupConfig.from_env()
+
+            self.assertEqual(config.root_config_dir, root_config.resolve())
+
+    def test_from_env_uses_explicit_other_root_dirs(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            root_codex = tmp_path / "root-codex"
+            root_claude = tmp_path / "root-claude"
+            root_agents = tmp_path / "root-agents"
+            root_ssh = tmp_path / "root-ssh"
+            root_npm = tmp_path / "root-npm"
+            root_codex.mkdir()
+            root_claude.mkdir()
+            root_agents.mkdir()
+            root_ssh.mkdir()
+            root_npm.mkdir()
+
+            env = {
+                "OPENCLAW_BACKUP_DATASET_REPO": "user/demo-backup",
+                "OPENCLAW_BACKUP_ROOT_CODEX_DIR": str(root_codex),
+                "OPENCLAW_BACKUP_ROOT_CLAUDE_DIR": str(root_claude),
+                "OPENCLAW_BACKUP_ROOT_AGENTS_DIR": str(root_agents),
+                "OPENCLAW_BACKUP_ROOT_SSH_DIR": str(root_ssh),
+                "OPENCLAW_BACKUP_ROOT_NPM_DIR": str(root_npm),
+            }
+            with mock.patch.dict("os.environ", env, clear=True):
+                config = BackupConfig.from_env()
+
+            self.assertEqual(config.root_codex_dir, root_codex.resolve())
+            self.assertEqual(config.root_claude_dir, root_claude.resolve())
+            self.assertEqual(config.root_agents_dir, root_agents.resolve())
+            self.assertEqual(config.root_ssh_dir, root_ssh.resolve())
+            self.assertEqual(config.root_npm_dir, root_npm.resolve())
+
     def test_from_env_uses_explicit_backup_keep_count(self):
         env = {
             "OPENCLAW_BACKUP_DATASET_REPO": "user/demo-backup",
@@ -94,6 +146,7 @@ class BackupTests(unittest.TestCase):
                 dataset_repo="user/demo-backup",
                 state_dir=state_dir,
                 backup_source_dir=state_dir,
+                root_config_dir=tmp_path / "root-config",
                 work_dir=tmp_path / "work",
                 repo_type="dataset",
                 path_prefix="backups",
@@ -124,6 +177,7 @@ class BackupTests(unittest.TestCase):
                 dataset_repo="user/demo-backup",
                 state_dir=state_dir,
                 backup_source_dir=source_dir,
+                root_config_dir=tmp_path / "root-config",
                 work_dir=tmp_path / "work",
                 repo_type="dataset",
                 path_prefix="backups",
@@ -140,6 +194,63 @@ class BackupTests(unittest.TestCase):
 
             self.assertIn("openclaw-state/from-home-node.txt", members)
 
+    def test_create_archive_contains_extra_root_trees_when_exist(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            state_dir = tmp_path / "state"
+            root_config_dir = tmp_path / "root-config"
+            root_codex_dir = tmp_path / "root-codex"
+            root_claude_dir = tmp_path / "root-claude"
+            root_agents_dir = tmp_path / "root-agents"
+            root_ssh_dir = tmp_path / "root-ssh"
+            root_npm_dir = tmp_path / "root-npm"
+            state_dir.mkdir(parents=True)
+            root_config_dir.mkdir(parents=True)
+            root_codex_dir.mkdir(parents=True)
+            root_claude_dir.mkdir(parents=True)
+            root_agents_dir.mkdir(parents=True)
+            root_ssh_dir.mkdir(parents=True)
+            root_npm_dir.mkdir(parents=True)
+            (state_dir / "state.txt").write_text("state\n", encoding="utf-8")
+            (root_config_dir / "settings.json").write_text('{"key":"value"}\n', encoding="utf-8")
+            (root_codex_dir / "config.toml").write_text("theme = \"dark\"\n", encoding="utf-8")
+            (root_claude_dir / "profile.json").write_text('{"provider":"claude"}\n', encoding="utf-8")
+            (root_agents_dir / "agent.yaml").write_text("name: default\n", encoding="utf-8")
+            (root_ssh_dir / "config").write_text("Host *\n  ServerAliveInterval 60\n", encoding="utf-8")
+            (root_npm_dir / "cache-index.json").write_text('{"npm":"cache"}\n', encoding="utf-8")
+
+            config = BackupConfig(
+                dataset_repo="user/demo-backup",
+                state_dir=state_dir,
+                backup_source_dir=state_dir,
+                root_config_dir=root_config_dir,
+                root_codex_dir=root_codex_dir,
+                root_claude_dir=root_claude_dir,
+                root_agents_dir=root_agents_dir,
+                root_ssh_dir=root_ssh_dir,
+                root_npm_dir=root_npm_dir,
+                work_dir=tmp_path / "work",
+                repo_type="dataset",
+                path_prefix="backups",
+                latest_name="latest-backup.tar.gz",
+                private=True,
+            )
+            runner = OpenClawBackup(config=config, api=FakeApi(), token="hf_test")
+
+            archive = runner.create_archive(timestamp="20260324-120000")
+            self.assertTrue(archive.exists())
+
+            with tarfile.open(archive, "r:gz") as tar:
+                members = tar.getnames()
+
+            self.assertIn("openclaw-state/state.txt", members)
+            self.assertIn("root-config/settings.json", members)
+            self.assertIn("root-codex/config.toml", members)
+            self.assertIn("root-claude/profile.json", members)
+            self.assertIn("root-agents/agent.yaml", members)
+            self.assertIn("root-ssh/config", members)
+            self.assertIn("root-npm/cache-index.json", members)
+
     def test_upload_backup_writes_timestamp_and_latest(self):
         with tempfile.TemporaryDirectory() as tmp:
             tmp_path = Path(tmp)
@@ -151,6 +262,7 @@ class BackupTests(unittest.TestCase):
                 dataset_repo="user/demo-backup",
                 state_dir=tmp_path / "state",
                 backup_source_dir=tmp_path / "state",
+                root_config_dir=tmp_path / "root-config",
                 work_dir=tmp_path / "work",
                 repo_type="dataset",
                 path_prefix="backups",
@@ -189,6 +301,7 @@ class BackupTests(unittest.TestCase):
                 dataset_repo="user/demo-backup",
                 state_dir=tmp_path / "state",
                 backup_source_dir=tmp_path / "state",
+                root_config_dir=tmp_path / "root-config",
                 work_dir=tmp_path / "work",
                 repo_type="dataset",
                 path_prefix="backups",
@@ -209,6 +322,166 @@ class BackupTests(unittest.TestCase):
                 ],
             )
 
+    def test_restore_restores_extra_root_dirs_when_present_in_archive(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            state_target = tmp_path / "state-target"
+            root_config_target = tmp_path / "root-config-target"
+            root_codex_target = tmp_path / "root-codex-target"
+            root_claude_target = tmp_path / "root-claude-target"
+            root_agents_target = tmp_path / "root-agents-target"
+            root_ssh_target = tmp_path / "root-ssh-target"
+            root_npm_target = tmp_path / "root-npm-target"
+            state_target.mkdir(parents=True)
+            root_config_target.mkdir(parents=True)
+            root_codex_target.mkdir(parents=True)
+            root_claude_target.mkdir(parents=True)
+            root_agents_target.mkdir(parents=True)
+            root_ssh_target.mkdir(parents=True)
+            root_npm_target.mkdir(parents=True)
+            (state_target / "old-state.txt").write_text("old-state\n", encoding="utf-8")
+            (root_config_target / "old-config.json").write_text('{"old":true}\n', encoding="utf-8")
+            (root_codex_target / "old-codex.toml").write_text("old = true\n", encoding="utf-8")
+            (root_claude_target / "old-claude.json").write_text('{"old":true}\n', encoding="utf-8")
+            (root_agents_target / "old-agent.yaml").write_text("old: true\n", encoding="utf-8")
+            (root_ssh_target / "old-ssh-config").write_text("Host old\n", encoding="utf-8")
+            (root_npm_target / "old-cache.json").write_text('{"old":"cache"}\n', encoding="utf-8")
+
+            restore_payload = tmp_path / "restore-payload"
+            restore_state = restore_payload / "openclaw-state"
+            restore_root_config = restore_payload / "root-config"
+            restore_root_codex = restore_payload / "root-codex"
+            restore_root_claude = restore_payload / "root-claude"
+            restore_root_agents = restore_payload / "root-agents"
+            restore_root_ssh = restore_payload / "root-ssh"
+            restore_root_npm = restore_payload / "root-npm"
+            restore_state.mkdir(parents=True)
+            restore_root_config.mkdir(parents=True)
+            restore_root_codex.mkdir(parents=True)
+            restore_root_claude.mkdir(parents=True)
+            restore_root_agents.mkdir(parents=True)
+            restore_root_ssh.mkdir(parents=True)
+            restore_root_npm.mkdir(parents=True)
+            (restore_state / "new-state.txt").write_text("new-state\n", encoding="utf-8")
+            (restore_root_config / "new-config.json").write_text('{"new":true}\n', encoding="utf-8")
+            (restore_root_codex / "new-codex.toml").write_text("new = true\n", encoding="utf-8")
+            (restore_root_claude / "new-claude.json").write_text('{"new":true}\n', encoding="utf-8")
+            (restore_root_agents / "new-agent.yaml").write_text("new: true\n", encoding="utf-8")
+            (restore_root_ssh / "config").write_text("Host *\n", encoding="utf-8")
+            (restore_root_npm / "cache.json").write_text('{"new":"cache"}\n', encoding="utf-8")
+
+            archive = tmp_path / "latest-backup.tar.gz"
+            with tarfile.open(archive, "w:gz") as tar:
+                tar.add(str(restore_state), arcname="openclaw-state")
+                tar.add(str(restore_root_config), arcname="root-config")
+                tar.add(str(restore_root_codex), arcname="root-codex")
+                tar.add(str(restore_root_claude), arcname="root-claude")
+                tar.add(str(restore_root_agents), arcname="root-agents")
+                tar.add(str(restore_root_ssh), arcname="root-ssh")
+                tar.add(str(restore_root_npm), arcname="root-npm")
+
+            config = BackupConfig(
+                dataset_repo="user/demo-backup",
+                state_dir=state_target,
+                backup_source_dir=state_target,
+                root_config_dir=root_config_target,
+                root_codex_dir=root_codex_target,
+                root_claude_dir=root_claude_target,
+                root_agents_dir=root_agents_target,
+                root_ssh_dir=root_ssh_target,
+                root_npm_dir=root_npm_target,
+                work_dir=tmp_path / "work",
+                repo_type="dataset",
+                path_prefix="backups",
+                latest_name="latest-backup.tar.gz",
+                private=True,
+            )
+            runner = OpenClawBackup(config=config, api=FakeApi(), token="hf_test")
+
+            with mock.patch.object(runner, "download_latest_archive", return_value=archive):
+                restored = runner.restore()
+
+            self.assertTrue(restored)
+            self.assertTrue((state_target / "new-state.txt").exists())
+            self.assertFalse((state_target / "old-state.txt").exists())
+            self.assertTrue((root_config_target / "new-config.json").exists())
+            self.assertFalse((root_config_target / "old-config.json").exists())
+            self.assertTrue((root_codex_target / "new-codex.toml").exists())
+            self.assertFalse((root_codex_target / "old-codex.toml").exists())
+            self.assertTrue((root_claude_target / "new-claude.json").exists())
+            self.assertFalse((root_claude_target / "old-claude.json").exists())
+            self.assertTrue((root_agents_target / "new-agent.yaml").exists())
+            self.assertFalse((root_agents_target / "old-agent.yaml").exists())
+            self.assertTrue((root_ssh_target / "config").exists())
+            self.assertFalse((root_ssh_target / "old-ssh-config").exists())
+            self.assertTrue((root_npm_target / "cache.json").exists())
+            self.assertFalse((root_npm_target / "old-cache.json").exists())
+
+    def test_restore_keeps_extra_root_dirs_untouched_when_archive_missing_them(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = Path(tmp)
+            state_target = tmp_path / "state-target"
+            root_config_target = tmp_path / "root-config-target"
+            root_codex_target = tmp_path / "root-codex-target"
+            root_claude_target = tmp_path / "root-claude-target"
+            root_agents_target = tmp_path / "root-agents-target"
+            root_ssh_target = tmp_path / "root-ssh-target"
+            root_npm_target = tmp_path / "root-npm-target"
+            state_target.mkdir(parents=True)
+            root_config_target.mkdir(parents=True)
+            root_codex_target.mkdir(parents=True)
+            root_claude_target.mkdir(parents=True)
+            root_agents_target.mkdir(parents=True)
+            root_ssh_target.mkdir(parents=True)
+            root_npm_target.mkdir(parents=True)
+            (state_target / "old-state.txt").write_text("old-state\n", encoding="utf-8")
+            (root_config_target / "old-config.json").write_text('{"old":true}\n', encoding="utf-8")
+            (root_codex_target / "old-codex.toml").write_text("old = true\n", encoding="utf-8")
+            (root_claude_target / "old-claude.json").write_text('{"old":true}\n', encoding="utf-8")
+            (root_agents_target / "old-agent.yaml").write_text("old: true\n", encoding="utf-8")
+            (root_ssh_target / "old-ssh-config").write_text("Host old\n", encoding="utf-8")
+            (root_npm_target / "old-cache.json").write_text('{"old":"cache"}\n', encoding="utf-8")
+
+            restore_payload = tmp_path / "restore-payload"
+            restore_state = restore_payload / "openclaw-state"
+            restore_state.mkdir(parents=True)
+            (restore_state / "new-state.txt").write_text("new-state\n", encoding="utf-8")
+
+            archive = tmp_path / "latest-backup.tar.gz"
+            with tarfile.open(archive, "w:gz") as tar:
+                tar.add(str(restore_state), arcname="openclaw-state")
+
+            config = BackupConfig(
+                dataset_repo="user/demo-backup",
+                state_dir=state_target,
+                backup_source_dir=state_target,
+                root_config_dir=root_config_target,
+                root_codex_dir=root_codex_target,
+                root_claude_dir=root_claude_target,
+                root_agents_dir=root_agents_target,
+                root_ssh_dir=root_ssh_target,
+                root_npm_dir=root_npm_target,
+                work_dir=tmp_path / "work",
+                repo_type="dataset",
+                path_prefix="backups",
+                latest_name="latest-backup.tar.gz",
+                private=True,
+            )
+            runner = OpenClawBackup(config=config, api=FakeApi(), token="hf_test")
+
+            with mock.patch.object(runner, "download_latest_archive", return_value=archive):
+                restored = runner.restore()
+
+            self.assertTrue(restored)
+            self.assertTrue((state_target / "new-state.txt").exists())
+            self.assertFalse((state_target / "old-state.txt").exists())
+            self.assertTrue((root_config_target / "old-config.json").exists())
+            self.assertTrue((root_codex_target / "old-codex.toml").exists())
+            self.assertTrue((root_claude_target / "old-claude.json").exists())
+            self.assertTrue((root_agents_target / "old-agent.yaml").exists())
+            self.assertTrue((root_ssh_target / "old-ssh-config").exists())
+            self.assertTrue((root_npm_target / "old-cache.json").exists())
+
     def test_replace_dir_contents_clears_old_files(self):
         with tempfile.TemporaryDirectory() as tmp:
             tmp_path = Path(tmp)

tests/test_runtime_user_defaults.py

@@ -25,6 +25,12 @@ class RuntimeUserDefaultsTests(unittest.TestCase):
         self.assertIn("ENV OPENCLAW_USER=root", dockerfile)
         self.assertIn("ENV OPENCLAW_GROUP=root", dockerfile)
         self.assertIn("ENV OPENCLAW_BACKUP_SOURCE_DIR=/root/.openclaw", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_CONFIG_DIR=/root/.config", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_CODEX_DIR=/root/.codex", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_CLAUDE_DIR=/root/.claude", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_AGENTS_DIR=/root/.agents", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_SSH_DIR=/root/.ssh", dockerfile)
+        self.assertIn("ENV OPENCLAW_BACKUP_ROOT_NPM_DIR=/root/.npm", dockerfile)
         self.assertIn('OPENCLAW_BIN="$(command -v openclaw || true)"', dockerfile)
         self.assertIn('if [[ -z "$OPENCLAW_BIN" ]] && [[ -x /root/.npm-global/bin/openclaw ]]; then', dockerfile)
         self.assertIn('elif [[ -z "$OPENCLAW_BIN" ]] && [[ -x /root/.local/bin/openclaw ]]; then', dockerfile)
@@ -40,7 +46,11 @@ class RuntimeUserDefaultsTests(unittest.TestCase):
 
     def test_dockerfile_preinstalls_common_cli_tools(self):
         dockerfile = self._dockerfile_path().read_text(encoding="utf-8")
+        self.assertIn("python3", dockerfile)
         self.assertIn("vim; then", dockerfile)
+        self.assertIn("neovim", dockerfile)
+        self.assertIn("chromium-headless-shell", dockerfile)
+        self.assertIn("gh", dockerfile)
         self.assertIn(
             "npm install -g --no-audit --no-fund opencode-ai @openai/codex @anthropic-ai/claude-code",
             dockerfile,
@@ -48,6 +58,8 @@ class RuntimeUserDefaultsTests(unittest.TestCase):
         self.assertIn("for cmd in opencode codex claude; do", dockerfile)
         self.assertIn('ln -sf "$CLI_BIN" "/usr/local/bin/$cmd"', dockerfile)
         self.assertIn('"/usr/local/bin/$cmd" --help >/dev/null', dockerfile)
+        self.assertIn('hf --help >/dev/null', dockerfile)
+        self.assertIn("uv --version >/dev/null", dockerfile)
 
     def test_entrypoint_defaults_to_root_runtime_user(self):
         entrypoint = self._entrypoint_path().read_text(encoding="utf-8")
@@ -55,6 +67,12 @@ class RuntimeUserDefaultsTests(unittest.TestCase):
         self.assertIn('OPENCLAW_GROUP="${OPENCLAW_GROUP:-root}"', entrypoint)
         self.assertIn('OPENCLAW_HOME="${OPENCLAW_HOME:-/root}"', entrypoint)
         self.assertIn('OPENCLAW_BACKUP_SOURCE_DIR="${OPENCLAW_BACKUP_SOURCE_DIR:-${OPENCLAW_STATE_DIR}}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_CONFIG_DIR="${OPENCLAW_BACKUP_ROOT_CONFIG_DIR:-/root/.config}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_CODEX_DIR="${OPENCLAW_BACKUP_ROOT_CODEX_DIR:-/root/.codex}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_CLAUDE_DIR="${OPENCLAW_BACKUP_ROOT_CLAUDE_DIR:-/root/.claude}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_AGENTS_DIR="${OPENCLAW_BACKUP_ROOT_AGENTS_DIR:-/root/.agents}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_SSH_DIR="${OPENCLAW_BACKUP_ROOT_SSH_DIR:-/root/.ssh}"', entrypoint)
+        self.assertIn('OPENCLAW_BACKUP_ROOT_NPM_DIR="${OPENCLAW_BACKUP_ROOT_NPM_DIR:-/root/.npm}"', entrypoint)
 
     def test_backup_cron_uses_openclaw_user(self):
         entrypoint = self._entrypoint_path().read_text(encoding="utf-8")
@@ -83,6 +101,12 @@ class RuntimeUserDefaultsTests(unittest.TestCase):
     def test_backup_env_file_includes_keep_count(self):
         entrypoint = self._entrypoint_path().read_text(encoding="utf-8")
         self.assertIn("OPENCLAW_BACKUP_KEEP_COUNT", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_CONFIG_DIR", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_CODEX_DIR", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_CLAUDE_DIR", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_AGENTS_DIR", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_SSH_DIR", entrypoint)
+        self.assertIn("OPENCLAW_BACKUP_ROOT_NPM_DIR", entrypoint)
 
     def test_sshx_auto_start_does_not_use_command_substitution(self):
         entrypoint = self._entrypoint_path().read_text(encoding="utf-8")