fix(desktop): collect + persist API key for custom OpenAI endpoints (#43896)

The desktop "Local / custom endpoint" onboarding never collected an API key and /api/model/set silently dropped one, so an auth-gated endpoint (e.g. a hosted vLLM behind a key) could never enumerate models — and Settings' "Set up custom endpoint" routed `custom` into a non-existent OAuth flow, booting the user back to the first screen (the reported loop). Backend (web_server.py): - /api/providers/validate accepts an optional api_key and sends it as a Bearer header when probing a custom endpoint's /v1/models. - /api/model/set accepts api_key, persists it to model.api_key (same switch/preserve lifecycle as base_url), and registers a named custom_providers entry via _save_custom_provider — matching the `hermes model` CLI flow so the endpoint shows up as a ready picker row. Desktop: - ApiKeyForm shows an optional API key field for the local/custom option; the key is threaded through saveOnboardingLocalEndpoint → validate + setModelAssignment. - New onboarding `localEndpoint` intent + startManualLocalEndpoint(); the Settings "Set up custom endpoint" button now opens the local-endpoint form (URL + key) instead of the OAuth dead-end. - Added localApiKeyPlaceholder i18n key (en + types + zh). Tests: api_key lifecycle on _apply_main_model_assignment, key persistence + custom_providers registration on /api/model/set, Bearer-header probe; onboarding store forwards + persists the key.
2026-06-12 00:03:55 +00:00
parent c6007e5c1a
commit 4ddb03390a
13 changed files with 363 additions and 37 deletions
@@ -15,7 +15,7 @@ import type { AuxiliaryModelsResponse, ModelOptionProvider, StaleAuxAssignment }
 import { useI18n } from '@/i18n'
 import { AlertTriangle, Cpu, Loader2 } from '@/lib/icons'
 import { cn } from '@/lib/utils'
-import { startManualProviderOAuth } from '@/store/onboarding'
+import { startManualLocalEndpoint, startManualProviderOAuth } from '@/store/onboarding'

 import { CONTROL_TEXT } from './constants'
 import { ListRow, LoadingState, Pill, SectionHeading } from './primitives'
@@ -224,10 +224,23 @@ export function ModelSettings({ onMainModelChanged }: ModelSettingsProps) {
  }, [apiKeyDraft, selectedProviderRow])

  // OAuth / external providers can't be activated with a pasted key — hand off
-  // to the shared onboarding flow scoped to this provider's real sign-in.
+  // to the shared onboarding flow scoped to this provider's real sign-in. The
+  // custom / local endpoint is NOT an OAuth provider, so it gets the dedicated
+  // local-endpoint form (URL + optional API key) instead of being dead-ended
+  // on the OAuth picker (the original "booted back to the first screen" loop).
  const startProviderSetup = useCallback(() => {
-    if (selectedProviderRow?.slug) {
-      startManualProviderOAuth(selectedProviderRow.slug)
+    const slug = selectedProviderRow?.slug
+
+    if (!slug) {
+      return
+    }
+
+    const lower = slug.toLowerCase()
+
+    if (lower === 'custom' || lower === 'local' || lower.startsWith('custom:')) {
+      startManualLocalEndpoint()
+    } else {
+      startManualProviderOAuth(slug)
    }
  }, [selectedProviderRow])

@@ -26,7 +26,8 @@ function setProviders(providers: OAuthProvider[]) {
    reason: null,
    requested: false,
    firstRunSkipped: false,
-    manual: false
+    manual: false,
+    localEndpoint: false
  } satisfies DesktopOnboardingState)
 }

@@ -49,7 +50,8 @@ afterEach(() => {
    reason: null,
    requested: false,
    firstRunSkipped: false,
-    manual: false
+    manual: false,
+    localEndpoint: false
  })
 })

@@ -430,19 +430,24 @@ const persistShowAll = (value: boolean) => {

 export function Picker({ ctx }: { ctx: OnboardingContext }) {
  const { t } = useI18n()
-  const { manual, mode, providers } = useStore($desktopOnboarding)
+  const { localEndpoint, manual, mode, providers } = useStore($desktopOnboarding)
  const [showAll, setShowAll] = useState(readShowAll)
  const ordered = useMemo(() => (providers ? sortProviders(providers) : []), [providers])
  const hasOauth = ordered.length > 0
  const apiKeyOptions = useApiKeyCatalog()

-  if (mode === 'apikey' || !hasOauth) {
+  // localEndpoint forces the key form regardless of `mode` (which a manual
+  // provider refresh may flip back to 'oauth'); it preselects the local option
+  // and hides the "back to sign in" link since the user came specifically to
+  // configure a custom endpoint.
+  if (localEndpoint || mode === 'apikey' || !hasOauth) {
    return (
      <div className="grid gap-3">
        <ApiKeyForm
-          canGoBack={hasOauth}
+          canGoBack={hasOauth && !localEndpoint}
+          initialEnvKey={localEndpoint ? 'OPENAI_BASE_URL' : undefined}
          onBack={() => setOnboardingMode('oauth')}
-          onSave={(envKey, value, name) => saveOnboardingApiKey(envKey, value, name, ctx)}
+          onSave={(envKey, value, name, apiKey) => saveOnboardingApiKey(envKey, value, name, ctx, apiKey)}
          options={apiKeyOptions}
        />
        {manual ? null : (
@@ -630,6 +635,7 @@ export function ProviderRow({
 // surfaces render the identical form.
 export function ApiKeyForm({
  canGoBack,
+  initialEnvKey,
  isSet,
  onBack,
  onClear,
@@ -638,16 +644,31 @@ export function ApiKeyForm({
  redactedValue
 }: {
  canGoBack: boolean
+  /** Preselect a specific option by env key (e.g. 'OPENAI_BASE_URL' to land on
+   *  the local / custom endpoint form). Falls back to the first option. */
+  initialEnvKey?: string
  isSet?: (envKey: string) => boolean
  onBack: () => void
  onClear?: (envKey: string) => void
-  onSave: (envKey: string, value: string, name: string) => Promise<{ message?: string; ok: boolean }>
+  onSave: (
+    envKey: string,
+    value: string,
+    name: string,
+    apiKey?: string
+  ) => Promise<{ message?: string; ok: boolean }>
  options?: ApiKeyOption[]
  redactedValue?: (envKey: string) => null | string | undefined
 }) {
  const { t } = useI18n()
-  const [option, setOption] = useState<ApiKeyOption>(options[0])
+
+  const [option, setOption] = useState<ApiKeyOption>(
+    () => options.find(o => o.envKey === initialEnvKey) ?? options[0]
+  )
+
  const [value, setValue] = useState('')
+  // Optional endpoint API key, only used by the local / custom endpoint option
+  // (whose `value` is the base URL). Cleared whenever the option changes.
+  const [localKey, setLocalKey] = useState('')
  const [saving, setSaving] = useState(false)
  const [error, setError] = useState<null | string>(null)
  // `options` can change at runtime when callers filter the catalog (e.g. the
@@ -657,6 +678,7 @@ export function ApiKeyForm({
    if (options.length > 0 && !options.some(o => o.envKey === option.envKey)) {
      setOption(options[0])
      setValue('')
+      setLocalKey('')
      setError(null)
    }
  }, [option.envKey, options])
@@ -668,6 +690,7 @@ export function ApiKeyForm({
  const pick = (o: ApiKeyOption) => {
    setOption(o)
    setValue('')
+    setLocalKey('')
    setError(null)
    requestAnimationFrame(() => {
      entryRef.current?.scrollIntoView({ behavior: 'smooth', block: 'center' })
@@ -693,10 +716,11 @@ export function ApiKeyForm({

    setSaving(true)
    setError(null)
-    const result = await onSave(option.envKey, value, option.name)
+    const result = await onSave(option.envKey, value, option.name, isLocal ? localKey : undefined)

    if (result.ok) {
      setValue('')
+      setLocalKey('')
    } else {
      setError(result.message ?? t.onboarding.couldNotSave)
    }
@@ -759,6 +783,17 @@ export function ApiKeyForm({
          type={isLocal ? 'text' : 'password'}
          value={value}
        />
+        {isLocal ? (
+          <Input
+            autoComplete="off"
+            className="font-mono"
+            onChange={e => setLocalKey(e.target.value)}
+            onKeyDown={e => e.key === 'Enter' && void submit()}
+            placeholder={t.onboarding.localApiKeyPlaceholder}
+            type="password"
+            value={localKey}
+          />
+        ) : null}
        {error ? <p className="text-xs text-destructive">{error}</p> : null}
      </div>

@@ -41,7 +41,8 @@ function resetStores() {
    reason: null,
    requested: false,
    firstRunSkipped: false,
-    manual: false
+    manual: false,
+    localEndpoint: false
  })
 }

@@ -343,13 +343,14 @@ export function setEnvVar(key: string, value: string): Promise<{ ok: boolean }>

 export function validateProviderCredential(
  key: string,
-  value: string
+  value: string,
+  apiKey?: string
 ): Promise<{ ok: boolean; reachable: boolean; message: string; models?: string[] }> {
  return window.hermesDesktop.api<{ ok: boolean; reachable: boolean; message: string; models?: string[] }>({
    ...profileScoped(),
    path: '/api/providers/validate',
    method: 'POST',
-    body: { key, value }
+    body: { key, value, api_key: apiKey ?? '' }
  })
 }

@@ -1372,6 +1372,7 @@ export const en: Translations = {
    getKey: 'Get a key',
    replaceCurrent: 'Replace current value',
    pasteApiKey: 'Paste API key',
+    localApiKeyPlaceholder: 'API key (optional — only if your endpoint requires one)',
    couldNotSave: 'Could not save credential.',
    connecting: 'Connecting',
    update: 'Update',
@@ -1041,6 +1041,7 @@ export interface Translations {
    getKey: string
    replaceCurrent: string
    pasteApiKey: string
+    localApiKeyPlaceholder: string
    couldNotSave: string
    connecting: string
    update: string
@@ -1554,6 +1554,7 @@ export const zh: Translations = {
    getKey: '获取密钥',
    replaceCurrent: '替换当前值',
    pasteApiKey: '粘贴 API 密钥',
+    localApiKeyPlaceholder: 'API 密钥（可选 — 仅当端点需要时填写）',
    couldNotSave: '无法保存凭据。',
    connecting: '连接中',
    update: '更新',
@@ -33,6 +33,7 @@ function baseState(overrides: Partial<DesktopOnboardingState> = {}): DesktopOnbo
    requested: false,
    firstRunSkipped: false,
    manual: false,
+    localEndpoint: false,
    ...overrides
  }
 }
@@ -233,10 +234,12 @@ describe('OAuth onboarding', () => {
    const state = $desktopOnboarding.get()
    expect(state.reason).toBeNull()
    expect(state.flow.status).toBe('confirming_model')
+
    if (state.flow.status === 'confirming_model') {
      expect(state.flow.label).toBe('Nous Portal')
      expect(state.flow.currentModel).toBe(model)
    }
+
    expect(calls.some(c => c.path === '/api/model/set')).toBe(true)
  })
 })
@@ -283,7 +286,7 @@ describe('saveOnboardingLocalEndpoint', () => {
      throw new Error(`unexpected api path: ${path}`)
    })

-    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', {
+    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
      requestGateway: readyGateway()
    })

@@ -313,7 +316,7 @@ describe('saveOnboardingLocalEndpoint', () => {
    installApiMock(api)
    const onCompleted = vi.fn()

-    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', {
+    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
      onCompleted,
      requestGateway: readyGateway()
    })
@@ -332,6 +335,46 @@ describe('saveOnboardingLocalEndpoint', () => {
    expect($desktopOnboarding.get().configured).toBe(true)
  })

+  it('forwards the API key to the probe and persists it for auth-gated endpoints', async () => {
+    const calls: { body?: unknown; path: string }[] = []
+
+    const api = vi.fn(async ({ body, path }: { body?: unknown; path: string }) => {
+      calls.push({ body, path })
+
+      if (path === '/api/providers/validate') {
+        return { ok: true, reachable: true, message: '', models: ['gpt-oss-120b'] }
+      }
+
+      if (path === '/api/model/set') {
+        return { ok: true, provider: 'custom', model: 'gpt-oss-120b', base_url: 'https://text.example.com/v1' }
+      }
+
+      throw new Error(`unexpected api path: ${path}`)
+    })
+
+    installApiMock(api)
+
+    const result = await saveOnboardingLocalEndpoint('https://text.example.com/v1', 'sk-secret', {
+      requestGateway: readyGateway()
+    })
+
+    expect(result.ok).toBe(true)
+
+    // The probe must receive the key so an auth-gated /v1/models enumerates.
+    const probe = calls.find(c => c.path === '/api/providers/validate')
+    expect(probe?.body).toMatchObject({ key: 'OPENAI_BASE_URL', value: 'https://text.example.com/v1', api_key: 'sk-secret' })
+
+    // And the key must be persisted alongside the endpoint for runtime auth.
+    const assign = calls.find(c => c.path === '/api/model/set')
+    expect(assign?.body).toMatchObject({
+      scope: 'main',
+      provider: 'custom',
+      model: 'gpt-oss-120b',
+      base_url: 'https://text.example.com/v1',
+      api_key: 'sk-secret'
+    })
+  })
+
  it('reports the runtime reason when resolution still fails after saving', async () => {
    installApiMock(async ({ path }: { path: string }) => {
      if (path === '/api/providers/validate') {
@@ -361,7 +404,7 @@ describe('saveOnboardingLocalEndpoint', () => {
      throw new Error(`unexpected gateway method: ${method}`)
    }

-    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', {
+    const result = await saveOnboardingLocalEndpoint('http://127.0.0.1:8000/v1', '', {
      requestGateway: failingGateway
    })

@@ -72,6 +72,11 @@ export interface DesktopOnboardingState {
   *  picker's "Add provider" button). Forces the overlay to show the picker
   *  even when configured === true, and adds a close affordance. */
  manual: boolean
+  /** True when the overlay was opened specifically to configure a local /
+   *  custom OpenAI-compatible endpoint (e.g. from Settings → Model's "Set up
+   *  custom endpoint"). Forces the API-key form with the local option
+   *  preselected instead of the OAuth picker. */
+  localEndpoint: boolean
 }

 export interface OnboardingContext {
@@ -150,7 +155,8 @@ const INITIAL: DesktopOnboardingState = {
  reason: null,
  requested: false,
  firstRunSkipped: readCachedSkipped(),
-  manual: false
+  manual: false,
+  localEndpoint: false
 }

 export const $desktopOnboarding = atom<DesktopOnboardingState>(INITIAL)
@@ -392,6 +398,7 @@ export function startManualOnboarding(reason: null | string = DEFAULT_MANUAL_ONB
  patch({
    manual: true,
    requested: true,
+    localEndpoint: false,
    // `null` opts out of the prompt banner entirely (e.g. when the user already
    // picked a specific provider and we auto-start its sign-in).
    reason: reason ? reason.trim() || DEFAULT_ONBOARDING_REASON : null,
@@ -400,6 +407,24 @@ export function startManualOnboarding(reason: null | string = DEFAULT_MANUAL_ONB
  void refreshProviders()
 }

+// Open the onboarding overlay directly on the local / custom endpoint form
+// (URL + optional API key), bypassing the OAuth picker. Used by Settings →
+// Model's "Set up custom endpoint" so it lands on a form that can actually
+// configure the endpoint instead of dead-ending on the OAuth provider list
+// (`custom` is not an OAuth provider, so the generic manual flow would just
+// re-show the picker — the original "booted back to the first screen" loop).
+export function startManualLocalEndpoint(reason: null | string = null) {
+  pendingProviderOAuthId = null
+  patch({
+    manual: true,
+    requested: true,
+    localEndpoint: true,
+    mode: 'apikey',
+    reason: reason ? reason.trim() || DEFAULT_ONBOARDING_REASON : null,
+    flow: { status: 'idle' }
+  })
+}
+
 // One-shot hand-off used when the dedicated Providers settings page launches a
 // specific provider's sign-in: we open the manual onboarding overlay AND
 // remember which provider to start, so the overlay drives that exact OAuth
@@ -431,7 +456,7 @@ export function clearPendingProviderOAuth() {
 export function closeManualOnboarding() {
  pendingProviderOAuthId = null

-  patch({ manual: false, requested: false, flow: { status: 'idle' } })
+  patch({ manual: false, requested: false, localEndpoint: false, flow: { status: 'idle' } })
 }

 export function completeDesktopOnboarding() {
@@ -448,7 +473,8 @@ export function completeDesktopOnboarding() {
    reason: null,
    requested: false,
    firstRunSkipped: false,
-    manual: false
+    manual: false,
+    localEndpoint: false
  })
 }

@@ -461,7 +487,7 @@ export function completeDesktopOnboarding() {
 export function dismissFirstRunOnboarding() {
  clearPoll()
  writeCachedSkipped(true)
-  patch({ firstRunSkipped: true, requested: false, manual: false, flow: { status: 'idle' } })
+  patch({ firstRunSkipped: true, requested: false, manual: false, localEndpoint: false, flow: { status: 'idle' } })
 }

 export function setOnboardingMode(mode: OnboardingMode) {
@@ -701,18 +727,28 @@ export async function recheckExternalSignin(ctx: OnboardingContext) {
  )
 }

-export async function saveOnboardingApiKey(envKey: string, value: string, label: string, ctx: OnboardingContext) {
+export async function saveOnboardingApiKey(
+  envKey: string,
+  value: string,
+  label: string,
+  ctx: OnboardingContext,
+  // Optional endpoint key — only meaningful for the "Local / custom endpoint"
+  // option, whose primary `value` is the base URL. Ignored for plain API-key
+  // providers (their key IS `value`).
+  endpointApiKey?: string
+) {
  const trimmed = value.trim()

  if (!trimmed) {
    return { ok: false, message: 'Enter a value first.' }
  }

-  // The "Local / custom endpoint" option carries a base URL, not an API key.
-  // It must be wired into config (provider=custom + base_url + model), not
-  // dropped into .env — runtime resolution ignores OPENAI_BASE_URL.
+  // The "Local / custom endpoint" option carries a base URL (in `value`) plus
+  // an optional API key. It must be wired into config (provider=custom +
+  // base_url + model + api_key), not dropped into .env — runtime resolution
+  // ignores OPENAI_BASE_URL.
  if (envKey === 'OPENAI_BASE_URL') {
-    return saveOnboardingLocalEndpoint(trimmed, ctx)
+    return saveOnboardingLocalEndpoint(trimmed, endpointApiKey?.trim() ?? '', ctx)
  }

  // No key validation here on purpose: we previously live-probed the key and
@@ -748,14 +784,17 @@ export async function saveOnboardingApiKey(envKey: string, value: string, label:
 // env var that resolution never consults.
 //
 // The model is auto-discovered from the endpoint's /v1/models (surfaced by the
-// validate probe) so the user only has to paste a URL — no extra UI field.
+// validate probe). The optional API key is forwarded to the probe (so hosted
+// endpoints that gate /v1/models behind auth still enumerate models) and
+// persisted to model.api_key so the runtime can authenticate.
 //
 // We deliberately don't route through completeWithModelConfirm: that path
 // re-assigns the model from /api/model/options WITHOUT a base_url, which would
 // wipe the base_url we just wrote. We have a concrete model already, so we
 // verify the runtime directly and finish.
-export async function saveOnboardingLocalEndpoint(baseUrl: string, ctx: OnboardingContext) {
+export async function saveOnboardingLocalEndpoint(baseUrl: string, apiKey: string, ctx: OnboardingContext) {
  const url = baseUrl.trim()
+  const key = apiKey.trim()

  if (!url) {
    return { ok: false, message: 'Enter the endpoint URL first.' }
@@ -767,7 +806,7 @@ export async function saveOnboardingLocalEndpoint(baseUrl: string, ctx: Onboardi
  let model = ''

  try {
-    const probe = await validateProviderCredential('OPENAI_BASE_URL', url)
+    const probe = await validateProviderCredential('OPENAI_BASE_URL', url, key)

    if (!probe.ok && probe.reachable) {
      return { ok: false, message: probe.message || 'Could not reach that endpoint.' }
@@ -790,7 +829,7 @@ export async function saveOnboardingLocalEndpoint(baseUrl: string, ctx: Onboardi
  }

  try {
-    await setModelAssignment({ scope: 'main', provider: 'custom', model, base_url: url })
+    await setModelAssignment({ scope: 'main', provider: 'custom', model, base_url: url, api_key: key })
    await ctx.requestGateway('reload.env').catch(() => undefined)

    const runtime = await checkRuntime(ctx)
@@ -638,6 +638,10 @@ export interface AuxiliaryModelsResponse {
 }

 export interface ModelAssignmentRequest {
+  /** Optional API key for a custom/local endpoint. Persisted to model.api_key
+   *  (where the runtime reads it) for self-hosted endpoints that require auth.
+   *  Only honored for custom/local providers on the main slot. */
+  api_key?: string
  /** OpenAI-compatible endpoint URL. Only honored for custom/local providers
   *  on the main slot — wires a self-hosted endpoint into runtime resolution. */
  base_url?: string