refactor: enhance gateway agent handling with dedicated OpenClaw agent IDs

backend/app/services/agent_provisioning.py

@@ -16,7 +16,11 @@ 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
+from app.services.gateway_agents import (
+    gateway_agent_session_key,
+    gateway_openclaw_agent_id,
+    parse_gateway_agent_session_key,
+)
 
 if TYPE_CHECKING:
     from app.models.agents import Agent
@@ -146,6 +150,9 @@ def _agent_id_from_session_key(session_key: str | None) -> str | None:
     value = (session_key or "").strip()
     if not value:
         return None
+    # Dedicated Mission Control gateway-agent session keys are not gateway config agent ids.
+    if parse_gateway_agent_session_key(value) is not None:
+        return None
     if not value.startswith("agent:"):
         return None
     parts = value.split(":")
@@ -880,22 +887,14 @@ async def provision_main_agent(
         label=agent.name or "Gateway Agent",
     )
 
-    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)
+    # Keep gateway default agent intact and use a dedicated OpenClaw agent id for Mission Control.
+    if not gateway.workspace_root:
+        msg = "gateway_workspace_root is required"
+        raise ValueError(msg)
+    agent_id = gateway_openclaw_agent_id(gateway)
+    workspace_path = _workspace_path(agent, gateway.workspace_root)
+    heartbeat = _heartbeat_config(agent)
+    await _patch_gateway_agent_list(agent_id, workspace_path, heartbeat, client_config)
 
     context = _build_main_context(agent, gateway, request.auth_token, request.user)
     supported = set(await _supported_gateway_files(client_config))

backend/app/services/gateway_agents.py

@@ -8,6 +8,7 @@ from app.models.gateways import Gateway
 
 _GATEWAY_AGENT_PREFIX = "agent:gateway-"
 _GATEWAY_AGENT_SUFFIX = ":main"
+_GATEWAY_OPENCLAW_AGENT_PREFIX = "mc-gateway-"
 
 
 def gateway_agent_session_key_for_id(gateway_id: UUID) -> str:
@@ -20,6 +21,16 @@ def gateway_agent_session_key(gateway: Gateway) -> str:
     return gateway_agent_session_key_for_id(gateway.id)
 
 
+def gateway_openclaw_agent_id_for_id(gateway_id: UUID) -> str:
+    """Return the dedicated OpenClaw config `agentId` for a gateway agent."""
+    return f"{_GATEWAY_OPENCLAW_AGENT_PREFIX}{gateway_id}"
+
+
+def gateway_openclaw_agent_id(gateway: Gateway) -> str:
+    """Return the dedicated OpenClaw config `agentId` for a gateway agent."""
+    return gateway_openclaw_agent_id_for_id(gateway.id)
+
+
 def parse_gateway_agent_session_key(session_key: str | None) -> UUID | None:
     """Parse a gateway id from a dedicated gateway-agent session key."""
     value = (session_key or "").strip()

backend/app/services/template_sync.py

@@ -31,7 +31,11 @@ from app.services.agent_provisioning import (
     provision_agent,
     provision_main_agent,
 )
-from app.services.gateway_agents import gateway_agent_session_key
+from app.services.gateway_agents import (
+    gateway_agent_session_key,
+    gateway_openclaw_agent_id,
+    parse_gateway_agent_session_key,
+)
 
 _TOOLS_KV_RE = re.compile(r"^(?P<key>[A-Z0-9_]+)=(?P<value>.*)$")
 SESSION_KEY_PARTS_MIN = 2
@@ -179,6 +183,9 @@ def _agent_id_from_session_key(session_key: str | None) -> str | None:
     value = (session_key or "").strip()
     if not value:
         return None
+    # Dedicated Mission Control gateway-agent session keys are not gateway config agent ids.
+    if parse_gateway_agent_session_key(value) is not None:
+        return None
     if not value.startswith("agent:"):
         return None
     parts = value.split(":")
@@ -314,6 +321,7 @@ async def _gateway_default_agent_id(
             return agent_id
     except OpenClawGatewayError:
         pass
+    # Avoid falling back to dedicated gateway session keys, which are not agent ids.
     return _agent_id_from_session_key(fallback_session_key)
 
 
@@ -533,22 +541,7 @@ async def _sync_main_agent(
             message=("Gateway agent record not found; " "skipping gateway agent template sync."),
         )
         return True
-    try:
-        main_gateway_agent_id = await _gateway_default_agent_id(
-            ctx.config,
-            fallback_session_key=main_session_key,
-            backoff=ctx.backoff,
-        )
-    except TimeoutError as exc:
-        _append_sync_error(result, agent=main_agent, message=str(exc))
-        return True
-    if not main_gateway_agent_id:
-        _append_sync_error(
-            result,
-            agent=main_agent,
-            message="Unable to resolve gateway agent id.",
-        )
-        return True
+    main_gateway_agent_id = gateway_openclaw_agent_id(ctx.gateway)
 
     token, fatal = await _resolve_agent_auth_token(
         ctx,