@swarmclawai/swarmclaw 1.9.20 → 1.9.21

package/README.md

@@ -81,8 +81,10 @@ Extension tutorial: https://swarmclaw.ai/docs/extension-tutorial
 Download the one-click installer from [swarmclaw.ai/downloads](https://swarmclaw.ai/downloads).
 Available for macOS (Apple Silicon & Intel), Windows, and Linux (AppImage + .deb).
 
-Current builds are ad-hoc signed but not notarized, so on first launch:
-- **macOS:** right-click the app in Finder → **Open** → **Open** to bypass Gatekeeper. If macOS instead reports *"SwarmClaw is damaged and can't be opened"* (common on Apple Silicon when the dmg was quarantined by Safari), strip the quarantine attribute and relaunch:
+The release workflow supports Developer ID signing and notarization when Apple
+credentials are configured. If a macOS build is still ad-hoc signed, first
+launch may need one manual approval:
+- **macOS:** right-click the app in Finder → **Open** → **Open** to bypass Gatekeeper. If macOS instead reports *"SwarmClaw is damaged and can't be opened"* (common when the dmg was quarantined by Safari), strip the quarantine attribute and relaunch:
   ```bash
   xattr -dr com.apple.quarantine /Applications/SwarmClaw.app
   ```
@@ -407,6 +409,15 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.9.21 Highlights
+
+Provider diagnostics release: connection checks now return a structured step timeline across setup, provider settings, and agent editing.
+
+- **Connection timelines.** Provider checks show endpoint resolution, model discovery, fallback selection, and chat/gateway verification steps.
+- **Safer error details.** Token-like values are redacted before check messages or diagnostics are returned to the UI.
+- **Local runtime debugging.** LM Studio, Ollama, custom OpenAI-compatible endpoints, cloud providers, OpenClaw gateways, and CLI providers all report concise pass/fail diagnostics.
+- **macOS signing path.** Desktop releases now forward Developer ID and Apple notarization credentials when configured, while ad-hoc fallback builds keep the quarantine workaround documented.
+
 ### v1.9.20 Highlights
 
 Provider reliability release: local OpenAI-compatible runtimes now get safer endpoint handling, clearer setup, and first-class LM Studio support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.9.20",
+  "version": "1.9.21",
   "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",
@@ -85,10 +85,10 @@
     "lint:baseline": "node ./scripts/lint-baseline.mjs check",
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
-    "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
+    "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/electron-after-pack.test.mjs scripts/electron-signing-config.test.mjs scripts/ensure-sandbox-browser-image.test.mjs scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
     "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/gateways/gateway-topology.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openai.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/gateways/topology-route.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
-    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
+    "test:runtime": "tsx --test src/lib/a2a/agent-card.test.ts src/lib/agent-planning-mode.test.ts src/lib/agent-config-history.test.ts src/lib/strip-internal-metadata.test.ts src/lib/provider-sets.test.ts src/lib/providers/opencode-cli.test.ts src/lib/providers/cli-provider-metadata.test.ts src/lib/providers/cli-utils.test.ts src/lib/providers/generic-cli.test.ts src/lib/server/agents/delegation-advisory.test.ts src/lib/server/cli-provider-readiness.test.ts src/lib/server/provider-health.test.ts src/lib/server/provider-diagnostics.test.ts src/lib/server/mcp-gateway-runtime.test.ts src/lib/server/mcp-connection-pool.test.ts src/lib/server/knowledge-sources.test.ts src/lib/server/extension-managed-resources.test.ts src/lib/server/eval/baseline.test.ts src/lib/server/eval/environment-plan.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/chat-execution/chat-turn-preparation.test.ts src/lib/server/chat-execution/iteration-timers.test.ts src/lib/server/chat-execution/post-stream-finalization.test.ts src/lib/server/chat-execution/prompt-sections.planning-mode.test.ts src/lib/server/chat-execution/reasoning-tag-scrubber.test.ts src/lib/server/chats/clear-undo-snapshots.test.ts src/lib/server/chats/session-context-pack.test.ts src/lib/server/connectors/email.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/runtime/queue-retry-policy.test.ts src/lib/server/runs/run-brief.test.ts src/lib/server/runs/run-handoff.test.ts src/lib/server/operations/operation-pulse.test.ts src/lib/server/schedules/schedule-history.test.ts src/lib/server/schedules/schedule-preview.test.ts src/lib/quality/release-readiness.test.ts src/lib/quality/architecture-health.test.ts src/lib/server/artifacts/artifact-resolver.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/lib/server/missions/mission-templates.test.ts src/lib/server/sharing/share-link-repository.test.ts src/lib/server/sharing/share-resolver.test.ts src/lib/server/tasks/task-execution-workspace.test.ts src/lib/server/tasks/task-execution-policy.test.ts src/lib/server/tasks/task-handoff.test.ts src/lib/server/tasks/task-service.test.ts src/lib/server/session-tools/execute.test.ts src/lib/server/session-tools/manage-tasks.test.ts src/lib/app/view-constants.test.ts src/lib/quality/quality-summary.test.ts src/app/api/approvals/route.test.ts src/app/api/agents/agents-route.test.ts src/app/api/tasks/tasks-route.test.ts src/app/api/tasks/task-workspace-route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/chats/clear-route.test.ts src/app/api/chats/compact-route.test.ts src/app/api/chats/context-pack-route.test.ts src/app/api/chats/context-status-route.test.ts src/app/api/config-versions/config-versions-route.test.ts src/app/api/runs/run-handoff-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/extensions/managed-resources/route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/portability/export/route.test.ts src/app/api/portability/import/route.test.ts src/app/api/providers/[id]/route.test.ts src/app/api/schedules/preview/route.test.ts src/app/api/schedules/schedule-history-route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",
     "test:e2e": "node --import tsx scripts/browser-e2e-smoke.ts",
     "test:mcp:conformance": "node --import tsx ./scripts/mcp-conformance-check.ts",

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

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict'
 import test from 'node:test'
 
 import { normalizeOllamaSetupEndpoint, normalizeOpenClawUrl, parseErrorMessage } from './helpers'
+import { POST } from './route'
 
 test('normalizeOllamaSetupEndpoint strips local /v1 suffixes but preserves cloud endpoints', () => {
   assert.equal(
@@ -117,3 +118,46 @@ test('normalizeOpenClawUrl handles bare IP:port', () => {
   assert.equal(httpUrl, 'http://10.0.0.5:18789')
   assert.equal(wsUrl, 'ws://10.0.0.5:18789')
 })
+
+test('POST returns provider diagnostics with normalized LM Studio targets and redacted errors', async () => {
+  const originalFetch = globalThis.fetch
+  const calls: string[] = []
+  globalThis.fetch = (async (input: RequestInfo | URL) => {
+    const url = String(input)
+    calls.push(url)
+    if (url.endsWith('/models')) {
+      return new Response(JSON.stringify({ data: [{ id: 'google/gemma-4-e4b' }] }), { status: 200 })
+    }
+    return new Response(
+      JSON.stringify({ error: { message: 'Malformed token sk-local-secret provided.' } }),
+      { status: 400 },
+    )
+  }) as typeof fetch
+
+  try {
+    const res = await POST(new Request('http://localhost/api/setup/check-provider', {
+      method: 'POST',
+      body: JSON.stringify({
+        provider: 'lmstudio',
+        endpoint: 'http://10.2.0.2:1234',
+      }),
+    }))
+    const payload = await res.json()
+
+    assert.equal(payload.ok, false)
+    assert.equal(payload.normalizedEndpoint, 'http://10.2.0.2:1234/v1')
+    assert.deepEqual(calls, [
+      'http://10.2.0.2:1234/v1/models',
+      'http://10.2.0.2:1234/v1/chat/completions',
+    ])
+    assert.ok(Array.isArray(payload.diagnostics))
+    assert.equal(payload.diagnostics[0].target, 'http://10.2.0.2:1234/v1')
+    assert.equal(payload.message, 'Malformed token sk-... provided.')
+    assert.equal(
+      payload.diagnostics.some((step: { detail?: string }) => step.detail?.includes('sk-local-secret')),
+      false,
+    )
+  } finally {
+    globalThis.fetch = originalFetch
+  }
+})

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

@@ -4,10 +4,12 @@ import { listCredentialIdsByProvider } from '@/lib/server/credentials/credential
 import { getDeviceId, wsConnect, rpcOnConnectedGateway } from '@/lib/providers/openclaw'
 import { isCliProviderId } from '@/lib/providers/cli-provider-metadata'
 import { checkCliProviderReady } from '@/lib/server/cli-provider-readiness'
+import { createProviderDiagnostics, sanitizeProviderDiagnosticText } from '@/lib/server/provider-diagnostics'
 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'
+import type { ProviderCheckResult } from '@/types/provider'
 
 interface SetupCheckBody {
   provider?: string
@@ -33,15 +35,21 @@ async function checkOpenAiCompatible(
   endpointRaw: string,
   defaultEndpoint: string,
   modelHint?: string,
-): Promise<{ ok: boolean; message: string; normalizedEndpoint: string }> {
+): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const normalizedEndpoint = (endpointRaw || defaultEndpoint).replace(/\/+$/, '')
+  diagnostics.pass('Endpoint resolved', { target: normalizedEndpoint })
   const authHeaders = apiKey ? { authorization: `Bearer ${apiKey}` } : undefined
 
   // First, discover a model to test with (prefer the hint, fall back to the first available model)
   let testModel = modelHint || ''
-  if (!testModel) {
+  if (testModel) {
+    diagnostics.pass('Test model selected', { detail: testModel })
+  } else {
+    const modelsTarget = `${normalizedEndpoint}/models`
+    const startedAt = Date.now()
     try {
-      const modelsRes = await fetch(`${normalizedEndpoint}/models`, {
+      const modelsRes = await fetch(modelsTarget, {
         headers: authHeaders,
         signal: AbortSignal.timeout(8_000),
         cache: 'no-store',
@@ -49,10 +57,33 @@ async function checkOpenAiCompatible(
       if (modelsRes.ok) {
         const modelsPayload = await modelsRes.json().catch(() => ({} as Record<string, unknown>))
         const first = Array.isArray(modelsPayload?.data) ? modelsPayload.data[0] : null
-        if (first?.id) testModel = String(first.id)
+        if (first?.id) {
+          testModel = String(first.id)
+          diagnostics.pass('Model discovery completed', {
+            target: modelsTarget,
+            detail: `Using ${testModel}`,
+            durationMs: Date.now() - startedAt,
+          })
+        } else {
+          diagnostics.warn('Model discovery returned no models', {
+            target: modelsTarget,
+            durationMs: Date.now() - startedAt,
+          })
+        }
+      } else {
+        const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(modelsRes, `${providerName} models returned ${modelsRes.status}.`))
+        diagnostics.warn('Model discovery failed', {
+          target: modelsTarget,
+          detail: `HTTP ${modelsRes.status}: ${detail}`,
+          durationMs: Date.now() - startedAt,
+        })
       }
-    } catch {
-      // Model discovery failed — we'll still try the chat endpoint with the provider's default
+    } catch (err: unknown) {
+      diagnostics.warn('Model discovery request failed', {
+        target: modelsTarget,
+        detail: err instanceof Error && err.message ? err.message : 'Unable to query models.',
+        durationMs: Date.now() - startedAt,
+      })
     }
   }
 
@@ -74,55 +105,105 @@ async function checkOpenAiCompatible(
       'LM Studio': 'local-model',
     }
     testModel = fallbacks[providerName] || 'gpt-4o-mini'
+    diagnostics.warn('Fallback test model selected', { detail: testModel })
   }
 
   // Test the chat completions endpoint with a minimal request
-  const res = await fetch(`${normalizedEndpoint}/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'content-type': 'application/json',
-      ...(authHeaders || {}),
-    },
-    body: JSON.stringify({
-      model: testModel,
-      max_completion_tokens: 8,
-      messages: [{ role: 'user', content: 'Reply OK' }],
-    }),
-    signal: AbortSignal.timeout(15_000),
-    cache: 'no-store',
-  })
+  const chatTarget = `${normalizedEndpoint}/chat/completions`
+  const chatStartedAt = Date.now()
+  let res: Response
+  try {
+    res = await fetch(chatTarget, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...(authHeaders || {}),
+      },
+      body: JSON.stringify({
+        model: testModel,
+        max_completion_tokens: 8,
+        messages: [{ role: 'user', content: 'Reply OK' }],
+      }),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Chat endpoint request failed.')
+    diagnostics.fail('Chat completion request failed', {
+      target: chatTarget,
+      detail: message,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), normalizedEndpoint, diagnostics: diagnostics.toJSON() }
+  }
   if (!res.ok) {
-    const detail = await parseErrorMessage(res, `${providerName} returned ${res.status}.`)
-    return { ok: false, message: detail, normalizedEndpoint }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `${providerName} returned ${res.status}.`))
+    diagnostics.fail('Chat completion check failed', {
+      target: chatTarget,
+      detail: `HTTP ${res.status}: ${detail}`,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: detail, normalizedEndpoint, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Chat completion check passed', {
+    target: chatTarget,
+    detail: `Verified with ${testModel}`,
+    durationMs: Date.now() - chatStartedAt,
+  })
   return {
     ok: true,
     message: `Connected to ${providerName}. Chat endpoint verified with ${testModel}.`,
     normalizedEndpoint,
+    diagnostics: diagnostics.toJSON(),
   }
 }
 
-async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: string): Promise<{ ok: boolean; message: string }> {
+async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: string): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const model = modelRaw || 'claude-sonnet-4-6'
   const baseUrl = (endpointRaw || 'https://api.anthropic.com').replace(/\/+$/, '')
-  const res = await fetch(`${baseUrl}/v1/messages`, {
-    method: 'POST',
-    headers: {
-      'x-api-key': apiKey,
-      'anthropic-version': '2023-06-01',
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify({
-      model,
-      max_tokens: 12,
-      messages: [{ role: 'user', content: 'Reply with ANTHROPIC_SETUP_OK' }],
-    }),
-    signal: AbortSignal.timeout(15_000),
-    cache: 'no-store',
-  })
+  diagnostics.pass('Endpoint resolved', { target: baseUrl })
+  diagnostics.pass('Test model selected', { detail: model })
+  const target = `${baseUrl}/v1/messages`
+  const startedAt = Date.now()
+  let res: Response
+  try {
+    res = await fetch(target, {
+      method: 'POST',
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 12,
+        messages: [{ role: 'user', content: 'Reply with ANTHROPIC_SETUP_OK' }],
+      }),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Anthropic request failed.')
+    diagnostics.fail('Message check request failed', {
+      target,
+      detail: message,
+      durationMs: Date.now() - startedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), diagnostics: diagnostics.toJSON() }
+  }
   if (!res.ok) {
-    const detail = await parseErrorMessage(res, `Anthropic returned ${res.status}.`)
-    return { ok: false, message: detail }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `Anthropic returned ${res.status}.`))
+    diagnostics.fail('Message check failed', {
+      target,
+      detail: `HTTP ${res.status}: ${detail}`,
+      durationMs: Date.now() - startedAt,
+    })
+    return { ok: false, message: detail, diagnostics: diagnostics.toJSON() }
   }
   const payload = await res.json().catch(() => ({} as Record<string, unknown>))
   const content = Array.isArray(payload.content) ? payload.content : []
@@ -130,7 +211,12 @@ async function checkAnthropic(apiKey: string, endpointRaw: string, modelRaw: str
   const text = firstContent && typeof firstContent === 'object' && 'text' in firstContent && typeof firstContent.text === 'string'
     ? firstContent.text
     : ''
-  return { ok: true, message: text ? `Connected to Anthropic. Sample: ${text.slice(0, 120)}` : 'Connected to Anthropic.' }
+  diagnostics.pass('Message check passed', {
+    target,
+    detail: text ? `Sample: ${text.slice(0, 80)}` : 'Provider returned a successful response.',
+    durationMs: Date.now() - startedAt,
+  })
+  return { ok: true, message: text ? `Connected to Anthropic. Sample: ${text.slice(0, 120)}` : 'Connected to Anthropic.', diagnostics: diagnostics.toJSON() }
 }
 
 async function checkOllama(params: {
@@ -138,7 +224,8 @@ async function checkOllama(params: {
   modelRaw: string
   ollamaMode?: string
   apiKey?: string
-}): Promise<{ ok: boolean; message: string; normalizedEndpoint: string; recommendedModel?: string }> {
+}): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const runtime = resolveOllamaRuntimeConfig({
     model: params.modelRaw,
     ollamaMode: params.ollamaMode ?? null,
@@ -146,22 +233,32 @@ async function checkOllama(params: {
     apiEndpoint: params.endpointRaw,
   })
   const normalizedEndpoint = normalizeOllamaSetupEndpoint(runtime.endpoint, runtime.useCloud)
+  diagnostics.pass('Endpoint resolved', {
+    target: normalizedEndpoint,
+    detail: runtime.useCloud ? 'Ollama Cloud mode' : 'Local Ollama mode',
+  })
   const headers: Record<string, string> = runtime.apiKey ? { authorization: `Bearer ${runtime.apiKey}` } : {}
   if (runtime.useCloud && !runtime.apiKey) {
+    diagnostics.fail('Credential required', { detail: 'Ollama Cloud requires an API key.' })
     return {
       ok: false,
       message: 'Ollama Cloud model requires an API key. Set OLLAMA_API_KEY or attach an Ollama credential.',
       normalizedEndpoint,
+      diagnostics: diagnostics.toJSON(),
     }
   }
 
   // Discover a model to test with
   let testModel = params.modelRaw || ''
   let recommendedModel: string | undefined
-  if (!testModel) {
+  if (testModel) {
+    diagnostics.pass('Test model selected', { detail: testModel })
+  } else {
+    const tagsPath = runtime.useCloud ? '/v1/models' : '/api/tags'
+    const target = `${normalizedEndpoint}${tagsPath}`
+    const startedAt = Date.now()
     try {
-      const tagsPath = runtime.useCloud ? '/v1/models' : '/api/tags'
-      const res = await fetch(`${normalizedEndpoint}${tagsPath}`, {
+      const res = await fetch(target, {
         headers: headers.authorization ? headers : undefined,
         signal: AbortSignal.timeout(8_000),
         cache: 'no-store',
@@ -177,63 +274,126 @@ async function checkOllama(params: {
         if (firstModel) {
           testModel = firstModel
           recommendedModel = firstModel
+          diagnostics.pass('Model discovery completed', {
+            target,
+            detail: `Using ${firstModel}`,
+            durationMs: Date.now() - startedAt,
+          })
         }
         if (models.length === 0) {
+          diagnostics.warn('Model discovery returned no models', {
+            target,
+            durationMs: Date.now() - startedAt,
+          })
           return {
             ok: true,
             message: runtime.useCloud
               ? 'Connected to Ollama Cloud, but no models were returned.'
               : 'Connected to Ollama, but no models are installed yet. Run `ollama pull <model>` to add one.',
             normalizedEndpoint,
+            diagnostics: diagnostics.toJSON(),
           }
         }
+      } else {
+        const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(res, `Ollama model discovery returned ${res.status}.`))
+        diagnostics.warn('Model discovery failed', {
+          target,
+          detail: `HTTP ${res.status}: ${detail}`,
+          durationMs: Date.now() - startedAt,
+        })
       }
-    } catch {
-      // Model discovery failed — try chat anyway
+    } catch (err: unknown) {
+      diagnostics.warn('Model discovery request failed', {
+        target,
+        detail: err instanceof Error && err.message ? err.message : 'Unable to query models.',
+        durationMs: Date.now() - startedAt,
+      })
     }
   }
 
-  if (!testModel) testModel = 'llama3.2'
+  if (!testModel) {
+    testModel = 'llama3.2'
+    diagnostics.warn('Fallback test model selected', { detail: testModel })
+  }
 
   // Test the chat endpoint
   const label = runtime.useCloud ? 'Ollama Cloud' : 'Ollama'
   const chatEndpoint = `${normalizedEndpoint}/v1/chat/completions`
   const chatBody = JSON.stringify({ model: testModel, max_completion_tokens: 8, messages: [{ role: 'user', content: 'Reply OK' }] })
 
-  const chatRes = await fetch(chatEndpoint, {
-    method: 'POST',
-    headers: { ...headers, 'content-type': 'application/json' },
-    body: chatBody,
-    signal: AbortSignal.timeout(30_000),
-    cache: 'no-store',
-  })
+  const chatStartedAt = Date.now()
+  let chatRes: Response
+  try {
+    chatRes = await fetch(chatEndpoint, {
+      method: 'POST',
+      headers: { ...headers, 'content-type': 'application/json' },
+      body: chatBody,
+      signal: AbortSignal.timeout(30_000),
+      cache: 'no-store',
+    })
+  } catch (err: unknown) {
+    const message = err instanceof Error && err.name === 'TimeoutError'
+      ? 'Connection check timed out. Verify endpoint/network and try again.'
+      : (err instanceof Error && err.message ? err.message : 'Ollama chat request failed.')
+    diagnostics.fail('Chat completion request failed', {
+      target: chatEndpoint,
+      detail: message,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(message), normalizedEndpoint, recommendedModel, diagnostics: diagnostics.toJSON() }
+  }
   if (!chatRes.ok) {
-    const detail = await parseErrorMessage(chatRes, `${label} chat returned ${chatRes.status}.`)
-    return { ok: false, message: detail, normalizedEndpoint, recommendedModel }
+    const detail = sanitizeProviderDiagnosticText(await parseErrorMessage(chatRes, `${label} chat returned ${chatRes.status}.`))
+    diagnostics.fail('Chat completion check failed', {
+      target: chatEndpoint,
+      detail: `HTTP ${chatRes.status}: ${detail}`,
+      durationMs: Date.now() - chatStartedAt,
+    })
+    return { ok: false, message: detail, normalizedEndpoint, recommendedModel, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Chat completion check passed', {
+    target: chatEndpoint,
+    detail: `Verified with ${testModel}`,
+    durationMs: Date.now() - chatStartedAt,
+  })
   return {
     ok: true,
     message: `Connected to ${label}. Chat verified with ${testModel}.`,
     normalizedEndpoint,
     recommendedModel: recommendedModel || testModel,
+    diagnostics: diagnostics.toJSON(),
   }
 }
 
-async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok: boolean; message: string; normalizedEndpoint: string; deviceId?: string; errorCode?: string; recommendedModel?: string }> {
+async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<ProviderCheckResult> {
+  const diagnostics = createProviderDiagnostics()
   const { httpUrl: normalizedEndpoint, wsUrl } = normalizeOpenClawUrl(endpointRaw)
   const token = apiKey || undefined
   const deviceId = getDeviceId()
+  diagnostics.pass('Endpoint resolved', { target: normalizedEndpoint })
 
+  const wsStartedAt = Date.now()
   const result = await wsConnect(wsUrl, token, true, 10_000)
 
   if (!result.ok) {
     if (result.ws) try { result.ws.close() } catch {}
-    return { ok: false, message: result.message, normalizedEndpoint, deviceId, errorCode: result.errorCode }
+    diagnostics.fail('Gateway websocket check failed', {
+      target: wsUrl,
+      detail: result.message,
+      durationMs: Date.now() - wsStartedAt,
+    })
+    return { ok: false, message: sanitizeProviderDiagnosticText(result.message), normalizedEndpoint, deviceId, errorCode: result.errorCode, diagnostics: diagnostics.toJSON() }
   }
+  diagnostics.pass('Gateway websocket check passed', {
+    target: wsUrl,
+    detail: deviceId ? `Device ${deviceId}` : undefined,
+    durationMs: Date.now() - wsStartedAt,
+  })
 
   // Attempt model discovery via RPC before closing the connection
   let recommendedModel: string | undefined
   if (result.ws) {
+    const modelStartedAt = Date.now()
     try {
       const payload = await rpcOnConnectedGateway(result.ws, 'models.list', {}, 8_000) as Record<string, unknown> | unknown[] | undefined
       const p = payload as Record<string, unknown> | undefined
@@ -246,13 +406,20 @@ async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok:
       } else if (typeof first?.name === 'string') {
         recommendedModel = first.name
       }
-    } catch {
-      // Model discovery is non-fatal — connection still counts as successful
+      diagnostics.pass('Gateway model discovery completed', {
+        detail: recommendedModel ? `Using ${recommendedModel}` : 'No model recommendation returned.',
+        durationMs: Date.now() - modelStartedAt,
+      })
+    } catch (err: unknown) {
+      diagnostics.warn('Gateway model discovery failed', {
+        detail: err instanceof Error && err.message ? err.message : 'Model discovery is unavailable.',
+        durationMs: Date.now() - modelStartedAt,
+      })
     }
     try { result.ws.close() } catch {}
   }
 
-  return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId, recommendedModel }
+  return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId, recommendedModel, diagnostics: diagnostics.toJSON() }
 }
 
 export async function POST(req: Request) {
@@ -302,7 +469,12 @@ export async function POST(req: Request) {
 
   if (isCliProviderId(provider)) {
     const result = checkCliProviderReady(provider)
-    return NextResponse.json(result)
+    const diagnostics = createProviderDiagnostics()
+    diagnostics.add('CLI readiness check', result.ok ? 'pass' : 'fail', {
+      detail: result.message,
+      target: result.binaryPath || result.binaryName || provider,
+    })
+    return NextResponse.json({ ...result, diagnostics: diagnostics.toJSON() })
   }
 
   if (!provider) {

package/src/components/agents/agent-sheet.tsx

@@ -10,7 +10,7 @@ import { sleep } from '@/lib/shared-utils'
 import { BottomSheet } from '@/components/shared/bottom-sheet'
 import { toast } from 'sonner'
 import { ModelCombobox } from '@/components/shared/model-combobox'
-import type { ProviderType, ClaudeSkill, AgentPackManifest, AgentRoutingStrategy, AgentRoutingTarget } from '@/types'
+import type { ProviderType, ProviderDiagnosticStep, ClaudeSkill, AgentPackManifest, AgentRoutingStrategy, AgentRoutingTarget } from '@/types'
 import { AVAILABLE_TOOLS, PLATFORM_TOOLS } from '@/lib/tool-definitions'
 import { MCP_INJECTION_PROVIDER_IDS, NATIVE_CAPABILITY_PROVIDER_IDS, NON_LANGGRAPH_PROVIDER_IDS, WORKER_ONLY_PROVIDER_IDS } from '@/lib/provider-sets'
 import { isOrchestratorProviderEligible } from '@/lib/orchestrator-config'
@@ -33,6 +33,7 @@ import { buildAgentSelectableProviders, resolveAgentSelectableProviderCredential
 import { AgentSocialSettings } from '@/features/swarmfeed/agent-social-settings'
 import { AgentMarketplaceSettings } from '@/features/swarmdock/agent-marketplace-settings'
 import type { ConfigVersion } from '@/types/config-version'
+import { ProviderDiagnosticsList } from '@/components/providers/provider-diagnostics-list'
 
 const HB_PRESETS = [1800, 3600, 7200, 21600, 43200] as const
 const FALLBACK_ELEVENLABS_VOICE_ID = 'JBFqnCBsd6RMkjVDRZzb'
@@ -284,6 +285,7 @@ export function AgentSheet() {
   const [testStatus, setTestStatus] = useState<'idle' | 'testing' | 'pass' | 'fail'>('idle')
   const [testMessage, setTestMessage] = useState('')
   const [testErrorCode, setTestErrorCode] = useState<string | null>(null)
+  const [testDiagnostics, setTestDiagnostics] = useState<ProviderDiagnosticStep[]>([])
   const [testDeviceId, setTestDeviceId] = useState<string | null>(null)
   const [openclawDeviceId, setOpenclawDeviceId] = useState<string | null>(null)
   const [configCopied, setConfigCopied] = useState(false)
@@ -426,6 +428,7 @@ export function AgentSheet() {
         .catch(() => {})
       setTestStatus('idle')
       setTestMessage('')
+      setTestDiagnostics([])
       setShowAdvancedSettings(false)
       if (editing) {
         setName(editing.name)
@@ -690,6 +693,7 @@ export function AgentSheet() {
   useEffect(() => {
     setTestStatus('idle')
     setTestMessage('')
+    setTestDiagnostics([])
   }, [provider, credentialId, apiEndpoint])
 
   // Fetch MCP tools when selected servers change
@@ -758,6 +762,7 @@ export function AgentSheet() {
     setTestStatus('idle')
     setTestMessage('')
     setTestErrorCode(null)
+    setTestDiagnostics([])
     setAddingKey(false)
     setNewKeyName('')
     setNewKeyValue('')
@@ -1047,8 +1052,9 @@ export function AgentSheet() {
     setTestStatus('testing')
     setTestMessage('')
     setTestErrorCode(null)
+    setTestDiagnostics([])
     try {
-      const result = await api<{ ok: boolean; message: string; errorCode?: string; deviceId?: string }>('POST', '/setup/check-provider', {
+      const result = await api<{ ok: boolean; message: string; errorCode?: string; deviceId?: string; diagnostics?: ProviderDiagnosticStep[] }>('POST', '/setup/check-provider', {
         provider,
         credentialId,
         endpoint: apiEndpoint,
@@ -1057,6 +1063,7 @@ export function AgentSheet() {
       }, {
         timeoutMs: CONNECTION_TEST_TIMEOUT_MS,
       })
+      setTestDiagnostics(result.diagnostics ?? [])
       if (result.deviceId) setTestDeviceId(result.deviceId)
       if (result.ok) {
         let syncedModels: string[] = []
@@ -1084,6 +1091,7 @@ export function AgentSheet() {
       const msg = err instanceof Error ? err.message : 'Connection test failed'
       setTestStatus('fail')
       setTestMessage(msg)
+      setTestDiagnostics([])
       toast.error(msg)
       return false
     }
@@ -1317,6 +1325,10 @@ export function AgentSheet() {
             <button
               type="button"
               onClick={() => {
+                setTestStatus('idle')
+                setTestMessage('')
+                setTestErrorCode(null)
+                setTestDiagnostics([])
                 if (!openclawEnabled) {
                   setOpenclawEnabled(true)
                   setProvider('openclaw')
@@ -1330,9 +1342,6 @@ export function AgentSheet() {
                   setApiEndpoint(null)
                   setCredentialId(null)
                   setGatewayProfileId(null)
-                  setTestStatus('idle')
-                  setTestMessage('')
-                  setTestErrorCode(null)
                 }
               }}
               className={`relative h-6 w-11 rounded-full border-none transition-colors duration-200 ${openclawEnabled ? 'bg-accent-bright' : 'bg-white/[0.12]'}`}
@@ -1473,6 +1482,7 @@ export function AgentSheet() {
                 <p className="text-[14px] text-emerald-400 font-600">Connected</p>
               </div>
               <p className="text-[13px] text-text-2/80 leading-[1.6]">Gateway is reachable and this device is paired. Tools and models are managed by the OpenClaw instance.</p>
+              <ProviderDiagnosticsList diagnostics={testDiagnostics} />
             </div>
           )}
           {testStatus === 'fail' && (
@@ -1548,6 +1558,7 @@ export function AgentSheet() {
                   </p>
                 </div>
               )}
+              <ProviderDiagnosticsList diagnostics={testDiagnostics} />
             </div>
           )}
         </div>
@@ -2965,11 +2976,13 @@ export function AgentSheet() {
       {!openclawEnabled && testStatus === 'fail' && (
         <div className="mb-4 p-3 rounded-[12px] bg-red-500/[0.08] border border-red-500/20">
           <p className="text-[13px] text-red-400">{testMessage || 'Connection test failed'}</p>
+          <ProviderDiagnosticsList diagnostics={testDiagnostics} />
         </div>
       )}
       {!openclawEnabled && testStatus === 'pass' && (
         <div className="mb-4 p-3 rounded-[12px] bg-emerald-500/[0.08] border border-emerald-500/20">
           <p className="text-[13px] text-emerald-400">{testMessage || 'Connected successfully'}</p>
+          <ProviderDiagnosticsList diagnostics={testDiagnostics} />
         </div>
       )}
 

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

@@ -5,7 +5,8 @@ import { api } from '@/lib/app/api-client'
 import { dedup, errorMessage } from '@/lib/shared-utils'
 import { getDefaultModelForProvider } from '@/lib/setup-defaults'
 import { OpenClawDeployPanel } from '@/components/openclaw/openclaw-deploy-panel'
-import type { Credential, Credentials, GatewayProfile, ProviderId, ProviderConfig } from '@/types'
+import { ProviderDiagnosticsList } from '@/components/providers/provider-diagnostics-list'
+import type { Credential, Credentials, GatewayProfile, ProviderDiagnosticStep, ProviderId, ProviderConfig } from '@/types'
 import type { StepConnectProps, CheckState, ProviderCheckResponse, ConfiguredProvider } from './types'
 import {
   formatEndpointHost,
@@ -34,6 +35,7 @@ export function StepConnect({
   const [checkState, setCheckState] = useState<CheckState>(editingProvider?.verified ? 'ok' : 'idle')
   const [checkMessage, setCheckMessage] = useState('')
   const [checkErrorCode, setCheckErrorCode] = useState<string | null>(null)
+  const [checkDiagnostics, setCheckDiagnostics] = useState<ProviderDiagnosticStep[]>([])
   const [openclawDeviceId, setOpenclawDeviceId] = useState<string | null>(null)
   const [providerSuggestedModel, setProviderSuggestedModel] = useState(
     editingProvider?.defaultModel || (provider === 'custom' ? '' : getDefaultModelForProvider(provider)),
@@ -111,6 +113,7 @@ export function StepConnect({
     setCheckState('idle')
     setCheckMessage('')
     setCheckErrorCode(null)
+    setCheckDiagnostics([])
     setError('')
   }
 
@@ -118,12 +121,14 @@ export function StepConnect({
     if (requiresKey && !hasKeyOrCredential) {
       setCheckState('error')
       setCheckMessage('Please paste your API key or select a saved key first.')
+      setCheckDiagnostics([])
       return false
     }
 
     setCheckState('checking')
     setCheckMessage('')
     setCheckErrorCode(null)
+    setCheckDiagnostics([])
     setError('')
     try {
       const result = await api<ProviderCheckResponse>('POST', '/setup/check-provider', {
@@ -140,6 +145,7 @@ export function StepConnect({
         setProviderSuggestedModel(result.recommendedModel)
       }
       setCheckErrorCode(result.errorCode || null)
+      setCheckDiagnostics(result.diagnostics ?? [])
       setOpenclawDeviceId(result.deviceId || null)
       setCheckState(result.ok ? 'ok' : 'error')
       setCheckMessage(result.message || (result.ok ? 'Connected successfully.' : 'Connection failed.'))
@@ -148,6 +154,7 @@ export function StepConnect({
       setCheckState('error')
       setCheckMessage(errorMessage(err))
       setCheckErrorCode(null)
+      setCheckDiagnostics([])
       return false
     }
   }
@@ -280,7 +287,7 @@ export function StepConnect({
             <input
               type="text"
               value={endpoint}
-              onChange={(e) => { setEndpoint(e.target.value); setCheckState('idle'); setCheckMessage('') }}
+              onChange={(e) => { setEndpoint(e.target.value); setCheckState('idle'); setCheckMessage(''); setCheckDiagnostics([]) }}
               placeholder={selectedProvider.defaultEndpoint || ''}
               className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-surface
                 text-text text-[14px] font-mono outline-none transition-all duration-200
@@ -295,6 +302,7 @@ export function StepConnect({
                     setEndpoint(isCloud ? (selectedProvider.defaultEndpoint || '') : selectedProvider.cloudEndpoint!)
                     setCheckState('idle')
                     setCheckMessage('')
+                    setCheckDiagnostics([])
                   }}
                   className="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-[10px] border text-[12px] font-500 cursor-pointer transition-all duration-200 bg-transparent
                     border-white/[0.08] text-text-2 hover:bg-white/[0.04]"
@@ -440,6 +448,7 @@ export function StepConnect({
                       setApiKey('')
                       setCheckState('idle')
                       setCheckMessage('')
+                      setCheckDiagnostics([])
                     }
                   }}
                   className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-surface
@@ -466,7 +475,7 @@ export function StepConnect({
                 <input
                   type="password"
                   value={apiKey}
-                  onChange={(e) => { setApiKey(e.target.value); setCredentialId(null); setCheckState('idle'); setCheckMessage(''); setError('') }}
+                  onChange={(e) => { setApiKey(e.target.value); setCredentialId(null); setCheckState('idle'); setCheckMessage(''); setCheckDiagnostics([]); setError('') }}
                   placeholder={selectedProvider.keyPlaceholder || (provider === 'openclaw' ? 'Paste OpenClaw bearer token' : 'sk-...')}
                   className="w-full px-4 py-3 rounded-[12px] border border-white/[0.08] bg-surface
                     text-text text-[14px] font-mono outline-none transition-all duration-200
@@ -530,6 +539,7 @@ export function StepConnect({
               Device paired as <code className="text-text-2">{openclawDeviceId.slice(0, 12)}...</code>.
             </p>
           )}
+          <ProviderDiagnosticsList diagnostics={checkDiagnostics} />
         </div>
       )}
 

package/src/components/auth/setup-wizard/types.ts

@@ -1,17 +1,10 @@
-import type { GatewayProfile, ProviderId } from '@/types'
+import type { GatewayProfile, ProviderCheckResult, ProviderId } from '@/types'
 import type { SetupProvider } from '@/lib/setup-defaults'
 
 export type SetupStep = 'profile' | 'path' | 'providers' | 'connect' | 'agents' | 'next' | 'done'
 export type CheckState = 'idle' | 'checking' | 'ok' | 'error'
 
-export interface ProviderCheckResponse {
-  ok: boolean
-  message: string
-  normalizedEndpoint?: string
-  recommendedModel?: string
-  errorCode?: string
-  deviceId?: string
-}
+export type ProviderCheckResponse = ProviderCheckResult
 
 export interface SetupDoctorCheck {
   id: string

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

@@ -0,0 +1,58 @@
+'use client'
+
+import type { ProviderDiagnosticStep } from '@/types'
+
+const STATUS_CLASSES: Record<ProviderDiagnosticStep['status'], string> = {
+  pass: 'border-emerald-500/25 bg-emerald-500/10 text-emerald-300',
+  warn: 'border-amber-500/25 bg-amber-500/10 text-amber-300',
+  fail: 'border-red-500/25 bg-red-500/10 text-red-300',
+}
+
+const STATUS_LABELS: Record<ProviderDiagnosticStep['status'], string> = {
+  pass: 'Pass',
+  warn: 'Warn',
+  fail: 'Fail',
+}
+
+export function ProviderDiagnosticsList({
+  diagnostics,
+  className = '',
+}: {
+  diagnostics?: ProviderDiagnosticStep[] | null
+  className?: string
+}) {
+  if (!diagnostics?.length) return null
+
+  return (
+    <div className={`mt-3 border-t border-white/[0.06] pt-3 ${className}`}>
+      <div className="mb-2 text-[11px] font-700 uppercase tracking-[0.1em] text-text-3/70">
+        Diagnostics
+      </div>
+      <ol className="space-y-2">
+        {diagnostics.map((step) => (
+          <li key={step.id} className="grid gap-1 text-left sm:grid-cols-[64px_minmax(0,1fr)] sm:gap-3">
+            <div>
+              <span className={`inline-flex min-w-[54px] items-center justify-center rounded-[999px] border px-2 py-0.5 text-[10px] font-700 uppercase tracking-[0.08em] ${STATUS_CLASSES[step.status]}`}>
+                {STATUS_LABELS[step.status]}
+              </span>
+            </div>
+            <div className="min-w-0">
+              <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+                <span className="text-[12px] font-650 text-text-2">{step.label}</span>
+                {typeof step.durationMs === 'number' && (
+                  <span className="text-[11px] text-text-3">{step.durationMs} ms</span>
+                )}
+              </div>
+              {step.target && (
+                <div className="mt-0.5 break-all font-mono text-[11px] text-text-3">{step.target}</div>
+              )}
+              {step.detail && (
+                <div className="mt-0.5 text-[11px] leading-relaxed text-text-3">{step.detail}</div>
+              )}
+            </div>
+          </li>
+        ))}
+      </ol>
+    </div>
+  )
+}

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

@@ -4,6 +4,7 @@ import { useEffect, useMemo, useState } from 'react'
 import { useAppStore } from '@/stores/use-app-store'
 import { BottomSheet } from '@/components/shared/bottom-sheet'
 import { ConfirmDialog } from '@/components/shared/confirm-dialog'
+import { ProviderDiagnosticsList } from '@/components/providers/provider-diagnostics-list'
 import { toast } from 'sonner'
 import { errorMessage } from '@/lib/shared-utils'
 import {
@@ -17,6 +18,7 @@ import {
   useSaveCustomProviderMutation,
 } from '@/features/providers/queries'
 import { useCreateCredentialMutation, useCredentialsQuery } from '@/features/credentials/queries'
+import type { ProviderDiagnosticStep } from '@/types'
 
 export function ProviderSheet() {
   const open = useAppStore((s) => s.providerSheetOpen)
@@ -54,6 +56,7 @@ export function ProviderSheet() {
   const [testStatus, setTestStatus] = useState<'idle' | 'testing' | 'pass' | 'fail'>('idle')
   const [testMessage, setTestMessage] = useState('')
   const [testModel, setTestModel] = useState('')
+  const [testDiagnostics, setTestDiagnostics] = useState<ProviderDiagnosticStep[]>([])
 
   const [liveModels, setLiveModels] = useState<string[]>([])
   const [liveLoading, setLiveLoading] = useState(false)
@@ -77,6 +80,7 @@ export function ProviderSheet() {
       setLiveCached(false)
       setTestStatus('idle')
       setTestMessage('')
+      setTestDiagnostics([])
       if (editingCustom) {
         setName(editingCustom.name)
         setBaseUrl(editingCustom.baseUrl || '')
@@ -108,6 +112,7 @@ export function ProviderSheet() {
   useEffect(() => {
     setTestStatus('idle')
     setTestMessage('')
+    setTestDiagnostics([])
   }, [credentialId, baseUrl])
 
   useEffect(() => {
@@ -121,6 +126,7 @@ export function ProviderSheet() {
     if (!isBuiltin) return
     setTestStatus('testing')
     setTestMessage('')
+    setTestDiagnostics([])
     try {
       const result = await checkProviderConnectionMutation.mutateAsync({
         provider: editingId || 'custom',
@@ -128,6 +134,7 @@ export function ProviderSheet() {
         endpoint: baseUrl,
         model: testModel || undefined,
       })
+      setTestDiagnostics(result.diagnostics ?? [])
       if (result.ok) {
         setTestStatus('pass')
         setTestMessage(result.message)
@@ -141,6 +148,7 @@ export function ProviderSheet() {
       const msg = err instanceof Error ? err.message : 'Connection test failed'
       setTestStatus('fail')
       setTestMessage(msg)
+      setTestDiagnostics([])
       toast.error(msg)
     }
   }
@@ -530,7 +538,7 @@ export function ProviderSheet() {
           </label>
           <select
             value={testModel}
-            onChange={(e) => { setTestModel(e.target.value); setTestStatus('idle'); setTestMessage('') }}
+            onChange={(e) => { setTestModel(e.target.value); setTestStatus('idle'); setTestMessage(''); setTestDiagnostics([]) }}
             className={`${inputClass} appearance-none cursor-pointer`}
             style={{ fontFamily: 'inherit' }}
           >
@@ -546,11 +554,13 @@ export function ProviderSheet() {
       {isBuiltin && testStatus === 'fail' && (
         <div className="mb-4 p-3 rounded-[12px] bg-red-500/[0.08] border border-red-500/20">
           <p className="text-[13px] text-red-400">{testMessage || 'Connection test failed'}</p>
+          <ProviderDiagnosticsList diagnostics={testDiagnostics} />
         </div>
       )}
       {isBuiltin && testStatus === 'pass' && (
         <div className="mb-4 p-3 rounded-[12px] bg-emerald-500/[0.08] border border-emerald-500/20">
           <p className="text-[13px] text-emerald-400">{testMessage || 'Connected successfully'}</p>
+          <ProviderDiagnosticsList diagnostics={testDiagnostics} />
         </div>
       )}
 

package/src/features/providers/queries.ts

@@ -13,6 +13,7 @@ import {
 import { fetchProviders } from '@/lib/chat/chats'
 import type {
   ProviderConfig,
+  ProviderCheckResult,
   ProviderInfo,
   ProviderModelDiscoveryResult,
 } from '@/types'
@@ -129,7 +130,7 @@ export function useResetProviderModelsMutation() {
 export function useCheckProviderConnectionMutation() {
   return useMutation({
     mutationFn: ({ provider, credentialId, endpoint, model }: CheckProviderConnectionInput) =>
-      api<{ ok: boolean; message: string }>('POST', '/setup/check-provider', {
+      api<ProviderCheckResult>('POST', '/setup/check-provider', {
         provider,
         credentialId,
         endpoint,

package/src/lib/server/provider-diagnostics.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+
+import {
+  createProviderDiagnostics,
+  sanitizeProviderDiagnosticTarget,
+  sanitizeProviderDiagnosticText,
+} from './provider-diagnostics'
+
+test('provider diagnostics records sanitized ordered steps', () => {
+  const diagnostics = createProviderDiagnostics()
+  diagnostics.pass('Endpoint resolved', { target: 'http://user:pass@127.0.0.1:1234/v1/models?token=sk-secret' })
+  diagnostics.fail('Chat failed', { detail: 'Malformed token sk-abc123456789 provided', durationMs: 12.4 })
+
+  const steps = diagnostics.toJSON()
+  assert.equal(steps.length, 2)
+  assert.deepEqual(
+    steps.map((step) => step.id),
+    ['diag-1', 'diag-2'],
+  )
+  assert.equal(steps[0].status, 'pass')
+  assert.equal(steps[0].target, 'http://127.0.0.1:1234/v1/models')
+  assert.equal(steps[1].detail, 'Malformed token sk-... provided')
+  assert.equal(steps[1].durationMs, 12)
+})
+
+test('sanitizeProviderDiagnosticText redacts common provider token prefixes', () => {
+  assert.equal(
+    sanitizeProviderDiagnosticText('bad keys: sk-test123 gsk_live456 hf_token789 AIzaSySecret'),
+    'bad keys: sk-... gsk_... hf_... AIza...',
+  )
+})
+
+test('sanitizeProviderDiagnosticTarget removes credentials, query, and hash from URLs', () => {
+  assert.equal(
+    sanitizeProviderDiagnosticTarget('https://user:secret@example.com/v1/models?api_key=sk-secret#frag'),
+    'https://example.com/v1/models',
+  )
+})

package/src/lib/server/provider-diagnostics.ts

@@ -0,0 +1,114 @@
+import type { ProviderDiagnosticStatus, ProviderDiagnosticStep } from '@/types/provider'
+
+const SECRET_PREFIXES = [
+  'sk-',
+  'sk_',
+  'gsk_',
+  'hf_',
+  'xai-',
+  'or-',
+  'pat_',
+  'ghp_',
+  'gho_',
+  'AIza',
+]
+
+const MAX_DETAIL_LENGTH = 300
+const MAX_TARGET_LENGTH = 220
+
+function isSecretBoundary(char: string | undefined): boolean {
+  if (!char) return true
+  return char === ' ' || char === '\n' || char === '\r' || char === '\t'
+    || char === '"' || char === "'" || char === '`'
+    || char === ',' || char === ';' || char === ')' || char === ']'
+    || char === '}' || char === '<' || char === '>'
+}
+
+export function sanitizeProviderDiagnosticText(value: unknown, maxLength = MAX_DETAIL_LENGTH): string {
+  const input = typeof value === 'string' ? value : String(value ?? '')
+  let out = ''
+  for (let i = 0; i < input.length;) {
+    const prefix = SECRET_PREFIXES.find((candidate) => input.startsWith(candidate, i))
+    if (!prefix) {
+      out += input[i]
+      i++
+      continue
+    }
+
+    let end = i + prefix.length
+    while (end < input.length && !isSecretBoundary(input[end]) && end - i < 160) end++
+    out += `${prefix}...`
+    i = end
+  }
+  const collapsed = out.split(/\s+/).join(' ').trim()
+  return collapsed.length > maxLength ? `${collapsed.slice(0, Math.max(0, maxLength - 1))}...` : collapsed
+}
+
+export function sanitizeProviderDiagnosticTarget(value: unknown): string {
+  const raw = sanitizeProviderDiagnosticText(value, MAX_TARGET_LENGTH)
+  try {
+    const url = new URL(raw)
+    url.username = ''
+    url.password = ''
+    url.search = ''
+    url.hash = ''
+    return sanitizeProviderDiagnosticText(url.toString(), MAX_TARGET_LENGTH)
+  } catch {
+    return raw
+  }
+}
+
+export interface ProviderDiagnostics {
+  add: (
+    label: string,
+    status: ProviderDiagnosticStatus,
+    options?: {
+      detail?: unknown
+      target?: unknown
+      durationMs?: number
+    },
+  ) => ProviderDiagnosticStep
+  pass: (label: string, options?: { detail?: unknown; target?: unknown; durationMs?: number }) => ProviderDiagnosticStep
+  warn: (label: string, options?: { detail?: unknown; target?: unknown; durationMs?: number }) => ProviderDiagnosticStep
+  fail: (label: string, options?: { detail?: unknown; target?: unknown; durationMs?: number }) => ProviderDiagnosticStep
+  toJSON: () => ProviderDiagnosticStep[]
+}
+
+export function createProviderDiagnostics(): ProviderDiagnostics {
+  const steps: ProviderDiagnosticStep[] = []
+  let sequence = 0
+
+  function add(
+    label: string,
+    status: ProviderDiagnosticStatus,
+    options: {
+      detail?: unknown
+      target?: unknown
+      durationMs?: number
+    } = {},
+  ): ProviderDiagnosticStep {
+    sequence++
+    const step: ProviderDiagnosticStep = {
+      id: `diag-${sequence}`,
+      label: sanitizeProviderDiagnosticText(label, 80),
+      status,
+    }
+    const detail = sanitizeProviderDiagnosticText(options.detail, MAX_DETAIL_LENGTH)
+    const target = sanitizeProviderDiagnosticTarget(options.target)
+    if (detail) step.detail = detail
+    if (target) step.target = target
+    if (typeof options.durationMs === 'number' && Number.isFinite(options.durationMs)) {
+      step.durationMs = Math.max(0, Math.round(options.durationMs))
+    }
+    steps.push(step)
+    return step
+  }
+
+  return {
+    add,
+    pass: (label, options) => add(label, 'pass', options),
+    warn: (label, options) => add(label, 'warn', options),
+    fail: (label, options) => add(label, 'fail', options),
+    toJSON: () => steps.map((step) => ({ ...step })),
+  }
+}

package/src/types/provider.ts

@@ -28,6 +28,27 @@ export interface ProviderModelDiscoveryResult {
   message?: string
 }
 
+export type ProviderDiagnosticStatus = 'pass' | 'warn' | 'fail'
+
+export interface ProviderDiagnosticStep {
+  id: string
+  label: string
+  status: ProviderDiagnosticStatus
+  detail?: string
+  target?: string
+  durationMs?: number
+}
+
+export interface ProviderCheckResult {
+  ok: boolean
+  message: string
+  normalizedEndpoint?: string
+  recommendedModel?: string
+  errorCode?: string
+  deviceId?: string
+  diagnostics?: ProviderDiagnosticStep[]
+}
+
 export interface Credential {
   id: string
   provider: string