lazyclaw 3.99.12 → 3.99.14

package/README.md

@@ -54,6 +54,54 @@ lazyclaw onboard --non-interactive --provider openai \
 
 `onboard` only prompts for an api-key when the picked provider's `requiresApiKey` is true (the picker labels each row `[subscription]` / `[api key]` / `[no key]` so the choice is explicit).
 
+### Built-in OpenAI-compatible vendors
+
+Eight popular OpenAI-compatible services ship as first-class providers — pick one in the setup picker (no `+ Add custom` walkthrough needed) or set the matching environment variable and they Just Work:
+
+| Provider | Models include | Env var |
+|---|---|---|
+| `nim`        | `meta/llama-3.1-405b-instruct`, `nvidia/llama-3.1-nemotron-70b-instruct`, `deepseek-ai/deepseek-r1`, `mistralai/mixtral-8x22b-instruct-v0.1` | `NVIDIA_API_KEY` (or `NIM_API_KEY`) |
+| `openrouter` | `anthropic/claude-3.5-sonnet`, `openai/gpt-4o`, `meta-llama/llama-3.1-405b-instruct`, `deepseek/deepseek-r1` | `OPENROUTER_API_KEY` |
+| `groq`       | `llama-3.3-70b-versatile`, `mixtral-8x7b-32768`, `deepseek-r1-distill-llama-70b` | `GROQ_API_KEY` |
+| `together`   | `meta-llama/Llama-3.3-70B-Instruct-Turbo`, `Qwen/Qwen2.5-72B-Instruct-Turbo`, `deepseek-ai/DeepSeek-V3` | `TOGETHER_API_KEY` |
+| `xai`        | `grok-2-latest`, `grok-2-vision-1212` | `XAI_API_KEY` (or `GROK_API_KEY`) |
+| `deepseek`   | `deepseek-chat`, `deepseek-reasoner` | `DEEPSEEK_API_KEY` |
+| `mistral`    | `mistral-large-latest`, `codestral-latest`, `pixtral-large-latest` | `MISTRAL_API_KEY` |
+| `fireworks`  | `accounts/fireworks/models/llama-v3p3-70b-instruct`, `…/deepseek-r1` | `FIREWORKS_API_KEY` |
+
+```bash
+# NVIDIA NIM via env var — no `lazyclaw onboard` needed
+export NVIDIA_API_KEY=nvapi-...
+lazyclaw chat --provider nim --model meta/llama-3.1-405b-instruct
+
+# Or commit the choice to ~/.lazyclaw/config.json
+lazyclaw onboard --non-interactive --provider nim \
+  --model nvidia/llama-3.1-nemotron-70b-instruct --api-key nvapi-...
+```
+
+Need a vendor that's **not** built-in? `+ Add a custom OpenAI-compatible endpoint…` inside the setup picker (or `lazyclaw providers add <name> --base-url <url>`) still works for vLLM / LM Studio / private gateways / anything else that speaks the OpenAI v1 wire format.
+
+## Launcher (no-arg `lazyclaw`)
+
+Running `lazyclaw` with no subcommand drops into an arrow-key launcher with every subcommand laid out as a menu. Navigation:
+
+| Key | What it does |
+|---|---|
+| `↑` / `↓` / `Home` / `End` / `PgUp` / `PgDn` | Move the selection |
+| `Enter` | Run the highlighted item |
+| `q` / `Esc` / `Ctrl-C` | Leave lazyclaw |
+| `/` | Open an inline slash-command prompt |
+
+Slash commands at the launcher (typed after `/`):
+
+| Slash | What it does |
+|---|---|
+| `/exit` / `/quit` | Leave lazyclaw |
+| `/help` | List launcher slash commands inline |
+| `/version` | Print version + node + platform |
+
+The slash buffer lives just below the menu — backspace edits it, deleting past `/` returns to menu mode, and `Esc` cancels slash mode without leaving lazyclaw.
+
 ## Interactive chat
 
 ```bash
@@ -88,12 +136,14 @@ Slash commands inside the REPL:
 |---|---|
 | `/help` | List slash commands |
 | `/status` | Print provider + model + masked key |
-| `/provider X` | Switch active provider mid-session (history kept) |
-| `/model X` | Switch model. Accepts unified `provider/model` form |
+| `/provider` | Open the family / provider / model arrow picker |
+| `/provider X` | Switch active provider directly by name |
+| `/model` | Open the per-provider model picker (type-filter + live `/v1/models` fetch) |
+| `/model X` | Switch model directly. Accepts unified `provider/model` form |
 | `/skill a,b` | Replace the system prompt with a composition of named skills |
 | `/usage` | Message count + chars + cumulative token totals |
 | `/new` / `/reset` | Wipe history and start over |
-| `/exit` | Quit |
+| `/exit` | Leave the chat REPL (returns to the launcher when chat was opened from it) |
 
 **Cursor-style ghost autocomplete**: type `/` and the longest matching slash command appears in dim grey after the cursor. **`→`** accepts; **`Tab`** cycles. **Ctrl-C** during a streaming reply aborts that turn (not the whole process); **Ctrl-C** at an empty prompt exits.
 

package/cli.mjs

@@ -33,19 +33,26 @@ function writeConfig(cfg) {
 // without forcing the dynamic import on every hot-path call.
 //   1. cfg.authProfiles[provider] active label, if set
 //   2. first profile in the array
-//   3. legacy single `cfg["api-key"]` (pre-v3.93 configs)
+//   3. customProviders[<provider>].apiKey (custom OpenAI-compat entries)
+//   4. PROVIDER_INFO[<provider>].envKey / altEnvKeys env var (built-in
+//      OpenAI-compat: nim → NVIDIA_API_KEY, openrouter → OPENROUTER_API_KEY, …)
+//   5. legacy single `cfg["api-key"]` (pre-v3.93 configs)
 function _resolveAuthKey(cfg, provider) {
   const arr = (cfg.authProfiles || {})[provider] || [];
   const active = (cfg.authActiveProfile || {})[provider];
   const hit = arr.find((p) => p && p.label === active) || arr[0];
   if (hit?.key) return hit.key;
-  // Custom OpenAI-compatible providers store their api-key inline in the
-  // customProviders[] entry. Honour that before falling back to the
-  // legacy single-key cfg['api-key'].
   const custom = Array.isArray(cfg.customProviders)
     ? cfg.customProviders.find((p) => p && p.name === provider)
     : null;
   if (custom?.apiKey) return custom.apiKey;
+  // Built-in OpenAI-compat env var fallback. Skipped silently when the
+  // registry module isn't loaded yet (every chat / agent path calls
+  // ensureRegistry() before _resolveAuthKey, so this is just defence-in-depth).
+  if (_registryMod && typeof _registryMod.resolveBuiltinEnvKey === 'function') {
+    const envHit = _registryMod.resolveBuiltinEnvKey(provider);
+    if (envHit) return envHit;
+  }
   return cfg['api-key'] || '';
 }
 
@@ -1798,17 +1805,58 @@ async function _pickProviderInteractive() {
   }
 
   // ── Step 3 — model ────────────────────────────────────────────
-  const meta = info[provider.id] || {};
+  const picked = await _pickModelInteractive(provider.id, {
+    titlePrefix: 'LazyClaw setup — Step 3 of 3:',
+    onBack: 'restart',
+  });
+  if (picked === 'CANCEL') return null;
+  if (picked === 'BACK')   return _pickProviderInteractive();
+  return { provider: provider.id, model: picked };
+}
+
+// Pause the chat REPL's readline + ghost-autocomplete while a sub-picker
+// (provider / model arrow menu) takes over the terminal. The sub-picker
+// installs its own `keypress` listener and toggles raw mode; the chat's
+// readline would race it for stdin if we left it active. After `body`
+// returns we re-emit keypress events, restore raw mode, and re-prompt
+// so the chat resumes cleanly. `body` is awaited — exceptions propagate.
+async function _pauseChatForSubMenu(rl, ghost, body) {
+  if (ghost && typeof ghost.suspend === 'function') ghost.suspend();
+  try { rl.pause(); } catch (_) {}
+  // Drop the readline keypress hook so the picker's own listener has
+  // sole ownership while it's open. We re-arm it on the way out.
+  if (process.stdin.setRawMode) {
+    try { process.stdin.setRawMode(false); } catch (_) {}
+  }
+  try {
+    await body();
+  } finally {
+    const readline = await import('node:readline');
+    try { readline.emitKeypressEvents(process.stdin); } catch (_) {}
+    if (process.stdin.setRawMode && process.stdin.isTTY) {
+      try { process.stdin.setRawMode(false); } catch (_) {}
+    }
+    process.stdin.resume();
+    if (process.stdin.ref) process.stdin.ref();
+    if (ghost && typeof ghost.resume === 'function') ghost.resume();
+    try { rl.resume(); } catch (_) {}
+    try { rl.prompt(); } catch (_) {}
+  }
+}
+
+// Standalone model picker for the chat REPL's `/model` slash. Returns
+// the chosen model id (string), 'BACK', or 'CANCEL'. Falls through to
+// null when the provider has no curated models and no live-fetch surface
+// (mock) — the caller should treat that as "use the provider default".
+async function _pickModelInteractive(providerId, opts = {}) {
+  const info = _registryMod.PROVIDER_INFO || {};
+  const meta = info[providerId] || {};
   const baseModels = Array.isArray(meta.suggestedModels) ? meta.suggestedModels.slice() : [];
   const isCustom = !!meta.custom;
-  const supportsLiveFetch = !!meta.baseUrl || provider.id === 'openai' || provider.id === 'ollama';
+  const isBuiltinCompat = !!meta.builtinOpenAICompat;
+  const supportsLiveFetch = !!meta.baseUrl || providerId === 'openai' || providerId === 'ollama' || isBuiltinCompat;
 
-  if (!baseModels.length && !supportsLiveFetch) {
-    // Provider has no curated models AND no live-fetch surface (mock) —
-    // return without a model so the underlying call uses the provider
-    // default.
-    return { provider: provider.id, model: null };
-  }
+  if (!baseModels.length && !supportsLiveFetch) return null;
 
   let dynamicModels = [];
   while (true) {
@@ -1818,7 +1866,7 @@ async function _pickProviderInteractive() {
       modelItems.unshift({
         id: '__fetch_models__',
         label: '↻ Fetch live model list from /v1/models',
-        desc: isCustom ? `GET ${meta.baseUrl}/models` : 'pulls the up-to-date catalogue from the provider',
+        desc: isCustom || isBuiltinCompat ? `GET ${meta.baseUrl}/models` : 'pulls the up-to-date catalogue from the provider',
         tag: '\x1b[38;5;245m[live]\x1b[0m',
       });
     }
@@ -1832,24 +1880,25 @@ async function _pickProviderInteractive() {
     const defaultIdx = supportsLiveFetch
       ? Math.max(0, 1 + allModels.indexOf(meta.defaultModel || allModels[0]))
       : Math.max(0, allModels.indexOf(meta.defaultModel || allModels[0]));
+    const titlePrefix = opts.titlePrefix ? `${opts.titlePrefix}  ` : '';
     const picked = await _arrowMenu({
-      title: `LazyClaw setup — Step 3 of 3:  pick a model for ${provider.id}`,
+      title: `${titlePrefix}pick a model for ${providerId}`,
       subtitle: `Type to filter ${allModels.length} model(s). Enter to confirm. Backspace clears one char, Ctrl+U clears the filter.`,
       items: modelItems,
       defaultIdx,
       searchable: true,
     });
-    if (picked === 'CANCEL') return null;
-    if (picked === 'BACK')   return _pickProviderInteractive(); // back to step 1
+    if (picked === 'CANCEL') return 'CANCEL';
+    if (picked === 'BACK')   return 'BACK';
     if (picked.id === '__custom_model__') {
-      const typed = (await _quickPrompt(`  model id for ${provider.id}: `)).trim();
+      const typed = (await _quickPrompt(`  model id for ${providerId}: `)).trim();
       if (!typed) continue;
-      return { provider: provider.id, model: typed };
+      return typed;
     }
     if (picked.id === '__fetch_models__') {
       try {
-        process.stdout.write(`\n  fetching ${provider.id} model list…\n`);
-        const fetched = await _fetchModelsForProvider(provider.id);
+        process.stdout.write(`\n  fetching ${providerId} model list…\n`);
+        const fetched = await _fetchModelsForProvider(providerId);
         if (!fetched.length) {
           process.stdout.write(`  ${'\x1b[33m'}no models returned${'\x1b[0m'} — falling back to the suggested list.\n`);
           await _quickPrompt('  press Enter to continue ');
@@ -1864,7 +1913,7 @@ async function _pickProviderInteractive() {
       }
       continue;
     }
-    return { provider: provider.id, model: picked.id };
+    return picked.id;
   }
 }
 
@@ -1878,6 +1927,12 @@ function _modelCatalogueFor(providerId) {
     const entry = (cfg.customProviders || []).find((p) => p && p.name === providerId) || {};
     return { baseUrl: meta.baseUrl, apiKey: entry.apiKey || cfg['api-key'] || '' };
   }
+  // Built-in OpenAI-compatible vendors (nim / openrouter / groq / together /
+  // xai / deepseek / mistral / fireworks). The registry exposes a baseUrl
+  // and the auth-key resolver already knows about the env-var fallback.
+  if (meta.builtinOpenAICompat && meta.baseUrl) {
+    return { baseUrl: meta.baseUrl, apiKey: _resolveAuthKey(cfg, providerId) };
+  }
   if (providerId === 'openai') {
     return { baseUrl: 'https://api.openai.com/v1', apiKey: _resolveAuthKey(cfg, 'openai') };
   }
@@ -2133,10 +2188,28 @@ async function cmdChat(flags = {}) {
         // `/provider <name>` switches the active provider for subsequent
         // turns. The conversation history stays put — the next user
         // message goes to the new provider with the existing context.
-        // `/provider` (no arg) prints the current name.
+        // `/provider` (no arg) opens the family/provider/model picker so
+        // the user can switch with arrow keys instead of memorising names.
         const arg = line.slice('/provider'.length).trim();
         if (!arg) {
-          process.stdout.write(`provider: ${activeProvName}\n`);
+          if (!useTerminal) {
+            process.stdout.write(`provider: ${activeProvName}\n`);
+            return true;
+          }
+          await _pauseChatForSubMenu(rl, _ghost, async () => {
+            const picked = await _pickProviderInteractive();
+            if (picked && picked.provider) {
+              const next = lookupProv(picked.provider);
+              if (!next) {
+                process.stdout.write(`unknown provider: ${picked.provider}\n`);
+                return;
+              }
+              activeProvName = picked.provider;
+              prov = next;
+              if (picked.model) activeModel = picked.model;
+              process.stdout.write(`provider → ${activeProvName}${picked.model ? ` · model → ${picked.model}` : ''}\n`);
+            }
+          });
           return true;
         }
         const next = lookupProv(arg);
@@ -2151,10 +2224,20 @@ async function cmdChat(flags = {}) {
       }
       case '/model': {
         // `/model <name>` updates the active model without touching the
-        // provider. `/model` (no arg) prints the current value.
+        // provider. `/model` (no arg) opens the per-provider model picker
+        // — same UX as setup step 3, scoped to the active provider.
         const arg = line.slice('/model'.length).trim();
         if (!arg) {
-          process.stdout.write(`model: ${activeModel || '(default)'}\n`);
+          if (!useTerminal) {
+            process.stdout.write(`model: ${activeModel || '(default)'}\n`);
+            return true;
+          }
+          await _pauseChatForSubMenu(rl, _ghost, async () => {
+            const chosen = await _pickModelInteractive(activeProvName, { titlePrefix: 'LazyClaw chat —' });
+            if (chosen === 'CANCEL' || chosen === 'BACK' || !chosen) return;
+            activeModel = chosen;
+            process.stdout.write(`model → ${activeModel}\n`);
+          });
           return true;
         }
         // Honor unified provider/model: `/model anthropic/claude-opus-4-7`
@@ -4084,7 +4167,7 @@ async function cmdLauncher() {
       process.stdout.write(`  ${dim('model    ·')} ${ok(model)}\n`);
       process.stdout.write(`  ${dim('config   ·')} ${dim(configPath())}\n`);
       process.stdout.write('\n');
-      process.stdout.write(`  ${dim('↑/↓ to move · Enter to select · q or Esc to quit')}\n\n`);
+      process.stdout.write(`  ${dim('↑/↓ to move · Enter to select · / for slash command (e.g. /exit) · q or Esc to quit')}\n\n`);
       const rowsAvail = Math.max(items.length, (process.stdout.rows || 30) - 14);
       const fromIdx = Math.max(0, Math.min(items.length - rowsAvail, idx - Math.floor(rowsAvail / 2)));
       const toIdx = Math.min(items.length, fromIdx + rowsAvail);
@@ -4097,10 +4180,74 @@ async function cmdLauncher() {
       process.stdout.write('\n');
     };
 
+    // Slash-command mini prompt rendered just below the menu. Lets users
+    // type `/exit` / `/quit` / `/help` to leave (or get a list of slash
+    // commands) without hunting for the right special key. The menu is
+    // raw-mode and never sees a newline-terminated line, so we accumulate
+    // keystrokes locally instead of round-tripping through readline.
+    let slashBuffer = null; // null = menu mode; string = slash mode (always starts with '/')
+    let slashNotice = '';   // one-line hint shown after the buffer (e.g. "unknown command")
+    const LAUNCHER_SLASH_HELP = [
+      { cmd: '/exit',    help: 'leave lazyclaw' },
+      { cmd: '/quit',    help: 'alias for /exit' },
+      { cmd: '/help',    help: 'list slash commands' },
+      { cmd: '/version', help: 'print version + node + platform' },
+    ];
+    const drawWithSlash = () => {
+      draw();
+      process.stdout.write(`  ${dim('slash ›')} ${slashBuffer}`);
+      if (slashNotice) process.stdout.write(`   ${slashNotice}`);
+      process.stdout.write('\x1b[?25h'); // show cursor while typing
+    };
+
     draw();
     const picked = await new Promise((resolve) => {
-      const onKey = (_str, key) => {
+      const onKey = (str, key) => {
         if (!key) return;
+
+        // ── Slash-command input mode ─────────────────────────────────
+        if (slashBuffer !== null) {
+          if (key.ctrl && key.name === 'c') { cleanup(); resolve({ id: 'quit', argv: null }); return; }
+          if (key.name === 'escape') { slashBuffer = null; slashNotice = ''; draw(); return; }
+          if (key.name === 'return') {
+            const cmd = slashBuffer.trim().toLowerCase();
+            if (cmd === '/exit' || cmd === '/quit') { cleanup(); resolve({ id: 'quit', argv: null }); return; }
+            if (cmd === '/help') {
+              slashBuffer = '/';
+              slashNotice = dim(LAUNCHER_SLASH_HELP.map(c => `${c.cmd} (${c.help})`).join(' · '));
+              drawWithSlash();
+              return;
+            }
+            if (cmd === '/version') {
+              const v = readVersionFromRepo();
+              slashNotice = ok(`v${v} · node ${process.version} · ${process.platform}-${process.arch}`);
+              drawWithSlash();
+              return;
+            }
+            // Unknown command — keep the buffer so the user can edit it
+            // rather than retyping from scratch. Esc / Backspace bails.
+            slashNotice = warn(`unknown — try ${LAUNCHER_SLASH_HELP.map(c => c.cmd).join(' · ')}`);
+            drawWithSlash();
+            return;
+          }
+          if (key.name === 'backspace') {
+            slashNotice = '';
+            if (slashBuffer.length > 1) slashBuffer = slashBuffer.slice(0, -1);
+            else slashBuffer = null;
+            slashBuffer === null ? draw() : drawWithSlash();
+            return;
+          }
+          // Append printable characters. Filter control / meta chords so
+          // Ctrl+L etc. don't pollute the buffer.
+          if (str && str.length === 1 && !key.ctrl && !key.meta && str >= ' ') {
+            slashBuffer += str;
+            slashNotice = '';
+            drawWithSlash();
+          }
+          return;
+        }
+
+        // ── Menu navigation mode ─────────────────────────────────────
         if (key.name === 'up')        { idx = (idx - 1 + items.length) % items.length; draw(); }
         else if (key.name === 'down') { idx = (idx + 1) % items.length; draw(); }
         else if (key.name === 'home') { idx = 0; draw(); }
@@ -4110,6 +4257,7 @@ async function cmdLauncher() {
         else if (key.name === 'return')   { cleanup(); resolve(items[idx]); }
         else if (key.ctrl && key.name === 'c') { cleanup(); resolve({ id: 'quit', argv: null }); }
         else if (key.name === 'escape' || key.name === 'q') { cleanup(); resolve({ id: 'quit', argv: null }); }
+        else if (str === '/') { slashBuffer = '/'; slashNotice = ''; drawWithSlash(); }
         function cleanup() {
           process.stdin.off('keypress', onKey);
           if (process.stdin.setRawMode) process.stdin.setRawMode(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazyclaw",
-  "version": "3.99.12",
+  "version": "3.99.14",
   "description": "Lazy, elegant terminal CLI for chatting with Claude / OpenAI / Gemini / Ollama and orchestrating multi-step LLM workflows. Banner-on-launch, slash-command ghost autocomplete, persistent sessions, local HTTP gateway.",
   "keywords": [
     "claude",

package/providers/registry.mjs

@@ -52,6 +52,164 @@ export const mockProvider = {
 export { anthropicProvider, openaiProvider, ollamaProvider, geminiProvider, claudeCliProvider };
 export { makeOpenAICompatProvider, fetchOpenAICompatModels };
 
+// Built-in OpenAI-compatible vendors. Same wire format → one factory call
+// each. The picker treats these like first-class providers so users don't
+// have to walk through "+ Add a custom endpoint" for the popular ones.
+//
+// Each entry must define baseUrl + envKey (the env var the chat path
+// consults when no api-key is configured) + suggestedModels (curated list
+// shown before the user fetches the live /v1/models catalogue).
+//
+// Adding a new vendor: drop a row here. The PROVIDERS / PROVIDER_INFO loops
+// below pick it up automatically.
+export const OPENAI_COMPAT_BUILTINS = {
+  nim: {
+    label: 'NVIDIA NIM',
+    baseUrl: 'https://integrate.api.nvidia.com/v1',
+    envKey: 'NVIDIA_API_KEY',
+    altEnvKeys: ['NIM_API_KEY'],
+    keyPrefix: 'nvapi-',
+    docs: 'NVIDIA NIM hosted catalogue (Llama 3.x, Nemotron, DeepSeek-R1, Mixtral, Phi-3, Qwen, etc.). Auth: NVIDIA_API_KEY env var or in-app api-key. Endpoint speaks the OpenAI v1 wire format.',
+    defaultModel: 'meta/llama-3.1-405b-instruct',
+    suggestedModels: [
+      'meta/llama-3.1-405b-instruct',
+      'meta/llama-3.1-70b-instruct',
+      'meta/llama-3.1-8b-instruct',
+      'nvidia/llama-3.1-nemotron-70b-instruct',
+      'nvidia/nemotron-mini-4b-instruct',
+      'nvidia/llama-3.3-nemotron-super-49b-v1',
+      'mistralai/mistral-nemo-12b-instruct',
+      'mistralai/mixtral-8x22b-instruct-v0.1',
+      'microsoft/phi-3-medium-4k-instruct',
+      'deepseek-ai/deepseek-r1',
+      'qwen/qwen2.5-7b-instruct',
+      'qwen/qwen2.5-coder-32b-instruct',
+    ],
+  },
+  openrouter: {
+    label: 'OpenRouter',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    envKey: 'OPENROUTER_API_KEY',
+    keyPrefix: 'sk-or-',
+    docs: 'OpenRouter unified gateway — 200+ models behind one OpenAI-compatible endpoint. Auth: OPENROUTER_API_KEY env var or in-app api-key. Uses x-title/HTTP-Referer headers for attribution.',
+    defaultModel: 'anthropic/claude-3.5-sonnet',
+    headers: { 'http-referer': 'https://github.com/cmblir/lazyclaude', 'x-title': 'lazyclaw' },
+    suggestedModels: [
+      'anthropic/claude-3.5-sonnet',
+      'anthropic/claude-3-opus',
+      'openai/gpt-4o',
+      'openai/gpt-4o-mini',
+      'openai/o1-preview',
+      'meta-llama/llama-3.1-405b-instruct',
+      'meta-llama/llama-3.3-70b-instruct',
+      'google/gemini-2.0-flash-exp:free',
+      'google/gemini-pro-1.5',
+      'deepseek/deepseek-chat',
+      'deepseek/deepseek-r1',
+      'qwen/qwen-2.5-coder-32b-instruct',
+      'mistralai/mistral-large',
+    ],
+  },
+  groq: {
+    label: 'Groq',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    envKey: 'GROQ_API_KEY',
+    keyPrefix: 'gsk_',
+    docs: 'Groq LPU inference — fastest-token-per-second tier for Llama / Mixtral / Gemma. Auth: GROQ_API_KEY env var or in-app api-key.',
+    defaultModel: 'llama-3.3-70b-versatile',
+    suggestedModels: [
+      'llama-3.3-70b-versatile',
+      'llama-3.1-70b-versatile',
+      'llama-3.1-8b-instant',
+      'llama-3.2-90b-vision-preview',
+      'mixtral-8x7b-32768',
+      'gemma2-9b-it',
+      'qwen-2.5-coder-32b',
+      'qwen-2.5-32b',
+      'deepseek-r1-distill-llama-70b',
+    ],
+  },
+  together: {
+    label: 'Together AI',
+    baseUrl: 'https://api.together.xyz/v1',
+    envKey: 'TOGETHER_API_KEY',
+    docs: 'Together AI hosted inference for open-weight models (Llama, Mixtral, Qwen, DeepSeek, etc.). Auth: TOGETHER_API_KEY env var or in-app api-key.',
+    defaultModel: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+    suggestedModels: [
+      'meta-llama/Llama-3.3-70B-Instruct-Turbo',
+      'meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo',
+      'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo',
+      'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+      'mistralai/Mixtral-8x22B-Instruct-v0.1',
+      'mistralai/Mixtral-8x7B-Instruct-v0.1',
+      'Qwen/Qwen2.5-72B-Instruct-Turbo',
+      'Qwen/Qwen2.5-Coder-32B-Instruct',
+      'deepseek-ai/DeepSeek-V3',
+      'deepseek-ai/DeepSeek-R1',
+    ],
+  },
+  xai: {
+    label: 'xAI (Grok)',
+    baseUrl: 'https://api.x.ai/v1',
+    envKey: 'XAI_API_KEY',
+    altEnvKeys: ['GROK_API_KEY'],
+    keyPrefix: 'xai-',
+    docs: 'xAI Grok models. Auth: XAI_API_KEY env var or in-app api-key.',
+    defaultModel: 'grok-2-latest',
+    suggestedModels: [
+      'grok-2-latest',
+      'grok-2-1212',
+      'grok-2-vision-1212',
+      'grok-beta',
+      'grok-vision-beta',
+    ],
+  },
+  deepseek: {
+    label: 'DeepSeek',
+    baseUrl: 'https://api.deepseek.com/v1',
+    envKey: 'DEEPSEEK_API_KEY',
+    keyPrefix: 'sk-',
+    docs: 'DeepSeek (deepseek-chat / deepseek-reasoner). Auth: DEEPSEEK_API_KEY env var or in-app api-key.',
+    defaultModel: 'deepseek-chat',
+    suggestedModels: [
+      'deepseek-chat',
+      'deepseek-reasoner',
+      'deepseek-coder',
+    ],
+  },
+  mistral: {
+    label: 'Mistral La Plateforme',
+    baseUrl: 'https://api.mistral.ai/v1',
+    envKey: 'MISTRAL_API_KEY',
+    docs: 'Mistral La Plateforme (mistral-large, codestral, ministral, pixtral). Auth: MISTRAL_API_KEY env var or in-app api-key.',
+    defaultModel: 'mistral-large-latest',
+    suggestedModels: [
+      'mistral-large-latest',
+      'mistral-small-latest',
+      'codestral-latest',
+      'ministral-8b-latest',
+      'ministral-3b-latest',
+      'pixtral-large-latest',
+      'open-mistral-nemo',
+    ],
+  },
+  fireworks: {
+    label: 'Fireworks AI',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    envKey: 'FIREWORKS_API_KEY',
+    docs: 'Fireworks AI hosted models. Auth: FIREWORKS_API_KEY env var or in-app api-key.',
+    defaultModel: 'accounts/fireworks/models/llama-v3p3-70b-instruct',
+    suggestedModels: [
+      'accounts/fireworks/models/llama-v3p3-70b-instruct',
+      'accounts/fireworks/models/llama-v3p1-405b-instruct',
+      'accounts/fireworks/models/qwen2p5-coder-32b-instruct',
+      'accounts/fireworks/models/deepseek-r1',
+      'accounts/fireworks/models/deepseek-v3',
+      'accounts/fireworks/models/mixtral-8x22b-instruct',
+    ],
+  },
+};
+
 // Insertion order is the picker order. The list goes first-to-last in
 // rough "user-familiar / popular" order so a first-time onboard lands
 // the cursor on a vendor most users recognise. v3.99.5 reordered per
@@ -63,11 +221,34 @@ export const PROVIDERS = {
   // Tier 2 — Claude. CLI variant first because it's keyless.
   'claude-cli': claudeCliProvider,
   anthropic: anthropicProvider,
-  // Tier 3 — local + dev/test.
+  // Tier 3 — popular OpenAI-compatible aggregators / hosted catalogues.
+  // Inserted by the loop below from OPENAI_COMPAT_BUILTINS so the order
+  // here mirrors that object's insertion order.
+  // Tier 4 — local + dev/test.
   ollama: ollamaProvider,
   mock: mockProvider,
 };
 
+// Wire each OpenAI-compat builtin into PROVIDERS as a callable provider.
+// Insertion is between Tier 2 (anthropic) and Tier 4 (ollama) by reordering
+// the keys after the loop runs — JS objects honour insertion order and
+// cmdLauncher's families helper relies on that for the picker.
+{
+  const local = { ollama: PROVIDERS.ollama, mock: PROVIDERS.mock };
+  delete PROVIDERS.ollama;
+  delete PROVIDERS.mock;
+  for (const [name, def] of Object.entries(OPENAI_COMPAT_BUILTINS)) {
+    PROVIDERS[name] = makeOpenAICompatProvider({
+      name,
+      baseUrl: def.baseUrl,
+      defaultModel: def.defaultModel,
+      headers: def.headers,
+    });
+  }
+  PROVIDERS.ollama = local.ollama;
+  PROVIDERS.mock = local.mock;
+}
+
 // Static metadata for `lazyclaw providers list/info`. Kept next to PROVIDERS
 // so adding a provider in one place can't drift from the list shown to users.
 export const PROVIDER_INFO = {
@@ -167,6 +348,44 @@ export const PROVIDER_INFO = {
   },
 };
 
+// Mirror the OpenAI-compat builtins into PROVIDER_INFO so picker / docs /
+// `lazyclaw providers info` see them with the same shape as the hand-written
+// entries above.
+for (const [name, def] of Object.entries(OPENAI_COMPAT_BUILTINS)) {
+  PROVIDER_INFO[name] = {
+    name,
+    label: def.label,
+    requiresApiKey: true,
+    keyPrefix: def.keyPrefix,
+    envKey: def.envKey,
+    altEnvKeys: Array.isArray(def.altEnvKeys) ? def.altEnvKeys.slice() : [],
+    docs: def.docs,
+    endpoint: `${def.baseUrl}/chat/completions`,
+    defaultModel: def.defaultModel,
+    suggestedModels: Array.isArray(def.suggestedModels) ? def.suggestedModels.slice() : [],
+    builtin: true,
+    builtinOpenAICompat: true,
+    baseUrl: def.baseUrl,
+    headers: def.headers,
+  };
+}
+
+/**
+ * Resolve an api-key for a built-in OpenAI-compatible provider from the
+ * environment, scanning {envKey} then any {altEnvKeys}. Returns '' when
+ * no env var is set so the caller can fall through to its config-based
+ * lookup chain.
+ */
+export function resolveBuiltinEnvKey(provider) {
+  const meta = PROVIDER_INFO[provider];
+  if (!meta || !meta.builtinOpenAICompat) return '';
+  const candidates = [meta.envKey, ...(meta.altEnvKeys || [])].filter(Boolean);
+  for (const k of candidates) {
+    if (process.env[k]) return process.env[k];
+  }
+  return '';
+}
+
 /**
  * Split a unified "provider/model" string (OpenClaw style:
  * "anthropic/claude-opus-4-7"). Also accepts a bare model id and returns
@@ -198,6 +417,8 @@ export function parseProviderModel(s) {
 // uses internally. Custom registrations must not collide with these.
 const RESERVED_PROVIDER_NAMES = new Set([
   'mock', 'claude-cli', 'anthropic', 'openai', 'gemini', 'ollama',
+  // OpenAI-compatible builtins (kept in lockstep with OPENAI_COMPAT_BUILTINS).
+  ...Object.keys(OPENAI_COMPAT_BUILTINS),
   '__add_custom__', '__custom_model__', '__fetch_models__',
 ]);