@swarmclawai/swarmclaw 0.7.6 → 0.7.7

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

@@ -6,13 +6,24 @@ 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 } from '@/types'
+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 }) {
@@ -78,13 +89,14 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
     await loadGatewayProfiles()
   }
 
-  const handleDeployApply = (patch: { endpoint?: string; token?: string; name?: string; notes?: string }) => {
+  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,
     })
   }
 
@@ -103,13 +115,45 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
       }
 
       const existing = gatewayProfiles.find((gateway) => gateway.endpoint === deployDraft.endpoint) || null
-      const nextTags = Array.from(new Set([...(existing?.tags || []), 'managed-deploy']))
+      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,
       }
 
@@ -129,6 +173,48 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
     }
   }
 
+  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,
@@ -151,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 (
@@ -286,6 +384,11 @@ export function ProviderList({ inSidebar }: { inSidebar?: boolean }) {
       )}
       <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"
@@ -327,17 +430,57 @@ 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">
@@ -363,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>
-                  <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="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>
+                </div>
+                <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 {

package/src/lib/server/agent-thread-session.ts

@@ -26,6 +26,8 @@ function buildThreadSession(agent: Agent, sessionId: string, user: string, creat
     fallbackCredentialIds: agent.fallbackCredentialIds || [],
     apiEndpoint: agent.apiEndpoint || null,
     gatewayProfileId: agent.gatewayProfileId || null,
+    routePreferredGatewayTags: existing?.routePreferredGatewayTags || [],
+    routePreferredGatewayUseCase: existing?.routePreferredGatewayUseCase || null,
     claudeSessionId: existing?.claudeSessionId || null,
     codexThreadId: existing?.codexThreadId || null,
     opencodeSessionId: existing?.opencodeSessionId || null,
@@ -77,7 +79,13 @@ function buildThreadSession(agent: Agent, sessionId: string, user: string, creat
     avatar: existing?.avatar,
     canvasContent: existing?.canvasContent || null,
   }
-  return applyResolvedRoute(baseSession, resolvePrimaryAgentRoute(agent))
+  return applyResolvedRoute(
+    baseSession,
+    resolvePrimaryAgentRoute(agent, undefined, {
+      preferredGatewayTags: baseSession.routePreferredGatewayTags || [],
+      preferredGatewayUseCase: baseSession.routePreferredGatewayUseCase || null,
+    }),
+  )
 }
 
 export function ensureAgentThreadSession(agentId: string, user = 'default'): Session | null {

package/src/lib/server/chat-execution.ts

@@ -626,7 +626,10 @@ function syncSessionFromAgent(sessionId: string): void {
   if (!agent) return
 
   let changed = false
-  const route = resolvePrimaryAgentRoute(agent)
+  const route = resolvePrimaryAgentRoute(agent, undefined, {
+    preferredGatewayTags: session.routePreferredGatewayTags || [],
+    preferredGatewayUseCase: session.routePreferredGatewayUseCase || null,
+  })
   if (!session.provider && agent.provider) { session.provider = agent.provider; changed = true }
   if ((session.model === undefined || session.model === null || session.model === '') && agent.model !== undefined) {
     session.model = agent.model
@@ -849,7 +852,10 @@ export async function executeSessionChatTurn(input: ExecuteChatTurnInput): Promi
     ? session
     : { ...session, plugins: pluginsForRun }
   if (agentForSession) {
-    const preferredRoute = resolvePrimaryAgentRoute(agentForSession)
+    const preferredRoute = resolvePrimaryAgentRoute(agentForSession, undefined, {
+      preferredGatewayTags: session.routePreferredGatewayTags || [],
+      preferredGatewayUseCase: session.routePreferredGatewayUseCase || null,
+    })
     if (preferredRoute) {
       sessionForRun = applyResolvedRoute({ ...sessionForRun }, preferredRoute)
     }

package/src/lib/server/openclaw-deploy.test.ts

@@ -18,12 +18,16 @@ test('docker smart deploy bundle uses official image and provider-specific metad
   assert.equal(bundle.providerLabel, 'DigitalOcean')
   assert.equal(bundle.endpoint, 'https://gateway.example.com/v1')
   assert.equal(bundle.wsUrl, 'wss://gateway.example.com')
+  assert.equal(bundle.useCase, 'single-vps')
+  assert.equal(bundle.exposure, 'caddy')
   assert.match(bundle.summary, /official OpenClaw Docker image/i)
   assert.deepEqual(bundle.files.map((file) => file.name), [
     'cloud-init.yaml',
     '.env',
     'docker-compose.yml',
     'bootstrap.sh',
+    'docker-compose.proxy.yml',
+    'Caddyfile',
   ])
 
   const envFile = bundle.files.find((file) => file.name === '.env')
@@ -36,6 +40,10 @@ test('docker smart deploy bundle uses official image and provider-specific metad
   assert.match(cloudInit.content, /docker\.io/)
   assert.match(cloudInit.content, /docker pull "\$\{OPENCLAW_IMAGE:-openclaw:latest\}"/)
   assert.match(cloudInit.content, /\/opt\/openclaw\/docker-compose\.yml/)
+
+  const caddyfile = bundle.files.find((file) => file.name === 'Caddyfile')
+  assert.ok(caddyfile)
+  assert.match(caddyfile.content, /gateway\.example\.com/)
 })
 
 test('render bundle stays aligned with the official repo flow', () => {