refactor: update gateway agent session key handling and improve related logic

backend/app/services/agent_provisioning.py

@@ -16,6 +16,7 @@ from jinja2 import Environment, FileSystemLoader, StrictUndefined, select_autoes
 from app.core.config import settings
 from app.integrations.openclaw_gateway import GatewayConfig as GatewayClientConfig
 from app.integrations.openclaw_gateway import OpenClawGatewayError, ensure_session, openclaw_call
+from app.services.gateway_agents import gateway_agent_session_key
 
 if TYPE_CHECKING:
     from app.models.agents import Agent
@@ -124,6 +125,7 @@ class MainAgentProvisionRequest:
     gateway: Gateway
     auth_token: str
     user: User | None
+    session_key: str | None = None
     options: ProvisionOptions = field(default_factory=ProvisionOptions)
 
 
@@ -307,15 +309,12 @@ def _build_context(
     if not gateway.workspace_root:
         msg = "gateway_workspace_root is required"
         raise ValueError(msg)
-    if not gateway.main_session_key:
-        msg = "gateway_main_session_key is required"
-        raise ValueError(msg)
     agent_id = str(agent.id)
     workspace_root = gateway.workspace_root
     workspace_path = _workspace_path(agent, workspace_root)
     session_key = agent.openclaw_session_id or ""
     base_url = settings.base_url or "REPLACE_WITH_BASE_URL"
-    main_session_key = gateway.main_session_key
+    main_session_key = gateway_agent_session_key(gateway)
     identity_profile: dict[str, Any] = {}
     if isinstance(agent.identity_profile, dict):
         identity_profile = agent.identity_profile
@@ -411,7 +410,7 @@ def _build_main_context(
         "session_key": agent.openclaw_session_id or "",
         "base_url": base_url,
         "auth_token": auth_token,
-        "main_session_key": gateway.main_session_key or "",
+        "main_session_key": gateway_agent_session_key(gateway),
         "workspace_root": gateway.workspace_root or "",
         "user_name": (user.name or "") if user else "",
         "user_preferred_name": preferred_name,
@@ -870,20 +869,30 @@ async def provision_main_agent(
     gateway = request.gateway
     if not gateway.url:
         return
-    if not gateway.main_session_key:
-        msg = "gateway main_session_key is required"
+    session_key = (request.session_key or gateway.main_session_key or "").strip()
+    if not session_key:
+        msg = "gateway main agent session_key is required"
         raise ValueError(msg)
     client_config = GatewayClientConfig(url=gateway.url, token=gateway.token)
     await ensure_session(
-        gateway.main_session_key,
+        session_key,
         config=client_config,
-        label="Main Agent",
+        label=agent.name or "Gateway Agent",
     )
 
-    agent_id = await _gateway_default_agent_id(
-        client_config,
-        fallback_session_key=gateway.main_session_key,
-    )
+    agent_id = _agent_id_from_session_key(session_key)
+    if agent_id:
+        if not gateway.workspace_root:
+            msg = "gateway_workspace_root is required"
+            raise ValueError(msg)
+        workspace_path = _workspace_path(agent, gateway.workspace_root)
+        heartbeat = _heartbeat_config(agent)
+        await _patch_gateway_agent_list(agent_id, workspace_path, heartbeat, client_config)
+    else:
+        agent_id = await _gateway_default_agent_id(
+            client_config,
+            fallback_session_key=session_key,
+        )
     if not agent_id:
         msg = "Unable to resolve gateway main agent id"
         raise OpenClawGatewayError(msg)
@@ -912,7 +921,7 @@ async def provision_main_agent(
         client_config=client_config,
     )
     if request.options.reset_session:
-        await _reset_session(gateway.main_session_key, client_config)
+        await _reset_session(session_key, client_config)
 
 
 async def cleanup_agent(