refactor: add overwrite option to various services and update documentation

backend/app/services/openclaw/admin_service.py

@@ -347,6 +347,7 @@ class GatewayAdminLifecycleService(OpenClawDBService):
                 reset_sessions=query.reset_sessions,
                 rotate_tokens=query.rotate_tokens,
                 force_bootstrap=query.force_bootstrap,
+                overwrite=query.overwrite,
                 board_id=query.board_id,
             ),
         )

backend/app/services/openclaw/provisioning.py

@@ -61,6 +61,7 @@ class ProvisionOptions:
 
     action: str = "provision"
     force_bootstrap: bool = False
+    overwrite: bool = False
 
 
 _ROLE_SOUL_MAX_CHARS = 24_000
@@ -715,6 +716,7 @@ class BaseAgentLifecycleManager(ABC):
         desired_file_names: set[str] | None = None,
         existing_files: dict[str, dict[str, Any]],
         action: str,
+        overwrite: bool = False,
     ) -> None:
         preserve_files = (
             self._preserve_files(agent) if agent is not None else set(PRESERVE_AGENT_EDITABLE_FILES)
@@ -728,15 +730,10 @@ class BaseAgentLifecycleManager(ABC):
             # Preserve "editable" files only during updates. During first-time provisioning,
             # the gateway may pre-create defaults for USER/MEMORY/etc, and we still want to
             # apply Mission Control's templates.
-            if action == "update" and name in preserve_files:
+            if action == "update" and not overwrite and name in preserve_files:
                 entry = existing_files.get(name)
                 if entry and not bool(entry.get("missing")):
-                    size = entry.get("size")
-                    if isinstance(size, int) and size == 0:
-                        # Treat 0-byte placeholders as missing so update can fill them.
-                        pass
-                    else:
-                        continue
+                    continue
             try:
                 await self._control_plane.set_agent_file(
                     agent_id=agent_id,
@@ -840,6 +837,7 @@ class BaseAgentLifecycleManager(ABC):
             desired_file_names=set(rendered.keys()),
             existing_files=existing_files,
             action=options.action,
+            overwrite=options.overwrite,
         )
 
 
@@ -1013,6 +1011,7 @@ class OpenClawGatewayProvisioner:
         user: User | None,
         action: str = "provision",
         force_bootstrap: bool = False,
+        overwrite: bool = False,
         reset_session: bool = False,
         wake: bool = True,
         deliver_wakeup: bool = True,
@@ -1056,7 +1055,11 @@ class OpenClawGatewayProvisioner:
             session_key=session_key,
             auth_token=auth_token,
             user=user,
-            options=ProvisionOptions(action=action, force_bootstrap=force_bootstrap),
+            options=ProvisionOptions(
+                action=action,
+                force_bootstrap=force_bootstrap,
+                overwrite=overwrite,
+            ),
             session_label=agent.name or "Gateway Agent",
         )
 

backend/app/services/openclaw/provisioning_db.py

@@ -113,6 +113,7 @@ class GatewayTemplateSyncOptions:
     reset_sessions: bool = False
     rotate_tokens: bool = False
     force_bootstrap: bool = False
+    overwrite: bool = False
     board_id: UUID | None = None
 
 
@@ -569,6 +570,7 @@ async def _sync_one_agent(
                 user=ctx.options.user,
                 action="update",
                 force_bootstrap=ctx.options.force_bootstrap,
+                overwrite=ctx.options.overwrite,
                 reset_session=ctx.options.reset_sessions,
                 wake=False,
             )
@@ -639,6 +641,7 @@ async def _sync_main_agent(
                 user=ctx.options.user,
                 action="update",
                 force_bootstrap=ctx.options.force_bootstrap,
+                overwrite=ctx.options.overwrite,
                 reset_session=ctx.options.reset_sessions,
                 wake=False,
             )

backend/app/services/openclaw/session_service.py

@@ -48,6 +48,7 @@ class GatewayTemplateSyncQuery:
     reset_sessions: bool
     rotate_tokens: bool
     force_bootstrap: bool
+    overwrite: bool
     board_id: UUID | None