@swarmclawai/swarmclaw 0.7.5 → 0.7.7

package/src/components/providers/provider-list.tsx

@@ -1,9 +1,30 @@
 'use client'
 
 import { useCallback, useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import { OpenClawDeployPanel } from '@/components/openclaw/openclaw-deploy-panel'
 import { useAppStore } from '@/stores/use-app-store'
 import { useWs } from '@/hooks/use-ws'
 import { api } from '@/lib/api-client'
+import type { Credential, GatewayProfile } from '@/types'
+
+interface OpenClawDeployDraft {
+  endpoint: string
+  token?: string
+  name?: string
+  notes?: string
+  deployment?: GatewayProfile['deployment']
+}
+
+function formatRuntimeTimestamp(value: number | null | undefined): string {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return 'Never'
+  return new Intl.DateTimeFormat(undefined, {
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  }).format(value)
+}
 
 export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
   const providers = useAppStore((s) => s.providers)
@@ -21,6 +42,8 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
   const setGatewaySheetOpen = useAppStore((s) => s.setGatewaySheetOpen)
   const setEditingGatewayId = useAppStore((s) => s.setEditingGatewayId)
   const [loaded, setLoaded] = useState(false)
+  const [deployDraft, setDeployDraft] = useState<OpenClawDeployDraft | null>(null)
+  const [savingDeploy, setSavingDeploy] = useState(false)
 
   const refresh = useCallback(async () => {
     await Promise.all([loadProviders(), loadProviderConfigs(), loadGatewayProfiles(), loadExternalAgents(), loadCredentials()])
@@ -66,6 +89,132 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
     await loadGatewayProfiles()
   }
 
+  const handleDeployApply = (patch: { endpoint?: string; token?: string; name?: string; notes?: string; deployment?: GatewayProfile['deployment'] | Record<string, unknown> | null }) => {
+    if (!patch.endpoint) return
+    setDeployDraft({
+      endpoint: patch.endpoint,
+      token: patch.token,
+      name: patch.name,
+      notes: patch.notes,
+      deployment: (patch.deployment as GatewayProfile['deployment']) || null,
+    })
+  }
+
+  const handleSavePreparedGateway = async () => {
+    if (!deployDraft?.endpoint) return
+    setSavingDeploy(true)
+    try {
+      let nextCredentialId: string | null = null
+      if (deployDraft.token?.trim()) {
+        const credential = await api<Credential>('POST', '/credentials', {
+          provider: 'openclaw',
+          name: `${deployDraft.name || 'OpenClaw Gateway'} token`,
+          apiKey: deployDraft.token.trim(),
+        })
+        nextCredentialId = credential.id
+      }
+
+      const existing = gatewayProfiles.find((gateway) => gateway.endpoint === deployDraft.endpoint) || null
+      const nextTags = Array.from(new Set([
+        ...(existing?.tags || []),
+        'managed-deploy',
+        ...(deployDraft.deployment?.useCase ? [deployDraft.deployment.useCase] : []),
+        ...(deployDraft.deployment?.exposure ? [deployDraft.deployment.exposure] : []),
+      ]))
+      const verify = await api<{
+        ok: boolean
+        verify?: {
+          ok: boolean
+          error?: string
+          hint?: string
+          models?: string[]
+        }
+      }>('POST', '/openclaw/deploy', {
+        action: 'verify',
+        endpoint: deployDraft.endpoint,
+        token: deployDraft.token?.trim() || undefined,
+      }).catch(() => ({ ok: false, verify: undefined as undefined }))
+      const verifiedOk = verify.verify?.ok === true
+      const payload = {
+        name: deployDraft.name || existing?.name || 'OpenClaw Gateway',
+        endpoint: deployDraft.endpoint,
+        credentialId: nextCredentialId || existing?.credentialId || null,
+        notes: deployDraft.notes || existing?.notes || 'Managed OpenClaw deploy prepared from SwarmClaw.',
+        tags: nextTags,
+        status: verifiedOk ? 'healthy' : (existing?.status || 'pending'),
+        deployment: {
+          ...(existing?.deployment || {}),
+          ...(deployDraft.deployment || {}),
+          managedBy: 'swarmclaw',
+          lastVerifiedAt: verify.verify ? Date.now() : (existing?.deployment?.lastVerifiedAt || null),
+          lastVerifiedOk: verify.verify ? verifiedOk : (existing?.deployment?.lastVerifiedOk ?? null),
+          lastVerifiedMessage: verify.verify
+            ? (verifiedOk
+              ? `Verified during save with ${verify.verify.models?.length || 0} model${(verify.verify.models?.length || 0) === 1 ? '' : 's'}.`
+              : (verify.verify.error || verify.verify.hint || 'Verification failed.'))
+            : (existing?.deployment?.lastVerifiedMessage || null),
+        },
+        isDefault: existing?.isDefault === true || gatewayProfiles.length === 0,
+      }
+
+      if (existing) {
+        await api('PUT', `/gateways/${existing.id}`, payload)
+      } else {
+        await api('POST', '/gateways', payload)
+      }
+
+      await Promise.all([loadGatewayProfiles(), loadCredentials()])
+      setDeployDraft(null)
+      toast.success(existing ? 'Gateway profile updated' : 'Gateway profile saved')
+    } catch (err: unknown) {
+      toast.error(err instanceof Error ? err.message : 'Failed to save prepared gateway')
+    } finally {
+      setSavingDeploy(false)
+    }
+  }
+
+  const handleCloneGateway = async (e: React.MouseEvent, gateway: GatewayProfile) => {
+    e.stopPropagation()
+    try {
+      await api('POST', '/gateways', {
+        name: `${gateway.name} Copy`,
+        endpoint: gateway.endpoint,
+        credentialId: gateway.credentialId || null,
+        notes: gateway.notes || null,
+        tags: gateway.tags || [],
+        deployment: gateway.deployment || null,
+        stats: gateway.stats || null,
+        isDefault: false,
+      })
+      await loadGatewayProfiles()
+      toast.success('Gateway cloned')
+    } catch (err: unknown) {
+      toast.error(err instanceof Error ? err.message : 'Failed to clone gateway')
+    }
+  }
+
+  const handleRuntimeAction = async (
+    e: React.MouseEvent,
+    runtimeId: string,
+    action: 'activate' | 'drain' | 'cordon' | 'restart',
+  ) => {
+    e.stopPropagation()
+    try {
+      await api('PUT', `/external-agents/${runtimeId}`, { action })
+      await loadExternalAgents()
+      const actionLabel = action === 'activate'
+        ? 'Runtime activated'
+        : action === 'drain'
+          ? 'Runtime draining'
+          : action === 'cordon'
+            ? 'Runtime cordoned'
+            : 'Restart requested'
+      toast.success(actionLabel)
+    } catch (err: unknown) {
+      toast.error(err instanceof Error ? err.message : 'Runtime action failed')
+    }
+  }
+
   // Merge built-in providers with custom configs
   const builtinItems = providers.map((p) => ({
     id: p.id,
@@ -88,6 +237,18 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
   }))
 
   const allItems = [...builtinItems, ...customItems]
+  const gatewayNameById = new Map(gatewayProfiles.map((gateway) => [gateway.id, gateway.name]))
+  const runtimeHealthByGateway = externalAgents.reduce<Record<string, { total: number; active: number; lastHeartbeatAt: number | null }>>((acc, runtime) => {
+    if (!runtime.gatewayProfileId) return acc
+    const current = acc[runtime.gatewayProfileId] || { total: 0, active: 0, lastHeartbeatAt: null }
+    current.total += 1
+    if (runtime.status === 'online' || runtime.status === 'idle') current.active += 1
+    if (typeof runtime.lastSeenAt === 'number' && (!current.lastHeartbeatAt || runtime.lastSeenAt > current.lastHeartbeatAt)) {
+      current.lastHeartbeatAt = runtime.lastSeenAt
+    }
+    acc[runtime.gatewayProfileId] = current
+    return acc
+  }, {})
 
   if (!loaded) {
     return (
@@ -180,17 +341,54 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
       <div className="mt-8 mb-4 flex items-center justify-between">
         <div className="text-[12px] font-700 uppercase tracking-[0.08em] text-text-3/60">OpenClaw Gateways</div>
         {!inSidebar && (
-          <button
-            type="button"
-            onClick={() => handleEditGateway(null)}
-            className="px-3 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] transition-all cursor-pointer"
-          >
-            + New Gateway
-          </button>
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              onClick={() => handleEditGateway(null)}
+              className="px-3 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] transition-all cursor-pointer"
+            >
+              + New Gateway
+            </button>
+          </div>
         )}
       </div>
+      {!inSidebar && (
+        <div className="mb-4 rounded-[16px] border border-white/[0.06] bg-white/[0.02] p-4">
+          <OpenClawDeployPanel
+            compact
+            title="Deploy OpenClaw Control Planes"
+            description="Use official OpenClaw sources only. Start a local control plane on this machine, or generate a pre-configured remote bundle for Docker VPS hosts like Hetzner, DigitalOcean, Vultr, Linode, Lightsail, plus Render, Fly.io, and Railway."
+            onApply={handleDeployApply}
+          />
+          {deployDraft?.endpoint && (
+            <div className="mt-3 flex flex-wrap items-center justify-between gap-3 rounded-[12px] border border-emerald-500/20 bg-emerald-500/[0.05] px-4 py-3">
+              <div>
+                <div className="text-[13px] font-700 text-emerald-300">Prepared gateway profile</div>
+                <div className="mt-1 text-[12px] text-text-3">
+                  {deployDraft.name || 'OpenClaw Gateway'} · <code className="text-text-2">{deployDraft.endpoint}</code>
+                </div>
+              </div>
+              <div className="flex flex-wrap gap-2">
+                <button
+                  type="button"
+                  onClick={() => void handleSavePreparedGateway()}
+                  disabled={savingDeploy}
+                  className="rounded-[10px] bg-accent-bright px-3.5 py-2 text-[12px] font-700 text-white border-none cursor-pointer hover:brightness-110 transition-all disabled:opacity-40"
+                >
+                  {savingDeploy ? 'Saving…' : 'Save Prepared Gateway'}
+                </button>
+              </div>
+            </div>
+          )}
+        </div>
+      )}
       <div className={inSidebar ? 'space-y-2' : 'grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-3'}>
         {gatewayProfiles.map((gateway, idx) => (
+          (() => {
+            const runtimeStats = runtimeHealthByGateway[gateway.id] || { total: 0, active: 0, lastHeartbeatAt: null }
+            const deployment = gateway.deployment || null
+            const stats = gateway.stats || null
+            return (
           <div
             key={gateway.id}
             role="button"
@@ -232,21 +430,61 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
             <div className="text-[12px] text-text-3/70">
               {gateway.tags?.length ? gateway.tags.join(', ') : (gateway.notes || 'Dedicated OpenClaw control plane')}
             </div>
+            {!inSidebar && (
+              <div className="mt-3 grid grid-cols-2 gap-2 text-[11px] text-text-3/65">
+                <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                  <div className="uppercase tracking-[0.08em] text-text-3/50">Deploy</div>
+                  <div className="mt-1 text-text-2">
+                    {deployment?.method || 'manual'}
+                    {deployment?.provider ? ` · ${deployment.provider}` : ''}
+                  </div>
+                </div>
+                <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                  <div className="uppercase tracking-[0.08em] text-text-3/50">Route hints</div>
+                  <div className="mt-1 text-text-2">
+                    {deployment?.useCase || 'general'}
+                    {deployment?.exposure ? ` · ${deployment.exposure}` : ''}
+                  </div>
+                </div>
+                <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                  <div className="uppercase tracking-[0.08em] text-text-3/50">Nodes / devices</div>
+                  <div className="mt-1 text-text-2">
+                    {stats?.connectedNodeCount ?? 0}/{stats?.nodeCount ?? 0} nodes · {stats?.pairedDeviceCount ?? 0} devices
+                  </div>
+                </div>
+                <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                  <div className="uppercase tracking-[0.08em] text-text-3/50">Runtimes</div>
+                  <div className="mt-1 text-text-2">
+                    {runtimeStats.active}/{runtimeStats.total} active
+                  </div>
+                </div>
+              </div>
+            )}
+            {!inSidebar && deployment?.lastVerifiedMessage && (
+              <div className="mt-3 text-[11px] text-text-3/60">
+                {deployment.lastVerifiedMessage}
+              </div>
+            )}
             {!inSidebar && (
               <div className="mt-3 flex items-center gap-2">
                 <button onClick={(e) => void handleHealthCheckGateway(e, gateway.id)} className="px-2.5 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] cursor-pointer transition-all">
                   Health
                 </button>
+                <button onClick={(e) => void handleCloneGateway(e, gateway)} className="px-2.5 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] cursor-pointer transition-all">
+                  Clone
+                </button>
                 <button onClick={(e) => handleDeleteGateway(e, gateway.id)} className="px-2.5 py-1.5 rounded-[8px] border border-red-400/20 bg-red-400/[0.06] text-[11px] font-700 text-red-300 hover:bg-red-400/[0.1] cursor-pointer transition-all">
                   Delete
                 </button>
               </div>
             )}
           </div>
+            )
+          })()
         ))}
         {gatewayProfiles.length === 0 && (
           <div className="p-4 rounded-[14px] border border-dashed border-white/[0.08] text-[13px] text-text-3/70">
-            No gateway profiles yet. Add one to route OpenClaw agents by named control plane instead of a singleton default.
+            No gateway profiles yet. Use Smart Deploy above for a local runtime, a Docker VPS bundle, or a hosted OpenClaw deployment profile.
           </div>
         )}
       </div>
@@ -268,23 +506,84 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
                 <div className="flex items-center justify-between gap-3 mb-2">
                   <div className="min-w-0">
                     <div className="font-display text-[14px] font-600 text-text truncate">{runtime.name}</div>
-                    <div className="text-[11px] text-text-3/60 truncate">{runtime.sourceType} · {runtime.transport || 'custom'}</div>
+                    <div className="text-[11px] text-text-3/60 truncate">
+                      {runtime.sourceType} · {runtime.transport || 'custom'}
+                      {runtime.version ? ` · ${runtime.version}` : ''}
+                    </div>
+                  </div>
+                  <div className="flex flex-wrap items-center justify-end gap-2">
+                    <span className={`text-[10px] font-700 px-2 py-0.5 rounded-[5px] uppercase tracking-wider ${
+                      runtime.lifecycleState === 'cordoned'
+                        ? 'bg-red-400/10 text-red-300'
+                        : runtime.lifecycleState === 'draining'
+                          ? 'bg-amber-400/10 text-amber-300'
+                          : 'bg-blue-400/10 text-blue-300'
+                    }`}>
+                      {runtime.lifecycleState || 'active'}
+                    </span>
+                    <span className={`text-[10px] font-700 px-2 py-0.5 rounded-[5px] uppercase tracking-wider ${
+                      runtime.status === 'online'
+                        ? 'bg-emerald-400/10 text-emerald-300'
+                        : runtime.status === 'stale'
+                          ? 'bg-amber-400/10 text-amber-300'
+                          : 'bg-white/[0.04] text-text-3'
+                    }`}>
+                      {runtime.status}
+                    </span>
+                  </div>
+                </div>
+                <div className="grid grid-cols-2 gap-2 text-[11px] text-text-3/65">
+                  <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                    <div className="uppercase tracking-[0.08em] text-text-3/50">Provider</div>
+                    <div className="mt-1 text-text-2">
+                      {runtime.provider || 'No provider'}
+                      {runtime.model ? ` · ${runtime.model}` : ''}
+                    </div>
+                  </div>
+                  <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                    <div className="uppercase tracking-[0.08em] text-text-3/50">Gateway</div>
+                    <div className="mt-1 text-text-2">
+                      {runtime.gatewayProfileId ? (gatewayNameById.get(runtime.gatewayProfileId) || runtime.gatewayProfileId) : 'Standalone'}
+                    </div>
+                  </div>
+                  <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                    <div className="uppercase tracking-[0.08em] text-text-3/50">Template</div>
+                    <div className="mt-1 text-text-2">{runtime.gatewayUseCase || 'general'}</div>
+                  </div>
+                  <div className="rounded-[10px] border border-white/[0.05] bg-white/[0.02] px-3 py-2">
+                    <div className="uppercase tracking-[0.08em] text-text-3/50">Last seen</div>
+                    <div className="mt-1 text-text-2">{formatRuntimeTimestamp(runtime.lastSeenAt || runtime.lastHeartbeatAt)}</div>
                   </div>
-                  <span className={`text-[10px] font-700 px-2 py-0.5 rounded-[5px] uppercase tracking-wider ${
-                    runtime.status === 'online'
-                      ? 'bg-emerald-400/10 text-emerald-300'
-                      : runtime.status === 'stale'
-                        ? 'bg-amber-400/10 text-amber-300'
-                        : 'bg-white/[0.04] text-text-3'
-                  }`}>
-                    {runtime.status}
-                  </span>
                 </div>
-                <div className="text-[12px] text-text-3/70">
-                  {runtime.provider || 'No provider'}
-                  {runtime.model ? ` · ${runtime.model}` : ''}
+                <div className="text-[11px] text-text-3/55 mt-3 font-mono truncate">{runtime.endpoint || runtime.workspace || runtime.id}</div>
+                {runtime.gatewayTags?.length ? (
+                  <div className="mt-3 flex flex-wrap gap-1.5">
+                    {runtime.gatewayTags.slice(0, 6).map((tag) => (
+                      <span key={`${runtime.id}-${tag}`} className="rounded-full border border-white/[0.06] bg-white/[0.03] px-2 py-0.5 text-[10px] font-700 uppercase tracking-[0.08em] text-text-3/70">
+                        {tag}
+                      </span>
+                    ))}
+                  </div>
+                ) : null}
+                {runtime.lastHealthNote && (
+                  <div className="mt-3 text-[11px] text-text-3/65 leading-relaxed">
+                    {runtime.lastHealthNote}
+                  </div>
+                )}
+                <div className="mt-3 flex flex-wrap gap-2">
+                  <button onClick={(e) => void handleRuntimeAction(e, runtime.id, 'activate')} className="px-2.5 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] cursor-pointer transition-all">
+                    Activate
+                  </button>
+                  <button onClick={(e) => void handleRuntimeAction(e, runtime.id, 'drain')} className="px-2.5 py-1.5 rounded-[8px] border border-amber-400/20 bg-amber-400/[0.06] text-[11px] font-700 text-amber-300 hover:bg-amber-400/[0.1] cursor-pointer transition-all">
+                    Drain
+                  </button>
+                  <button onClick={(e) => void handleRuntimeAction(e, runtime.id, 'cordon')} className="px-2.5 py-1.5 rounded-[8px] border border-red-400/20 bg-red-400/[0.06] text-[11px] font-700 text-red-300 hover:bg-red-400/[0.1] cursor-pointer transition-all">
+                    Cordon
+                  </button>
+                  <button onClick={(e) => void handleRuntimeAction(e, runtime.id, 'restart')} className="px-2.5 py-1.5 rounded-[8px] border border-white/[0.08] bg-transparent text-[11px] font-700 text-text-2 hover:bg-white/[0.04] cursor-pointer transition-all">
+                    Restart
+                  </button>
                 </div>
-                <div className="text-[11px] text-text-3/55 mt-2 font-mono truncate">{runtime.endpoint || runtime.workspace || runtime.id}</div>
               </div>
             ))}
             {externalAgents.length === 0 && (

package/src/lib/server/agent-runtime-config.ts

@@ -26,6 +26,11 @@ export interface ResolvedAgentRoute {
   source: 'agent' | 'routing-target'
 }
 
+interface GatewayRoutePreferences {
+  preferredGatewayTags?: string[]
+  preferredGatewayUseCase?: string | null
+}
+
 interface RouteSeed {
   id: string
   label?: string
@@ -35,6 +40,8 @@ interface RouteSeed {
   fallbackCredentialIds?: string[]
   apiEndpoint?: string | null
   gatewayProfileId?: string | null
+  preferredGatewayTags?: string[]
+  preferredGatewayUseCase?: string | null
   role?: AgentRoutingTarget['role']
   priority?: number
   source: ResolvedAgentRoute['source']
@@ -47,6 +54,68 @@ function ensureStringArray(value: unknown): string[] {
     .filter(Boolean)
 }
 
+function normalizeText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function normalizeNullableNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}
+
+function normalizeGatewayDeployment(
+  value: unknown,
+): GatewayProfile['deployment'] {
+  if (!value || typeof value !== 'object') return null
+  const deployment = value as Record<string, unknown>
+  type DeploymentConfig = NonNullable<GatewayProfile['deployment']>
+  return {
+    method: normalizeText(deployment.method) as DeploymentConfig['method'],
+    provider: normalizeText(deployment.provider) as DeploymentConfig['provider'],
+    remoteTarget: normalizeText(deployment.remoteTarget) as DeploymentConfig['remoteTarget'],
+    useCase: normalizeText(deployment.useCase) as DeploymentConfig['useCase'],
+    exposure: normalizeText(deployment.exposure) as DeploymentConfig['exposure'],
+    managedBy: normalizeText(deployment.managedBy) as DeploymentConfig['managedBy'],
+    targetHost: normalizeText(deployment.targetHost),
+    sshHost: normalizeText(deployment.sshHost),
+    sshUser: normalizeText(deployment.sshUser),
+    sshPort: normalizeNullableNumber(deployment.sshPort),
+    sshKeyPath: normalizeText(deployment.sshKeyPath),
+    sshTargetDir: normalizeText(deployment.sshTargetDir),
+    image: normalizeText(deployment.image),
+    version: normalizeText(deployment.version),
+    lastDeployAt: normalizeNullableNumber(deployment.lastDeployAt),
+    lastDeployAction: normalizeText(deployment.lastDeployAction),
+    lastDeployProcessId: normalizeText(deployment.lastDeployProcessId),
+    lastDeploySummary: normalizeText(deployment.lastDeploySummary),
+    lastVerifiedAt: normalizeNullableNumber(deployment.lastVerifiedAt),
+    lastVerifiedOk: typeof deployment.lastVerifiedOk === 'boolean' ? deployment.lastVerifiedOk : null,
+    lastVerifiedMessage: normalizeText(deployment.lastVerifiedMessage),
+    lastBackupPath: normalizeText(deployment.lastBackupPath),
+  }
+}
+
+function normalizeGatewayStats(value: unknown): GatewayProfile['stats'] {
+  if (!value || typeof value !== 'object') return null
+  const stats = value as Record<string, unknown>
+  return {
+    nodeCount: normalizeNullableNumber(stats.nodeCount) ?? undefined,
+    connectedNodeCount: normalizeNullableNumber(stats.connectedNodeCount) ?? undefined,
+    pendingNodePairings: normalizeNullableNumber(stats.pendingNodePairings) ?? undefined,
+    pairedDeviceCount: normalizeNullableNumber(stats.pairedDeviceCount) ?? undefined,
+    pendingDevicePairings: normalizeNullableNumber(stats.pendingDevicePairings) ?? undefined,
+    externalRuntimeCount: normalizeNullableNumber(stats.externalRuntimeCount) ?? undefined,
+  }
+}
+
+function normalizeRoutePreferences(
+  value?: GatewayRoutePreferences | null,
+): GatewayRoutePreferences {
+  return {
+    preferredGatewayTags: ensureStringArray(value?.preferredGatewayTags),
+    preferredGatewayUseCase: normalizeText(value?.preferredGatewayUseCase),
+  }
+}
+
 function normalizeGateway(raw: unknown, id: string): GatewayProfile | null {
   if (!raw || typeof raw !== 'object') return null
   const gateway = raw as Partial<GatewayProfile> & Record<string, unknown>
@@ -72,6 +141,8 @@ function normalizeGateway(raw: unknown, id: string): GatewayProfile | null {
     lastModelCount: typeof gateway.lastModelCount === 'number' ? gateway.lastModelCount : null,
     discoveredHost: typeof gateway.discoveredHost === 'string' ? gateway.discoveredHost : null,
     discoveredPort: typeof gateway.discoveredPort === 'number' ? gateway.discoveredPort : null,
+    deployment: normalizeGatewayDeployment(gateway.deployment),
+    stats: normalizeGatewayStats(gateway.stats),
     isDefault: gateway.isDefault === true,
     createdAt: typeof gateway.createdAt === 'number' ? gateway.createdAt : Date.now(),
     updatedAt: typeof gateway.updatedAt === 'number' ? gateway.updatedAt : Date.now(),
@@ -107,6 +178,50 @@ function defaultGatewayProfile(gatewayProfiles: GatewayProfile[]): GatewayProfil
   return gatewayProfiles.find((profile) => profile.isDefault) || gatewayProfiles[0] || null
 }
 
+function gatewayPreferenceScore(
+  gatewayProfile: GatewayProfile,
+  preferences?: GatewayRoutePreferences | null,
+): number {
+  const normalized = normalizeRoutePreferences(preferences)
+  const preferredTags = normalized.preferredGatewayTags || []
+  const preferredUseCase = normalized.preferredGatewayUseCase || null
+  const gatewayTags = new Set(ensureStringArray(gatewayProfile.tags))
+  const gatewayUseCase = normalizeText(gatewayProfile.deployment?.useCase)
+
+  let score = 0
+  if (preferredUseCase) {
+    if (gatewayUseCase !== preferredUseCase) return -1
+    score += 30
+  }
+  if (preferredTags.length > 0) {
+    const matchedTagCount = preferredTags.filter((tag) => gatewayTags.has(tag)).length
+    if (matchedTagCount === 0) return -1
+    score += matchedTagCount * 10
+    if (matchedTagCount === preferredTags.length) score += 8
+  }
+  if (gatewayProfile.status === 'healthy') score += 4
+  else if (gatewayProfile.status === 'degraded') score += 2
+  if (gatewayProfile.isDefault) score += 3
+  return score
+}
+
+function pickPreferredGatewayProfile(
+  gatewayProfiles: GatewayProfile[],
+  preferences?: GatewayRoutePreferences | null,
+): GatewayProfile | null {
+  const normalized = normalizeRoutePreferences(preferences)
+  if (!(normalized.preferredGatewayTags?.length || normalized.preferredGatewayUseCase)) {
+    return null
+  }
+  return gatewayProfiles
+    .map((profile) => ({ profile, score: gatewayPreferenceScore(profile, normalized) }))
+    .filter((entry) => entry.score >= 0)
+    .sort((left, right) => {
+      if (left.score !== right.score) return right.score - left.score
+      return left.profile.name.localeCompare(right.profile.name)
+    })[0]?.profile || null
+}
+
 function roleWeight(strategy: AgentRoutingStrategy, role?: AgentRoutingTarget['role']): number {
   const normalized = role || 'primary'
   const matrix: Record<AgentRoutingStrategy, Record<string, number>> = {
@@ -135,14 +250,21 @@ function dedupeCredentialIds(primary: string | null | undefined, candidates: str
 function buildRouteFromSeed(
   seed: RouteSeed,
   gatewayProfiles: GatewayProfile[],
+  routePreferences?: GatewayRoutePreferences | null,
   agentGatewayProfileId?: string | null,
 ): ResolvedAgentRoute | null {
   const provider = (seed.provider || 'claude-cli') as ProviderType
-  let gatewayProfileId = seed.gatewayProfileId ?? null
-  if (!gatewayProfileId && provider === 'openclaw') {
-    gatewayProfileId = agentGatewayProfileId ?? defaultGatewayProfile(gatewayProfiles)?.id ?? null
+  const mergedPreferences = normalizeRoutePreferences({
+    preferredGatewayTags: seed.preferredGatewayTags ?? routePreferences?.preferredGatewayTags,
+    preferredGatewayUseCase: seed.preferredGatewayUseCase ?? routePreferences?.preferredGatewayUseCase,
+  })
+  let gatewayProfile = findGatewayProfile(gatewayProfiles, seed.gatewayProfileId ?? null)
+  if (!gatewayProfile && provider === 'openclaw') {
+    gatewayProfile = pickPreferredGatewayProfile(gatewayProfiles, mergedPreferences)
+      || findGatewayProfile(gatewayProfiles, agentGatewayProfileId ?? null)
+      || defaultGatewayProfile(gatewayProfiles)
   }
-  const gatewayProfile = findGatewayProfile(gatewayProfiles, gatewayProfileId)
+  const gatewayProfileId = gatewayProfile?.id ?? seed.gatewayProfileId ?? agentGatewayProfileId ?? null
 
   const providerFromGateway = gatewayProfile?.provider === 'openclaw' ? 'openclaw' : provider
   const apiEndpoint = normalizeProviderEndpoint(
@@ -189,8 +311,9 @@ function dedupeRoutes(routes: ResolvedAgentRoute[]): ResolvedAgentRoute[] {
 export function resolveAgentRouteCandidates(
   agent: Agent | null | undefined,
   preferredStrategy?: AgentRoutingStrategy | null,
+  routePreferences?: GatewayRoutePreferences | null,
 ): ResolvedAgentRoute[] {
-  return resolveAgentRouteCandidatesWithProfiles(agent, getGatewayProfiles('openclaw'), preferredStrategy)
+  return resolveAgentRouteCandidatesWithProfiles(agent, getGatewayProfiles('openclaw'), preferredStrategy, undefined, routePreferences)
 }
 
 export function resolveAgentRouteCandidatesWithProfiles(
@@ -198,9 +321,16 @@ export function resolveAgentRouteCandidatesWithProfiles(
   gatewayProfiles: GatewayProfile[],
   preferredStrategy?: AgentRoutingStrategy | null,
   isCoolingDown: (providerId: string) => boolean = isProviderCoolingDown,
+  routePreferences?: GatewayRoutePreferences | null,
 ): ResolvedAgentRoute[] {
   if (!agent) return []
   const strategy = preferredStrategy || agent.routingStrategy || 'single'
+  const resolvedPreferences = normalizeRoutePreferences({
+    preferredGatewayTags: routePreferences?.preferredGatewayTags?.length
+      ? routePreferences.preferredGatewayTags
+      : agent.preferredGatewayTags,
+    preferredGatewayUseCase: routePreferences?.preferredGatewayUseCase || agent.preferredGatewayUseCase,
+  })
   const seeds: RouteSeed[] = [
     {
       id: 'base',
@@ -211,6 +341,8 @@ export function resolveAgentRouteCandidatesWithProfiles(
       fallbackCredentialIds: agent.fallbackCredentialIds || [],
       apiEndpoint: agent.apiEndpoint ?? null,
       gatewayProfileId: agent.gatewayProfileId ?? null,
+      preferredGatewayTags: agent.preferredGatewayTags || [],
+      preferredGatewayUseCase: agent.preferredGatewayUseCase ?? null,
       role: 'primary',
       priority: 0,
       source: 'agent',
@@ -224,6 +356,8 @@ export function resolveAgentRouteCandidatesWithProfiles(
       fallbackCredentialIds: target.fallbackCredentialIds || [],
       apiEndpoint: target.apiEndpoint ?? null,
       gatewayProfileId: target.gatewayProfileId ?? null,
+      preferredGatewayTags: target.preferredGatewayTags || [],
+      preferredGatewayUseCase: target.preferredGatewayUseCase ?? null,
       role: target.role,
       priority: typeof target.priority === 'number' ? target.priority : index + 1,
       source: 'routing-target' as const,
@@ -232,7 +366,7 @@ export function resolveAgentRouteCandidatesWithProfiles(
 
   return dedupeRoutes(
     seeds
-      .map((seed) => buildRouteFromSeed(seed, gatewayProfiles, agent.gatewayProfileId ?? null))
+      .map((seed) => buildRouteFromSeed(seed, gatewayProfiles, resolvedPreferences, agent.gatewayProfileId ?? null))
       .filter((route): route is ResolvedAgentRoute => Boolean(route)),
   ).sort((left, right) => {
     const leftCooling = isCoolingDown(left.provider)
@@ -249,8 +383,9 @@ export function resolveAgentRouteCandidatesWithProfiles(
 export function resolvePrimaryAgentRoute(
   agent: Agent | null | undefined,
   preferredStrategy?: AgentRoutingStrategy | null,
+  routePreferences?: GatewayRoutePreferences | null,
 ): ResolvedAgentRoute | null {
-  return resolveAgentRouteCandidates(agent, preferredStrategy)[0] || null
+  return resolveAgentRouteCandidates(agent, preferredStrategy, routePreferences)[0] || null
 }
 
 export function applyResolvedRoute<T extends {