fix: stabilize local provider switching

Author: waydelyle

README.md

@@ -182,7 +182,7 @@ Full hosted deployment guides live at https://swarmclaw.ai/docs/deployment
 
 ## Core Capabilities
 
-- **Providers**: 23 built-in — Claude Code CLI, Codex CLI, OpenCode CLI, Gemini CLI, Copilot CLI, Cursor Agent CLI, Qwen Code CLI, Goose, Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, Ollama, OpenClaw, and Hermes Agent, plus compatible custom endpoints.
+- **Providers**: 24+ built-in — Claude Code CLI, Codex CLI, OpenCode CLI, Gemini CLI, Copilot CLI, Cursor Agent CLI, Qwen Code CLI, Goose, Anthropic, OpenAI, OpenRouter, Google Gemini, DeepSeek, Groq, Together, Mistral, xAI, Fireworks, Nebius, DeepInfra, Ollama, LM Studio, OpenClaw, and Hermes Agent, plus compatible custom endpoints.
 - **OpenRouter**: <img src="public/provider-logos/openrouter.png" alt="OpenRouter logo" width="20" height="20" /> Use OpenRouter as a first-class built-in provider with its standard OpenAI-compatible endpoint and routed model IDs such as `openai/gpt-4.1-mini`.
 - **Hermes Agent**: <img src="public/provider-logos/hermes-agent.png" alt="Hermes Agent logo" width="20" height="20" /> Connect Hermes through its OpenAI-compatible API server, locally or through a reachable remote `/v1` endpoint.
 - **Delegation**: built-in delegation to Claude Code, Codex CLI, OpenCode CLI, Gemini CLI, Cursor Agent CLI, Qwen Code CLI, and native SwarmClaw subagents.
@@ -407,6 +407,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.20 Highlights
+
+Provider reliability release: local OpenAI-compatible runtimes now get safer endpoint handling, clearer setup, and first-class LM Studio support.
+
+- **LM Studio provider.** LM Studio is available in setup, provider settings, agent editing, model discovery, and connection checks with an optional API key.
+- **Endpoint normalization.** LM Studio and OpenAI-compatible OpenAI overrides normalize bare hosts like `http://127.0.0.1:1234` to `/v1` before calling models or chat completions.
+- **Provider switch isolation.** Switching an agent from a local endpoint back to a fixed cloud provider clears stale per-agent endpoints and fallback keys.
+- **Manual model flow.** Provider model saves now preserve explicit empty endpoint resets and optional-key providers can be tested without creating a credential.
+
 ### v1.9.19 Highlights
 
 Output hygiene release: final assistant responses now use the shared internal metadata scrubber before persistence, UI reset, connector delivery, and completion hooks.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.19",
+  "version": "1.9.20",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "main": "electron-dist/main.js",
   "license": "MIT",

package.json

@@ -5,6 +5,7 @@ import { getDeviceId, wsConnect, rpcOnConnectedGateway } from '@/lib/providers/o
 import { isCliProviderId } from '@/lib/providers/cli-provider-metadata'
 import { checkCliProviderReady } from '@/lib/server/cli-provider-readiness'
 import { OPENAI_COMPATIBLE_DEFAULTS } from '@/lib/server/provider-health'
+import { normalizeLmStudioEndpoint, normalizeOpenAiCompatibleV1Endpoint } from '@/lib/providers/openai-compatible-endpoint'
 import { resolveOllamaRuntimeConfig } from '@/lib/server/ollama-runtime'
 import { normalizeOllamaSetupEndpoint, normalizeOpenClawUrl, parseErrorMessage } from './helpers'
 
@@ -70,6 +71,7 @@ async function checkOpenAiCompatible(
       DeepInfra: 'deepseek-ai/DeepSeek-R1-0528',
       OpenRouter: 'openai/gpt-4.1-mini',
       'Hermes Agent': 'hermes-agent',
+      'LM Studio': 'local-model',
     }
     testModel = fallbacks[providerName] || 'gpt-4o-mini'
   }
@@ -312,7 +314,13 @@ export async function POST(req: Request) {
       case 'openai': {
         if (!apiKey) return NextResponse.json({ ok: false, message: 'OpenAI API key is required.' })
         const info = OPENAI_COMPATIBLE_DEFAULTS.openai
-        const result = await checkOpenAiCompatible(info.name, apiKey, endpoint, info.defaultEndpoint, model)
+        const result = await checkOpenAiCompatible(
+          info.name,
+          apiKey,
+          normalizeOpenAiCompatibleV1Endpoint(endpoint || info.defaultEndpoint, info.defaultEndpoint),
+          info.defaultEndpoint,
+          model,
+        )
         return NextResponse.json(result)
       }
       case 'openrouter': {
@@ -345,6 +353,17 @@ export async function POST(req: Request) {
         const result = await checkOpenAiCompatible(info.name, apiKey, endpoint, info.defaultEndpoint, model)
         return NextResponse.json(result)
       }
+      case 'lmstudio': {
+        const info = OPENAI_COMPATIBLE_DEFAULTS.lmstudio
+        const result = await checkOpenAiCompatible(
+          info.name,
+          apiKey,
+          normalizeLmStudioEndpoint(endpoint || info.defaultEndpoint),
+          info.defaultEndpoint,
+          model,
+        )
+        return NextResponse.json(result)
+      }
       case 'ollama': {
         const result = await checkOllama({
           endpointRaw: endpoint,

src/app/api/setup/check-provider/route.ts

@@ -50,6 +50,7 @@ const AUTO_SYNC_MODEL_PROVIDER_IDS = new Set<ProviderType>([
   'nebius',
   'deepinfra',
   'hermes',
+  'lmstudio',
   'ollama',
 ])
 const CONNECTION_TEST_TIMEOUT_MS = 40_000
@@ -745,6 +746,23 @@ export function AgentSheet() {
     if (!model) setModel('default')
   }
 
+  const applyDirectProviderSelection = (nextProviderId: string) => {
+    const nextProvider = agentSelectableProviders.find((item) => item.id === nextProviderId)
+    const nextCredentials = resolveAgentSelectableProviderCredentials(nextProviderId, credentials, providerConfigs)
+    setProvider(nextProviderId)
+    setModel(nextProvider?.models[0] || '')
+    setCredentialId(nextCredentials[0]?.id || null)
+    setFallbackCredentialIds([])
+    setGatewayProfileId(null)
+    setApiEndpoint(nextProvider?.requiresEndpoint ? nextProvider.defaultEndpoint || null : null)
+    setTestStatus('idle')
+    setTestMessage('')
+    setTestErrorCode(null)
+    setAddingKey(false)
+    setNewKeyName('')
+    setNewKeyValue('')
+  }
+
   const updateRoutingTarget = (targetId: string, patch: Partial<AgentRoutingTarget>) => {
     setRoutingTargets((current) => current.map((target) => (
       target.id === targetId
@@ -778,7 +796,8 @@ export function AgentSheet() {
 
   const handleSave = async () => {
     // For any endpoint, just ensure bare host:port gets a protocol prepended
-    let normalizedEndpoint = apiEndpoint
+    const providerAllowsAgentEndpoint = Boolean(openclawEnabled || currentProvider?.requiresEndpoint || currentProvider?.optionalEndpoint)
+    let normalizedEndpoint = providerAllowsAgentEndpoint ? apiEndpoint : null
     if (normalizedEndpoint) {
       const url = normalizedEndpoint.trim().replace(/\/+$/, '')
       normalizedEndpoint = /^(https?|wss?):\/\//i.test(url) ? url : `http://${url}`
@@ -1543,13 +1562,7 @@ export function AgentSheet() {
             return (
               <button
                 key={p.id}
-                onClick={() => {
-                  setProvider(p.id)
-                  if (!nextCredentials.some((item) => item.id === credentialId)) {
-                    setCredentialId(nextCredentials[0]?.id || null)
-                  }
-                  setGatewayProfileId(null)
-                }}
+                onClick={() => applyDirectProviderSelection(p.id)}
                 className={`relative py-3.5 px-4 rounded-[14px] text-center cursor-pointer transition-all duration-200
                   active:scale-[0.97] text-[14px] font-600 border
                   ${provider === p.id
@@ -1731,14 +1744,17 @@ export function AgentSheet() {
 
       {(currentProvider?.requiresEndpoint || currentProvider?.optionalEndpoint) && (provider !== 'ollama' || ollamaMode === 'local') && (
         <div className="mb-8">
-          <SectionLabel>{provider === 'openclaw' ? 'OpenClaw Endpoint' : provider === 'hermes' ? 'Hermes API Endpoint' : 'Endpoint'}</SectionLabel>
+          <SectionLabel>{provider === 'openclaw' ? 'OpenClaw Endpoint' : provider === 'hermes' ? 'Hermes API Endpoint' : provider === 'lmstudio' ? 'LM Studio Endpoint' : 'Endpoint'}</SectionLabel>
           <input type="text" value={apiEndpoint || ''} onChange={(e) => setApiEndpoint(e.target.value || null)} placeholder={currentProvider.defaultEndpoint || 'http://localhost:11434'} className={`${inputClass} font-mono text-[14px]`} />
           {provider === 'openclaw' && (
             <p className="text-[13px] text-text-3/70 mt-2">The URL of your OpenClaw gateway</p>
           )}
           {provider === 'hermes' && (
             <p className="text-[13px] text-text-3/70 mt-2">Point this at the Hermes API server, usually <code className="text-text-2">http://127.0.0.1:8642/v1</code>.</p>
           )}
+          {provider === 'lmstudio' && (
+            <p className="text-[13px] text-text-3/70 mt-2">Point this at the LM Studio local server. A bare host is normalized to <code className="text-text-2">/v1</code>.</p>
+          )}
         </div>
       )}
 

src/components/agents/agent-sheet.tsx

@@ -28,6 +28,7 @@ const SETUP_PROVIDERS_WITH_MODEL_DISCOVERY = new Set([
   'ollama',
   'openclaw',
   'hermes',
+  'lmstudio',
 ])
 
 /* ── Model combobox: search discovered models or type a custom one ── */

src/components/auth/setup-wizard/step-agents.tsx

@@ -335,6 +335,12 @@ export function StepConnect({
                 <p className="text-[12px] text-text-3">Use any reachable local or remote API-server endpoint exposed by Hermes.</p>
               </div>
             )}
+            {provider === 'lmstudio' && (
+              <div className="mt-2 space-y-0.5">
+                <p className="text-[12px] text-text-3">LM Studio&apos;s local server defaults to <code className="text-text-2">http://127.0.0.1:1234/v1</code>.</p>
+                <p className="text-[12px] text-text-3">If you paste a host without <code className="text-text-2">/v1</code>, SwarmClaw normalizes it before testing and chat.</p>
+              </div>
+            )}
           </div>
         )}
 

src/components/auth/setup-wizard/step-connect.tsx

@@ -271,7 +271,10 @@ export function ProviderSheet() {
   const modelList = models.split(',').map((m) => m.trim()).filter(Boolean)
   const showApiKey = isBuiltin ? editingBuiltin?.requiresApiKey || editingBuiltin?.optionalApiKey : requiresApiKey
   const canDiscoverModels = Boolean(isBuiltin && editingBuiltin?.supportsModelDiscovery)
-  const showTestButton = Boolean(isBuiltin && showApiKey && credentialId)
+  const showTestButton = Boolean(
+    isBuiltin
+    && (editingBuiltin?.requiresApiKey ? credentialId : (showApiKey || editingBuiltin?.requiresEndpoint || editingBuiltin?.optionalEndpoint)),
+  )
 
   const inputClass = "w-full px-4 py-3.5 rounded-[14px] border border-white/[0.08] bg-surface text-text text-[15px] outline-none transition-all duration-200 placeholder:text-text-3/50 focus-glow"
 

src/components/providers/provider-sheet.tsx

@@ -86,7 +86,7 @@ export function useSaveBuiltinProviderMutation() {
       await api('PUT', `/providers/${id}/models`, { models })
       return api('PUT', `/providers/${id}`, {
         isEnabled,
-        ...(baseUrl ? { baseUrl } : {}),
+        ...(typeof baseUrl === 'string' ? { baseUrl } : {}),
       })
     },
     onSuccess: async () => {

src/features/providers/queries.ts

@@ -77,6 +77,34 @@ test('builtin provider override records do not surface as custom providers', ()
   assert.equal(output.openAiCount, 1)
 })
 
+test('LM Studio is available as a first-class local OpenAI-compatible provider', () => {
+  const output = runWithTempDataDir<{
+    providerName: string | null
+    defaultEndpoint: string | null
+    requiresApiKey: boolean | null
+    optionalApiKey: boolean | null
+    supportsModelDiscovery: boolean | null
+  }>(`
+    const providersModule = await import('@/lib/providers/index')
+    const providers = providersModule.default || providersModule
+    const provider = providers.getProviderList().find((entry) => entry.id === 'lmstudio')
+
+    console.log(JSON.stringify({
+      providerName: provider?.name ?? null,
+      defaultEndpoint: provider?.defaultEndpoint ?? null,
+      requiresApiKey: provider?.requiresApiKey ?? null,
+      optionalApiKey: provider?.optionalApiKey ?? null,
+      supportsModelDiscovery: provider?.supportsModelDiscovery ?? null,
+    }))
+  `)
+
+  assert.equal(output.providerName, 'LM Studio')
+  assert.equal(output.defaultEndpoint, 'http://127.0.0.1:1234/v1')
+  assert.equal(output.requiresApiKey, false)
+  assert.equal(output.optionalApiKey, true)
+  assert.equal(output.supportsModelDiscovery, true)
+})
+
 test('custom provider resolution includes defaultEndpoint and optionalApiKey', () => {
   const output = runWithTempDataDir<{
     defaultEndpoint: string | null