[codex] hide Ollama until manually added (#170)

## Summary

Fixes #159 by making Ollama opt-in in Settings. `Ollama (local)` no
longer appears as a default provider row on fresh configs; users can add
it explicitly from the Add provider menu, and the keyless provider is
persisted without writing an empty secret.

## Type of change

- [x] Bug fix
- [ ] New feature
- [ ] Refactor (no behavior change)
- [ ] Documentation
- [ ] Build / CI / tooling
- [ ] Breaking change

## Linked issue

Closes #159

## Root cause

`toProviderRows()` always injected keyless builtin providers into the
rendered row set. Because Ollama is the only builtin with
`requiresApiKey: false`, Settings showed it even when the user had never
added or configured it.

## What changed

- Removed automatic keyless builtin injection from provider row
generation.
- Added regression coverage for hidden-until-persisted and
visible-after-persisted Ollama behavior.
- Allowed the Settings add-provider IPC path to persist keyless Ollama
without creating an empty secret.
- Added an explicit Ollama item to the Add provider menu, disabled after
it is already present.
- Added English and Chinese labels for the new menu entry and toast.
- Added a changeset for the user-visible Settings behavior change.

## Checklist

- [x] I read [`CLAUDE.md`](../CLAUDE.md) before starting
- [ ] I read [`docs/VISION.md`](../docs/VISION.md) and
[`docs/PRINCIPLES.md`](../docs/PRINCIPLES.md) before starting (not
present in this local checkout; `docs/` only contains `docs/research/`)
- [x] Commits are signed with DCO (`git commit -s`)
- [x] Added/updated tests for the change
- [x] Added a changeset (`pnpm changeset`) because behavior changed
- [x] Updated docs if behavior changed (not needed; behavior is covered
by Settings UI copy)

## PRINCIPLES §5b checks

- [x] Compatibility: Existing persisted provider/secret rows still
render; keyless Ollama remains allowed after explicit add.
- [x] Upgradeability: No schema changes; configs keep the same v3 shape.
- [x] No bloat: No dependency additions; only targeted IPC/UI/tests/i18n
changes.
- [x] Elegance: The row list now reflects persisted state, while the add
menu owns discovery.

## Validation

- `corepack pnpm --filter @open-codesign/desktop exec vitest run
src/main/provider-settings.test.ts src/main/onboarding-ipc.test.ts
src/renderer/src/components/Settings.test.ts` — 57 passed
- `corepack pnpm --filter @open-codesign/desktop typecheck` — passed
- `corepack pnpm lint` — passed
- `git diff --check` — passed

I also attempted the full desktop test suite on Windows. It is currently
blocked by environment/platform issues unrelated to this change: missing
`better-sqlite3` native binding after dependency install, POSIX `/tmp`
path expectations on Windows, and symlink permission failures.

## Screenshots / recordings (UI changes)

Not attached; this is a small Settings menu behavior change.

Signed-off-by: HUANG <15866338256@163.com>

Author: L4b0R

.changeset/fix-ollama-provider-row.md

@@ -0,0 +1,6 @@
+---
+"@open-codesign/desktop": patch
+"@open-codesign/i18n": patch
+---
+
+Fix Settings so Ollama is hidden until users add the local provider manually.

apps/desktop/src/main/onboarding-ipc.test.ts

@@ -165,6 +165,36 @@ describe('registerOnboardingIpc — channel versioning', () => {
     }
   });
 
+  it('lets settings add the keyless Ollama builtin without storing an empty secret', async () => {
+    const { readConfig, writeConfig } = await import('./config');
+    vi.mocked(readConfig).mockResolvedValueOnce(null);
+    vi.mocked(writeConfig).mockClear();
+    const { loadConfigOnBoot, registerOnboardingIpc } = await import('./onboarding-ipc');
+    await loadConfigOnBoot();
+    registerOnboardingIpc();
+
+    const handler = handlers.get('settings:v1:add-provider');
+    expect(handler).toBeDefined();
+
+    const rows = (await handler?.(
+      {},
+      {
+        provider: 'ollama',
+        apiKey: '',
+        modelPrimary: 'llama3.2',
+      },
+    )) as Array<{ provider: string }>;
+
+    const written = vi.mocked(writeConfig).mock.calls.at(-1)?.[0];
+    expect(written?.providers['ollama']).toMatchObject({
+      id: 'ollama',
+      name: 'Ollama (local)',
+      requiresApiKey: false,
+    });
+    expect(written?.secrets['ollama']).toBeUndefined();
+    expect(rows.some((row) => row.provider === 'ollama')).toBe(true);
+  });
+
   it('registers the canonical config:v1:set-provider-and-models handler', async () => {
     const { registerOnboardingIpc } = await import('./onboarding-ipc');
     registerOnboardingIpc();

apps/desktop/src/main/onboarding-ipc.ts

@@ -247,13 +247,17 @@ function parseSaveKey(raw: unknown): SaveKeyInput {
       ERROR_CODES.IPC_BAD_INPUT,
     );
   }
-  if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+  const providerId = provider.trim();
+  const isKeylessBuiltin =
+    isSupportedOnboardingProvider(providerId) &&
+    BUILTIN_PROVIDERS[providerId].requiresApiKey === false;
+  if (typeof apiKey !== 'string' || (apiKey.trim().length === 0 && !isKeylessBuiltin)) {
     throw new CodesignError('apiKey must be a non-empty string', ERROR_CODES.IPC_BAD_INPUT);
   }
   if (typeof modelPrimary !== 'string' || modelPrimary.trim().length === 0) {
     throw new CodesignError('modelPrimary must be a non-empty string', ERROR_CODES.IPC_BAD_INPUT);
   }
-  const out: SaveKeyInput = { provider, apiKey, modelPrimary };
+  const out: SaveKeyInput = { provider: providerId, apiKey: apiKey.trim(), modelPrimary };
   if (typeof baseUrl === 'string' && baseUrl.trim().length > 0) {
     try {
       new URL(baseUrl);
@@ -336,7 +340,6 @@ function parseSetProviderAndModels(raw: unknown): SetProviderAndModelsInput {
  * after Settings mutations.
  */
 async function runSetProviderAndModels(input: SetProviderAndModelsInput): Promise<OnboardingState> {
-  const secretRef = buildSecretRef(input.apiKey);
   const nextProviders: Record<string, ProviderEntry> = { ...(cachedConfig?.providers ?? {}) };
   const existing = nextProviders[input.provider];
   const builtin = BUILTIN_PROVIDERS[input.provider as SupportedOnboardingProvider];
@@ -354,10 +357,12 @@ async function runSetProviderAndModels(input: SetProviderAndModelsInput): Promis
     baseUrl: input.baseUrl ?? seed.baseUrl,
     defaultModel: input.modelPrimary || seed.defaultModel,
   };
-  const nextSecrets = {
-    ...(cachedConfig?.secrets ?? {}),
-    [input.provider]: secretRef,
-  };
+  const nextSecrets = { ...(cachedConfig?.secrets ?? {}) };
+  if (input.apiKey.length > 0) {
+    nextSecrets[input.provider] = buildSecretRef(input.apiKey);
+  } else {
+    delete nextSecrets[input.provider];
+  }
   const activate = input.setAsActive || cachedConfig === null;
   const nextActiveProvider = activate
     ? input.provider

apps/desktop/src/main/provider-settings.test.ts

@@ -1,4 +1,9 @@
-import { CodesignError, type Config, hydrateConfig } from '@open-codesign/shared';
+import {
+  BUILTIN_PROVIDERS,
+  CodesignError,
+  type Config,
+  hydrateConfig,
+} from '@open-codesign/shared';
 import { describe, expect, it } from 'vitest';
 import {
   assertProviderHasStoredSecret,
@@ -117,6 +122,39 @@ describe('toProviderRows', () => {
     expect(anthropicRow?.hasKey).toBe(false);
     expect(anthropicRow?.maskedKey).toBe('');
   });
+
+  it('does not surface Ollama until the user has persisted it', () => {
+    const cfg = makeCfg({
+      provider: 'openai',
+      modelPrimary: 'gpt-4o',
+      secrets: { openai: { ciphertext: 'enc' } },
+    });
+
+    const rows = toProviderRows(cfg, () => 'sk-test-token-1234567890');
+
+    expect(rows.some((row) => row.provider === 'ollama')).toBe(false);
+  });
+
+  it('surfaces Ollama after it has been persisted', () => {
+    const cfg = makeCfg({
+      provider: 'openai',
+      modelPrimary: 'gpt-4o',
+      secrets: { openai: { ciphertext: 'enc' } },
+      providers: {
+        ollama: { ...BUILTIN_PROVIDERS.ollama },
+      },
+    });
+
+    const rows = toProviderRows(cfg, () => 'sk-test-token-1234567890');
+    const ollamaRow = rows.find((row) => row.provider === 'ollama');
+
+    expect(ollamaRow).toMatchObject({
+      provider: 'ollama',
+      label: 'Ollama (local)',
+      hasKey: true,
+      maskedKey: '',
+    });
+  });
 });
 
 describe('assertProviderHasStoredSecret', () => {

apps/desktop/src/main/provider-settings.ts

@@ -8,7 +8,6 @@ import {
   PROVIDER_SHORTLIST,
   type ProviderEntry,
   type ReasoningLevel,
-  SUPPORTED_ONBOARDING_PROVIDERS,
   type WireApi,
   isSupportedOnboardingProvider,
 } from '@open-codesign/shared';
@@ -101,16 +100,6 @@ export function toProviderRows(
     ...Object.keys(cfg.providers ?? {}),
     ...Object.keys(cfg.secrets ?? {}),
   ]);
-  // Keyless builtins (e.g. Ollama) always surface as rows so users can
-  // discover + enable them without going through onboarding first. Without
-  // this, a fresh v3 install would hide Ollama entirely — the providers
-  // map gets populated lazily during onboarding, but Ollama has no
-  // onboarding step to run.
-  for (const builtinId of SUPPORTED_ONBOARDING_PROVIDERS) {
-    if (BUILTIN_PROVIDERS[builtinId].requiresApiKey === false) {
-      allIds.add(builtinId);
-    }
-  }
   for (const provider of allIds) {
     const ref = cfg.secrets?.[provider];
     const entry = resolveEntryFor(cfg, provider);

apps/desktop/src/renderer/src/components/Settings.tsx

@@ -1015,6 +1015,27 @@ function ModelsTab() {
     }
   }
 
+  async function handleAddOllama() {
+    if (!window.codesign) return;
+    try {
+      await window.codesign.settings.addProvider({
+        provider: 'ollama',
+        apiKey: '',
+        modelPrimary: SHORTLIST.ollama.defaultPrimary,
+      });
+      await reloadRows();
+      pushToast({ variant: 'success', title: t('settings.providers.import.ollamaDone') });
+    } catch (err) {
+      reportableErrorToast({
+        code: 'OLLAMA_ADD_FAILED',
+        scope: 'settings',
+        title: t('settings.providers.toast.saveFailed'),
+        description: err instanceof Error ? err.message : t('settings.common.unknownError'),
+        ...(err instanceof Error && err.stack !== undefined ? { stack: err.stack } : {}),
+      });
+    }
+  }
+
   async function handleImportGemini() {
     if (!window.codesign) return;
     // Capture pre-import warnings (e.g. "AIzaSy pattern mismatch") so a
@@ -1512,6 +1533,7 @@ function ModelsTab() {
             open={showAddMenu}
             setOpen={setShowAddMenu}
             hasClaudeCodeImported={rows.some((r) => r.provider === 'claude-code-imported')}
+            hasOllamaImported={rows.some((r) => r.provider === 'ollama')}
             onImportCodex={() => {
               setShowAddMenu(false);
               void handleImportCodex();
@@ -1520,6 +1542,10 @@ function ModelsTab() {
               setShowAddMenu(false);
               void handleImportClaudeCode();
             }}
+            onAddOllama={() => {
+              setShowAddMenu(false);
+              void handleAddOllama();
+            }}
             onAddCustom={() => {
               setShowAddMenu(false);
               setShowAddCustom(true);
@@ -2137,8 +2163,10 @@ interface AddProviderMenuProps {
   open: boolean;
   setOpen: (v: boolean) => void;
   hasClaudeCodeImported: boolean;
+  hasOllamaImported: boolean;
   onImportCodex: () => void;
   onImportClaudeCode: () => void;
+  onAddOllama: () => void;
   onAddCustom: () => void;
   onAddCliProxyApi: () => void;
 }
@@ -2147,8 +2175,10 @@ function AddProviderMenu({
   open,
   setOpen,
   hasClaudeCodeImported,
+  hasOllamaImported,
   onImportCodex,
   onImportClaudeCode,
+  onAddOllama,
   onAddCustom,
   onAddCliProxyApi,
 }: AddProviderMenuProps) {
@@ -2198,6 +2228,13 @@ function AddProviderMenu({
       disabled: hasClaudeCodeImported,
       onClick: onImportClaudeCode,
     },
+    {
+      key: 'ollama',
+      label: t('settings.providers.import.ollamaMenu'),
+      desc: t('settings.providers.import.ollamaMenuDesc'),
+      disabled: hasOllamaImported,
+      onClick: onAddOllama,
+    },
     {
       key: 'custom',
       label: t('settings.providers.import.customMenu', { defaultValue: '自定义服务' }),

packages/i18n/src/locales/en.json

@@ -264,6 +264,9 @@
         "codexMenuDesc": "Read ~/.codex/config.toml",
         "claudeCodeMenu": "Import from Claude Code",
         "claudeCodeMenuDesc": "Read the signed-in Claude Code session",
+        "ollamaMenu": "Ollama (local)",
+        "ollamaMenuDesc": "Add the local localhost:11434 provider",
+        "ollamaDone": "Ollama provider added",
         "customMenu": "Custom provider",
         "customMenuDesc": "Enter API key and URL manually",
         "alreadyImported": "Already imported"
@@ -293,6 +296,7 @@
         "switchedTo": "Switched to {{label}}",
         "switchFailed": "Switch failed",
         "saved": "Provider saved",
+        "saveFailed": "Failed to save provider",
         "modelSaveFailed": "Failed to save model selection",
         "reasoningSaved": "Reasoning depth saved",
         "reasoningSaveFailed": "Failed to save reasoning depth",

packages/i18n/src/locales/zh-CN.json

@@ -264,6 +264,9 @@
         "codexMenuDesc": "读取 ~/.codex/config.toml",
         "claudeCodeMenu": "从 Claude Code 导入",
         "claudeCodeMenuDesc": "读取已登录的 Claude Code 会话",
+        "ollamaMenu": "Ollama（本地）",
+        "ollamaMenuDesc": "添加 localhost:11434 本地模型服务",
+        "ollamaDone": "已添加 Ollama 服务",
         "customMenu": "自定义服务",
         "customMenuDesc": "手动填写 API key 和 URL",
         "alreadyImported": "已导入"
@@ -293,6 +296,7 @@
         "switchedTo": "已切换到 {{label}}",
         "switchFailed": "切换失败",
         "saved": "服务已保存",
+        "saveFailed": "保存服务失败",
         "modelSaveFailed": "保存模型选择失败",
         "reasoningSaved": "已保存推理深度",
         "reasoningSaveFailed": "保存推理深度失败",