@swarmclawai/swarmclaw 0.7.3 → 0.7.4

package/src/components/auth/setup-wizard.tsx

@@ -3,13 +3,18 @@
 import { useMemo, useState } from 'react'
 import { api } from '@/lib/api-client'
 import { useAppStore } from '@/stores/use-app-store'
-import type { ProviderType, Credential } from '@/types'
+import type { ProviderType, Credential, GatewayProfile } from '@/types'
 import {
+  ONBOARDING_PATHS,
   SETUP_PROVIDERS,
-  DEFAULT_AGENTS,
+  STARTER_KITS,
+  getDefaultModelForProvider,
+  type OnboardingPath,
   type SetupProvider,
+  type StarterKitAgentTemplate,
 } from '@/lib/setup-defaults'
 
+type SetupStep = 'path' | 'providers' | 'connect' | 'agents' | 'done'
 type CheckState = 'idle' | 'checking' | 'ok' | 'error'
 
 interface ProviderCheckResponse {
@@ -17,6 +22,8 @@ interface ProviderCheckResponse {
   message: string
   normalizedEndpoint?: string
   recommendedModel?: string
+  errorCode?: string
+  deviceId?: string
 }
 
 interface SetupDoctorCheck {
@@ -39,10 +46,118 @@ interface SetupWizardProps {
 }
 
 interface ConfiguredProvider {
+  id: string
   provider: SetupProvider
+  name: string
+  credentialId: string | null
+  endpoint: string | null
+  defaultModel: string
+  gatewayProfileId: string | null
+}
+
+interface StarterDraftAgent {
+  id: string
+  templateId: string
+  name: string
+  description: string
+  systemPrompt: string
+  providerConfigId: string | null
+  provider: SetupProvider | null
+  model: string
   credentialId: string | null
-  agentId: string
-  agentName: string
+  apiEndpoint: string | null
+  gatewayProfileId: string | null
+  tools: string[]
+  capabilities: string[]
+  platformAssignScope: 'self' | 'all'
+  enabled: boolean
+}
+
+interface CreatedAgentSummary {
+  id: string
+  name: string
+  provider: SetupProvider
+  providerName: string
+}
+
+const STEP_ORDER: SetupStep[] = ['path', 'providers', 'agents', 'done']
+const CONNECTOR_ICONS = [
+  { name: 'Discord', icon: 'D' },
+  { name: 'Slack', icon: 'S' },
+  { name: 'Telegram', icon: 'T' },
+  { name: 'WhatsApp', icon: 'W' },
+]
+
+function stepIndex(step: SetupStep): number {
+  if (step === 'connect') return STEP_ORDER.indexOf('providers')
+  return STEP_ORDER.indexOf(step)
+}
+
+function defaultKitForPath(path: OnboardingPath): string {
+  if (path === 'manual') return 'blank_workspace'
+  return 'personal_assistant'
+}
+
+function applyIntentContext(prompt: string, intentText: string): string {
+  const trimmed = intentText.trim()
+  if (!trimmed) return prompt
+  return `${prompt}
+
+Current user intent:
+- ${trimmed}
+
+Keep your help aligned to this intent unless the user changes direction.`
+}
+
+function formatAgentCount(count: number): string {
+  if (count === 0) return 'Blank'
+  if (count === 1) return '1 agent'
+  return `${count} agents`
+}
+
+function withHttpScheme(value: string): string {
+  return /^(https?|wss?):\/\//i.test(value) ? value : `http://${value}`
+}
+
+function parseProviderUrl(value: string | null | undefined): URL | null {
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  if (!trimmed) return null
+  try {
+    return new URL(withHttpScheme(trimmed))
+  } catch {
+    return null
+  }
+}
+
+function formatEndpointHost(value: string | null | undefined): string | null {
+  const parsed = parseProviderUrl(value)
+  if (!parsed) return null
+  return parsed.port ? `${parsed.hostname}:${parsed.port}` : parsed.hostname
+}
+
+function isLocalOpenClawEndpoint(value: string | null | undefined): boolean {
+  const parsed = parseProviderUrl(value)
+  if (!parsed) return false
+  const host = parsed.hostname.trim().toLowerCase()
+  return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0'
+}
+
+function resolveOpenClawPort(value: string | null | undefined): number {
+  const parsed = parseProviderUrl(value)
+  const port = parsed ? Number(parsed.port) : NaN
+  return Number.isFinite(port) && port > 0 ? port : 18789
+}
+
+function resolveOpenClawDashboardUrl(value: string | null | undefined): string {
+  const parsed = parseProviderUrl(value)
+  if (!parsed) return 'http://localhost:18789'
+  const next = new URL(parsed.toString())
+  if (next.protocol === 'wss:') next.protocol = 'https:'
+  if (next.protocol === 'ws:') next.protocol = 'http:'
+  next.pathname = ''
+  next.search = ''
+  next.hash = ''
+  return next.toString().replace(/\/+$/, '')
 }
 
 function SparkleIcon() {
@@ -99,83 +214,191 @@ function SkipLink({ onClick, label }: { onClick: () => void; label?: string }) {
   )
 }
 
-function ProviderBadge({ label }: { label?: string }) {
-  if (!label) return null
-  return (
-    <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-accent-bright/15 text-accent-bright text-[10px] uppercase tracking-[0.08em] font-600">
-      {label}
-    </span>
-  )
-}
-
-function ConfiguredChips({ providers }: { providers: ConfiguredProvider[] }) {
+function ConfiguredProviderChips({ providers }: { providers: ConfiguredProvider[] }) {
   if (providers.length === 0) return null
   return (
     <div className="flex flex-wrap gap-2 justify-center mb-6">
       {providers.map((cp) => (
         <span
-          key={cp.provider}
+          key={cp.id}
           className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-full bg-emerald-500/10 border border-emerald-500/25 text-emerald-300 text-[12px] font-500"
         >
           <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />
-          {cp.agentName}
+          {cp.name}
+          <span className="text-emerald-300/70">
+            {cp.provider === 'openclaw' && formatEndpointHost(cp.endpoint)
+              ? `· ${formatEndpointHost(cp.endpoint)}`
+              : ''}
+            {cp.defaultModel ? ` · ${cp.defaultModel}` : ''}
+          </span>
         </span>
       ))}
     </div>
   )
 }
 
-const CONNECTOR_ICONS = [
-  { name: 'Discord', icon: 'D' },
-  { name: 'Slack', icon: 'S' },
-  { name: 'Telegram', icon: 'T' },
-  { name: 'WhatsApp', icon: 'W' },
-]
-
 function getOpenClawErrorHint(message: string): string | null {
   const lower = message.toLowerCase()
-  if (lower.includes('timeout') || lower.includes('timed out'))
+  if (lower.includes('timeout') || lower.includes('timed out')) {
     return 'Ensure the port is open and reachable from this machine.'
-  if (lower.includes('401') || lower.includes('unauthorized'))
+  }
+  if (lower.includes('401') || lower.includes('unauthorized')) {
     return 'Check your gateway auth token.'
-  if (lower.includes('405') || lower.includes('method not allowed'))
+  }
+  if (lower.includes('405') || lower.includes('method not allowed')) {
     return 'Enable chatCompletions in your OpenClaw config: openclaw config set gateway.http.endpoints.chatCompletions.enabled true'
-  if (lower.includes('econnrefused') || lower.includes('connection refused') || lower.includes('connect econnrefused'))
+  }
+  if (lower.includes('econnrefused') || lower.includes('connection refused') || lower.includes('connect econnrefused')) {
     return 'Verify that the OpenClaw gateway is running on the target host.'
+  }
   return null
 }
 
+function preferredConfiguredProvider(
+  template: StarterKitAgentTemplate,
+  configuredProviders: ConfiguredProvider[],
+  fallbackProviderConfigId?: string | null,
+  fallbackProvider?: SetupProvider | null,
+): ConfiguredProvider | null {
+  if (fallbackProviderConfigId) {
+    const exact = configuredProviders.find((candidate) => candidate.id === fallbackProviderConfigId)
+    if (exact) return exact
+  }
+
+  if (fallbackProvider) {
+    const exact = configuredProviders.find((candidate) => candidate.provider === fallbackProvider)
+    if (exact) return exact
+  }
+
+  for (const provider of template.recommendedProviders || []) {
+    const exact = configuredProviders.find((candidate) => candidate.provider === provider)
+    if (exact) return exact
+  }
+
+  return configuredProviders[0] || null
+}
+
+function buildStarterDrafts(args: {
+  starterKitId: string | null
+  intentText: string
+  configuredProviders: ConfiguredProvider[]
+  previousDrafts?: StarterDraftAgent[]
+}): StarterDraftAgent[] {
+  const { starterKitId, intentText, configuredProviders, previousDrafts = [] } = args
+  const starterKit = STARTER_KITS.find((kit) => kit.id === starterKitId)
+  if (!starterKit) return []
+
+  const previousById = new Map(previousDrafts.map((draft) => [draft.id, draft]))
+
+  return starterKit.agents.map((template) => {
+    const id = `${starterKit.id}:${template.id}`
+    const previous = previousById.get(id)
+    const configuredProvider = preferredConfiguredProvider(
+      template,
+      configuredProviders,
+      previous?.providerConfigId,
+      previous?.provider,
+    )
+    const oldProvider = previous?.provider || null
+    const oldProviderDefault = oldProvider ? getDefaultModelForProvider(oldProvider) : ''
+    const nextProviderDefault = configuredProvider?.defaultModel || ''
+    const shouldRefreshModel =
+      !previous?.model
+      || (oldProvider !== configuredProvider?.provider && previous.model === oldProviderDefault)
+
+    return {
+      id,
+      templateId: template.id,
+      name: previous?.name || template.name,
+      description: previous?.description || template.description,
+      systemPrompt: previous?.systemPrompt || applyIntentContext(template.systemPrompt, intentText),
+      providerConfigId: configuredProvider?.id || null,
+      provider: configuredProvider?.provider || null,
+      model: shouldRefreshModel ? nextProviderDefault : previous.model,
+      credentialId: configuredProvider?.credentialId || null,
+      apiEndpoint: configuredProvider?.endpoint || null,
+      gatewayProfileId: configuredProvider?.gatewayProfileId || null,
+      tools: template.tools,
+      capabilities: previous?.capabilities || template.capabilities || [],
+      platformAssignScope: previous?.platformAssignScope || template.platformAssignScope || 'self',
+      enabled: previous?.enabled ?? true,
+    }
+  })
+}
+
 export function SetupWizard({ onComplete }: SetupWizardProps) {
-  const [step, setStep] = useState(0)
+  const [step, setStep] = useState<SetupStep>('path')
+  const [onboardingPath, setOnboardingPath] = useState<OnboardingPath | null>(null)
+  const [starterKitId, setStarterKitId] = useState<string | null>(null)
+  const [intentText, setIntentText] = useState('')
+
   const [provider, setProvider] = useState<SetupProvider | null>(null)
+  const [providerLabel, setProviderLabel] = useState('')
   const [endpoint, setEndpoint] = useState('')
   const [apiKey, setApiKey] = useState('')
   const [credentialId, setCredentialId] = useState<string | null>(null)
   const [checkState, setCheckState] = useState<CheckState>('idle')
   const [checkMessage, setCheckMessage] = useState('')
+  const [checkErrorCode, setCheckErrorCode] = useState<string | null>(null)
+  const [openclawDeviceId, setOpenclawDeviceId] = useState<string | null>(null)
+  const [providerSuggestedModel, setProviderSuggestedModel] = useState('')
+  const [commandCopyState, setCommandCopyState] = useState<'idle' | 'copied' | 'failed'>('idle')
+
   const [doctorState, setDoctorState] = useState<'idle' | 'checking' | 'done' | 'error'>('idle')
   const [doctorError, setDoctorError] = useState('')
   const [doctorReport, setDoctorReport] = useState<SetupDoctorResponse | null>(null)
+  const [configuredProviders, setConfiguredProviders] = useState<ConfiguredProvider[]>([])
+  const [draftAgents, setDraftAgents] = useState<StarterDraftAgent[]>([])
+  const [createdAgents, setCreatedAgents] = useState<CreatedAgentSummary[]>([])
   const [saving, setSaving] = useState(false)
   const [error, setError] = useState('')
 
-  const [agentName, setAgentName] = useState('')
-  const [agentDescription, setAgentDescription] = useState('')
-  const [agentPrompt, setAgentPrompt] = useState('')
-  const [agentModel, setAgentModel] = useState('')
-
-  const [configuredProviders, setConfiguredProviders] = useState<ConfiguredProvider[]>([])
-
   const selectedProvider = useMemo(
-    () => SETUP_PROVIDERS.find((p) => p.id === provider) || null,
+    () => SETUP_PROVIDERS.find((candidate) => candidate.id === provider) || null,
     [provider],
   )
-  const totalSteps = 4
+  const selectedStarterKit = useMemo(
+    () => STARTER_KITS.find((candidate) => candidate.id === starterKitId) || null,
+    [starterKitId],
+  )
+  const totalSteps = STEP_ORDER.length
+  const singleUseProviderIds = new Set(
+    configuredProviders
+      .filter((cp) => !SETUP_PROVIDERS.find((candidate) => candidate.id === cp.provider)?.allowMultiple)
+      .map((cp) => cp.provider),
+  )
+
   const requiresKey = selectedProvider?.requiresKey || false
   const supportsEndpoint = selectedProvider?.supportsEndpoint || false
   const keyIsOptional = selectedProvider?.optionalKey || false
   const requiresVerifiedConnection = provider === 'openclaw'
-  const configuredIds = new Set(configuredProviders.map((cp) => cp.provider))
+  const canContinueFromProviders = configuredProviders.length > 0 || (selectedStarterKit?.agents.length || 0) === 0
+  const openClawEndpointValue = provider === 'openclaw'
+    ? (endpoint.trim() || selectedProvider?.defaultEndpoint || 'http://localhost:18789/v1')
+    : null
+  const openClawEndpointHost = openClawEndpointValue ? formatEndpointHost(openClawEndpointValue) : null
+  const openClawDashboardUrl = provider === 'openclaw'
+    ? resolveOpenClawDashboardUrl(openClawEndpointValue)
+    : null
+  const openClawLocal = provider === 'openclaw' ? isLocalOpenClawEndpoint(openClawEndpointValue) : false
+  const openClawPort = provider === 'openclaw' ? resolveOpenClawPort(openClawEndpointValue) : 18789
+  const openClawLocalCommand = `npx openclaw gateway run --bind loopback --port ${openClawPort} --verbose`
+  const openClawLocalCommandPnpm = `pnpm openclaw gateway run --bind loopback --port ${openClawPort} --verbose`
+
+  const resetProviderForm = () => {
+    setProvider(null)
+    setProviderLabel('')
+    setEndpoint('')
+    setApiKey('')
+    setCredentialId(null)
+    setCheckState('idle')
+    setCheckMessage('')
+    setCheckErrorCode(null)
+    setOpenclawDeviceId(null)
+    setProviderSuggestedModel('')
+    setCommandCopyState('idle')
+    setError('')
+  }
 
   const skip = async () => {
     try {
@@ -186,24 +409,47 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
     onComplete()
   }
 
-  const selectProvider = (next: SetupProvider) => {
-    const defaults = DEFAULT_AGENTS[next]
-    const meta = SETUP_PROVIDERS.find((p) => p.id === next)
+  const applyPathSelection = (nextPath: OnboardingPath) => {
+    setOnboardingPath(nextPath)
+    setStarterKitId((current) => current || defaultKitForPath(nextPath))
+    setError('')
+  }
 
-    setProvider(next)
+  const continueFromPath = () => {
+    if (!onboardingPath) {
+      setError('Choose how you want to get started.')
+      return
+    }
+    if (!starterKitId) {
+      setError('Choose a starter kit or blank workspace.')
+      return
+    }
+
+    setDraftAgents(buildStarterDrafts({
+      starterKitId,
+      intentText,
+      configuredProviders,
+    }))
+    setError('')
+    setStep('providers')
+  }
+
+  const selectProvider = (nextProvider: SetupProvider) => {
+    const meta = SETUP_PROVIDERS.find((candidate) => candidate.id === nextProvider)
+    const nextCount = configuredProviders.filter((candidate) => candidate.provider === nextProvider).length + 1
+    setProvider(nextProvider)
+    setProviderLabel(meta?.allowMultiple ? `${meta.name} ${nextCount}` : (meta?.name || ''))
     setEndpoint(meta?.defaultEndpoint || '')
     setApiKey('')
     setCredentialId(null)
     setCheckState('idle')
     setCheckMessage('')
+    setCheckErrorCode(null)
+    setOpenclawDeviceId(null)
+    setProviderSuggestedModel(getDefaultModelForProvider(nextProvider))
+    setCommandCopyState('idle')
     setError('')
-
-    setAgentName(defaults.name)
-    setAgentDescription(defaults.description)
-    setAgentPrompt(defaults.systemPrompt)
-    setAgentModel(defaults.model)
-
-    setStep(1)
+    setStep('connect')
   }
 
   const runConnectionCheck = async (): Promise<boolean> => {
@@ -216,31 +462,30 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
 
     setCheckState('checking')
     setCheckMessage('')
+    setCheckErrorCode(null)
     setError('')
     try {
       const result = await api<ProviderCheckResponse>('POST', '/setup/check-provider', {
         provider,
         apiKey: apiKey.trim() || undefined,
         endpoint: supportsEndpoint ? endpoint.trim() || undefined : undefined,
-        model: agentModel.trim() || undefined,
       })
 
       if (result.normalizedEndpoint && supportsEndpoint) {
         setEndpoint(result.normalizedEndpoint)
       }
-      if (result.recommendedModel && provider) {
-        const currentModel = agentModel.trim()
-        const defaultModel = DEFAULT_AGENTS[provider].model
-        if (!currentModel || currentModel === defaultModel) {
-          setAgentModel(result.recommendedModel)
-        }
+      if (result.recommendedModel) {
+        setProviderSuggestedModel(result.recommendedModel)
       }
+      setCheckErrorCode(result.errorCode || null)
+      setOpenclawDeviceId(result.deviceId || null)
       setCheckState(result.ok ? 'ok' : 'error')
       setCheckMessage(result.message || (result.ok ? 'Connected successfully.' : 'Connection failed.'))
       return !!result.ok
     } catch (err: unknown) {
       setCheckState('error')
       setCheckMessage(err instanceof Error ? err.message : String(err))
+      setCheckErrorCode(null)
       return false
     }
   }
@@ -259,7 +504,7 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
     }
   }
 
-  const saveProviderAndContinue = async () => {
+  const saveProvider = async () => {
     if (!provider || !selectedProvider) return
     if (requiresKey && !apiKey.trim()) {
       setError('This provider requires an API key.')
@@ -283,14 +528,33 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
       if (shouldSaveCredential && !nextCredentialId) {
         const cred = await api<Credential>('POST', '/credentials', {
           provider,
-          name: `${selectedProvider.name} key`,
+          name: `${providerLabel.trim() || selectedProvider.name} key`,
           apiKey: apiKey.trim(),
         })
         nextCredentialId = cred.id
       }
 
+      const configuredProvider: ConfiguredProvider = {
+        id: crypto.randomUUID(),
+        provider,
+        name: providerLabel.trim() || selectedProvider.name,
+        credentialId: nextCredentialId || null,
+        endpoint: supportsEndpoint ? (endpoint.trim() || selectedProvider.defaultEndpoint || null) : null,
+        defaultModel: providerSuggestedModel || getDefaultModelForProvider(provider),
+        gatewayProfileId: null,
+      }
+
+      const nextConfigured = [...configuredProviders, configuredProvider]
       setCredentialId(nextCredentialId || null)
-      setStep(2)
+      setConfiguredProviders(nextConfigured)
+      setDraftAgents((current) => buildStarterDrafts({
+        starterKitId,
+        intentText,
+        configuredProviders: nextConfigured,
+        previousDrafts: current,
+      }))
+      resetProviderForm()
+      setStep('providers')
     } catch (err: unknown) {
       setError(err instanceof Error ? err.message : String(err))
     } finally {
@@ -298,87 +562,165 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
     }
   }
 
-  const createAgentAndFinish = async (addAnother: boolean) => {
-    if (!provider || !agentName.trim()) return
-    if (requiresVerifiedConnection && checkState !== 'ok') {
-      setError('OpenClaw connection is not verified. Go back and run the connection check.')
-      setStep(1)
+  const goToAgentReview = () => {
+    setDraftAgents((current) => buildStarterDrafts({
+      starterKitId,
+      intentText,
+      configuredProviders,
+      previousDrafts: current,
+    }))
+    setError('')
+    setStep('agents')
+  }
+
+  const updateDraftAgent = (id: string, patch: Partial<StarterDraftAgent>) => {
+    setDraftAgents((current) => current.map((draft) => (
+      draft.id === id
+        ? { ...draft, ...patch }
+        : draft
+    )))
+  }
+
+  const updateDraftAgentProvider = (id: string, nextProviderConfigId: string) => {
+    const configuredProvider = configuredProviders.find((candidate) => candidate.id === nextProviderConfigId)
+    if (!configuredProvider) return
+
+    setDraftAgents((current) => current.map((draft) => {
+      if (draft.id !== id) return draft
+      const previousDefault = draft.provider ? getDefaultModelForProvider(draft.provider) : ''
+      const nextModel = !draft.model || draft.model === previousDefault
+        ? configuredProvider.defaultModel
+        : draft.model
+      return {
+        ...draft,
+        providerConfigId: configuredProvider.id,
+        provider: configuredProvider.provider,
+        credentialId: configuredProvider.credentialId,
+        apiEndpoint: configuredProvider.endpoint,
+        gatewayProfileId: configuredProvider.gatewayProfileId,
+        model: nextModel,
+      }
+    }))
+  }
+
+  const copyOpenClawLocalCommand = async () => {
+    try {
+      await navigator.clipboard.writeText(openClawLocalCommand)
+      setCommandCopyState('copied')
+      window.setTimeout(() => setCommandCopyState('idle'), 1200)
+    } catch {
+      setCommandCopyState('failed')
+      window.setTimeout(() => setCommandCopyState('idle'), 1800)
+    }
+  }
+
+  const createAgentsAndFinish = async () => {
+    const enabledDrafts = draftAgents.filter((draft) => draft.enabled)
+    if (enabledDrafts.some((draft) => !draft.provider)) {
+      setError('Every enabled agent needs a provider assignment before you continue.')
       return
     }
+
     setSaving(true)
     setError('')
     try {
-      const payload: Record<string, unknown> = {
-        name: agentName.trim(),
-        description: agentDescription.trim(),
-        systemPrompt: agentPrompt.trim(),
-        provider: provider as ProviderType,
-        model: agentModel.trim() || DEFAULT_AGENTS[provider].model,
-        credentialId: credentialId || null,
-        plugins: DEFAULT_AGENTS[provider].tools,
-      }
-
-      if (supportsEndpoint && endpoint.trim()) {
-        payload.apiEndpoint = endpoint.trim()
+      const gatewayProfileIdsByProviderConfig = new Map<string, string>()
+      const openClawProviders = configuredProviders.filter((candidate) => candidate.provider === 'openclaw')
+      if (openClawProviders.length > 0) {
+        const existingGateways = await api<GatewayProfile[]>('GET', '/gateways')
+        let shouldCreateDefault = existingGateways.length === 0
+
+        for (const configuredProvider of openClawProviders) {
+          const normalizedEndpoint = (configuredProvider.endpoint || 'http://localhost:18789').trim()
+          const existing = existingGateways.find((gateway) => (
+            gateway.provider === 'openclaw'
+            && gateway.endpoint === normalizedEndpoint
+            && (gateway.credentialId || null) === (configuredProvider.credentialId || null)
+          ))
+          if (existing) {
+            gatewayProfileIdsByProviderConfig.set(configuredProvider.id, existing.id)
+            continue
+          }
+
+          const createdGateway = await api<GatewayProfile>('POST', '/gateways', {
+            name: configuredProvider.name,
+            endpoint: normalizedEndpoint,
+            credentialId: configuredProvider.credentialId || null,
+            tags: ['onboarding'],
+            notes: `Created during setup for ${configuredProvider.name}.`,
+            isDefault: shouldCreateDefault,
+          })
+          gatewayProfileIdsByProviderConfig.set(configuredProvider.id, createdGateway.id)
+          existingGateways.push(createdGateway)
+          shouldCreateDefault = false
+        }
       }
 
-      const isFirstProvider = configuredProviders.length === 0
-      let agentId: string
-
-      if (isFirstProvider) {
-        const agents = await api<Record<string, { id: string }>>('GET', '/agents')
-        const canReuseDefault =
-          !!agents.default
-          && Object.keys(agents).length === 1
-          && agentName.trim().toLowerCase() === DEFAULT_AGENTS[provider].name.toLowerCase()
+      const existingAgents = await api<Record<string, { id: string }>>('GET', '/agents')
+      let canReuseDefault = !!existingAgents.default && Object.keys(existingAgents).length === 1
+      const created: CreatedAgentSummary[] = []
+
+      for (const draft of enabledDrafts) {
+        const payload: Record<string, unknown> = {
+          name: draft.name.trim(),
+          description: draft.description.trim(),
+          systemPrompt: draft.systemPrompt.trim(),
+          provider: draft.provider as ProviderType,
+          model: draft.model.trim() || getDefaultModelForProvider(draft.provider as SetupProvider),
+          credentialId: draft.credentialId || null,
+          plugins: draft.tools,
+          capabilities: draft.capabilities,
+          platformAssignScope: draft.platformAssignScope,
+        }
 
-        agentId = canReuseDefault
-          ? 'default'
-          : (await api<{ id: string }>('POST', '/agents', payload)).id
+        if (draft.apiEndpoint) {
+          payload.apiEndpoint = draft.apiEndpoint
+        }
+        const gatewayProfileId = (draft.providerConfigId && gatewayProfileIdsByProviderConfig.get(draft.providerConfigId)) || draft.gatewayProfileId
+        if (gatewayProfileId) {
+          payload.gatewayProfileId = gatewayProfileId
+        }
 
+        let agentId: string
         if (canReuseDefault) {
           await api('PUT', '/agents/default', payload)
+          agentId = 'default'
+          canReuseDefault = false
+        } else {
+          agentId = (await api<{ id: string }>('POST', '/agents', payload)).id
         }
 
-        // Set the default agent and open its thread
-        const appState = useAppStore.getState()
-        if (agentId) {
-          await appState.updateSettings({ defaultAgentId: agentId })
-          await appState.setCurrentAgent(agentId)
-        }
-      } else {
-        // Additional providers just create the agent
-        agentId = (await api<{ id: string }>('POST', '/agents', payload)).id
+        created.push({
+          id: agentId,
+          name: draft.name.trim(),
+          provider: draft.provider as SetupProvider,
+          providerName: configuredProviders.find((candidate) => candidate.id === draft.providerConfigId)?.name || draft.provider as SetupProvider,
+        })
       }
 
-      const newConfigured: ConfiguredProvider = {
-        provider,
-        credentialId: credentialId || null,
-        agentId,
-        agentName: agentName.trim(),
+      if (created[0]) {
+        const appState = useAppStore.getState()
+        await appState.updateSettings({ defaultAgentId: created[0].id })
+        await appState.setCurrentAgent(created[0].id)
       }
-      const nextConfigured = [...configuredProviders, newConfigured]
-      setConfiguredProviders(nextConfigured)
 
-      if (addAnother) {
-        // Reset for next provider selection
-        setProvider(null)
-        setEndpoint('')
-        setApiKey('')
-        setCredentialId(null)
-        setCheckState('idle')
-        setCheckMessage('')
-        setAgentName('')
-        setAgentDescription('')
-        setAgentPrompt('')
-        setAgentModel('')
-        setError('')
-        setStep(0)
-      } else {
-        // Finish setup
-        await api('PUT', '/settings', { setupCompleted: true })
-        setStep(3)
-      }
+      await api('PUT', '/settings', { setupCompleted: true })
+      setCreatedAgents(created)
+      setStep('done')
+    } catch (err: unknown) {
+      setError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const finishWithoutAgents = async () => {
+    setSaving(true)
+    setError('')
+    try {
+      await api('PUT', '/settings', { setupCompleted: true })
+      setCreatedAgents([])
+      setStep('done')
     } catch (err: unknown) {
       setError(err instanceof Error ? err.message : String(err))
     } finally {
@@ -399,35 +741,171 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
       </div>
 
       <div
-        className="relative max-w-[520px] w-full text-center"
+        className="relative max-w-[760px] w-full text-center"
         style={{ animation: 'fade-in 0.6s cubic-bezier(0.16, 1, 0.3, 1)' }}
       >
         <SparkleIcon />
-        <StepDots current={step} total={totalSteps} />
+        <StepDots current={stepIndex(step)} total={totalSteps} />
 
-        {step === 0 && (
+        {step === 'path' && (
           <>
             <h1 className="font-display text-[36px] font-800 leading-[1.05] tracking-[-0.04em] mb-3">
-              {configuredProviders.length > 0 ? 'Add Another Provider' : '2-Minute Setup'}
+              Choose Your Setup Path
             </h1>
             <p className="text-[15px] text-text-2 mb-2">
-              {configuredProviders.length > 0
-                ? 'Pick another provider to set up, or finish below.'
-                : 'No coding required. Pick a provider, paste a key if needed, and start chatting.'}
+              Start from your intent, start from your provider, or build it yourself.
             </p>
             <p className="text-[13px] text-text-3 mb-8">
-              You can change providers, models, and agent settings anytime later.
+              You can still change providers, models, agents, and templates later.
             </p>
 
-            <ConfiguredChips providers={configuredProviders} />
+            <div className="grid gap-3 md:grid-cols-3 text-left mb-6">
+              {ONBOARDING_PATHS.map((path) => {
+                const active = onboardingPath === path.id
+                return (
+                  <button
+                    key={path.id}
+                    onClick={() => applyPathSelection(path.id)}
+                    className={`rounded-[16px] border px-5 py-4 transition-all duration-200 cursor-pointer ${
+                      active
+                        ? 'border-accent-bright/40 bg-accent-bright/10'
+                        : 'border-white/[0.08] bg-surface hover:border-accent-bright/20 hover:bg-surface-hover'
+                    }`}
+                  >
+                    <div className="flex items-center gap-2 mb-2">
+                      <span className="text-[15px] font-display font-700 text-text">{path.title}</span>
+                      {path.badge && (
+                        <span className="inline-flex items-center px-2 py-0.5 rounded-md bg-accent-bright/15 text-accent-bright text-[10px] uppercase tracking-[0.08em] font-600">
+                          {path.badge}
+                        </span>
+                      )}
+                    </div>
+                    <p className="text-[13px] text-text-2 leading-relaxed mb-2">{path.description}</p>
+                    <p className="text-[12px] text-text-3 leading-relaxed">{path.detail}</p>
+                  </button>
+                )
+              })}
+            </div>
 
-            <div className="flex flex-col gap-3 max-h-[44vh] overflow-y-auto pr-1">
-              {SETUP_PROVIDERS.map((p) => {
-                const isConfigured = configuredIds.has(p.id)
+            {onboardingPath === 'intent' && (
+              <div className="mb-6 text-left rounded-[16px] border border-white/[0.08] bg-surface p-4">
+                <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">
+                  What do you want SwarmClaw to help with?
+                </label>
+                <textarea
+                  value={intentText}
+                  onChange={(e) => setIntentText(e.target.value)}
+                  rows={3}
+                  placeholder="Examples: help me research AI products, build a SaaS app, manage personal projects, write better content..."
+                  className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                    text-text text-[14px] outline-none transition-all duration-200 resize-none
+                    focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                />
+                <p className="mt-2 text-[12px] text-text-3">
+                  This is used to tailor your starter agents. You can leave it blank and refine later.
+                </p>
+              </div>
+            )}
+
+            <div className="text-left mb-6">
+              <div className="flex items-center justify-between mb-3">
+                <div>
+                  <div className="text-[13px] font-600 text-text">Starter Kits</div>
+                  <div className="text-[12px] text-text-3">Choose a template or start blank. You can opt individual agents in or out on the next screen.</div>
+                </div>
+              </div>
+              <div className="grid gap-3 md:grid-cols-2">
+                {STARTER_KITS.map((kit) => {
+                  const active = starterKitId === kit.id
+                  return (
+                    <button
+                      key={kit.id}
+                      onClick={() => setStarterKitId(kit.id)}
+                      className={`rounded-[16px] border px-5 py-4 text-left transition-all duration-200 cursor-pointer ${
+                        active
+                          ? 'border-accent-bright/40 bg-accent-bright/10'
+                          : 'border-white/[0.08] bg-surface hover:border-accent-bright/20 hover:bg-surface-hover'
+                      }`}
+                    >
+                      <div className="flex items-center gap-2 mb-2">
+                        <span className="text-[15px] font-display font-700 text-text">{kit.name}</span>
+                        {kit.badge && (
+                          <span className="inline-flex items-center px-2 py-0.5 rounded-md bg-white/[0.06] text-text-2 text-[10px] uppercase tracking-[0.08em] font-600">
+                            {kit.badge}
+                          </span>
+                        )}
+                      </div>
+                      <p className="text-[13px] text-text-2 mb-2">{kit.description}</p>
+                      <p className="text-[12px] text-text-3 leading-relaxed mb-3">{kit.detail}</p>
+                      <div className="flex items-center gap-2 text-[11px] text-text-3">
+                        <span className="inline-flex items-center px-2 py-0.5 rounded-md bg-white/[0.04] border border-white/[0.06]">
+                          {formatAgentCount(kit.agents.length)}
+                        </span>
+                        {kit.recommendedFor?.includes(onboardingPath || 'quick') && (
+                          <span className="inline-flex items-center px-2 py-0.5 rounded-md bg-emerald-500/10 border border-emerald-500/20 text-emerald-300">
+                            Fits this path
+                          </span>
+                        )}
+                      </div>
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+
+            {error && <p className="mb-4 text-[13px] text-red-400">{error}</p>}
+
+            <div className="flex items-center justify-center gap-3">
+              <button
+                onClick={continueFromPath}
+                disabled={!onboardingPath || !starterKitId}
+                className="px-8 py-3.5 rounded-[14px] border-none bg-accent-bright text-white text-[15px] font-display font-600
+                  cursor-pointer hover:brightness-110 active:scale-[0.97] transition-all duration-200
+                  shadow-[0_6px_28px_rgba(99,102,241,0.3)] disabled:opacity-30"
+              >
+                Continue
+              </button>
+            </div>
+
+            <SkipLink onClick={skip} />
+          </>
+        )}
+
+        {step === 'providers' && (
+          <>
+            <h1 className="font-display text-[36px] font-800 leading-[1.05] tracking-[-0.04em] mb-3">
+              Connect Providers
+            </h1>
+            <p className="text-[15px] text-text-2 mb-2">
+              Add one or more providers, then map them onto your starter agents.
+            </p>
+            <p className="text-[13px] text-text-3 mb-8">
+              Providers are reusable. You will choose or change the provider and model for each starter agent on the next step.
+            </p>
+
+            {selectedStarterKit && (
+              <div className="mb-6 p-4 rounded-[14px] border border-white/[0.08] bg-surface text-left">
+                <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Starter Kit</div>
+                <div className="text-[14px] text-text mb-1">{selectedStarterKit.name}</div>
+                <div className="text-[12px] text-text-3">{selectedStarterKit.detail}</div>
+                {!!intentText.trim() && (
+                  <div className="mt-3 text-[12px] text-text-2">
+                    Intent: <span className="text-text-3">{intentText.trim()}</span>
+                  </div>
+                )}
+              </div>
+            )}
+
+            <ConfiguredProviderChips providers={configuredProviders} />
+
+            <div className="flex flex-col gap-3 max-h-[42vh] overflow-y-auto pr-1">
+              {SETUP_PROVIDERS.map((candidate) => {
+                const isConfigured = !candidate.allowMultiple && singleUseProviderIds.has(candidate.id)
+                const configuredCount = configuredProviders.filter((cp) => cp.provider === candidate.id).length
                 return (
                   <button
-                    key={p.id}
-                    onClick={() => !isConfigured && selectProvider(p.id)}
+                    key={candidate.id}
+                    onClick={() => !isConfigured && selectProvider(candidate.id)}
                     disabled={isConfigured}
                     className={`w-full px-5 py-4 rounded-[14px] border border-white/[0.08] bg-surface text-left
                       transition-all duration-200 flex items-start gap-4
@@ -438,19 +916,26 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
                   >
                     <div className="w-10 h-10 rounded-[10px] bg-white/[0.04] border border-white/[0.06] flex items-center justify-center shrink-0 mt-0.5">
                       <span className="text-[16px] font-display font-700 text-accent-bright">
-                        {p.icon}
+                        {candidate.icon}
                       </span>
                     </div>
                     <div>
                       <div className="text-[15px] font-display font-600 text-text mb-1">
-                        {p.name}
-                        {isConfigured
-                          ? <span className="ml-2 text-[10px] text-emerald-400 uppercase tracking-[0.08em]">Configured</span>
-                          : <ProviderBadge label={p.badge} />
-                        }
+                        {candidate.name}
+                        {isConfigured ? (
+                          <span className="ml-2 text-[10px] text-emerald-400 uppercase tracking-[0.08em]">Ready</span>
+                        ) : candidate.allowMultiple && configuredCount > 0 ? (
+                          <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-300 text-[10px] uppercase tracking-[0.08em] font-600">
+                            {configuredCount} saved
+                          </span>
+                        ) : candidate.badge ? (
+                          <span className="ml-2 inline-flex items-center gap-1 px-2 py-0.5 rounded-md bg-accent-bright/15 text-accent-bright text-[10px] uppercase tracking-[0.08em] font-600">
+                            {candidate.badge}
+                          </span>
+                        ) : null}
                       </div>
-                      <div className="text-[13px] text-text-3 leading-relaxed">{p.description}</div>
-                      {!p.requiresKey && !isConfigured && (
+                      <div className="text-[13px] text-text-3 leading-relaxed">{candidate.description}</div>
+                      {!candidate.requiresKey && !isConfigured && (
                         <div className="mt-1.5 inline-flex items-center gap-1.5 px-2 py-0.5 rounded-md bg-emerald-500/10 text-emerald-400 text-[11px] font-500">
                           <span className="w-1.5 h-1.5 rounded-full bg-emerald-400" />
                           No API key required
@@ -481,7 +966,7 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
                   <div className={`text-[12px] font-600 ${doctorReport.ok ? 'text-emerald-300' : 'text-amber-300'}`}>
                     {doctorReport.summary}
                   </div>
-                  {doctorReport.checks.filter((c) => c.status !== 'pass').slice(0, 3).map((check) => (
+                  {doctorReport.checks.filter((check) => check.status !== 'pass').slice(0, 3).map((check) => (
                     <div key={check.id} className="mt-1 text-[11px] text-text-3">
                       - {check.label}: {check.detail}
                     </div>
@@ -495,31 +980,64 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
               )}
             </div>
 
-            <SkipLink
-              onClick={configuredProviders.length > 0 ? async () => {
-                await api('PUT', '/settings', { setupCompleted: true })
-                setStep(3)
-              } : skip}
-              label={configuredProviders.length > 0 ? 'Finish Setup' : 'Skip setup for now'}
-            />
+            {error && <p className="mt-4 text-[13px] text-red-400">{error}</p>}
+
+            <div className="mt-6 flex items-center justify-center gap-3">
+              <button
+                onClick={() => setStep('path')}
+                className="px-6 py-3.5 rounded-[14px] border border-white/[0.08] bg-transparent text-text-2 text-[14px]
+                  font-display font-500 cursor-pointer hover:bg-white/[0.03] transition-all duration-200"
+              >
+                Back
+              </button>
+              <button
+                onClick={goToAgentReview}
+                disabled={!canContinueFromProviders}
+                className="px-8 py-3.5 rounded-[14px] border-none bg-accent-bright text-white text-[15px] font-display font-600
+                  cursor-pointer hover:brightness-110 active:scale-[0.97] transition-all duration-200
+                  shadow-[0_6px_28px_rgba(99,102,241,0.3)] disabled:opacity-30"
+              >
+                {selectedStarterKit?.agents.length ? 'Review Starter Agents' : 'Continue'}
+              </button>
+            </div>
+
+            <SkipLink onClick={skip} />
           </>
         )}
 
-        {step === 1 && provider && selectedProvider && (
+        {step === 'connect' && provider && selectedProvider && (
           <>
             <h1 className="font-display text-[36px] font-800 leading-[1.05] tracking-[-0.04em] mb-3">
               Connect {selectedProvider.name}
             </h1>
             <p className="text-[15px] text-text-2 mb-2">
-              Add only what is needed for this provider, then check connection.
+              Save this provider once, then reuse it across your starter agents.
             </p>
             <p className="text-[13px] text-text-3 mb-7">
               {requiresVerifiedConnection
                 ? 'OpenClaw must pass connection check before you can continue.'
-                : 'You can keep going even if the check fails and fix details later.'}
+                : 'You can still continue even if the check fails and fix details later.'}
             </p>
 
             <div className="flex flex-col gap-3 text-left mb-4">
+              <div>
+                <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">
+                  Connection name
+                </label>
+                <input
+                  type="text"
+                  value={providerLabel}
+                  onChange={(e) => setProviderLabel(e.target.value)}
+                  placeholder={selectedProvider.name}
+                  className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-surface
+                    text-text text-[14px] outline-none transition-all duration-200
+                    focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                />
+                <p className="mt-1.5 text-[11px] text-text-3">
+                  Helpful for multiple OpenClaw gateways or distinct provider profiles.
+                </p>
+              </div>
+
               {supportsEndpoint && (
                 <div>
                   <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">
@@ -536,18 +1054,76 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
                   />
                   {provider === 'openclaw' && (
                     <div className="mt-2 space-y-0.5">
-                      <p className="text-[12px] text-text-3">Works with local (<code className="text-text-2">localhost:18789</code>) or remote OpenClaw instances.</p>
-                      <p className="text-[12px] text-text-3">For remote: use your server&apos;s IP/domain with port (e.g. <code className="text-text-2">http://your-server:60924/v1</code>).</p>
-                      <p className="text-[12px] text-text-3 mt-1">
-                        <a href="/docs/openclaw-setup" target="_blank" rel="noopener noreferrer" className="text-accent-bright hover:underline">
-                          Setup guide &rarr;
-                        </a>
-                      </p>
+                      <p className="text-[12px] text-text-3">Works with local (<code className="text-text-2">http://localhost:18789/v1</code>) or remote OpenClaw instances.</p>
+                      <p className="text-[12px] text-text-3">Remote example: <code className="text-text-2">https://your-gateway.ts.net/v1</code>.</p>
                     </div>
                   )}
                 </div>
               )}
 
+              {provider === 'openclaw' && (
+                <div className="rounded-[14px] border border-white/[0.08] bg-surface p-4 space-y-4">
+                  <div className="grid gap-3 md:grid-cols-2">
+                    <div className="rounded-[12px] border border-white/[0.06] bg-bg px-4 py-3">
+                      <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Remote gateway</div>
+                      <p className="text-[13px] text-text-2 leading-relaxed">
+                        Recommended when your OpenClaw node runs on another machine or VPS. Use a URL reachable from the machine running SwarmClaw.
+                      </p>
+                      <p className="mt-2 text-[12px] text-text-3 leading-relaxed">
+                        Tailscale example: <code className="text-text-2">https://&lt;gateway-host&gt;.ts.net/v1</code>
+                      </p>
+                      <p className="mt-2 text-[12px] text-text-3 leading-relaxed">
+                        If you only have a WebSocket gateway URL, you can still paste it here. SwarmClaw will normalize it for agent chat.
+                      </p>
+                    </div>
+                    <div className="rounded-[12px] border border-white/[0.06] bg-bg px-4 py-3">
+                      <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Run locally</div>
+                      <p className="text-[13px] text-text-2 leading-relaxed">
+                        Use this when SwarmClaw and OpenClaw are on the same host. <code className="text-text-2">localhost</code> always refers to the SwarmClaw host.
+                      </p>
+                      <div className="mt-3 rounded-[10px] border border-white/[0.06] bg-surface px-3 py-2">
+                        <code className="block overflow-x-auto whitespace-nowrap text-[12px] text-text-2">
+                          {openClawLocalCommand}
+                        </code>
+                      </div>
+                      <div className="mt-2 flex items-center gap-2">
+                        <button
+                          type="button"
+                          onClick={copyOpenClawLocalCommand}
+                          className="px-3 py-2 rounded-[10px] border border-white/[0.08] bg-white/[0.03] text-[12px] text-text cursor-pointer hover:bg-white/[0.06] transition-all duration-200"
+                        >
+                          {commandCopyState === 'copied'
+                            ? 'Copied'
+                            : commandCopyState === 'failed'
+                              ? 'Copy failed'
+                              : 'Copy command'}
+                        </button>
+                        <button
+                          type="button"
+                          onClick={() => { setEndpoint(selectedProvider.defaultEndpoint || 'http://localhost:18789/v1'); setCheckState('idle'); setCheckMessage(''); setCheckErrorCode(null) }}
+                          className="px-3 py-2 rounded-[10px] border border-white/[0.08] bg-white/[0.03] text-[12px] text-text cursor-pointer hover:bg-white/[0.06] transition-all duration-200"
+                        >
+                          Use local default
+                        </button>
+                      </div>
+                      <p className="mt-2 text-[11px] text-text-3">
+                        In a source checkout, use <code className="text-text-2">{openClawLocalCommandPnpm}</code>.
+                      </p>
+                    </div>
+                  </div>
+
+                  <div className="rounded-[12px] border border-white/[0.06] bg-bg px-4 py-3">
+                    <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Connection mental model</div>
+                    <p className="text-[12px] text-text-3 leading-relaxed">
+                      SwarmClaw talks to this endpoint from its own host. If SwarmClaw is on a server, <code className="text-text-2">localhost</code> means that server, not your laptop.
+                    </p>
+                    <p className="mt-2 text-[12px] text-text-3 leading-relaxed">
+                      Current target: <span className="text-text-2">{openClawEndpointHost || 'localhost:18789'}</span>{openClawLocal ? ' · local route' : ' · remote route'}
+                    </p>
+                  </div>
+                </div>
+              )}
+
               {(requiresKey || keyIsOptional) && (
                 <div>
                   <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">
@@ -594,6 +1170,48 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
                   const hint = getOpenClawErrorHint(checkMessage)
                   return hint ? <p className="mt-1.5 text-[11px] text-text-3">{hint}</p> : null
                 })()}
+                {providerSuggestedModel && (
+                  <p className="mt-1.5 text-[11px] text-text-3">Suggested model: {providerSuggestedModel}</p>
+                )}
+                {provider === 'openclaw' && checkState === 'ok' && openclawDeviceId && (
+                  <p className="mt-1.5 text-[11px] text-text-3">
+                    Device paired as <code className="text-text-2">{openclawDeviceId.slice(0, 12)}...</code>.
+                  </p>
+                )}
+              </div>
+            )}
+
+            {provider === 'openclaw' && checkState === 'error' && checkErrorCode === 'PAIRING_REQUIRED' && (
+              <div className="mb-4 rounded-[12px] border border-emerald-500/20 bg-emerald-500/5 px-4 py-3 text-left">
+                <div className="text-[13px] font-600 text-emerald-300">Awaiting gateway approval</div>
+                <p className="mt-1.5 text-[12px] text-text-3 leading-relaxed">
+                  This device is pending approval on that OpenClaw gateway. Approve it from Nodes, then run the connection check again.
+                  {openclawDeviceId ? (
+                    <> Device: <code className="text-text-2">{openclawDeviceId}</code>.</>
+                  ) : null}
+                </p>
+                {openClawDashboardUrl && (
+                  <a
+                    href={openClawDashboardUrl}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="mt-3 inline-flex items-center gap-1.5 rounded-[10px] border border-white/[0.08] bg-white/[0.03] px-3 py-2 text-[12px] text-text hover:bg-white/[0.06] transition-all duration-200"
+                  >
+                    Open gateway dashboard
+                  </a>
+                )}
+              </div>
+            )}
+
+            {provider === 'openclaw' && checkState === 'error' && checkErrorCode === 'DEVICE_AUTH_INVALID' && (
+              <div className="mb-4 rounded-[12px] border border-white/[0.08] bg-surface px-4 py-3 text-left">
+                <div className="text-[13px] font-600 text-text">Device not paired</div>
+                <p className="mt-1.5 text-[12px] text-text-3 leading-relaxed">
+                  The gateway does not recognize this device yet. Add or approve it from Nodes, then retry.
+                  {openclawDeviceId ? (
+                    <> Device: <code className="text-text-2">{openclawDeviceId}</code>.</>
+                  ) : null}
+                </p>
               </div>
             )}
 
@@ -601,7 +1219,7 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
 
             <div className="flex items-center justify-center gap-3">
               <button
-                onClick={() => { setStep(0); setError('') }}
+                onClick={() => { resetProviderForm(); setStep('providers') }}
                 className="px-6 py-3.5 rounded-[14px] border border-white/[0.08] bg-transparent text-text-2 text-[14px]
                   font-display font-500 cursor-pointer hover:bg-white/[0.03] transition-all duration-200"
               >
@@ -616,171 +1234,248 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
                 {checkState === 'checking' ? 'Checking...' : 'Check Connection'}
               </button>
               <button
-                onClick={saveProviderAndContinue}
+                onClick={saveProvider}
                 disabled={(requiresKey && !apiKey.trim()) || saving}
                 className="px-8 py-3.5 rounded-[14px] border-none bg-accent-bright text-white text-[15px] font-display font-600
                   cursor-pointer hover:brightness-110 active:scale-[0.97] transition-all duration-200
                   shadow-[0_6px_28px_rgba(99,102,241,0.3)] disabled:opacity-30"
               >
-                {saving
-                  ? 'Saving...'
-                  : requiresVerifiedConnection
-                    ? 'Verify & Continue'
-                    : 'Save & Continue'}
+                {saving ? 'Saving...' : 'Save Provider'}
               </button>
             </div>
 
-            <SkipLink
-              onClick={configuredProviders.length > 0 ? async () => {
-                await api('PUT', '/settings', { setupCompleted: true })
-                setStep(3)
-              } : skip}
-              label={configuredProviders.length > 0 ? 'Finish Setup' : 'Skip setup for now'}
-            />
+            <SkipLink onClick={skip} />
           </>
         )}
 
-        {step === 2 && provider && selectedProvider && (
+        {step === 'agents' && (
           <>
             <h1 className="font-display text-[36px] font-800 leading-[1.05] tracking-[-0.04em] mb-3">
-              Create Your Agent
+              Review Starter Agents
             </h1>
-            <p className="text-[15px] text-text-2 mb-7">
-              We&apos;ll create a starter agent so you can begin immediately.
+            <p className="text-[15px] text-text-2 mb-2">
+              Choose which agents to start with, then adjust provider and model per agent.
+            </p>
+            <p className="text-[13px] text-text-3 mb-7">
+              These are just starting points. You can edit them later from Agents.
             </p>
 
-            <div className="mb-5 p-4 rounded-[14px] border border-white/[0.08] bg-surface text-left">
-              <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Setup Summary</div>
-              <div className="text-[14px] text-text mb-1">Provider: {selectedProvider.name}</div>
-              {supportsEndpoint && endpoint.trim() && (
-                <div className="text-[12px] font-mono text-text-3 break-all">Endpoint: {endpoint.trim()}</div>
-              )}
-              {checkState === 'ok' && (
-                <div className="mt-2 text-[12px] text-emerald-300">{checkMessage}</div>
-              )}
-              {checkState === 'error' && (
-                <div className="mt-2 text-[12px] text-amber-300">Connection was not verified. You can still continue.</div>
-              )}
-            </div>
-
-            <details className="mb-6 text-left rounded-[14px] border border-white/[0.08] bg-surface px-4 py-3">
-              <summary className="cursor-pointer text-[13px] text-text-2 font-600">
-                Advanced agent settings (optional)
-              </summary>
-              <div className="mt-3 space-y-3">
-                <div>
-                  <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Name</label>
-                  <input
-                    type="text"
-                    value={agentName}
-                    onChange={(e) => setAgentName(e.target.value)}
-                    className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
-                      text-text text-[14px] outline-none transition-all duration-200
-                      focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
-                  />
-                </div>
-                <div>
-                  <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Description</label>
-                  <input
-                    type="text"
-                    value={agentDescription}
-                    onChange={(e) => setAgentDescription(e.target.value)}
-                    className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
-                      text-text text-[14px] outline-none transition-all duration-200
-                      focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
-                  />
-                </div>
-                <div>
-                  <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">System Prompt</label>
-                  <textarea
-                    value={agentPrompt}
-                    onChange={(e) => setAgentPrompt(e.target.value)}
-                    rows={3}
-                    className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
-                      text-text text-[14px] outline-none transition-all duration-200 resize-none
-                      focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
-                  />
-                </div>
-                <div>
-                  <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Model</label>
-                  <input
-                    type="text"
-                    value={agentModel}
-                    onChange={(e) => setAgentModel(e.target.value)}
-                    className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
-                      text-text text-[14px] font-mono outline-none transition-all duration-200
-                      focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
-                  />
+            {selectedStarterKit && (
+              <div className="mb-5 p-4 rounded-[14px] border border-white/[0.08] bg-surface text-left">
+                <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-2">Setup Summary</div>
+                <div className="text-[14px] text-text mb-1">{selectedStarterKit.name}</div>
+                <div className="text-[12px] text-text-3">{selectedStarterKit.detail}</div>
+                {!!intentText.trim() && (
+                  <div className="mt-3 text-[12px] text-text-2">
+                    Intent: <span className="text-text-3">{intentText.trim()}</span>
+                  </div>
+                )}
+                <div className="mt-3 text-[12px] text-text-3">
+                  Providers ready: {configuredProviders.length || 'none'}
                 </div>
               </div>
-            </details>
+            )}
+
+            {draftAgents.length === 0 ? (
+              <div className="mb-6 p-6 rounded-[16px] border border-white/[0.08] bg-surface text-left">
+                <div className="text-[16px] font-display font-700 text-text mb-2">Blank workspace selected</div>
+                <p className="text-[13px] text-text-3 leading-relaxed">
+                  Finish setup now and create your first provider, agent, task, or project later from inside the app.
+                </p>
+              </div>
+            ) : (
+              <div className="space-y-4 max-h-[46vh] overflow-y-auto pr-1 text-left mb-6">
+                {draftAgents.map((draft) => (
+                  <div key={draft.id} className="rounded-[16px] border border-white/[0.08] bg-surface p-4">
+                    <div className="flex items-center justify-between gap-4 mb-4">
+                      <div>
+                        <div className="text-[15px] font-display font-700 text-text">{draft.name}</div>
+                        <div className="text-[12px] text-text-3">{draft.description}</div>
+                      </div>
+                      <label className="inline-flex items-center gap-2 text-[12px] text-text-2">
+                        <input
+                          type="checkbox"
+                          checked={draft.enabled}
+                          onChange={(e) => updateDraftAgent(draft.id, { enabled: e.target.checked })}
+                        />
+                        Start with this agent
+                      </label>
+                    </div>
+
+                    <div className="grid gap-3 md:grid-cols-2">
+                      <div>
+                        <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Name</label>
+                        <input
+                          type="text"
+                          value={draft.name}
+                          onChange={(e) => updateDraftAgent(draft.id, { name: e.target.value })}
+                          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                            text-text text-[14px] outline-none transition-all duration-200
+                            focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                        />
+                      </div>
+                      <div>
+                        <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Provider</label>
+                        <select
+                          value={draft.providerConfigId || ''}
+                          onChange={(e) => updateDraftAgentProvider(draft.id, e.target.value)}
+                          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                            text-text text-[14px] outline-none transition-all duration-200
+                            focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                        >
+                          <option value="">Choose provider</option>
+                          {configuredProviders.map((configuredProvider) => (
+                            <option key={configuredProvider.id} value={configuredProvider.id}>
+                              {configuredProvider.name}
+                              {configuredProvider.provider === 'openclaw' && formatEndpointHost(configuredProvider.endpoint)
+                                ? ` · ${formatEndpointHost(configuredProvider.endpoint)}`
+                                : ''}
+                              {configuredProvider.defaultModel ? ` · ${configuredProvider.defaultModel}` : ''}
+                            </option>
+                          ))}
+                        </select>
+                      </div>
+                      <div className="md:col-span-2">
+                        <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Description</label>
+                        <input
+                          type="text"
+                          value={draft.description}
+                          onChange={(e) => updateDraftAgent(draft.id, { description: e.target.value })}
+                          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                            text-text text-[14px] outline-none transition-all duration-200
+                            focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                        />
+                      </div>
+                      <div>
+                        <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Model</label>
+                        <input
+                          type="text"
+                          value={draft.model}
+                          onChange={(e) => updateDraftAgent(draft.id, { model: e.target.value })}
+                          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                            text-text text-[14px] font-mono outline-none transition-all duration-200
+                            focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                        />
+                      </div>
+                      <div>
+                        <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Mode</label>
+                        <select
+                          value={draft.platformAssignScope}
+                          onChange={(e) => updateDraftAgent(draft.id, { platformAssignScope: e.target.value as 'self' | 'all' })}
+                          className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-bg
+                            text-text text-[14px] outline-none transition-all duration-200
+                            focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                        >
+                          <option value="self">Focused agent</option>
+                          <option value="all">Delegating orchestrator</option>
+                        </select>
+                      </div>
+                    </div>
+
+                    <details className="mt-4 rounded-[12px] border border-white/[0.08] bg-bg px-4 py-3">
+                      <summary className="cursor-pointer text-[13px] text-text-2 font-600">
+                        Prompt and tools
+                      </summary>
+                      <div className="mt-3 space-y-3">
+                        <div>
+                          <label className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">System Prompt</label>
+                          <textarea
+                            value={draft.systemPrompt}
+                            onChange={(e) => updateDraftAgent(draft.id, { systemPrompt: e.target.value })}
+                            rows={5}
+                            className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-surface
+                              text-text text-[14px] outline-none transition-all duration-200 resize-none
+                              focus:border-accent-bright/30 focus:shadow-[0_0_30px_rgba(99,102,241,0.1)]"
+                          />
+                        </div>
+                        <div>
+                          <div className="block text-[12px] text-text-3 font-500 mb-1.5 ml-1">Tools</div>
+                          <div className="flex flex-wrap gap-2">
+                            {draft.tools.map((tool) => (
+                              <span
+                                key={tool}
+                                className="inline-flex items-center px-2 py-0.5 rounded-md bg-white/[0.04] border border-white/[0.06] text-[11px] text-text-2"
+                              >
+                                {tool}
+                              </span>
+                            ))}
+                          </div>
+                        </div>
+                      </div>
+                    </details>
+                  </div>
+                ))}
+              </div>
+            )}
 
             {error && <p className="mb-4 text-[13px] text-red-400">{error}</p>}
 
             <div className="flex items-center justify-center gap-3">
               <button
-                onClick={() => { setStep(1); setError('') }}
+                onClick={() => setStep('providers')}
                 className="px-6 py-3.5 rounded-[14px] border border-white/[0.08] bg-transparent text-text-2 text-[14px]
                   font-display font-500 cursor-pointer hover:bg-white/[0.03] transition-all duration-200"
               >
                 Back
               </button>
               <button
-                onClick={() => createAgentAndFinish(true)}
-                disabled={!agentName.trim() || saving}
+                onClick={() => setStep('providers')}
                 className="px-6 py-3.5 rounded-[14px] border border-white/[0.08] bg-white/[0.03] text-text text-[14px]
-                  font-display font-600 cursor-pointer hover:bg-white/[0.06] transition-all duration-200 disabled:opacity-40"
+                  font-display font-600 cursor-pointer hover:bg-white/[0.06] transition-all duration-200"
               >
-                {saving ? 'Creating...' : 'Create & Add Another'}
+                Add Another Provider
               </button>
               <button
-                onClick={() => createAgentAndFinish(false)}
-                disabled={!agentName.trim() || saving}
+                onClick={draftAgents.length === 0 ? finishWithoutAgents : createAgentsAndFinish}
+                disabled={saving}
                 className="px-8 py-3.5 rounded-[14px] border-none bg-accent-bright text-white text-[15px] font-display font-600
                   cursor-pointer hover:brightness-110 active:scale-[0.97] transition-all duration-200
                   shadow-[0_6px_28px_rgba(99,102,241,0.3)] disabled:opacity-30"
               >
-                {saving ? 'Creating...' : 'Create & Finish'}
+                {saving
+                  ? 'Saving...'
+                  : draftAgents.length === 0
+                    ? 'Finish Setup'
+                    : `Create ${draftAgents.filter((draft) => draft.enabled).length} Agent${draftAgents.filter((draft) => draft.enabled).length === 1 ? '' : 's'}`}
               </button>
             </div>
 
-            <SkipLink
-              onClick={configuredProviders.length > 0 ? async () => {
-                await api('PUT', '/settings', { setupCompleted: true })
-                setStep(3)
-              } : skip}
-              label={configuredProviders.length > 0 ? 'Finish Setup' : 'Skip setup for now'}
-            />
+            <SkipLink onClick={skip} />
           </>
         )}
 
-        {step === 3 && (
+        {step === 'done' && (
           <>
             <h1 className="font-display text-[36px] font-800 leading-[1.05] tracking-[-0.04em] mb-3">
               You&apos;re All Set
             </h1>
             <p className="text-[15px] text-text-2 mb-7">
-              {configuredProviders.length === 1
-                ? 'Your agent is ready to chat.'
-                : `${configuredProviders.length} agents created and ready to chat.`}
+              {createdAgents.length === 0
+                ? 'Your workspace is ready. Add providers and agents whenever you want.'
+                : createdAgents.length === 1
+                  ? 'Your starter agent is ready to chat.'
+                  : `${createdAgents.length} starter agents are ready to go.`}
             </p>
 
-            {configuredProviders.length > 0 && (
+            {createdAgents.length > 0 && (
               <div className="mb-6 p-4 rounded-[14px] border border-white/[0.08] bg-surface text-left">
                 <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-3">Agents Created</div>
                 <div className="space-y-2">
-                  {configuredProviders.map((cp) => {
-                    const meta = SETUP_PROVIDERS.find((p) => p.id === cp.provider)
+                  {createdAgents.map((agent) => {
+                    const meta = SETUP_PROVIDERS.find((candidate) => candidate.id === agent.provider)
                     return (
-                      <div key={cp.provider} className="flex items-center gap-3">
+                      <div key={agent.id} className="flex items-center gap-3">
                         <div className="w-8 h-8 rounded-[8px] bg-white/[0.04] border border-white/[0.06] flex items-center justify-center shrink-0">
                           <span className="text-[13px] font-display font-700 text-accent-bright">
                             {meta?.icon || '?'}
                           </span>
                         </div>
                         <div>
-                          <div className="text-[14px] text-text font-500">{cp.agentName}</div>
-                          <div className="text-[12px] text-text-3">{meta?.name || cp.provider}</div>
+                          <div className="text-[14px] text-text font-500">{agent.name}</div>
+                          <div className="text-[12px] text-text-3">
+                            {agent.providerName}
+                            {agent.providerName !== (meta?.name || agent.provider) ? ` · ${meta?.name || agent.provider}` : ''}
+                          </div>
                         </div>
                       </div>
                     )
@@ -790,17 +1485,17 @@ export function SetupWizard({ onComplete }: SetupWizardProps) {
             )}
 
             <div className="mb-8 p-4 rounded-[14px] border border-white/[0.08] bg-surface text-left">
-              <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-3">Coming Soon — Connectors</div>
+              <div className="text-[12px] uppercase tracking-[0.08em] text-text-3 mb-3">Next Up — Connectors</div>
               <p className="text-[13px] text-text-2 mb-3">
-                Bridge your agents to chat platforms. Set this up anytime from Connectors.
+                Bridge your agents to chat platforms any time from Connectors.
               </p>
               <div className="flex gap-3">
-                {CONNECTOR_ICONS.map((c) => (
-                  <div key={c.name} className="flex flex-col items-center gap-1.5">
+                {CONNECTOR_ICONS.map((connector) => (
+                  <div key={connector.name} className="flex flex-col items-center gap-1.5">
                     <div className="w-10 h-10 rounded-[10px] bg-white/[0.04] border border-white/[0.06] flex items-center justify-center">
-                      <span className="text-[14px] font-display font-600 text-text-3">{c.icon}</span>
+                      <span className="text-[14px] font-display font-600 text-text-3">{connector.icon}</span>
                     </div>
-                    <span className="text-[10px] text-text-3">{c.name}</span>
+                    <span className="text-[10px] text-text-3">{connector.name}</span>
                   </div>
                 ))}
               </div>