free-coding-models 0.3.17 → 0.3.18

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ---
 
+## 0.3.18
+
+### Added
+- **Missing tool bootstrap flow**: FCM now detects when a target CLI is absent, offers a minimal in-TUI install confirmation, runs the official global install command, then resumes the selected model launch automatically.
+
+### Changed
+- **TUI readability overhaul across every screen**: the main table, Settings, Help, Smart Recommend, Feedback, and Changelog overlays now share a semantic high-contrast theme system instead of a patchwork of hardcoded colors.
+- **Global theme switching now works for real**: press `G` to cycle `auto → dark → light` live, and the Settings screen now exposes a visible `Global Theme` row for the same control.
+- **Launcher binary resolution**: direct tool launches now search PATH plus common user bin directories so a freshly installed CLI can be reused immediately in the same FCM session.
+
+### Fixed
+- **Theme repaint bugs**: provider colors, tier colors, separators, badges, cursor highlights, and overlay backgrounds now update immediately when the theme changes instead of keeping stale import-time colors.
+
 ## 0.3.17
 
 ### Added

package/README.md

@@ -103,6 +103,8 @@ free-coding-models
 
 On first run, you'll be prompted to enter your API key(s). You can skip providers and add more later with **`P`**.
 
+Need to fix contrast because your terminal theme is fighting the TUI? Press **`G`** at any time to cycle **Auto → Dark → Light**. The switch recolors the full interface live: table, Settings, Help, Smart Recommend, Feedback, and Changelog.
+
 **③ Pick a model and launch your tool:**
 
 ```
@@ -111,6 +113,8 @@ On first run, you'll be prompted to enter your API key(s). You can skip provider
 
 The model you select is automatically written into your tool's config (OpenCode, OpenClaw, Crush, etc.) and the tool opens immediately. Done.
 
+If the active CLI tool is missing, FCM now catches it before launch, offers a tiny Yes/No install prompt, installs the tool with its official global command, then resumes the same model launch automatically.
+
 > 💡 You can also run `free-coding-models --goose --tier S` to pre-filter to S-tier models for Goose before the TUI even opens.
 
 
@@ -171,8 +175,9 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 | `D` | Cycle provider filter |
 | `E` | Toggle configured-only mode |
 | `F` | Favorite / unfavorite model |
+| `G` | Cycle global theme (`Auto → Dark → Light`) |
 | `R/S/C/M/O/L/A/H/V/B/U` | Sort columns |
-| `P` | Settings (API keys, providers, updates) |
+| `P` | Settings (API keys, providers, updates, theme) |
 | `Y` | Install Endpoints (push provider into tool config) |
 | `Q` | Smart Recommend overlay |
 | `N` | Changelog |
@@ -196,7 +201,10 @@ Press **`Z`** in the TUI to cycle between tools without restarting.
 - **Keyless latency** — models ping even without an API key (show 🔑 NO KEY)
 - **Smart Recommend** — questionnaire picks the best model for your task type
 - **Install Endpoints** — push a full provider catalog into any tool's config (`Y`)
+- **Missing tool bootstrap** — detect absent CLIs, offer one-click install, then continue the selected launch automatically
 - **Width guardrail** — shows a warning instead of a broken table in narrow terminals
+- **Readable everywhere** — semantic theme palette keeps table rows, overlays, badges, and help screens legible in dark and light terminals
+- **Global theme switch** — `G` cycles `auto`, `dark`, and `light` live without restarting
 - **Auto-retry** — timeout models keep getting retried
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-coding-models",
-  "version": "0.3.17",
+  "version": "0.3.18",
   "description": "Find the fastest coding LLM models in seconds — ping free models from multiple providers, pick the best one for OpenCode, Cursor, or any AI coding assistant.",
   "keywords": [
     "nvidia",

package/src/app.js

@@ -122,6 +122,7 @@ import { createOverlayRenderers } from '../src/overlays.js'
 import { createKeyHandler } from '../src/key-handler.js'
 import { getToolModeOrder, getToolMeta } from '../src/tool-metadata.js'
 import { startExternalTool } from '../src/tool-launchers.js'
+import { getToolInstallPlan, installToolWithPlan, isToolInstalled } from '../src/tool-bootstrap.js'
 import { getConfiguredInstallableProviders, installProviderEndpoints, refreshInstalledEndpoints, getInstallTargetModes, getProviderCatalogModels } from '../src/endpoint-installer.js'
 import { loadCache, saveCache, clearCache, getCacheAge } from '../src/cache.js'
 import { checkConfigSecurity } from '../src/security.js'
@@ -176,7 +177,7 @@ const LOCAL_VERSION = pkg.version
 export async function runApp(cliArgs, config) {
 
   // 📖 Detect user active terminal theme
-  detectActiveTheme(config.settings?.theme || 'dark')
+  detectActiveTheme(config.settings?.theme || 'auto')
 
   // 📖 Check config file security — warn and offer auto-fix if permissions are too open
   const securityCheck = checkConfigSecurity()
@@ -420,6 +421,14 @@ export async function runApp(cliArgs, config) {
     installEndpointsSelectedModelIds: new Set(), // 📖 Multi-select buffer for the selected-models phase
     installEndpointsErrorMsg: null, // 📖 Temporary validation/error message inside the install flow
     installEndpointsResult: null, // 📖 Final install result shown in the result phase
+    // 📖 Missing-tool bootstrap overlay — confirms a one-click install before retrying the launch.
+    toolInstallPromptOpen: false,
+    toolInstallPromptCursor: 0,
+    toolInstallPromptScrollOffset: 0,
+    toolInstallPromptMode: null,
+    toolInstallPromptModel: null,
+    toolInstallPromptPlan: null,
+    toolInstallPromptErrorMsg: null,
     // 📖 Smart Recommend overlay state (Q key opens it)
     recommendOpen: false,         // 📖 Whether the recommend overlay is active
     recommendPhase: 'questionnaire', // 📖 'questionnaire'|'analyzing'|'results' — current phase
@@ -750,6 +759,8 @@ export async function runApp(cliArgs, config) {
     getInstallTargetModes,
     getProviderCatalogModels,
     getToolMeta,
+    getToolInstallPlan,
+    padEndDisplay,
   })
 
   onKeyPress = createKeyHandler({
@@ -785,6 +796,9 @@ export async function runApp(cliArgs, config) {
     startOpenCode,
     startExternalTool,
     getToolModeOrder,
+    getToolInstallPlan,
+    isToolInstalled,
+    installToolWithPlan,
     startRecommendAnalysis: overlays.startRecommendAnalysis,
     stopRecommendAnalysis: overlays.stopRecommendAnalysis,
     sendBugReport,
@@ -844,7 +858,7 @@ export async function runApp(cliArgs, config) {
     refreshAutoPingMode()
     state.frame++
     // 📖 Cache visible+sorted models each frame so Enter handler always matches the display
-    if (!state.settingsOpen && !state.installEndpointsOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
+    if (!state.settingsOpen && !state.installEndpointsOpen && !state.toolInstallPromptOpen && !state.recommendOpen && !state.feedbackOpen && !state.changelogOpen) {
       const visible = state.results.filter(r => !r.hidden)
       state.visibleSorted = sortResultsWithPinnedFavorites(visible, state.sortColumn, state.sortDirection)
     }
@@ -852,6 +866,8 @@ export async function runApp(cliArgs, config) {
       ? overlays.renderSettings()
       : state.installEndpointsOpen
         ? overlays.renderInstallEndpoints()
+      : state.toolInstallPromptOpen
+        ? overlays.renderToolInstallPrompt()
       : state.recommendOpen
         ? overlays.renderRecommend()
         : state.feedbackOpen

package/src/config.js

@@ -210,7 +210,7 @@ function normalizeSettingsSection(settings) {
     ...safeSettings,
     hideUnconfiguredModels: typeof safeSettings.hideUnconfiguredModels === 'boolean' ? safeSettings.hideUnconfiguredModels : true,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
-    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'dark',
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -231,7 +231,7 @@ function normalizeProfileSettings(settings) {
     ..._emptyProfileSettings(),
     ...safeSettings,
     disableWidthsWarning: safeSettings.disableWidthsWarning === true,
-    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'dark',
+    theme: ['dark', 'light', 'auto'].includes(safeSettings.theme) ? safeSettings.theme : 'auto',
   }
 }
 
@@ -844,7 +844,7 @@ export function _emptyProfileSettings() {
     hideUnconfiguredModels: true, // 📖 true = default to providers that are actually configured
     preferredToolMode: 'opencode', // 📖 remember the last Z-selected launcher across app restarts
     disableWidthsWarning: false, // 📖 Disable widths warning (default off)
-    theme: 'dark',        // 📖 'dark', 'light', or 'auto'
+    theme: 'auto',        // 📖 'auto' follows the terminal/OS theme, override with 'dark' or 'light' if needed
   }
 }
 

package/src/key-handler.js

@@ -30,6 +30,7 @@
 import { loadChangelog } from './changelog-loader.js'
 import { loadConfig, replaceConfigContents } from './config.js'
 import { cleanupLegacyProxyArtifacts } from './legacy-proxy-cleanup.js'
+import { cycleThemeSetting, detectActiveTheme } from './theme.js'
 
 // 📖 Some providers need an explicit probe model because the first catalog entry
 // 📖 is not guaranteed to be accepted by their chat endpoint.
@@ -184,6 +185,9 @@ export function createKeyHandler(ctx) {
     startOpenCode,
     startExternalTool,
     getToolModeOrder,
+    getToolInstallPlan,
+    isToolInstalled,
+    installToolWithPlan,
     startRecommendAnalysis,
     stopRecommendAnalysis,
     sendBugReport,
@@ -207,6 +211,97 @@ export function createKeyHandler(ctx) {
 
   let userSelected = null
 
+  function resetToolInstallPrompt() {
+    state.toolInstallPromptOpen = false
+    state.toolInstallPromptCursor = 0
+    state.toolInstallPromptScrollOffset = 0
+    state.toolInstallPromptMode = null
+    state.toolInstallPromptModel = null
+    state.toolInstallPromptPlan = null
+    state.toolInstallPromptErrorMsg = null
+  }
+
+  function shouldCheckMissingTool(mode) {
+    return mode !== 'opencode-desktop'
+  }
+
+  async function launchSelectedModel(selected, options = {}) {
+    const { uiAlreadyStopped = false } = options
+    userSelected = { modelId: selected.modelId, label: selected.label, tier: selected.tier, providerKey: selected.providerKey }
+
+    if (!uiAlreadyStopped) {
+      readline.emitKeypressEvents(process.stdin)
+      if (process.stdin.isTTY) process.stdin.setRawMode(true)
+      stopUi()
+    }
+
+    // 📖 Show selection status before handing control to the target tool.
+    if (selected.status === 'timeout') {
+      console.log(chalk.yellow(`  ⚠ Selected: ${selected.label} (currently timing out)`))
+    } else if (selected.status === 'down') {
+      console.log(chalk.red(`  ⚠ Selected: ${selected.label} (currently down)`))
+    } else {
+      console.log(chalk.cyan(`  ✓ Selected: ${selected.label}`))
+    }
+    console.log()
+
+    // 📖 OpenClaw manages API keys inside its own config file. All other tools
+    // 📖 still need a provider key to be useful, so keep the existing warning.
+    if (state.mode !== 'openclaw') {
+      const selectedApiKey = getApiKey(state.config, selected.providerKey)
+      if (!selectedApiKey) {
+        console.log(chalk.yellow(`  Warning: No API key configured for ${selected.providerKey}.`))
+        console.log(chalk.yellow(`  The selected tool may not be able to use ${selected.label}.`))
+        console.log(chalk.dim(`  Set ${ENV_VAR_NAMES[selected.providerKey] || selected.providerKey.toUpperCase() + '_API_KEY'} or configure via settings (P key).`))
+        console.log()
+      }
+    }
+
+    let exitCode = 0
+    if (state.mode === 'openclaw') {
+      exitCode = await startOpenClaw(userSelected, state.config, { launchCli: true })
+    } else if (state.mode === 'opencode-desktop') {
+      exitCode = await startOpenCodeDesktop(userSelected, state.config)
+    } else if (state.mode === 'opencode') {
+      exitCode = await startOpenCode(userSelected, state.config)
+    } else {
+      exitCode = await startExternalTool(state.mode, userSelected, state.config)
+    }
+
+    process.exit(typeof exitCode === 'number' ? exitCode : 0)
+  }
+
+  async function installMissingToolAndLaunch(selected, installPlan) {
+    const currentPlan = installPlan || getToolInstallPlan(state.mode)
+    stopUi({ resetRawMode: true })
+
+    console.log(chalk.cyan(`  📦 Installing missing tool for ${state.mode}...`))
+    if (currentPlan?.summary) console.log(chalk.dim(`  ${currentPlan.summary}`))
+    if (currentPlan?.shellCommand) console.log(chalk.dim(`  ${currentPlan.shellCommand}`))
+    if (currentPlan?.note) console.log(chalk.dim(`  ${currentPlan.note}`))
+    console.log()
+
+    const installResult = await installToolWithPlan(currentPlan)
+    if (!installResult.ok) {
+      console.log(chalk.red(`  X Tool installation failed with exit code ${installResult.exitCode}.`))
+      if (currentPlan?.docsUrl) console.log(chalk.dim(`  Docs: ${currentPlan.docsUrl}`))
+      console.log()
+      process.exit(installResult.exitCode || 1)
+    }
+
+    if (shouldCheckMissingTool(state.mode) && !isToolInstalled(state.mode)) {
+      console.log(chalk.yellow('  ⚠ The installer finished, but the tool is still not reachable from this terminal session.'))
+      console.log(chalk.dim('  Restart your shell or add the tool bin directory to PATH, then retry the launch.'))
+      if (currentPlan?.docsUrl) console.log(chalk.dim(`  Docs: ${currentPlan.docsUrl}`))
+      console.log()
+      process.exit(1)
+    }
+
+    console.log(chalk.green('  ✓ Tool installed successfully. Continuing with the selected model...'))
+    console.log()
+    await launchSelectedModel(selected, { uiAlreadyStopped: true })
+  }
+
   // ─── Settings key test helper ───────────────────────────────────────────────
   // 📖 Fires a single ping to the selected provider to verify the API key works.
   async function testProviderKey(providerKey) {
@@ -383,6 +478,20 @@ export function createKeyHandler(ctx) {
     saveConfig(state.config)
   }
 
+  // 📖 Theme switches need to update both persisted preference and the live
+  // 📖 semantic palette immediately so every screen redraw adopts the new colors.
+  function applyThemeSetting(nextTheme) {
+    if (!state.config.settings) state.config.settings = {}
+    state.config.settings.theme = nextTheme
+    saveConfig(state.config)
+    detectActiveTheme(nextTheme)
+  }
+
+  function cycleGlobalTheme() {
+    const currentTheme = state.config.settings?.theme || 'auto'
+    applyThemeSetting(cycleThemeSetting(currentTheme))
+  }
+
   function resetInstallEndpointsOverlay() {
     state.installEndpointsOpen = false
     state.installEndpointsPhase = 'providers'
@@ -431,6 +540,11 @@ export function createKeyHandler(ctx) {
     if (!key) return
     noteUserActivity()
 
+    if (!state.feedbackOpen && !state.settingsEditMode && !state.settingsAddKeyMode && key.name === 'g' && !key.ctrl && !key.meta) {
+      cycleGlobalTheme()
+      return
+    }
+
     // 📖 Profile system removed - API keys now persist permanently across all sessions
 
     // 📖 Install Endpoints overlay: provider → tool → connection → scope → optional model subset.
@@ -614,6 +728,44 @@ export function createKeyHandler(ctx) {
       return
     }
 
+    if (state.toolInstallPromptOpen) {
+      if (key.ctrl && key.name === 'c') { exit(0); return }
+
+      const installPlan = state.toolInstallPromptPlan || getToolInstallPlan(state.toolInstallPromptMode)
+      const installSupported = Boolean(installPlan?.supported)
+
+      if (key.name === 'escape') {
+        resetToolInstallPrompt()
+        return
+      }
+
+      if (installSupported && key.name === 'up') {
+        state.toolInstallPromptCursor = Math.max(0, state.toolInstallPromptCursor - 1)
+        return
+      }
+
+      if (installSupported && key.name === 'down') {
+        state.toolInstallPromptCursor = Math.min(1, state.toolInstallPromptCursor + 1)
+        return
+      }
+
+      if (key.name === 'return') {
+        if (!installSupported) {
+          resetToolInstallPrompt()
+          return
+        }
+
+        const selectedModel = state.toolInstallPromptModel
+        const shouldInstall = state.toolInstallPromptCursor === 0
+        resetToolInstallPrompt()
+
+        if (!shouldInstall || !selectedModel) return
+        await installMissingToolAndLaunch(selectedModel, installPlan)
+      }
+
+      return
+    }
+
     // 📖 Feedback overlay: intercept ALL keys while overlay is active.
     // 📖 Enter → send to Discord, Esc → cancel, Backspace → delete char, printable → append to buffer.
     if (state.feedbackOpen) {
@@ -1078,6 +1230,11 @@ export function createKeyHandler(ctx) {
           return
         }
 
+        if (state.settingsCursor === themeRowIdx) {
+          cycleGlobalTheme()
+          return
+        }
+
         if (state.settingsCursor === cleanupLegacyProxyRowIdx) {
           runLegacyProxyCleanup()
           return
@@ -1098,6 +1255,7 @@ export function createKeyHandler(ctx) {
 
         // 📖 Enter edit mode for the selected provider's key
         const pk = providerKeys[state.settingsCursor]
+        if (!pk) return
         state.settingsEditBuffer = resolveApiKeys(state.config, pk)[0] ?? ''
         state.settingsEditMode = true
         return
@@ -1112,15 +1270,7 @@ export function createKeyHandler(ctx) {
         ) return
         // 📖 Theme configuration cycle inside settings
         if (state.settingsCursor === themeRowIdx) {
-          const themes = ['dark', 'light', 'auto']
-          const currentTheme = state.config.settings?.theme || 'dark'
-          const nextIndex = (themes.indexOf(currentTheme) + 1) % themes.length
-          state.config.settings.theme = themes[nextIndex]
-          saveConfig(state.config)
-          try {
-            const { detectActiveTheme } = await import('../src/theme.js')
-            detectActiveTheme(state.config.settings.theme)
-          } catch {}
+          cycleGlobalTheme()
           return
         }
         // 📖 Widths Warning toggle (disable/enable)
@@ -1142,6 +1292,8 @@ export function createKeyHandler(ctx) {
       if (key.name === 't') {
         if (
           state.settingsCursor === updateRowIdx
+          || state.settingsCursor === widthWarningRowIdx
+          || state.settingsCursor === themeRowIdx
           || state.settingsCursor === cleanupLegacyProxyRowIdx
           || state.settingsCursor === changelogViewRowIdx
         ) return
@@ -1149,6 +1301,7 @@ export function createKeyHandler(ctx) {
 
         // 📖 Test the selected provider's key (fires a real ping)
         const pk = providerKeys[state.settingsCursor]
+        if (!pk) return
         testProviderKey(pk)
         return
       }
@@ -1442,46 +1595,24 @@ export function createKeyHandler(ctx) {
       // 📖 Use the cached visible+sorted array — guaranteed to match what's on screen
       const selected = state.visibleSorted[state.cursor]
       if (!selected) return // 📖 Guard: empty visible list (all filtered out)
-      // 📖 Allow selecting ANY model (even timeout/down) - user knows what they're doing
-      userSelected = { modelId: selected.modelId, label: selected.label, tier: selected.tier, providerKey: selected.providerKey }
-
-      // 📖 Stop everything and act on selection immediately
-      readline.emitKeypressEvents(process.stdin)
-      process.stdin.setRawMode(true)
-      stopUi()
-
-      // 📖 Show selection with status
-      if (selected.status === 'timeout') {
-        console.log(chalk.yellow(`  ⚠ Selected: ${selected.label} (currently timing out)`))
-      } else if (selected.status === 'down') {
-        console.log(chalk.red(`  ⚠ Selected: ${selected.label} (currently down)`))
-      } else {
-        console.log(chalk.cyan(`  ✓ Selected: ${selected.label}`))
-      }
-      console.log()
-
-      // 📖 Warn if no API key is configured for the selected model's provider
-      if (state.mode !== 'openclaw') {
-        const selectedApiKey = getApiKey(state.config, selected.providerKey)
-        if (!selectedApiKey) {
-          console.log(chalk.yellow(`  Warning: No API key configured for ${selected.providerKey}.`))
-          console.log(chalk.yellow(`  The selected tool may not be able to use ${selected.label}.`))
-          console.log(chalk.dim(`  Set ${ENV_VAR_NAMES[selected.providerKey] || selected.providerKey.toUpperCase() + '_API_KEY'} or configure via settings (P key).`))
-          console.log()
+      if (shouldCheckMissingTool(state.mode) && !isToolInstalled(state.mode)) {
+        state.toolInstallPromptOpen = true
+        state.toolInstallPromptCursor = 0
+        state.toolInstallPromptScrollOffset = 0
+        state.toolInstallPromptMode = state.mode
+        state.toolInstallPromptModel = {
+          modelId: selected.modelId,
+          label: selected.label,
+          tier: selected.tier,
+          providerKey: selected.providerKey,
+          status: selected.status,
         }
+        state.toolInstallPromptPlan = getToolInstallPlan(state.mode)
+        state.toolInstallPromptErrorMsg = null
+        return
       }
 
-      // 📖 Dispatch to the correct integration based on active mode
-      if (state.mode === 'openclaw') {
-        await startOpenClaw(userSelected, state.config)
-      } else if (state.mode === 'opencode-desktop') {
-        await startOpenCodeDesktop(userSelected, state.config)
-      } else if (state.mode === 'opencode') {
-        await startOpenCode(userSelected, state.config)
-      } else {
-        await startExternalTool(state.mode, userSelected, state.config)
-      }
-      process.exit(0)
+      await launchSelectedModel(selected)
     }
   }
 }

package/src/openclaw.js

@@ -3,10 +3,12 @@
  * @description OpenClaw config helpers for persisting the selected provider/model as the default.
  *
  * @details
- *   📖 OpenClaw is config-driven: FCM does not launch a separate foreground CLI here.
+ *   📖 OpenClaw is primarily config-driven, but FCM can now optionally launch the
+ *   📖 installed CLI right after persisting the selected default model.
  *   📖 Pressing Enter in `OpenClaw` mode must therefore do two things reliably:
  *   - install the selected provider/model into `~/.openclaw/openclaw.json`
  *   - set that exact model as the default primary model for the next OpenClaw session
+ *   - optionally start `openclaw` immediately when the caller asks for it
  *
  *   📖 The old implementation was hard-coded to `nvidia/*`, which meant selecting
  *   📖 a Groq/Cerebras/etc. row silently wrote the wrong provider/model into the
@@ -30,6 +32,7 @@ import { dirname, join } from 'path'
 import { installProviderEndpoints } from './endpoint-installer.js'
 import { ENV_VAR_NAMES } from './provider-metadata.js'
 import { PROVIDER_COLOR } from './render-table.js'
+import { resolveToolBinaryPath } from './tool-bootstrap.js'
 
 const OPENCLAW_CONFIG = join(homedir(), '.openclaw', 'openclaw.json')
 
@@ -53,13 +56,38 @@ export function saveOpenClawConfig(config, options = {}) {
   writeFileSync(filePath, JSON.stringify(config, null, 2))
 }
 
+function spawnOpenClawCli() {
+  return new Promise(async (resolve, reject) => {
+    const { spawn } = await import('child_process')
+    const command = resolveToolBinaryPath('openclaw') || 'openclaw'
+    const child = spawn(command, [], {
+      stdio: 'inherit',
+      shell: false,
+      detached: false,
+      env: process.env,
+    })
+
+    child.on('exit', (code) => resolve(typeof code === 'number' ? code : 0))
+    child.on('error', (error) => {
+      if (error?.code === 'ENOENT') {
+        console.log(chalk.red('  X Could not find "openclaw" in PATH.'))
+        console.log(chalk.dim('  Install: npm install -g openclaw@latest  or see https://docs.openclaw.ai/install'))
+        console.log()
+        resolve(1)
+        return
+      }
+      reject(error)
+    })
+  })
+}
+
 /**
  * 📖 startOpenClaw installs the selected provider/model into OpenClaw and sets
  * 📖 it as the primary default model. OpenClaw itself is not launched here.
  *
  * @param {{ providerKey: string, modelId: string, label: string }} model
  * @param {Record<string, unknown>} config
- * @param {{ paths?: { openclawConfigPath?: string } }} [options]
+ * @param {{ paths?: { openclawConfigPath?: string }, launchCli?: boolean }} [options]
  * @returns {Promise<ReturnType<typeof installProviderEndpoints> | null>}
  */
 export async function startOpenClaw(model, config, options = {}) {
@@ -85,9 +113,15 @@ export async function startOpenClaw(model, config, options = {}) {
     if (result.backupPath) console.log(chalk.dim(`  💾 Backup: ${result.backupPath}`))
     if (providerEnvName) console.log(chalk.dim(`  🔑 API key synced under config env.${providerEnvName}`))
     console.log()
-    console.log(chalk.dim('  💡 OpenClaw will reload config automatically when it notices the file change.'))
-    console.log(chalk.dim(`     To apply manually: openclaw models set ${result.primaryModelRef || `${result.providerId}/${model.modelId}`}`))
-    console.log()
+    if (options.launchCli) {
+      console.log(chalk.dim('  Starting OpenClaw...'))
+      console.log()
+      await spawnOpenClawCli()
+    } else {
+      console.log(chalk.dim('  💡 OpenClaw will reload config automatically when it notices the file change.'))
+      console.log(chalk.dim(`     To apply manually: openclaw models set ${result.primaryModelRef || `${result.providerId}/${model.modelId}`}`))
+      console.log()
+    }
     return result
   } catch (error) {
     console.log(chalk.red(`  X Could not configure OpenClaw: ${error instanceof Error ? error.message : String(error)}`))

package/src/opencode.js

@@ -32,6 +32,7 @@ import { PROVIDER_COLOR } from './render-table.js'
 import { loadOpenCodeConfig, saveOpenCodeConfig } from './opencode-config.js'
 import { getApiKey } from './config.js'
 import { ENV_VAR_NAMES, OPENCODE_MODEL_MAP, isWindows, isMac, isLinux } from './provider-metadata.js'
+import { resolveToolBinaryPath } from './tool-bootstrap.js'
 
 // 📖 OpenCode config location: ~/.config/opencode/opencode.json on ALL platforms.
 // 📖 OpenCode uses xdg-basedir which resolves to %USERPROFILE%\.config on Windows.
@@ -177,7 +178,7 @@ async function spawnOpenCode(args, providerKey, fcmConfig, existingZaiProxy = nu
   }
 
   const { spawn } = await import('child_process')
-  const child = spawn('opencode', finalArgs, {
+  const child = spawn(resolveToolBinaryPath('opencode') || 'opencode', finalArgs, {
     stdio: 'inherit',
     shell: true,
     detached: false,